NexaCombat Documentation

Plugin-specific YAML settings used by this product.

# ...
# Short documentation excerpt from addons.yml.
# This is not the complete YAML file.
# Lines before and after this preview are omitted from the docs.
# ...
settings:
  apply-pending-on-reload: true
  allow-delete: true
  marketplace:
    enabled: false
    catalog-url: ""
    timeout-ms: 10000
    download-artifacts: false
    download-directory: "addons"
  messages:
    queued-install: "&aQueued addon install: &e%addon%&a."
    queued-update: "&aQueued addon update: &e%addon%&a."
    queued-delete: "&cQueued addon delete: &e%addon%&c."
    enabled: "&aEnabled addon: &e%addon%&a."
    disabled: "&cDisabled addon: &e%addon%&c."
    cancelled: "&eCancelled pending action for &6%addon%&e."
    artifact-downloaded: "&aDownloaded addon artifact for &e%addon%&a."
    artifact-failed: "&cCould not download addon artifact for &e%addon%&c: %error%"
    marketplace-disabled: "&cAddon marketplace sync is disabled."
    marketplace-missing-url: "&cAddon marketplace catalog-url is empty."
    marketplace-synced: "&aSynced &e%count% &aaddon catalog entrie(s)."
    marketplace-failed: "&cAddon marketplace sync failed: %error%"
addons:
  actionbar-ui:
    display-name: "ActionBar UI"
    category: "ui"
    description:
      - "Combat timer actionbar expansion."
    version: "1.0.0"
    latest-version: "1.0.0"
    installed: true
    installed-version: "1.0.0"
    enabled: true
    restart-required: false
# ...
# More options continue in the generated plugin YAML file.
# Open plugins/<plugin-folder>/addons.yml to review every setting.
# ...

Main runtime settings, license, modules, limits, storage and feature behavior.

# ...
# Short documentation excerpt from config.yml.
# This is not the complete YAML file.
# Lines before and after this preview are omitted from the docs.
# ...
license-key: LICENSE

settings:
  debug: false
  event-priorities:
    enabled: false
    note: "When enabled, core combat listener methods are registered programmatically with these priorities."
    listeners:
      combat-damage: MONITOR
      combat-block-damage: MONITOR
      combat-death: MONITOR
      combat-quit: NORMAL
      combat-join: NORMAL
      mob-death: MONITOR

command-aliases:
  enabled: false
  aliases:
    combatmenu: "combat menu"
    nc: "nexacombat"

language:
  active: messages.yml

hooks:
  vault: true
  suite-plugins:
    enabled: true
    cache-expire: 2s
    additional-plugin-names: []
    command-blocks:
      enabled: true
      bypass-permission: nexacombat.bypass.suite-hooks
      message: "&cYou cannot use that Nexa plugin command while in combat."
# ...
# More options continue in the generated plugin YAML file.
# Open plugins/<plugin-folder>/config.yml to review every setting.
# ...

Plugin-specific YAML settings used by this product.

# ...
# Short documentation excerpt from network-sync.yml.
# This is not the complete YAML file.
# Lines before and after this preview are omitted from the docs.
# ...
servers: {}
# ...
# More options continue in the generated plugin YAML file.
# Open plugins/<plugin-folder>/network-sync.yml to review every setting.
# ...

# ...
# Short documentation excerpt from messages.yml.
# This is not the complete YAML file.
# Lines before and after this preview are omitted from the docs.
# ...
prefix: "&8[&6NexaCombat&8] &7"
missing-message: "&cMissing message: %key%"

no-permission: "&cNo permission."
player-not-found: "&cPlayer not found."
only-players: "&cOnly players can use this command."
config-reloaded: "&aNexaCombat configs reloaded."
invalid-number: "&cInvalid number."

admin-input:
  title: "&8&m------------------------------"
  prompt: "&7Type a new value for &e%label%&7."
  integer-prompt: "&7Type a whole number for &e%label%&7."
  current: "&7Current: &e%current%"
  range: "&7Range: &e%min% &7- &e%max%"
  clear: "&7Type &e- &7to clear this value."
  cancel: "&7Type &ccancel &7to cancel."
  cancelled: "&cInput cancelled."
  empty-denied: "&cThis value cannot be empty."
  too-long: "&cThis value is too long. Max length is 128 characters."
  invalid-integer: "&cInvalid number."
  out-of-range: "&cValue must be between &e%min% &cand &e%max%&c."
  saved: "&aSaved &e%label%&a."

language:
  display-name: "&eEnglish"
  material: BOOK
  changed: "&aLanguage changed to &e%language%&a."
  reloaded: "&aMessages reloaded."
  not-found: "&cLanguage file not found."

combat-ui:
  shown: "&aCombat UI is now visible."
  hidden: "&cCombat UI has been hidden."
# ...
# More options continue in the generated plugin YAML file.
# Open plugins/<plugin-folder>/messages.yml to review every setting.
# ...

Purpose: Connects gameplay behavior to claims, regions or group ownership rules.

Troubleshooting: If region or claim rules do not apply, check region priority, claim ownership, world names and whether the hook is enabled.

1. Install the claim or region plugin before this product starts.
2. Create the region, claim, town or faction area you want the plugin to read.
3. Enable the matching hook in the integration/config file when a toggle exists.
4. Test the protected workflow inside and outside the region with a normal player.

Purpose: Provides economy withdrawals, deposits, prices, banks or metadata through Vault.

Troubleshooting: If balances, rewards or banks do not work, confirm Vault has an active economy provider and that no economy plugin loads after this product.

1. Install Vault and one compatible economy or permission provider.
2. Restart the server and confirm Vault reports a provider in console.
3. Enable prices, banks, rewards or currency features that depend on Vault.
4. Test one deposit and one withdrawal with a non-op account.

Purpose: Provides permission, group and metadata checks for admin access, limits, bypass nodes and formatted player data.

Troubleshooting: If permissions or metadata look wrong, run a verbose LuckPerms check and verify inherited groups, contexts and bypass nodes.

1. Install LuckPerms before this product starts.
2. Create the permission groups and inheritance used by your server.
3. Assign the permission nodes listed in the Permissions section.
4. Test with a non-op account so inherited admin and bypass nodes do not hide permission issues.

Purpose: Registers or consumes PlaceholderAPI values for scoreboards, formats and external displays.

Troubleshooting: If values stay blank, reload expansions and verify the identifier exactly matches the placeholder shown in this docs page.

1. Install PlaceholderAPI or the listed placeholder provider.
2. Install required expansions when the provider uses external expansions.
3. Use the exact placeholder identifiers documented in this page.
4. Reload the display plugin after changing scoreboard, tablist, menu or chat format files.

Purpose: Provides NPC entities used by bot or combat punishment workflows.

Troubleshooting: If NPCs or bots fail, check Citizens startup errors, skin fetch warnings, disabled worlds and pathfinder restrictions.

1. Install Citizens before starting the server.
2. Confirm Citizens loads without NPC registry errors.
3. Enable the feature that uses NPCs, bots, corpses or combat entities.
4. Spawn or trigger one test entity and check console for skin, pathfinder or trait errors.

Purpose: Adds combat AI behavior on top of Citizens NPC entities when NPC combat behavior is enabled.

Troubleshooting: If NPCs or bots fail, check Citizens startup errors, skin fetch warnings, disabled worlds and pathfinder restrictions.

1. Install Citizens before starting the server.
2. Confirm Citizens loads without NPC registry errors.
3. Enable the feature that uses NPCs, bots, corpses or combat entities.
4. Spawn or trigger one test entity and check console for skin, pathfinder or trait errors.

Purpose: Provides packet-level compatibility for visual, combat or display features that need lower-level server events.

Troubleshooting: If packet features fail, update ProtocolLib for your exact server build and check for packet listener errors on startup.

1. Install the ProtocolLib build that matches your server version.
2. Restart and confirm ProtocolLib has no packet listener errors.
3. Enable the visual/combat feature that depends on packet events.
4. Test with one normal player and watch console for packet compatibility warnings.

Purpose: Connects gameplay behavior to claims, regions or group ownership rules.

Troubleshooting: If region or claim rules do not apply, check region priority, claim ownership, world names and whether the hook is enabled.

1. Install the claim or region plugin before this product starts.
2. Create the region, claim, town or faction area you want the plugin to read.
3. Enable the matching hook in the integration/config file when a toggle exists.
4. Test the protected workflow inside and outside the region with a normal player.

Purpose: Connects gameplay behavior to claims, regions or group ownership rules.

Troubleshooting: If region or claim rules do not apply, check region priority, claim ownership, world names and whether the hook is enabled.

1. Install the claim or region plugin before this product starts.
2. Create the region, claim, town or faction area you want the plugin to read.
3. Enable the matching hook in the integration/config file when a toggle exists.
4. Test the protected workflow inside and outside the region with a normal player.

Purpose: Connects gameplay behavior to claims, regions or group ownership rules.

Troubleshooting: If region or claim rules do not apply, check region priority, claim ownership, world names and whether the hook is enabled.

1. Install the claim or region plugin before this product starts.
2. Create the region, claim, town or faction area you want the plugin to read.
3. Enable the matching hook in the integration/config file when a toggle exists.
4. Test the protected workflow inside and outside the region with a normal player.

Purpose: Connects this product to the practice and bot training ecosystem.

Troubleshooting: If queues or duels do not bridge, confirm the arena/kit exists and both plugins agree on the same mode/profile names.

1. Install EventPractice and confirm arenas, kits and queues load correctly.
2. Enable the practice/bot duel bridge in the relevant config file.
3. Use a test queue, duel or arena flow to confirm both plugins exchange state.
4. Check that match cleanup works after the integration flow ends.

Purpose: Connects this product to the practice and bot training ecosystem.

Troubleshooting: If bots do not fight correctly, test the profile directly in TrainingBot before testing the external bridge.

1. Install TrainingBot and its runtime requirements when bot fights are used.
2. Create at least one saved bot profile and kit.
3. Enable the hook from the practice or combat plugin config.
4. Start one bot duel or bot spawn test and verify movement, attacks and cleanup.

Purpose: Connects this product to another Nexa plugin so team, chat, combat, shop or vault state can be reused.

Troubleshooting: If the Nexa bridge does not react, confirm both plugin versions are compatible and that the shared module/hook is enabled on the same server.

1. Install both Nexa plugins on the same server or network target.
2. Confirm both products load successfully before testing the bridge.
3. Enable the related hook or module in config when available.
4. Test the shared workflow, such as team checks, chat metadata, combat restrictions, shop transactions or vault access.

/forcetag <player> [opponent] [duration] [cause] · /forceuntag <player> · /combat status

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. A tag starts only for valid damage and records the correct cause.
2. A forced recovery clears UI, restrictions, storage state and opponent references.
3. A reconnect cannot duplicate or resurrect an expired session.

/combat recap <player|id> timeline · /combat evidence <player|id> export

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. Cancelled/zero damage does not create a false tag.
2. Ignored projectiles never create reward credit.
3. Recap source labels match the actual damage source after delayed explosions.

/combatui · /combatui on · /combatui off

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. Normal, protected, bypass and bounty players see the correct state.
2. Other scoreboard/bossbar plugins do not overwrite NexaCombat output.
3. UI visibility persists correctly through reload and reconnect.

/combat debug · /combat evidence list · /combat recap

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. Punishment happens once and is linked to the combatlog record.
2. Full inventory, armor and offhand are recoverable where configured.
3. A corpse/ghost cleanup does not delete items during restart or timeout.

/combat debug · /combat evidence <player|id> gui

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. Each item is accessible to exactly the configured roles.
2. Saved items restore once and leftovers follow the configured policy.
3. Corpse GUI/chest access and protection messages match the permission matrix.

/combat profile · /combat reload · /combat debug

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. The rule blocks only the intended scope and reports a clear message.
2. Bypass works for staff without disabling unrelated protection.
3. A malformed material/enchantment/command entry produces a safe validation warning.

/combat region [player] · /combat worlds

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. Region resolution matches WorldGuard priority.
2. Teleport, portal, pearl and world-change restrictions follow the intended escape policy.
3. Bypass accounts can test safely without granting normal players a bypass.

/combat oldpvp · /combat knockback

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. Use one fixed kit and compare normal, sprint, critical, projectile and explosion hits.
2. Test with competing combat/knockback listeners disabled first.
3. Restart after GUI edits and confirm the saved profile is active.

/togglepvp · /pvp · /grace status · /grace give <player> <duration> · /grace remove <player> · /grace disable

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. Protection cannot be used to farm or trap other players.
2. Bounty/forced-combat rules resolve against protection exactly as documented.
3. Placeholders and UI show the true PvP/protection state.

/bounty create <player> [amount] [anonymous] · /bounty list · /bounty info <player> · /bounty compass <player> · /bounty remove <id>

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. Invalid amounts do not change balances.
2. A bounty target cannot be claimed twice for one kill.
3. Forced combat/PvP enable does not bypass an explicitly protected staff/test account.

/combat stats · /combat points · /combat assist · /combat resetstats <player>

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. One kill produces each configured reward exactly once.
2. Assists do not replace or duplicate killer payout.
3. Debt prevention and unavailable economy providers fail safely.
4. Kills, deaths, combatlogs, KD, streaks, assists and points survive restart.

/combat ranking · /combat season start <id> <duration> · /combat season end · /combat season top · /combat reputation <player>

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. A disabled/deleted mode does not silently erase rating history.
2. Season end freezes or archives records as configured.
3. Ranking output remains correct after storage reconnect.
4. Reputation tier and LuckPerms context agree with the stored score.

/sellhead · /deathback · /combat trophies

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. Only valid trophy metadata pays Vault currency.
2. DeathBack expires/clears once and respects disabled worlds.
3. Inventory-full, world-change and restart paths are recoverable.

/combat recap <player|id> [gui] · /combat recap list [player] [gui] · /combat recap <id> export · /combat evidence <player|id> gui · /combat evidence list [filter] gui

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. Recap, evidence and replay ids point to the same fight.
2. Risk flags are explainable and not based on missing data.
3. Staff can review without granting normal players evidence/delete permissions.

/combat antifarm <player> · /combat cleanup <player>

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. Fair kills are not blocked by a missing optional relation hook.
2. Cleanup detects third-party kills and applies the configured warning/resistance/action.
3. Staff report includes enough evidence to explain the decision.

/combat recap <player|id> replay · /combat recap replay <id> · /combat recap recordings · /combat heatmap

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. Playback never changes the live world.
2. Replay finalization handles terrain timeout and per-tick block budget.
3. Binary files are retained/cleaned as configured and heatmap storage does not grow without limit.

/combat reload · /combat oldpvp · /combat knockback · /combat debug

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. GUI output and YAML value agree after reconnect.
2. A broken menu item does not block unrelated admin menus.
3. Permission-gated editors cannot be opened by normal players.

/combat reload · /combat debug · /combat status

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. Database reconnect does not duplicate or lose a session.
2. A backend shutdown clears stale locks after the configured window.
3. Proxy transfer does not create duplicate tags or reward claims.

/combat debug · /combat region [player] · /combat status

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. Missing optional plugins never prevent NexaCombat from enabling.
2. API consumers handle nullable services and plugin disable safely.
3. Player/world operations run on the correct server scheduler.

/combat status · /combat debug · /combat reload

Give command access through the smallest matching permission and verify the output as a normal player, staff account and bypass account where applicable.

1. Normal, protected, tagged, disconnected and multi-attacker accounts all behave correctly.
2. One kill creates one recap/evidence/reward result.
3. Replay cannot modify the live world and network locks recover after backend shutdown.
4. Rollback points exist for config, database, evidence and replay directories.

webhooks:
  enabled: false
  timeout-seconds: 8
  rate-limit: 2s
  max-queue: 100
  retry:
    enabled: true
combat-heatmap:
  enabled: true
  retention: 30d

• Queue overflow must drop or reject according to the configured policy, never freeze the combat thread.
• Retries must not duplicate a payout or punishment event.
• Remove player-sensitive fields that the receiving endpoint does not need.
• Review status counters after endpoint recovery and plugin restart.

Confirm the damage event is not cancelled by spawn protection, WorldGuard, claims or another PvP plugin. Test outside safezones with two non-op players and check combat module toggles.

Check the punishment mode, quit listener, bypass permissions and whether the player is still tagged at disconnect time. Test with a real disconnect, not only /kick.

Verify the exact WorldGuard region name, region priority and hook toggle. Also confirm your safezone action is enabled for entry, exit or damage as expected.

Confirm Vault/economy provider is loaded, reward rules match the kill context and anti-farm did not block the kill. Check console for transaction failures.

Review same-player, same-IP, cooldown and alt-detection limits. Increase thresholds if normal repeated fights are being blocked.

Confirm Citizens is installed when NPC/corpse features are enabled, then check disabled worlds, cleanup timers and skin/pathfinder console warnings.

Check server version compatibility, module toggles and whether another combat plugin modifies attack cooldown, knockback or shield behavior later in the event chain.