NexaTeams Documentation

What is NexaTeams?#

A team/clan layer for SMP and Lifesteal servers with social, teleport, vault and bank workflows.

Who is it for?#

Server owners who want a lightweight team system that can integrate with economy and placeholder plugins.

Supported server types#

SMP, Lifesteal, Survival, Factions-like and small network servers.

Main features#

• Team creation
• Invites and membership
• Team home
• Team vault
• Team bank
• Team chat
• Friendly fire toggle
• Privacy and MOTD

Dependencies#

• Java 17
• Paper-compatible 1.21 server
• Vault optional
• PlaceholderAPI optional
• GriefPrevention optional

Setup checklist#

1. Choose storage behavior
2. Configure team limits
3. Configure vault rules
4. Set home and ally behavior
5. Give permissions
6. Test team creation

Production notes#

• Give permissions through LuckPerms or your permission manager.
• Keep backups of YAML files and database tables.
• Use a staging server before large updates.
• Do not claim Folia or network support unless the full setup has been tested.

How to edit messages#

This product ships messages.yml. Edit the generated copy in the plugin folder, keep placeholders intact, then reload the plugin command or restart for startup-level changes.

Formatting#

<red>Error message</red>
&cLegacy color message
{player} {amount} {reason}

Anvil Guis#

Text-input GUI definitions for values such as bank deposit amounts or team-related typed input.

• Configured title: Deposit Amount

Team Bank#

Team economy menu for shared balance display, deposits, withdrawals and bank navigation.

• Configured title: ᴛᴇᴀᴍ ʙᴀɴᴋ
• Size: 27 slots
• Configured items: 5
• Actions: deposit, back

Team Create#

Team creation flow used before a player becomes the owner of a new team.

• Configured title: ᴄʀᴇᴀᴛᴇ ᴛᴇᴀᴍ
• Size: 27 slots
• Configured items: 2

Team Flag#

Team flag menu for toggling team behavior options exposed as flags.

• Configured title: ᴛᴇᴀᴍ ꜰʟᴀɢ
• Configured items: 5
• Actions: back

Team Home#

Team home menu for setting, teleporting to and managing the shared team home location.

• Configured title: ᴛᴇᴀᴍ ʜᴏᴍᴇ
• Configured items: 4
• Actions: sethome back: slot: 0, back

Team List#

Team list browser for viewing existing teams and navigating team information pages.

• Configured title: ᴛᴇᴀᴍ ʟɪsᴛ
• Size: 54 slots
• Configured items: 4

Team Main#

Main team dashboard linking bank, home, members, settings, vault and live team information.

• Configured title: ᴛᴇᴀᴍ ᴍᴇɴᴜ
• Size: 27 slots
• Configured items: 7
• Actions: home, vault

Team Members#

Member management menu for viewing team players and handling membership actions.

• Configured title: ᴛᴇᴀᴍ ᴍᴇᴍʙᴇʀs
• Size: 54 slots
• Configured items: 5
• Actions: back

Team Settings#

Team settings menu for privacy, glow, flags and other configurable team behavior.

• Configured title: ᴛᴇᴀᴍ sᴇᴛᴛɪɴɢs
• Size: 27 slots
• Configured items: 7
• Actions: glow, flag tag: slot: 15, tag back: slot: 18, back

Team Teleport#

Team teleport menu used for team travel flows and shared destination navigation.

• Configured title: Team Teleport
• Size: 54 slots
• Configured items: 5
• Actions: back

Team Vault#

Team vault menu for controlled shared storage access through the team system.

• Configured title: ᴛᴇᴀᴍ ᴠᴀᴜʟᴛ
• Size: 54 slots
• Configured items: 2
• Actions: back

Placeholder surface#

Identifier: nexateams. The expansion covers team membership, name, tag, bank balance, owner and member count.

Usage notes#

• Install PlaceholderAPI before using these values in scoreboards or chat formats.
• Reload PlaceholderAPI expansions after plugin updates.
• Keep placeholder identifiers lowercase exactly as shown unless the product uses a legacy mixed-case identifier.

Storage recommendation#

NexaTeams config exposes SQLite and MySQL under database.method; SQLite fits one server and MySQL fits production shared storage.

Backup checklist#

• Stop the server before copying live flat files.
• Export SQL databases before updates.
• Keep plugin version and server version in backup notes.
• Test migration on a copy first.

Bootstrap checklist#

1. Install the api-version: 1.21 plugin on Paper or Folia with the required Java/server baseline.
2. Copy plugins/NexaTeams/ before editing configuration.
3. Set license-key and verify LicenseGate during startup.
4. Choose SQLite for a small server or MySQL for a network.
5. Install Vault and PlaceholderAPI when bank/economy or scoreboard features are required.
6. Use /nexateams reload only for runtime configuration changes.

Runtime baseline#

database.method: "SQLite"
team-settings.max-members: 10
vault.enabled: true
vault.rows: 6
integrations.placeholderapi: true
integrations.worldguard: true
integrations.combatlogx: true
integrations.pvpmanager: true

Keep license, schema and storage changes inside a maintenance window. Confirm /nexateams reports the expected version after startup.

Player lifecycle#

1. Create a team through /team create or the team-create GUI.
2. Invite an online player with /team invite <player>.
3. Let the target use /team accept or /team deny.
4. Inspect membership with /team info and /team online.
5. Use /team leave for members; the owner must transfer or disband instead.

Staff/owner lifecycle#

1. Remove a member with /team kick <player> after checking role permissions.
2. Transfer ownership with /team transfer <player> and verify old/new rank state.
3. Use /team disband only after withdrawing or documenting bank/vault assets.
4. Test max-members and invite cost before public launch.
5. Do not advertise /team gift; its permission is declared but the feature is marked not implemented.

Built-in rank model#

• MEMBER can use actions granted by team policy.
• MODERATOR is the default minimum for invite, kick, bank withdrawal, tag, flag, home, friendly fire, privacy, glow, MOTD, mute and bank access management.
• OWNER is required for promote, demote, permission management and viewing team logs.
• Use /team moderator add|remove <player> for role changes.
• Use the member options and member permissions menus to review custom permissions.

Permission QA#

1. Test invite, kick and bank withdrawal as member, moderator and owner.
2. Promote/demote a disposable account and reopen the member list.
3. Toggle a custom permission, reconnect and verify it persists.
4. Transfer ownership and confirm the previous owner no longer has owner-only actions.
5. Review /team logs after each governance change.

Identity commands#

/team tag <tag>
/team tag remove
/team flag
/team motd <message>
/team privacy
/team info

The flag GUI uses the held item as the team icon. Tag and MOTD changes are role-gated and can carry the configured command cost.

Visibility tools#

1. Toggle privacy and confirm the team is hidden from the public team list while staff bypass remains available.
2. Open /team online and verify online member output.
3. Use /team coordinate only when members have knowingly enabled coordinate visibility.
4. Use /team logs to audit identity and visibility changes.
5. Reconnect and verify tag/MOTD/flag state remains after reload.

Chat flow#

1. Use /team chat to toggle team-only chat mode.
2. Send a message and confirm only active team members receive it.
3. Use /team mute as an authorized moderator to suppress member chat.
4. Confirm moderators retain the configured moderation visibility.
5. Toggle chat off and verify normal server chat resumes.

Operational checks#

• Team chat state must survive the listener’s player lifecycle rules correctly.
• MOTD is edited with /team motd <message> and displayed on join according to message config.
• Muted state is team-scoped, not a global server mute.
• Use nexateams.chat, nexateams.mute and nexateams.motd independently.

Friendly fire#

Use /team friendlyfire to toggle team damage. The damage listener covers melee and projectile-style sources such as arrows and snowballs.

Team glow#

Use /team glow to toggle the team visibility effect. Packet/Glow adapters can reapply visibility after world changes.

QA matrix#

• Owner versus member melee
• Projectile from a teammate
• Damage after toggle/reload
• World change with glow enabled
• Combat plugin state and reconnect

Bank workflow#

1. Install Vault and an economy plugin, then confirm vault.enabled: true.
2. Open /team bank or the team bank menu.
3. Deposit a small amount and verify the actor/amount/timestamp log.
4. Attempt withdrawal as member and moderator, then compare the bank permission policy.
5. Use /team bank log and inspect the configured max log count.

Economy controls#

team-settings.initial-bank-balance: 0
bank-settings.max-logs: 10
command-costs.create: 1000.0
command-costs.sethome: 500.0
command-costs.tp: 0.0
command-costs.bank: 0.0

Every configured command cost is checked before the operation. A failed withdrawal/cost check must not mutate team state.

Vault player flow#

1. Use /team vault to open the configured vault GUI.
2. Place and remove a test item from two team members.
3. Verify outsider access is denied and member permissions match the team policy.
4. Close/reopen the menu and compare slot contents.
5. Restart after a change and confirm the item remains exactly once.

Persistence controls#

vault.enabled: true
vault.rows: 6
vault.update-cooldown-ms: 100
vault.batch-save: false

• Up to 54 GUI slots can be configured, with the content/control layout defined in menus/team-vault.yml.
• Vault slot updates use locks, versions and WAL transaction ids.
• Uncommitted WAL records are replayed during startup recovery.

Home flow#

1. Use /team sethome inside an allowed claim/region.
2. Use /team home and verify countdown, cost and cancellation.
3. Remove it with /team delhome and confirm the stored location is cleared.
4. Move or take damage during countdown and verify teleport cancellation.
5. Reconnect and confirm the home location persists.

Member teleport flow#

1. Use /team tp <player> to request/teleport to a teammate.
2. Use /team tptoggle as the target to deny or allow incoming teleport.
3. Test offline, outsider and self-target cases.
4. Verify GriefPrevention trust/accessor requirements for home placement.

Core menus#

team-create.yml, team-list.yml, team-main.yml, team-members.yml, member-options.yml and member-perms.yml cover creation and governance.

Asset menus#

team-bank.yml, team-vault.yml, team-home.yml, team-teleport.yml, team-logs.yml and team-settings.yml cover shared operations.

Input menus#

team-flag.yml and anvil-guis.yml provide flag selection and text input. Materials, slots, fill items, titles and actions are YAML-driven.

Economy#

Vault supplies command costs and team bank economy. Without a valid provider, economy-required actions must fail clearly.

Claims & combat#

GriefPrevention controls home placement/access. CombatLogX and PvPManager participate in teleport/auto protection rules. Test missing-hook fallback.

Display & glow#

PlaceholderAPI exposes team values. PacketEvents and glow adapters support efficient team visibility; verify world-change refresh.

Database setup#

• SQLite writes nexateams.db in the plugin data folder with synchronous commit settings.
• MySQL uses host, port, database, username, password and SSL from database.data.
• Tables include teams, team_members, bank_logs, team_logs and team_vault_items.
• Existing bank logs can be migrated into team logs during schema setup.
• Folia/Spigot schedulers keep database work away from unsafe player threads.

Maintenance commands#

1. Run /nexateams and record the active version.
2. Use /nexateams reload after messages/menu/config changes.
3. Use /nexateams backup for the supported YAML backup workflow.
4. Use /nexateams restore <backup> only during a maintenance window.
5. After storage changes, verify members, roles, home, balance, logs and vault slots.

PlaceholderAPI setup#

1. Install PlaceholderAPI and keep integrations.placeholderapi: true.
2. Use team presence, name, tag, owner, bank and member count in displays.
3. Test a player without a team and a player after leave/disband.
4. Verify formatted balance output matches the server economy format.

%nexateams_has_team%
%nexateams_name%
%nexateams_tag%
%nexateams_owner%
%nexateams_bank%
%nexateams_members_count%

Integration boundaries#

• TeamPlaceholderExpansion is the display hook.
• VaultHook and GriefPreventionHook provide optional provider boundaries.
• Team listeners expose behavior through Bukkit events/listeners rather than a documented public API package.
• Use /nexateams inspect and placeholders for diagnostics.

Admin commands#

/nexateams help
/nexateams reload
/nexateams inspect
/nexateams inspect <player|team>

• /nexateams inspect opens the team list for staff.
• Inspecting a target opens the team main menu with admin view enabled.
• nexateams.admin.bypass bypasses privacy checks; keep it separate from normal admin access.

Recovery checklist#

1. Record team name/UUID and affected player before changing data.
2. Review /team logs and bank/vault histories.
3. Back up before restore or manual database intervention.
4. Replay/recover WAL records before diagnosing missing vault items.
5. Reopen the affected GUI and verify role, balance, home and vault state.

Stage 1 — sandbox#

• Use SQLite and a disposable team.
• Test create/invite/accept/deny/leave/disband.
• Test role permissions, chat, friendly fire and privacy.

Stage 2 — asset pilot#

• Enable Vault bank and 54-slot vault.
• Test WAL recovery, concurrent viewers and full menus.
• Test home/teleport, claim checks and combat cancellation.

Stage 3 — live/Folia#

• Use MySQL for network-scale persistence.
• Test Folia region scheduling and world changes.
• Restrict admin bypass and restore permissions.

Team lifecycle#

1. Use /team to create the team and confirm the configured creation cost.
2. Invite a player, accept the invite and open the member/settings menus.
3. Set friendly fire and role permissions before adding valuable assets.
4. Deposit a small amount into the team bank and inspect the bank log.
5. Open the team vault, test access as owner/member, then test a denied outsider.
6. Set the team home and verify teleport cost, cooldown and relation rules.

Shared asset baseline#

team-settings:
  max-members: 10
bank-settings:
  max-logs: 10
vault:
  enabled: true
  rows: 6
command-costs:
  create: 1000.0
  sethome: 500.0
  home: 10.0

Friendly-fire rollout#

Start with friendly fire disabled, verify team relations and external claim/region hooks, then enable only the combat behavior your server expects. Test team glow and team chat after a reconnect.

Disband safety#

Before disbanding, export/withdraw bank and vault contents, remove team home and review audit history. Do not use admin reset commands as a normal leave workflow.

Lifesteal Teams Setup#

Use stricter cooldowns, staff visibility, abuse protection and clear player feedback for high-conflict gameplay.

SMP Clans Setup#

Use conservative defaults, SQLite or simple file storage, readable messages and relaxed limits for community servers.

Faction-like Setup#

Set team limits, invite rules, home behavior, bank or vault permissions and relation rules before opening the server.

Small Server Setup#

Use conservative defaults, SQLite or simple file storage, readable messages and relaxed limits for community servers.

Network Setup#

Use production SQL, unique server IDs, shared sync secrets and a controlled Redis or proxy transport.

Before asking for support#

• Test on the latest available plugin version.
• Check server version and Java version.
• Temporarily remove unrelated plugins when debugging conflicts.
• Attach changed YAML files when config is involved.