don
/
neon-sprawl
mirror of https://github.com/ViPro-Technologies/neon-sprawl
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
neon-sprawl/docs/decomposition/modules/E5_M2_NpcAiAndBehaviorProfi...

5.5 KiB
Raw Blame History

E5.M2 — NpcAiAndBehaviorProfiles

Summary

Field Value
Module ID E5.M2
Epic Epic 5 — PvE Combat
Stage target Prototype
Status In Progress — Slice 2 backlog E5M2-prototype-backlog.md: E5M2-01 NEO-87 catalog + CI landed · E5M2-02 NEO-88 server load landed → E5M2-12 NEO-98
Linear Label E5.M2 · E5M2-prototype-backlog.md E5M2-01 NEO-87 · E5M2-02 NEO-88 → E5M2-12 NEO-98

Purpose

Authority: Client vs server — server owns NPC behavior state, aggro holders, telegraph timing, and NPC→player damage; client displays telegraphs and state from polled snapshots only.

Enemy archetype behavior loops, aggro logic, and telegraph scheduling on top of E5.M1 — CombatRulesEngine. Replaces passive prototype_target_alpha / beta dummies with three fight-back NPC instances for the vision prototype minimum (three archetypes).

Responsibilities

  • Run NpcBehaviorDef; emit TelegraphEvent; apply AggroRule / ThreatState integration with combat state.
  • Lazy NPC tick advance on GET /game/world/npc-runtime-snapshot poll (prototype).
  • Session IPlayerCombatHealthStore for incoming NPC damage (no Postgres in Slice 2).

Key contracts

Contract Role
NpcBehaviorDef Archetype scripts or state machines (content JSON + schema).
TelegraphEvent Telegraph timing for UI and dodge windows.
AggroRule Target selection and leash behavior.
ThreatState Per-NPC aggro holder (playerId or empty).

Module dependencies

  • E5.M1 — CombatRulesEngine (player → NPC damage, combat-target HP, cast funnel).

Dependents (by design)

  • E4.M2 — SpawnEcologyController.
  • E5.M3 — EncounterAndRewardTables.

Related implementation slices

Epic 5 Slice 2 — NPC archetypes and telegraphs: three archetypes (melee pressure, ranged control, elite mini-boss); telemetry telegraph_fired, npc_state_transition.

Linear backlog (decomposed)

Full story tables, kickoff defaults, and blockedBy graph: E5M2-prototype-backlog.md.

Slug Linear
E5M2-01 NEO-87
E5M2-02 NEO-88
E5M2-03 NEO-89
E5M2-04 NEO-90
E5M2-05 NEO-91
E5M2-06 NEO-92
E5M2-07 NEO-93
E5M2-08 NEO-94
E5M2-09 NEO-95
E5M2-10 NEO-96
E5M2-11 NEO-97
E5M2-12 NEO-98

Prototype Slice 2 freeze (E5M2-01)

The first shipped three-archetype NPC spine under content/npc-behaviors/*.json is frozen for behavior binding, aggro tuning, and telegraph timings until a deliberate migration issue expands the roster.

NpcBehaviorDef.id displayName archetypeKind maxHp aggroRadius leashRadius telegraphWindupSeconds attackDamage attackCooldownSeconds
prototype_melee_pressure Melee Pressure melee_pressure 100 8.0 16.0 1.5 15 3.0
prototype_ranged_control Ranged Control ranged_control 80 10.0 20.0 2.0 12 4.0
prototype_elite_mini_boss Elite Mini-Boss elite_mini_boss 200 8.0 18.0 2.5 25 5.0

NPC instance ids (E5M2-05): prototype_npc_melee, prototype_npc_ranged, prototype_npc_elite — each binds one behavior def + world anchor (replaces prototype_target_alpha / beta).

Rules: Do not rename frozen behavior id values without a migration issue. CI (scripts/validate_content.py) enforces exactly these three behavior ids, duplicate-id rejection, and leashRadius > aggroRadius per row. Relaxing or changing that gate belongs in a new Linear issue once the catalog intentionally grows. Plan: NEO-87 implementation plan.

Risks and telemetry

  • Telegraph desync: single npc-runtime-snapshot poll surface; no client windup math.
  • Aggro confusion: deterministic first-hit + leash rules; instrument npc_state_transition when E9.M1 lands.

Source anchors