Fixing minor bugs, some renaming

docs/NPC_BEHAVIOR.md

@@ -0,0 +1,85 @@
+# Hostile NPC Behavior
+
+## Authority and update order
+
+Hostile NPC behavior is simulated by `LocationGameState` and
+`CharacterState`. Rendering objects do not select targets and do not change
+NPC combat state.
+
+During each authoritative simulation tick:
+
+1. The location gathers the enabled players and NPCs visible to the
+   simulation.
+2. Each hostile NPC selects or retains a player target.
+3. Every character advances using the same tick-start observations.
+4. Movement reservations and attack damage are resolved deterministically.
+5. Navigation recovery events are applied by `InternalGameServer`.
+
+The resulting state and recovery decisions are replicated through the existing
+WebSocket lockstep stream. NPC target changes are simulation consequences, not
+client commands.
+
+## Eligible players and nearest selection
+
+An eligible target must:
+
+- exist in the campaign player map;
+- be enabled;
+- have positive health; and
+- be within the NPC's `visibleRange` when a new target is selected.
+
+Distance is measured in the X/Z plane. If two players are equally close,
+their stable player IDs are compared lexicographically. This gives every
+lockstep replica the same result regardless of hash-map iteration order.
+
+## Ordinary target locking
+
+Once a hostile NPC has a valid target, it keeps that target during ordinary
+ticks. The target remains locked even if it moves outside `visibleRange`.
+The lock ends when the player dies or becomes disabled.
+
+When a lock ends, the NPC selects the nearest eligible player in range. If no
+player qualifies, it clears the attack target, leaves combat state, and
+requests a route to its `homePosition`.
+
+## Movement blockage and target reconsideration
+
+NPC movement uses a retry schedule after a character blocks its path. The
+blocked NPC first stops and waits for its deterministic navigation retry
+cooldown. When the retry event emits `forceNavigationReplan`, the authoritative
+location state performs a fresh target selection across all eligible players.
+
+This blocked-replan selection differs from ordinary target locking:
+
+- the current target is not privileged;
+- the nearest eligible player may remain the target;
+- a nearer eligible player replaces the current target;
+- the route is rebuilt from the NPC's current position toward the selected
+  player's current position.
+
+If no eligible player is in range during blocked recovery, the NPC clears its
+stale chase target and returns toward its home position instead. The blocker is
+still passed to path planning so the immediate replan does not route through
+the character that caused the recovery event.
+
+## Death, disconnect, and attack safety
+
+Dead or disabled players are excluded from target acquisition. A target that
+dies or disconnects is therefore invalidated on the next authoritative
+selection pass, and the NPC either switches to another player or returns home.
+
+Attack impacts are also validated at application time. Damage is ignored if
+the recorded target no longer exists, is disabled, or has already reached
+zero health. This prevents a queued animation impact from damaging a stale
+target.
+
+## Regression expectations
+
+The state and pathfinding tests should preserve these guarantees:
+
+- nearest in-range player selection is deterministic;
+- a valid ordinary lock is retained;
+- blocked NPC recovery can replace the target and rebuild the chase route;
+- no-target blocked recovery clears combat and routes home;
+- dead and disabled players cannot be selected or damaged;
+- retry cooldowns and blocker identity remain deterministic.