diff --git a/.idea/ReanimateMC.iml b/.idea/ReanimateMC.iml
index 3cf00db..bbeeb3e 100644
--- a/.idea/ReanimateMC.iml
+++ b/.idea/ReanimateMC.iml
@@ -5,6 +5,7 @@
PAPER
+ ADVENTURE1
diff --git a/.idea/jarRepositories.xml b/.idea/jarRepositories.xml
index dfa4d4a..a264e1a 100644
--- a/.idea/jarRepositories.xml
+++ b/.idea/jarRepositories.xml
@@ -11,35 +11,25 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
-
-
-
+
+
+
-
-
-
+
+
+
@@ -56,5 +46,25 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..b4644bc
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,423 @@
+# Changelog
+
+All notable changes to ReanimateMC are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [1.2.13] — Unreleased
+
+### Bug Fixes
+
+#### Build
+
+- `plugin.yml` used `${project.version}` as a literal string because Maven resource
+ filtering was not enabled. Added `true`
+ to `pom.xml`; the JAR now shows the real version in all log messages and
+ `/rmc version` output.
+
+#### K.O. System — Movement & Input
+
+- **ArmorStand mount removed.** The previous implementation seated KO'd players
+ on an invisible `ArmorStand` to prevent movement. On Bedrock Edition, any
+ passenger relationship shows the dismount UI and maps the crouch button to
+ "dismount" rather than "crouch", which caused immediate auto-cancellation of
+ every surrender attempt and displayed a ride icon the player never requested.
+ The mount is replaced by `event.setTo()` cancellation in `PlayerMoveEvent`,
+ which blocks horizontal movement and vertical jumps server-side with no
+ client-side side-effects on either platform.
+
+- **Prone animation.** `player.setSwimming(true)` is called on KO entry
+ regardless of crawl state, so the player renders horizontal ("lying down")
+ on both Java Edition and Bedrock Edition.
+
+- **Jump blocking in crawl mode.** When `prone.allow_crawl` is enabled,
+ horizontal movement is permitted but upward velocity is cancelled unless
+ `prone.crawl_allow_jump` is set to `true` (new config key, default `false`).
+
+- **Surrender cancel while crawling.** The surrender timer was not cancelled by
+ movement when crawl mode was active because the movement handler skipped the
+ cancel check in the crawl branch. The check is now present in all three
+ movement branches (full-lock, movement-allowed, crawl).
+
+- **Surrender cancel message always shown.** The 3-second throttle previously
+ covered both the cancel message and the distress signal, so rapid triggers
+ silenced the message. The message is now sent unconditionally on every
+ cancel; only the distress signal is throttled.
+
+- **Repeated sneak-down events in crawl mode.** The swim state generated
+ repeated `PlayerToggleSneakEvent(isSneaking=true)` events while crawling,
+ restarting the surrender timer repeatedly. The handler now ignores sneak-down
+ events when a surrender task is already running.
+
+- **Bedrock surrender cancel.** On Bedrock, `sneak-up` does not fire while
+ the player is in swim-crawl pose because the crouch button is also the
+ "stop crawling" input. Three additional cancel triggers were added:
+ - `PlayerDropItemEvent` (Q / drop button) — primary Bedrock cancel method;
+ always fires reliably via Geyser and is the most natural action for a
+ downed Bedrock player.
+ - `PlayerInteractEvent(RIGHT_CLICK_AIR)` with empty main hand — tap on empty
+ space.
+ - `PlayerAnimationEvent(ARM_SWING)` — any tap gesture; does not send
+ a distress signal to avoid noise.
+
+#### K.O. System — Mob Targeting
+
+- `KOProtectionListener.onEntityTarget` prevented mobs from retargeting a KO'd
+ player but did not stop mobs that already had the player targeted before
+ they went down. Added `EntityDamageByEntityEvent` handler that cancels
+ melee damage from any `Mob` and projectile damage where the shooter is a
+ `Mob`, then clears the mob's target in both cases.
+
+#### NPC System
+
+- **PROTECTOR immortal at 0 HP.** `applyTransferredDamage` floored health at
+ 0.5 using `Math.max(0.5, hp - absorbed)`. Changed to `entity.damage(absorbed)`
+ so Bukkit processes the death event normally and `NPCDamageListener` handles
+ cleanup.
+
+- **Self-damage when stuck.** Iron Golems deal ENTITY_ATTACK damage to
+ themselves when pathfinding traps them against a wall. `NPCDamageListener`
+ now cancels any `EntityDamageByEntityEvent` where the damager UUID matches
+ the victim (the golem hitting itself) and cancels friendly-fire between
+ allied golems.
+
+- **`ConcurrentModificationException` in behavior task.** The scheduler task
+ iterated `activeNPCs.entrySet()` directly while `removeNPC()` mutated the
+ map. Replaced with a snapshot copy before the loop; expired entries are
+ collected in a separate list and removed after iteration completes.
+
+- **`IllegalArgumentException: x not finite` in `ProtectorBehavior`.** The
+ knockback burst called `normalize()` on a zero-length vector when an entity
+ occupied the exact same XZ position as the golem. A guard now skips any
+ entity where both X and Z delta are zero.
+
+- **PROTECTOR reviving owner.** `updateBehavior()` applied the owner-KO revive
+ path to all NPC types unconditionally. Added `canReviveOwner()` to
+ `NPCBehavior`; PROTECTOR returns `false`. The path is now gated behind this
+ check and also behind a live check for an active HEALER NPC when
+ `protector.revive_if_no_healer` is enabled.
+
+- **NPC persistence ignoring elapsed offline time.** `NPCPersistenceManager`
+ saved remaining seconds at shutdown time, then restored that same value
+ on startup regardless of how long the server was down. Changed to save
+ absolute expiry timestamps (epoch ms). On load, entries whose timestamp
+ has already passed are discarded; survivors have their remaining seconds
+ computed from the delta between the timestamp and `System.currentTimeMillis()`.
+
+- **HEALER heal timer unreliable.** Heal interval was checked against the raw
+ `behaviorTick` counter (increments every second). If the interval was not
+ a multiple of the idle-tick cadence (3 s), the heal could be skipped
+ indefinitely. Fixed with a dedicated `idleTick` counter incremented only
+ inside `onIdleTick()`.
+
+- **HEALER particles invisible at full HP.** Particles were gated behind
+ `health < max`. Particles now always spawn on each heal tick so players
+ can see the aura range.
+
+- **`EntityKnockbackEvent` wrong package.** Used Bukkit's deprecated
+ `org.bukkit.event.entity.EntityKnockbackEvent` which has no `setKnockback()`.
+ Changed to `io.papermc.paper.event.entity.EntityKnockbackEvent`.
+
+- **`PlayerJumpEvent` does not exist in Paper 1.21.4.** Handler removed;
+ Y-velocity check in `PlayerMoveEvent` covers both Java and Bedrock jump
+ detection.
+
+- **`api-version: 1.20` rejected by Paper 1.21+.** Corrected to `1.21`.
+
+- **`GolemManager` random type and wrong summon target.** Shift-click on a
+ natural Iron Golem picked a random type and passed the owner as the revive
+ target (which was never KO'd). Now resolves the highest-tier type the
+ player is permitted and passes `null` as the explicit target.
+
+- **Permission namespace typo** `reanimate.summon` → `reanimatemc.summon`
+ throughout `NPCSummonManager` and `ReanimateMCCommand`.
+
+- **Duplicate `ReanimateMCCommand` instance.** `setExecutor` and
+ `setTabCompleter` each constructed a new instance. A single shared instance
+ is now registered for both.
+
+- **Config new keys not merged into existing files.** Added
+ `copyDefaults(true)` + `saveConfig()` on startup and `/rmc reload`.
+
+- **Lang new keys not merged into existing translations.** `Lang.java`
+ rewritten to use `setDefaults` + `copyDefaults(true)`; falls back to `en`
+ for any missing key; never overwrites existing translations.
+
+- **Duplicate `config_reloaded` key** in `kr.yml` and `pt.yml`. First
+ duplicate removed.
+
+- **Paper 1.21.4 particle renames.**
+ `VILLAGER_HAPPY` → `HAPPY_VILLAGER`,
+ `SMOKE_LARGE` → `LARGE_SMOKE`,
+ `EXPLOSION_LARGE` → `EXPLOSION_EMITTER`.
+
+- **`reanimatemc.config` and `reanimatemc.removeglow` missing from
+ `plugin.yml`.** Both nodes added.
+
+#### Commands
+
+- **`removeGlowingEffect` command not found.** The switch case matched
+ `removeglowingreffect` (double `r`) but the tab-complete list contained
+ `removeGlowingEffect`, so the command was never routed correctly.
+ All three variants now match in both the switch and the tab-complete list.
+
+- **`/selfrevive` reported as unknown command.** The subcommand was handled
+ inside the `reanimatemc` switch but not registered as a standalone command
+ in `plugin.yml`. Added `selfrevive` and `cancelselfrevive` as first-class
+ commands with `sr` / `cancelsr` aliases; both are registered in
+ `ReanimateMC.java` with the shared `commandHandler`.
+
+### Added
+
+#### NPC Reanimator System
+
+A full autonomous NPC system built on Iron Golems. Three types share a common
+`NPCBehavior` strategy interface so each type is fully isolated.
+
+##### GOLEM — Standard Reanimator
+
+Follows owner, revives on K.O., defends from any attacker (not limited to
+`instanceof Monster`).
+
+Default HP: 80. Default revive time: ~5 s (100 ticks).
+
+##### HEALER — Support Reanimator
+
+All GOLEM capabilities plus: auto-scans for nearby K.O.'d allies within
+`scan_radius` and rushes to the nearest one without manual assignment.
+Periodic HP restoration every `periodic_heal_interval` seconds to the owner,
+nearby allies, itself (`heal_self`), and allied golems (`heal_golems`).
+Circular HEART + HAPPY_VILLAGER particle aura on each heal tick (configurable
+radius and toggle). Regeneration potion when owner HP drops below
+`aura_hp_threshold`. Bonus HP granted on revive.
+
+Default HP: 120. Default revive time: ~3 s (60 ticks — fastest).
+
+##### PROTECTOR — Tank Reanimator
+
+Does not revive or heal. Intercepts 75% of every hit the owner takes
+(`damage_transfer_ratio`, configurable) and applies that damage to the
+golem's own HP via `entity.damage()`. Attacks any `LivingEntity` threatening
+the owner; allied Iron Golems are excluded from targeting. When the owner
+falls K.O., sends a forced distress signal on their behalf and notifies them
+once per session that the PROTECTOR cannot revive. Optionally revives the
+owner when no HEALER is active (`revive_if_no_healer`, default `true`).
+
+Default HP: 200. Default revive time when fallback-reviving: ~8 s (160 ticks).
+
+##### Shared NPC Features
+
+- All HP values configurable per type via `npc_summon..max_hp`.
+- Per-type summon cost (`summon_cost`) deducted via Vault on summon.
+- Per-type cooldown and lifetime.
+- LuckPerms lifetime overrides via `reanimatemc.summon.lifetime..`.
+- Timed revive with live action-bar progress bar (10-segment, percentage) shown
+ to both the KO'd player and the NPC owner.
+- Nameplate shows owner name: `✦ Healing Golem [PlayerName] | ❤ 87 | ⏱ 8m32s`.
+ Color shifts green → yellow → red by HP percentage.
+- Stuck detection: if the NPC does not move more than 0.5 blocks in
+ `stuck_ticks_threshold` ticks while following, it teleports next to the owner
+ with PORTAL particles.
+- Persistence across restarts via `NPCPersistenceManager` using absolute expiry
+ timestamps.
+- `/rmc summon [player]` — when `[player]` is specified the NPC belongs
+ to that player; the summoner pays the cost and cooldown.
+- `/rmc summon team ...` — summons one NPC per team member;
+ total cost = `summon_cost * team.size()`.
+- `/rmc dismiss ` — dismiss by type or all at once.
+- `/rmc npcs` — per-NPC action-bar status with HP bar, countdown, and target name.
+- `/rmc extend ` — extend lifetime; charges Vault economy cost.
+
+#### Self-Revive System (`/rmc selfrevive`, alias `/sr`)
+
+KO'd players can revive themselves at the cost of items and a longer channel
+time. Every aspect is configurable:
+
+- `require_items` — whether items are consumed (default `true`).
+- `required_items` — list of `{material, amount}` entries; all must be present.
+ Default: 2× Golden Apple.
+- `duration_ticks` — channel time (default 200, ~10 s).
+- `health_restored` — HP after self-revive (default 2).
+- `cooldown_seconds` — per-player cooldown (default 120).
+- `max_uses_per_ko` — limit per KO session, 0 = unlimited (default 1).
+- `cancel_on_move` / `cancel_on_damage` — interrupt on movement or incoming hit.
+- `combat_block_seconds` — block use if last damage was within this window.
+- `effects_on_selfrevive` — separate post-revive effect set, harsher than
+ teammate revive defaults.
+
+`/rmc cancelselfrevive` (alias `/cancelsr`) cancels an active channel.
+
+#### Distress Signal Rework
+
+Four independent triggers, all respecting the same per-player cooldown and
+`reanimatemc.distress` permission:
+
+| Trigger | Platform | Config key |
+|---|---|---|
+| F (swap hands) | Java Edition | always active |
+| Q / drop button | Java + Bedrock mobile | `knockout.distress.drop_key_trigger` |
+| Double-tap sneak | Bedrock + Java | `knockout.distress.bedrock_doubletap_ms` |
+| `/rmc distress` | All | `knockout.allowed_commands` (pre-added) |
+
+When the player cancels a surrender by releasing the crouch button, a distress
+signal is automatically sent on their behalf, so teammates are notified whenever
+someone chooses to fight on.
+
+The PROTECTOR NPC sends a forced distress signal (bypassing the player cooldown)
+the first time the owner falls K.O. per session.
+
+#### Command Improvements
+
+`/rmc` with no arguments now shows a structured status panel:
+
+```
+━━━━━━━━━ ReanimateMC ━━━━━━━━━
+ Version v1.2.13 | API 1.21.4 | Author Jachou
+ Language en
+ ─── Systems ───────────────────
+ K.O. System ✔
+ Execution System ✔
+ Crawl / Prone ✔
+ Distress Signal ✔
+ Self-Revive ✔
+ NPC Reanimators ✔
+ ─── Integrations ──────────────
+ Vault Economy ✘
+ PlaceholderAPI ✔
+ ─── Live Status ───────────────
+ Players currently K.O.: 0
+ Type /rmc help for all commands
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+`/rmc help` reads all descriptions from the active language file; no English
+is hardcoded. `/rmc version` shows plugin version, author, Minecraft version,
+and API target.
+
+#### New Permissions
+
+| Permission | Default | Purpose |
+|---|---|---|
+| `reanimatemc.summon` | false | Base summon permission |
+| `reanimatemc.summon.use.golem` | false | GOLEM type (requires base) |
+| `reanimatemc.summon.use.healer` | false | HEALER type (requires base) |
+| `reanimatemc.summon.use.protector` | false | PROTECTOR type (requires base) |
+| `reanimatemc.distress` | true | Distress signal |
+| `reanimatemc.selfrevive` | true | Self-revive |
+| `reanimatemc.summon.overridecost` | op | Bypass cooldowns and economy costs |
+| `reanimatemc.summon.admin` | op | Manage other players' NPCs |
+
+#### PlaceholderAPI Integration
+
+New expansion prefix `%reanimatemc_*%`:
+
+- `%reanimatemc_is_ko%`
+- `%reanimatemc_ko_time_remaining%`
+- `%reanimatemc_npc_count%`
+- `%reanimatemc_npc_type%`
+- `%reanimatemc_npc_time_remaining%`
+- `%reanimatemc_npc_hp%`
+
+#### ConfigGUI Additions
+
+- Three new K.O. toggles: Mobs Attack KO, Disable Knockback on KO,
+ Must Be Still to Surrender.
+- New `DOUBLE` option type (Comparator icon, left-click −0.05 / shift-click +0.05).
+- New entries: Crawl Nausea Effect, Crawl Nausea Level, NPC System on/off,
+ NPC Invulnerable Mode, Protector Damage Transfer ratio,
+ Protector Revives (No Healer).
+
+#### New Configuration Keys
+
+All keys ship with documented inline comments in `config.yml`. A QUICK
+REFERENCE block at the top of the file explains effect levels, duration
+fields, and the distress subsection.
+
+Highlights:
+
+```yaml
+knockout:
+ crawl_nausea_enabled: true
+ crawl_nausea_level: 1
+
+ distress:
+ enabled: true
+ cooldown_seconds: 15
+ drop_key_trigger: true
+ bedrock_doubletap_ms: 400
+
+prone:
+ crawl_allow_jump: false
+
+self_revive:
+ enabled: true
+ require_items: true
+ required_items:
+ - material: GOLDEN_APPLE
+ amount: 2
+ duration_ticks: 200
+ health_restored: 2
+ cooldown_seconds: 120
+ max_uses_per_ko: 1
+ cancel_on_move: true
+ cancel_on_damage: true
+ combat_block_seconds: 0
+ effects_on_selfrevive:
+ nausea: 10
+ slowness: 15
+ resistance: 5
+
+npc_summon:
+ golem:
+ max_hp: 80
+ revive_duration_ticks: 100
+ combat_radius: 12.0
+ summon_cost: 0.0
+ healer:
+ max_hp: 120
+ revive_duration_ticks: 60
+ heal_self: true
+ heal_golems: true
+ aura_particle_enabled: true
+ aura_particle_radius: 3
+ protector:
+ max_hp: 200
+ revive_duration_ticks: 160
+ damage_transfer_ratio: 0.75
+ revive_if_no_healer: true
+```
+
+#### New Files
+
+| File | Description |
+|---|---|
+| `behavior/NPCBehavior.java` | Strategy interface: `onIdleTick`, `onSpawn`, `onRevive`, `canRevive`, `canReviveOwner` |
+| `behavior/GolemBehavior.java` | GOLEM implementation |
+| `behavior/HealerBehavior.java` | HEALER implementation |
+| `behavior/ProtectorBehavior.java` | PROTECTOR implementation |
+| `api/NPCSummonedEvent.java` | Cancellable summon event |
+| `api/NPCDismissedEvent.java` | Dismissal event with `Reason` enum |
+| `hooks/VaultHook.java` | Vault economy wrapper |
+| `hooks/PlaceholderHook.java` | PlaceholderAPI expansion |
+| `listeners/KOProtectionListener.java` | Knockback zeroing + mob targeting + projectile protection |
+| `listeners/NPCDamageListener.java` | NPC self-damage prevention, low-HP alerts, death cleanup |
+| `managers/NPCPersistenceManager.java` | YAML persistence with absolute expiry timestamps |
+| `data/ReanimatorNPC.java` | NPC state record (LICENSE header) |
+| `managers/NPCSummonManager.java` | NPC orchestration (LICENSE header) |
+| `CLAUDE.md` | Development context document |
+
+### Language Files
+
+`en.yml` and `es.yml` have full translations for all new keys.
+`de.yml`, `fr.yml`, `it.yml`, `ru.yml`, `zh.yml`, `kr.yml`, and `pt.yml`
+have been updated with English fallback strings marked
+`# EN — awaiting translation`. The plugin's `Lang.java` `copyDefaults(true)`
+mechanism ensures existing translations are never overwritten.
+
+---
+
+## [1.2.10] — Previous Release
+
+See the [GitHub releases page](https://github.com/MatisseAD/ReanimateMC/releases)
+for earlier versions.
diff --git a/README.md b/README.md
index 184ae70..c017d7c 100644
--- a/README.md
+++ b/README.md
@@ -1,530 +1,527 @@
# ReanimateMC
-New wiki page : https://matissead.github.io/ReanimateMC/
+New wiki page: https://matissead.github.io/ReanimateMC/
-
-
-
+
+
+
## Table of Contents
- [Overview](#overview)
-- [Features](#features)
+- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Commands](#commands)
- [Permissions](#permissions)
-- [Gameplay Mechanics](#gameplay-mechanics)
+- [K.O. System](#ko-system)
+- [NPC Reanimator System](#npc-reanimator-system)
+- [Self-Revive System](#self-revive-system)
+- [Distress Signal](#distress-signal)
- [API for Developers](#api-for-developers)
- [Language Support](#language-support)
- [Compatibility](#compatibility)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
+---
+
## Overview
-ReanimateMC is a revolutionary Minecraft plugin that transforms the conventional death system by introducing a **KO (Knockout) state**. Instead of players dying instantly when their health reaches zero, they enter an intermediary knockout state where they can be revived by teammates or executed by enemies.
+ReanimateMC replaces instant death with a K.O. (Knockout) state. When a player's
+health reaches zero they enter a downed state where teammates can revive them,
+enemies can execute them, or a timer forces death. Version 1.2.13 adds a full
+NPC Reanimator System, a configurable self-revive mechanic, and reworks the
+distress signal for both Java Edition and Bedrock mobile.
-This innovative mechanic creates dynamic gameplay opportunities perfect for:
-- **Hardcore Survival servers** - Adding tension and teamwork
-- **Role-play servers** - Creating dramatic rescue scenarios
-- **PvP servers** - Strategic decisions between mercy and execution
-- **Adventure maps** - Enhanced cooperative gameplay
+---
-
+## Requirements
-## Features
+- **Server:** Paper 1.21.4 or higher (Paper required for NPC pathfinder API and `EntityKnockbackEvent`)
+- **Java:** 17 or higher
+- **Optional:** Vault + economy plugin, PlaceholderAPI, LuckPerms
-### Core Mechanics
-- **KO State System** - Players enter knockout instead of dying instantly
-- **Revival System** - Teammates can revive KO'd players with configurable items
-- **Execution System** - Option to permanently eliminate KO'd players
-- **Persistent KO** - KO state maintained across disconnections
-- **Distress Signals** - KO'd players can call for help with beacons
+---
-### Gameplay Features
-- **Crawling Mode** - KO'd players can toggle between immobilized and slow crawling
-- **Visual Effects** - Particles, blindness, and glowing effects during KO
-- **Audio Feedback** - Heartbeat sounds and audio cues
-- **Tab List Integration** - Visual KO indicators in player list
-- **Inventory Protection** - Configurable looting system for KO'd players
+## Installation
-### Advanced Features
-- **Offline KO Timer** - Countdown continues even when players disconnect
-- **Suicide Prevention** - Configurable hold-to-suicide mechanics
-- **Weakness Effects** - Debuffs applied during KO state
-- **GUI Configuration** - In-game configuration interface
-- **Statistics Tracking** - KO and revival statistics
-- **Multi-language Support** - 10+ language translations
+1. Drop `ReanimateMC.jar` into `plugins/`.
+2. Restart the server.
+3. Edit `plugins/ReanimateMC/config.yml` or use `/rmc config` to open the GUI.
-## Installation
+---
-### Requirements
-- **Minecraft Server**: 1.20.1 or higher
-- **Server Software**: Spigot, Paper, Bukkit, or compatible forks
-- **Java**: 16 or higher
+## Quick Start
-### Installation Steps
+```
+/rmc config open the in-game configuration GUI
+/rmc reload reload config and lang files without restart
+/rmc help list all commands in the active language
+/rmc summon golem summon a GOLEM reanimator for yourself
+/rmc summon healer summon a HEALER reanimator for yourself
+/rmc summon protector summon a PROTECTOR reanimator for yourself
+/rmc selfrevive revive yourself while K.O.'d (uses items)
+```
-1. **Download** the latest ReanimateMC.jar from the [releases page](https://github.com/MatisseAD/ReanimateMC/releases)
+---
-2. **Upload** the JAR file to your server's `plugins/` directory
+## Configuration
-3. **Restart** your server (or use a plugin manager to load it)
+All settings live in `plugins/ReanimateMC/config.yml`. A `QUICK REFERENCE`
+block at the top of the file explains effect levels, duration fields, and the
+distress subsection. New keys are automatically merged into existing files on
+startup and `/rmc reload`; your existing values are never overwritten.
-4. **Configure** the plugin using the command `/reanimatemc config` or by editing the generated config files
+### Key Sections
-### First Setup
+| Section | What it controls |
+|---|---|
+| `language` | Active lang file (`en`, `es`, `de`, `fr`, `it`, `nl`, `ru`, `zh`, `kr`, `pl`, `pt`) |
+| `reanimation` | Item requirement, hold duration, HP restored, cooldown |
+| `knockout` | Duration, movement lock, effects, surrender, mobs, distress |
+| `execution` | Toggle, hold duration, broadcast |
+| `effects_on_revive` | Temporary effects applied after revival (seconds) |
+| `prone` | Crawl toggle, slowness level, auto-crawl, jump blocking |
+| `self_revive` | Item list, channel time, cooldown, cancel conditions |
+| `npc_summon` | Per-type HP, lifetime, cooldown, cost, heal amounts, revive speed |
-When you first install the plugin:
+---
-1. Operators will receive a setup message on join
-2. Use `/reanimatemc config` to open the GUI configuration
-3. Adjust settings to match your server's gameplay style
-4. Use `/reanimatemc setup` to mark setup as complete
+## Commands
-## Quick Start
+All commands run via `/rmc` or `/reanimatemc`.
-### Basic Usage
+### Player Commands
-1. **When a player's health reaches 0**, they enter KO state instead of dying
-2. **To revive**: Crouch near a KO'd player and hold the required item (default: Golden Apple)
-3. **To execute**: Left-click and hold on a KO'd player
-4. **Distress signal**: KO'd players can press F (swap hands) to send a help signal
+| Command | Permission | Description |
+|---|---|---|
+| `/rmc help` | — | List all commands in the active language |
+| `/rmc status ` | `reanimatemc.status` | Check K.O. state |
+| `/rmc crawl` | `reanimatemc.crawl` | Toggle crawl while K.O.'d |
+| `/rmc distress` | `reanimatemc.distress` | Send a distress signal while K.O.'d |
+| `/rmc selfrevive` | `reanimatemc.selfrevive` | Revive yourself using items |
+| `/rmc cancelselfrevive` | `reanimatemc.selfrevive` | Cancel an active self-revive channel |
+| `/rmc revive ` | `reanimatemc.revive` | Start a timed revive via your active HEALER NPC |
+| `/rmc summon [player]` | `reanimatemc.summon.use.` | Summon a Reanimator NPC |
+| `/rmc summon team ...` | `reanimatemc.summon.use.` | Summon one NPC per team member |
+| `/rmc dismiss ` | `reanimatemc.summon` | Dismiss NPC(s) |
+| `/rmc extend ` | `reanimatemc.summon` | Extend active NPC lifetime |
+| `/rmc npcs` | `reanimatemc.summon` | Show HP, countdown, and target for active NPCs |
+
+Aliases: `/sr` = `/rmc selfrevive`, `/cancelsr` = `/rmc cancelselfrevive`.
+
+### Admin Commands
-### Essential Commands
+| Command | Permission | Description |
+|---|---|---|
+| `/rmc reload` | `reanimatemc.admin` | Reload config and lang |
+| `/rmc knockout ` | `reanimatemc.knockout` | Force K.O. |
+| `/rmc kolist` | `reanimatemc.admin` | List K.O.'d players with time remaining |
+| `/rmc purge` | `reanimatemc.admin` | Remove stale K.O. holograms from all worlds |
+| `/rmc info` | `reanimatemc.admin` | Show plugin status and integration state |
+| `/rmc version` | `reanimatemc.admin` | Show plugin version |
+| `/rmc config` | `reanimatemc.config` | Open configuration GUI |
+| `/rmc removeGlowingEffect ` | `reanimatemc.removeglow` | Remove glow from a player |
-```
-/reanimatemc config # Open configuration GUI
-/reanimatemc reload # Reload plugin configuration
-/reanimatemc status # Check player's KO status
-```
+---
-## Configuration
+## Permissions
-The plugin creates several configuration files in `plugins/ReanimateMC/`:
+### Core
-### Main Configuration (`config.yml`)
+| Permission | Default | Description |
+|---|---|---|
+| `reanimatemc.revive` | true | Revive K.O.'d players |
+| `reanimatemc.execute` | true | Execute K.O.'d players |
+| `reanimatemc.status` | true | Check K.O. status |
+| `reanimatemc.crawl` | true | Toggle crawl while K.O.'d |
+| `reanimatemc.distress` | true | Send distress signals |
+| `reanimatemc.selfrevive` | true | Self-revive while K.O.'d |
+| `reanimatemc.bypass` | op | Die instantly, bypass K.O. |
+| `reanimatemc.knockout` | op | Force K.O. via command |
+| `reanimatemc.admin` | op | All admin commands |
+
+### NPC Summon
+
+`reanimatemc.summon` and all `summon.use.*` nodes default to `false`. Grant
+explicitly via a permission plugin. OPs always have access.
+
+| Permission | Default |
+|---|---|
+| `reanimatemc.summon` | false |
+| `reanimatemc.summon.use.golem` | false |
+| `reanimatemc.summon.use.healer` | false |
+| `reanimatemc.summon.use.protector` | false |
+| `reanimatemc.summon.overridecost` | op |
+| `reanimatemc.summon.admin` | op |
+
+**Recommended tier setup:**
```yaml
-# Language settings
-language: "en"
-first_run: true
-setup_completed: false
-
-# Revival system
-reanimation:
- require_special_item: true
- required_item: GOLDEN_APPLE
- duration_ticks: 100 # Time to revive (5 seconds)
- health_restored: 4 # Hearts restored after revival
- cooldown: 60 # Cooldown between revivals
- revive_cooldown: 60 # Personal revive cooldown
-
-# KO system settings
-knockout:
- enabled: true
- duration_seconds: 30 # How long KO lasts
- movement_disabled: true # Disable movement during KO
- use_particles: true # Show particles around KO'd players
- heartbeat_sound: true # Play heartbeat sound
- blindness: true # Apply blindness effect
- suicide_hold_seconds: 3 # Hold time to suicide
- weakness_level: 1 # Weakness effect level
- fatigue_level: 1 # Mining fatigue level
-
-# Execution system
-execution:
- enabled: true
- hold_duration_ticks: 40 # Hold time to execute (2 seconds)
- message_broadcast: true # Announce executions
+# VIP
+reanimatemc.summon: true
+reanimatemc.summon.use.golem: true
+
+# Premium
+reanimatemc.summon: true
+reanimatemc.summon.use.golem: true
+reanimatemc.summon.use.healer: true
+
+# Elite
+reanimatemc.summon: true
+reanimatemc.summon.use.golem: true
+reanimatemc.summon.use.healer: true
+reanimatemc.summon.use.protector: true
+```
-# Effects applied after revival
-effects_on_revive:
- nausea: 5 # Nausea duration (seconds)
- slowness: 10 # Slowness duration (seconds)
- resistance: 10 # Resistance duration (seconds)
+**LuckPerms lifetime overrides** — grant
+`reanimatemc.summon.lifetime..` to override NPC lifetime per group.
+The highest value across all of a player's permissions wins.
-# Crawling/prone mechanics
-prone:
- enabled: true
- allow_crawl: true # Allow crawling movement
- crawl_slowness_level: 5 # Slowness level when crawling
- auto_crawl: false # Auto-enable crawling
+---
-# Inventory looting
-looting:
- enabled: true
+## K.O. System
-# Tab list integration
-tablist:
- enabled: true # Show [KO] tag in tab list
-```
+When a player's health reaches zero:
-### GUI Configuration
+1. Player enters K.O. state; health is set to 1.
+2. Player renders horizontal (prone animation) on both Java and Bedrock.
+3. Movement and jumping are blocked server-side (`movement_disabled: true`).
+4. Countdown begins (`knockout.duration_seconds`).
+5. Player can be revived, execute themselves (surrender), or die when the timer expires.
-Use `/reanimatemc config` to access an intuitive GUI for configuring all settings:
+### Revival
-- **Categories**: Settings organized by function
-- **Live Preview**: See changes immediately
-- **Easy Toggles**: Click to enable/disable features
-- **Value Editing**: Click to modify numeric values
-- **Material Selection**: Easy item selection interface
+A player reviving a teammate must crouch near them while holding the required
+item (`reanimation.required_item`). A progress bar appears in the action bar.
+Items are consumed on success. Post-revival effects (`effects_on_revive`) apply.
-## Commands
+When using `/rmc revive `:
-### Administrative Commands
+- The caller must have an active HEALER NPC.
+- The HEALER teleports to the target before the channel begins.
+- If `reanimation.require_special_item` is enabled, the caller must hold the item.
+- The target receives a notification naming the reviver.
-| Command | Permission | Description |
-|---------|------------|-------------|
-| `/reanimatemc reload` | `reanimatemc.admin` | Reload configuration and language files |
-| `/reanimatemc config` | `reanimatemc.admin` | Open GUI configuration interface |
-| `/reanimatemc setup` | `reanimatemc.admin` | Mark initial setup as complete |
+### Surrender
-### Player Management Commands
+Hold crouch for `knockout.suicide_hold_seconds` (default 3) to surrender.
+Any movement cancels the timer if `surrender_require_still` is enabled.
-| Command | Permission | Description |
-|---------|------------|-------------|
-| `/reanimatemc revive ` | `reanimatemc.revive` | Forcefully revive a KO'd player |
-| `/reanimatemc knockout ` | `reanimatemc.knockout` | Force a player into KO state |
-| `/reanimatemc status ` | `reanimatemc.status` | Check a player's current state |
-| `/reanimatemc crawl` | `reanimatemc.crawl` | Toggle crawling mode (KO'd players only) |
+To cancel on Bedrock (where sneak-up may not fire in prone state):
+- Press Q (drop button) — primary method
+- Tap empty space (RIGHT_CLICK_AIR with empty hand)
+- Any arm-swing gesture
-### Utility Commands
+Cancelling a surrender automatically sends a distress signal once.
-| Command | Permission | Description |
-|---------|------------|-------------|
-| `/reanimatemc removeGlowingEffect ` | `reanimatemc.removeGlowingEffect` | Remove glowing effect from a player |
+### Crawl Mode
-## Permissions
+Toggle with `/rmc crawl`. Allows slow horizontal movement while K.O.'d.
+Configurable slowness level (`prone.crawl_slowness_level`). Jump blocking
+is separate (`prone.crawl_allow_jump`, default `false`). Nausea applies only
+while crawl is active (`knockout.crawl_nausea_enabled`).
-### Core Permissions
+### Mob Protection
-| Permission | Default | Description |
-|------------|---------|-------------|
-| `reanimatemc.admin` | `op` | Access to all administrative commands and GUI config |
-| `reanimatemc.revive` | `true` | Ability to revive KO'd players |
-| `reanimatemc.execute` | `true` | Ability to execute KO'd players |
-| `reanimatemc.bypass` | `op` | Bypass KO system (die instantly) |
+When `knockout.mobs_attack_ko: false`, mobs cannot:
-### Feature Permissions
+- Select a K.O.'d player as a new target (`EntityTargetEvent`).
+- Deal melee damage to a K.O.'d player.
+- Hit a K.O.'d player with a projectile.
-| Permission | Default | Description |
-|------------|---------|-------------|
-| `reanimatemc.knockout` | `op` | Force players into KO state |
-| `reanimatemc.status` | `true` | Check player KO status |
-| `reanimatemc.crawl` | `true` | Toggle crawling mode when KO'd |
-| `reanimatemc.loot` | `op` | Access KO'd player inventories |
-| `reanimatemc.removeGlowingEffect` | `op` | Remove glowing effects |
+Mobs that were already targeting the player before K.O. have their target cleared.
-### Permission Groups
+---
+
+## NPC Reanimator System
+
+### Summoning
-```yaml
-# Example permission setup for different server roles
-
-# Regular Players
-- reanimatemc.revive
-- reanimatemc.execute
-- reanimatemc.status
-- reanimatemc.crawl
-
-# Moderators (add to above)
-- reanimatemc.knockout
-- reanimatemc.loot
-- reanimatemc.removeGlowingEffect
-
-# Administrators (add to above)
-- reanimatemc.admin
-- reanimatemc.bypass
+```
+/rmc summon golem [player]
+/rmc summon healer [player]
+/rmc summon protector
+/rmc summon team ...
```
-## Gameplay Mechanics
+When `[player]` is specified the NPC belongs to that player; the summoner pays
+the cost and cooldown. Team summon charges `summon_cost * team_size` via Vault.
+
+### Type Comparison
+
+| Feature | GOLEM | HEALER | PROTECTOR |
+|---|:---:|:---:|:---:|
+| Default HP | 80 | 120 | 200 |
+| Revives owner when K.O. | Yes | Yes | When no HEALER active |
+| Revives explicit target | Yes | Yes | No |
+| Auto-revives nearby K.O. allies | No | Yes | No |
+| Heals owner / allies | No | Yes | No |
+| Heals self / allied golems | No | Configurable | No |
+| Circular heal aura particles | No | Yes | No |
+| Defends owner (any attacker type) | Yes | No | Yes |
+| Absorbs owner damage | No | No | 75% (configurable) |
+| Sends distress on owner K.O. | No | No | Yes |
+| Default revive time | ~5 s | ~3 s | ~8 s |
+| Default summon cooldown | 5 min | 5 min | 1 min |
+
+All HP values are configurable via `npc_summon..max_hp`.
+All revive durations are configurable via `npc_summon..revive_duration_ticks`.
+
+### GOLEM — Standard Reanimator
+
+Follows the owner, revives them when K.O.'d, and defends against attackers.
+Targets whoever last dealt damage to the owner (any entity type) and falls back
+to the nearest hostile mob within `combat_radius`.
+
+### HEALER — Support Reanimator
+
+All GOLEM capabilities plus:
+
+- Scans `scan_radius` blocks for any K.O.'d ally and rushes to the nearest one
+ without manual assignment.
+- Heals HP every `periodic_heal_interval` seconds to the owner, nearby allies,
+ itself (`heal_self`), and allied Iron Golems (`heal_golems`). All amounts and
+ ranges are configurable.
+- Circular HEART + HAPPY_VILLAGER particle aura on every heal tick, always
+ visible regardless of current HP so players can see the range.
+- Applies Regeneration when the owner HP drops below `aura_hp_threshold`.
+- Grants bonus HP to the revived player (`bonus_hp_on_revive`).
+- The HEALER does not leave the owner more than `max_leash_distance` blocks away
+ even when chasing a K.O.'d ally.
+
+### PROTECTOR — Tank Reanimator
+
+- Cannot revive or heal anyone except as a fallback when no HEALER is active
+ (`revive_if_no_healer: true`).
+- Intercepts `damage_transfer_ratio` (default 75%) of every hit the owner takes
+ and applies it to the golem via `entity.damage()`. CRIT particles fire on impact.
+- Attacks any `LivingEntity` threatening the owner. Allied Iron Golems are
+ excluded from targeting.
+- When the owner falls K.O., sends a forced distress signal and notifies the
+ owner once per K.O. session that it cannot revive them.
+- Dies normally at 0 HP; record is cleaned up by `NPCDamageListener`.
+
+### Revive Progress Bar
-### The KO System
+```
+Healing Golem reviving... ██████░░░░ 65% <- shown to K.O.'d player
+Reviving PlayerName... ██████░░░░ 65% <- shown to NPC owner
+```
-When a player's health reaches zero:
+### Nameplate Format
-1. **KO Trigger**: Player enters knockout state instead of dying
-2. **Visual Effects**: Player lies down, optional particles and blindness
-3. **Movement**: Immobilized or limited crawling based on configuration
-4. **Timer**: Countdown begins (configurable duration)
-5. **Options**: Can be revived, executed, or will die when timer expires
+```
+✦ Iron Golem Reanimator [PlayerName] | ❤ 67 | ⏱ 8m32s
+```
-### Revival Process
+HP color shifts green (> 50%) → yellow (> 25%) → red.
+Nameplate updates every 2 seconds.
-**Requirements:**
-- Another player must crouch near the KO'd player
-- Reviver must hold the required item (default: Golden Apple)
-- Revival takes time (configurable, default 5 seconds)
-- Both players must remain still during revival
+### Persistence
-**Revival Effects:**
-- KO'd player regains health
-- Temporary effects applied (nausea, slowness, resistance)
-- Cooldown applied to prevent spam
+`NPCPersistenceManager` saves an absolute expiry timestamp for each active NPC
+on shutdown. On startup, entries whose timestamp has passed are discarded;
+survivors are restored with their correct remaining lifetime. Golems that
+expire while the owner is offline are never restored.
-### Execution System
+### Status and Management
-**Process:**
-- Any player can execute a KO'd player
-- Hold left-click for configured duration (default 2 seconds)
-- Optional broadcast message announces executions
-- Results in permanent death
+```
+/rmc npcs show HP bar, time, and target for all golems
+/rmc dismiss all dismiss all active NPCs
+/rmc dismiss healer dismiss only HEALERs
+/rmc extend 300 add 5 minutes (Vault cost if configured)
+```
-### Distress Signal System
+---
-**Activation:**
-- KO'd players press F (swap hands key)
-- Creates a beacon at their location
-- Broadcasts coordinates to nearby players
-- One-time use per KO
+## Self-Revive System
-### Offline KO Management
+KO'd players can revive themselves using items at the cost of a longer channel
+time than a teammate revive.
-**When KO'd players disconnect:**
-- KO state is saved to file
-- Timer continues counting down
-- Player dies if timer expires before reconnection
-- State restored when player reconnects
+### Flow
-### Crawling Mechanics
+1. Player runs `/rmc selfrevive` (or `/sr`).
+2. All preconditions are validated; failure sends a specific message.
+3. A progress bar appears in the action bar for `duration_ticks` ticks.
+4. On completion: items consumed, `revive()` called, `effects_on_selfrevive` applied.
+5. Any movement or incoming damage cancels the channel (if configured).
-**Two Movement States:**
-1. **Immobilized**: Complete movement restriction
-2. **Crawling**: Slow movement with heavy slowness effect
+### Configuration Reference
-**Controls:**
-- Use `/reanimatemc crawl` to toggle states
-- Configurable auto-crawl option
-- Separate permission for crawling ability
+```yaml
+self_revive:
+ enabled: true
+ require_items: true
+ required_items:
+ - material: GOLDEN_APPLE
+ amount: 2
+ duration_ticks: 200 # ~10 seconds
+ health_restored: 2
+ cooldown_seconds: 120
+ max_uses_per_ko: 1 # 0 = unlimited
+ cancel_on_move: true
+ cancel_on_damage: true
+ combat_block_seconds: 0 # 0 = disabled
+ effects_on_selfrevive:
+ nausea: 10
+ slowness: 15
+ resistance: 5
+```
-## API for Developers
+---
-ReanimateMC provides a comprehensive API for other plugins to integrate with the KO system.
+## Distress Signal
-### Events
+When sent, broadcasts the player's coordinates to all online players and places
+a glowing marker at their location. Respects `distress.cooldown_seconds` and
+`reanimatemc.distress` permission.
+
+### Triggers
+
+| Method | Platform | Config key |
+|---|---|---|
+| F key (swap hands) | Java | always active |
+| Q / drop button | Java + Bedrock | `distress.drop_key_trigger` |
+| Double-tap sneak | Bedrock + Java | `distress.bedrock_doubletap_ms` |
+| Cancelling surrender | All | automatic |
+| `/rmc distress` | All | pre-added to `allowed_commands` |
+
+The PROTECTOR NPC sends a forced distress signal (bypassing the player cooldown)
+the first time the owner falls K.O. in a session.
+
+---
-#### PlayerKOEvent
-Fired when a player enters KO state.
+## API for Developers
+
+### Events
```java
+// Fired when a player enters K.O. state — cancellable
@EventHandler
public void onPlayerKO(PlayerKOEvent event) {
Player player = event.getPlayer();
- int duration = event.getDuration();
-
- // Cancel the KO event
event.setCancelled(true);
-
- // Custom logic here
}
-```
-#### PlayerReanimatedEvent
-Fired when a player is revived from KO state.
-
-```java
+// Fired when a player is revived
@EventHandler
-public void onPlayerRevived(PlayerReanimatedEvent event) {
- Player player = event.getPlayer();
+public void onRevived(PlayerReanimatedEvent event) {
+ Player player = event.getPlayer();
Player reanimator = event.getReanimator();
- boolean successful = event.isSuccessful();
- long timestamp = event.getTimestamp();
-
- // Custom logic here
}
-```
-### API Access
+// Fired when an NPC is summoned — cancellable
+@EventHandler
+public void onNPCSummoned(NPCSummonedEvent event) {
+ ReanimatorNPC npc = event.getNPC();
+ event.setCancelled(true);
+}
+
+// Fired when an NPC is removed
+@EventHandler
+public void onNPCDismissed(NPCDismissedEvent event) {
+ ReanimatorNPC npc = event.getNPC();
+ NPCDismissedEvent.Reason why = event.getReason(); // MANUAL, EXPIRED, OFFLINE_TIMEOUT, PLUGIN_DISABLE
+}
+```
-Get the KOManager instance:
+### Programmatic Access
```java
-// Get the plugin instance
ReanimateMC plugin = (ReanimateMC) Bukkit.getPluginManager().getPlugin("ReanimateMC");
-// Access the KO manager
-KOManager koManager = plugin.getKoManager();
-
-// Check if player is KO'd
-boolean isKO = koManager.isKO(player);
-
-// Force KO a player
-koManager.setKO(player, 30); // 30 seconds
-
-// Revive a player
-koManager.revive(player, reviverPlayer);
-
-// Execute a player
-koManager.execute(player);
+KOManager ko = plugin.getKoManager();
+ko.isKO(player);
+ko.setKO(player);
+ko.revive(player, reviver);
+ko.sendDistress(player);
+ko.startSelfRevive(player);
+
+NPCSummonManager npc = plugin.getNpcSummonManager();
+npc.summon(player, ReanimatorNPC.ReanimatorType.HEALER, null);
+npc.dismissAll(player);
+npc.getPlayerSummons(player);
```
-### Dependency Setup
+### PlaceholderAPI
+
+| Placeholder | Returns |
+|---|---|
+| `%reanimatemc_is_ko%` | `true` / `false` |
+| `%reanimatemc_ko_time_remaining%` | seconds remaining |
+| `%reanimatemc_npc_count%` | number of active NPCs |
+| `%reanimatemc_npc_type%` | type name of first active NPC |
+| `%reanimatemc_npc_time_remaining%` | NPC lifetime remaining |
+| `%reanimatemc_npc_hp%` | NPC current HP |
-Add ReanimateMC as a dependency in your plugin.yml:
+### Dependency
+`plugin.yml`:
```yaml
-depend: [ReanimateMC]
-# or
softdepend: [ReanimateMC]
```
-Maven dependency:
-```xml
-
- fr.jachou
- ReanimateMC
- 1.2.12
- provided
-
-```
+---
## Language Support
-ReanimateMC supports multiple languages with complete translations:
-
-### Available Languages
-- **English** (`en`) - Default
-- **French** (`fr`) - Français
-- **Spanish** (`es`) - Español
-- **German** (`de`) - Deutsch
-- **Italian** (`it`) - Italiano
-- **Dutch** (`nl`) - Nederlands
-- **Russian** (`ru`) - Русский
-- **Chinese** (`zh`) - 中文
-- **Korean** (`kr`) - 한국어
-- **Polish** (`pl`) - Polski
-- **Portuguese** (`pt`) - Português
-
-### Changing Language
-
-1. **Via Config**: Set `language: "fr"` in config.yml
-2. **Via GUI**: Use `/reanimatemc config` and click the language option
-3. **Via Command**: Reload after changing config: `/reanimatemc reload`
+10 languages ship with the plugin. All new keys in v1.2.13 are present in every
+file. `en.yml` and `es.yml` have full translations; other languages have English
+fallback strings marked for community translation.
-### Custom Translations
+Change language: set `language: "es"` in `config.yml` and run `/rmc reload`.
+Custom translations: copy `lang/en.yml`, rename, translate, set the file name
+(without extension) as the `language` value.
-Language files are stored in `plugins/ReanimateMC/lang/`. You can:
-
-1. Copy an existing language file (e.g., `en.yml`)
-2. Rename it (e.g., `custom.yml`)
-3. Translate all messages
-4. Set `language: "custom"` in config.yml
+---
## Compatibility
-### Server Software
-- ✅ **Spigot** - Fully supported
-- ✅ **Paper** - Fully supported
-- ✅ **Bukkit** - Supported
-- ✅ **Purpur** - Compatible
-- ⚠️ **Magma** - Limited compatibility
-- ⚠️ **Sponge** - Basic compatibility
-
-### Minecraft Versions
-- **Minimum**: 1.20.1
-- **Recommended**: 1.20.4+
-- **Latest Tested**: 1.21.x
-- **Native Version**: 1.20.1
-
-### Plugin Compatibility
-
-**Known Compatible Plugins:**
-- WorldGuard - Respects region flags
-- EssentialsX - Works with teleportation
-- mcMMO - Integrates with skill systems
-- Citizens - NPCs can be revived
-- MythicMobs - Custom mobs work with KO system
-
-**Potential Conflicts:**
-- Death/respawn modifying plugins
-- Health management plugins
-- Combat logging plugins (may need configuration)
-
-## Troubleshooting
-
-### Common Issues
-
-#### Players die instantly instead of entering KO
-**Solutions:**
-- Check that `knockout.enabled: true` in config.yml
-- Verify players don't have `reanimatemc.bypass` permission
-- Ensure no conflicting death plugins are installed
-
-#### Revival not working
-**Solutions:**
-- Check reviver has `reanimatemc.revive` permission
-- Verify reviver is crouching and holding correct item
-- Check revival cooldowns haven't been triggered
-- Ensure `reanimation.require_special_item` setting matches usage
-
-#### GUI configuration not opening
-**Solutions:**
-- Verify player has `reanimatemc.admin` permission
-- Check console for errors during plugin load
-- Try `/reanimatemc reload` and retry
-
-#### Language files not loading
-**Solutions:**
-- Check language code is correct in config.yml
-- Verify language file exists in `plugins/ReanimateMC/lang/`
-- Use `/reanimatemc reload` after changes
-
-### Debug Information
+| Software | Status |
+|---|---|
+| Paper 1.21.4+ | Full support (recommended) |
+| Spigot 1.21+ | Supported; NPC pathfinding limited |
+| Purpur | Compatible |
-Enable debug logging by setting your server's logging level to DEBUG for more detailed error information.
+Paper is required for `io.papermc.paper.event.entity.EntityKnockbackEvent`
+and the Pathfinder API used by NPC navigation.
-### Getting Help
+---
-1. **Check the console** for error messages
-2. **Verify configuration** using the GUI or config files
-3. **Test permissions** using a permission plugin
-4. **Submit issues** on GitHub with full error logs
+## Troubleshooting
-### Performance Tips
+| Symptom | Cause | Fix |
+|---|---|---|
+| Version shows `${project.version}` | Old JAR built without filtering | Rebuild with this PR's `pom.xml` |
+| Mobs still attack K.O.'d players | Mobs targeted player before K.O. | Set `mobs_attack_ko: false`; confirmed to clear existing targets |
+| Bedrock ride icon on K.O. | Old JAR with ArmorStand mount | Upgrade to 1.2.13 |
+| Self-revive says unknown command | Old JAR without `plugin.yml` registration | Upgrade to 1.2.13 |
+| PROTECTOR doesn't die | Old `setHealth(0.5)` floor | Upgrade to 1.2.13 |
+| New config keys missing | Config predates 1.2.13 | Run `/rmc reload`; keys merge automatically |
+| HEALER not healing | Heal aura visible but no HP change? Player is at max HP. Check `periodic_heal_amount` | Increase `periodic_heal_amount` |
+| NPC restored with wrong lifetime | Old persistence format stored relative seconds | Upgrade to 1.2.13; delete `npc_data.yml` once |
-- Disable particles if experiencing lag: `knockout.use_particles: false`
-- Reduce heartbeat sound frequency for lower resource usage
-- Consider shorter KO durations on high-population servers
-- Use Paper server software for better performance
+---
## Contributing
-We welcome contributions to ReanimateMC! Here's how you can help:
-
-### Reporting Issues
-- Use the [GitHub Issues](https://github.com/MatisseAD/ReanimateMC/issues) page
-- Include server version, plugin version, and full error logs
-- Describe steps to reproduce the issue
-
-### Feature Requests
-- Submit detailed feature requests with use cases
-- Explain how the feature would benefit gameplay
-- Consider implementation complexity
-
-### Translation Help
-- Help translate the plugin into new languages
-- Improve existing translations
-- Submit language files via pull requests
-
-### Code Contributions
-- Fork the repository
-- Create feature branches
-- Follow existing code style
-- Submit pull requests with clear descriptions
+- Bug reports: [GitHub Issues](https://github.com/MatisseAD/ReanimateMC/issues)
+- Lang improvements: submit updated `lang/.yml` via pull request
+- Code contributions: follow existing package structure; one behavior class per
+ NPC type; no logic in listener classes beyond event routing
-## Statistics
-
-
+---
## Credits
-**Author:** Jachou
-**License:** Proprietary - All rights reserved
-**Support:** [GitHub Issues](https://github.com/MatisseAD/ReanimateMC/issues)
+**Author:** Jachou
+**License:** Proprietary — all rights reserved
+**Wiki:** https://matissead.github.io/ReanimateMC/
----
-
-*ReanimateMC - Transform your server's death system and create unforgettable gameplay moments.*
+
diff --git a/docs/api.html b/docs/api.html
index ce9b9d0..956c115 100644
--- a/docs/api.html
+++ b/docs/api.html
@@ -453,7 +453,7 @@
+---
## Credits
-**Author:** Jachou
-**License:** Proprietary - All rights reserved
-**Support:** [GitHub Issues](https://github.com/MatisseAD/ReanimateMC/issues)
+**Author:** Jachou
+**License:** Proprietary — all rights reserved
+**Wiki:** https://matissead.github.io/ReanimateMC/
----
-
-*ReanimateMC - Transform your server's death system and create unforgettable gameplay moments.*
+