# Enemy rework with Unity Behavior

13 October 2026. The user selected Unity Behavior (`com.unity.behavior`) for the
replacement and will install it. This updates the implementation direction for the
[replacement scenarios](2026-10-13-ai-replacement-scenarios.md); it does not change
their confirmed gameplay requirements or establish working replacement AI.

## Decision and current baseline

Use Unity Behavior graphs for individual enemy action selection. Do not build a
second general-purpose behavior-tree runtime or custom graph editor. Keep encounter
guidance, squad assignment, perception, tactical positioning and action execution in
focused C# components; graph nodes call those components.

The current baseline has passive networked damageable enemies following the
[AI teardown](../../superpowers/plans/2026-10-13-enemy-ai-removal.md). There is no
replacement tree to migrate. The old `current-enemy-state-machine.mmd` describes the
retired cover-grace implementation and is historical, not the replacement blueprint.

At this review, the manifest does not contain `com.unity.behavior`. Installation is
the user's next step. After installation, read the resolved manifest and lockfile,
record the exact version, and inspect that version's APIs and execution semantics
before writing package-dependent code. Preserve Unity 6000.6.4f1 and existing pins;
do not silently upgrade Unity or other packages. No paid generation is required by
this design, and no paid service is authorized.

Unity documents custom Action, Modifier and Sequencing nodes with C# start/update/end
hooks, and per-graph blackboards with optional shared variables. These support this
direction; compatibility and runtime behavior still need proof with the installed
version. Sources checked 13 October 2026:
[custom nodes](https://docs.unity3d.com/Packages/com.unity.behavior@1.0/manual/create-custom-node.html),
[blackboards](https://docs.unity3d.com/Packages/com.unity.behavior@1.0/manual/blackboard-variables.html).

## Ownership and graph boundary

| Owner | Responsibility |
| --- | --- |
| Encounter/squad C# | Broad moving pressure assignments, admission budgets and scoped observation reports; no exact hidden-player aim guidance. |
| Per-enemy C# context | Target identity/lifetime, observations and their ages, pursuit progress, cooldowns, committed attacks and current assignment. |
| Unity Behavior graph | Choose role-appropriate approach, attack, reposition, investigate or reassignment actions from that context. |
| Positioning/movement C# | Budgeted reachable-position queries, claims, physical navigation and bounded recovery; return useful failure/deferred results. |
| Attack/status/lifecycle C# | Validate release and physical hits, apply status restrictions, retain launched effects and paid recovery, enforce death/despawn/reset cleanup. |
| Client presentation | Display replicated movement, telegraphs and combat outcomes; never run authoritative enemy decisions or damage. |

The retained `PrototypeEnemy` owns entity health/status/Scan/death and currently stops
its NavMesh agent on server spawn. Integrate graph startup only after valid server
spawn/context initialization, and deliberately connect movement ownership. Merely
adding a Behavior Agent component must not activate decisions on clients, before
network spawn or after teardown. Check authority again where actions execute.

Use graph-instance blackboard variables for per-enemy bindings and action results.
Do not mark target, observation, cooldown, pursuit or attack state as `Shared`.
Reusable graph/blackboard assets are authoring definitions, not a global mutable
enemy memory. Keep durable action state in the per-enemy context across branch
changes; avoid a second independently writable copy in the blackboard. Bind explicit
inputs to reused subgraphs and verify isolation with two instances. Squad sharing
remains scoped by the squad system, with source/time/identity validation.

Use built-in control-flow nodes where their measured semantics fit. Custom nodes
should express meaningful actions such as seek a firing position or execute a
validated shot, rather than rebuilding every mechanic as tiny graph operations.
Keep policy values in authored enemy/role definitions; do not scatter them across
duplicated graphs. Add reusable subgraphs only when an actual second role needs them.

## Execution and interruption requirements

The first graph should select a valid attack opportunity, otherwise seek a useful
position/approach, then request bounded recovery or reassignment when necessary.
Death/despawn and status restrictions override ordinary actions. This is conceptual
priority, not a claim that a package selector automatically interrupts running nodes.
Inspect and test running-node reevaluation and stop behavior in the installed version.

- Node completion, interruption and graph shutdown release only the movement/position
  claims and subscriptions owned by that action. Cleanup must be idempotent, with
  explicit entity lifecycle cleanup even if a node end callback is unavailable.
- Root and stun retain distinct restrictions. Stun cancels applicable queued attacks;
  root constrains movement without becoming a blanket attack prohibition. Preserve
  actual status/weapon contracts when wiring each role.
- Preparation, commitment, release and recovery remain distinct. An ordinary
  obstructed unreleased shot is withheld/cancelled; branch changes cannot refund paid
  costs, restart recovery, retarget a committed shot or erase launched projectiles.
- Sight, ally reports, remembered positions and broad guidance remain distinct.
  A failed position query does not erase knowledge; budget deferral does not count as
  route failure or eligibility for retirement. Preserve safe accepted work while deferred.
- Pursuit progress/limits and Bombardier remembered-fire expiry survive graph changes.
  Reentry, retries and renamed tasks cannot renew either allowance. Fresh qualifying
  visual observation alone updates the relevant remembered location/time.
- Reset/despawn invalidates the context and outstanding callbacks by enemy lifetime.
  Reassignment releases obsolete claims. Hidden retirement remains a validated server
  lifecycle action, never a generic graph failure or unconditional destroy node.

All existing scenario constraints remain: no pack-wide cover freeze, routine warp,
health reset, unsupported gap crossing, invented emergency weapon, reward-bearing
retirement or boss deletion. Package convenience nodes must not bypass these rules.

## Implementation sequence and proof

1. **Package prerequisite:** user installs; record exact version/dependencies, confirm
   connected project, compile/import readiness and clean Console. Inspect graph startup,
   tick/stop APIs, interruption and blackboard/subgraph semantics in that version.
2. **One ordinary shooter:** implement a server-only graph and the minimum perception,
   valid attack, positioning and reassignment components. Create graphs/prefab bindings
   through supported Editor APIs/UI; preserve metas, manual terrain and saved NavMeshes.
   Use an isolated fixture before changing normal-stage defaults.
3. **Focused proof:** cover/alternate exit K01–K05, stairs/close transit M01–M04,
   deferred/invalid claims M07–M08 and pursuit P03. Also verify two enemies sharing one
   graph keep independent state; interrupt during preparation/commit/recovery; root,
   stun, death, despawn and reset; zero client decisions/damage; no stale callback action.
4. **Extend roles:** melee commitment/stopping, Bombardier memory expiry, then support
   and specialist behavior using their scenarios. Boss behavior has separate recovery
   and progression requirements. Do not give every role the shooter's tree unchanged.
5. **Integrate:** follow TESTING.md and the catalogue, positively discover actual new
   fixtures, run affected retained combat/spawn/session suites and required two/four
   player, latency/disconnect and progression checks. Profile graph ticks separately
   from perception, path queries and position scoring at representative enemy counts.
   Human combat/readability and hardware/separate-network acceptance remain open.

## Task scope and remaining decisions

This change records the selected framework in this design, the scenario catalogue,
project brief and historical diagram annotation. Lead owns documentation; no runtime,
package, scene or prefab changes. Documentation risk is low: authority, lifecycle,
evidence and acceptance policy are preserved. Lead checks relative links, consistency
and diff; no Unity tests are needed for this prose-only change. The future runtime
slice is high risk and requires independent technical, gameplay and design/UX reviews
before and after implementation under AGENT_WORKFLOW.md.

Hypothesis for the first slice: Unity Behavior can express useful shooter decisions
while custom execution preserves evidence, commitments and server authority. Branch
reentry resetting state, client execution, unreleased claims or unacceptable measured
cost contradicts that hypothesis and requires tuning the integration before expansion.
Exact node APIs, scheduling and performance are unverified until installation/proof.
Guidance precision, melee-lunge limits, memory duration and support retirement eligibility
remain unresolved as recorded in the scenarios; package selection settles none of them.
Implementation duration is unknown until version inspection and the first slice.
Stop this documentation task after consistency checks; implementation is a later task.