---
path: /studio/hathor/npc-behavior-control
surface: studio
domain: hathor
auth: signed-in + studio entitlement
source: apps/oshun/web/src/app/studio/hathor/npc-behavior-control/page.tsx
status: walked
last_walked:
  '2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data
  (2xx), console/page-errors, expected content, screenshot verified; live
  screen-reader, touch, offline, and telemetry-delivery checks pending a manual
  AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; body
  re-derived 2026-06-03 from current source (lane-console architecture)'
---

# Studio Hathor · NPC Behavior Control

## Purpose

Admin lane console for the `@hathor/simulation` behavior-tree engine. The single
**Guard Behavior Operations Lane** feeds a canonical guard NPC a world state
(threat detected, health, armed, heard a noise) and the real tree engine resolves
the selected behavior by priority fallthrough (critical-flee → engage-when-armed →
unarmed-retreat → investigate → patrol), returning a per-branch execution trace.
Admin-scoped and fail-closed.

## Entry points

- **Direct URL / bookmark** — `/studio/hathor/npc-behavior-control`;
  `alternates.canonical` is set.
- **Quick-action from siblings** — this page links to the NPC Safety Guardrails
  lane.
- **Studio overview** — see [`../../studio-overview.md`](../../studio-overview.md).

## Layout regions

`page.tsx` renders inside `<ShellLayout active="studio">`:

- **Workspace** (`StudioHathorNpcBehaviorControlWorkspace`,
  `data-hathor-npc-behavior-control-workspace`):
  - `<h1>` `WorkspaceHeading` — "Hathor NPC Behavior Control Workspace"
  - Summary `<p data-hathor-npc-behavior-control-summary>`
  - **Guard Behavior Operations Lane** (`<h2 data-hathor-nbc-lane-heading>`):
    catalog state, then the world-state form + result.
- **Route Map panel** (`<section data-hathor-npc-behavior-control-route-map>`,
  `<h2>Route Map</h2>`): 5 entries from
  `STUDIO_HATHOR_NPC_BEHAVIOR_CONTROL_ROUTE_MAP` (path + purpose).
- **Quick-action lane** (`className="quickAction"` Links): NPC Safety
  Guardrails, Back to Studio workspace index.

## States

- [ ] **Loading** — `<p data-hathor-nbc-loading>` "Loading NPC behavior engine…".
- [ ] **Unauthorized** — `data-hathor-nbc-unauthorized` on 401/403 (admin-scope).
- [ ] **Error** — `data-hathor-nbc-error` on a non-OK catalog response or network
      failure.
- [ ] **Ready (form)** — `data-hathor-nbc-engine-summary` + `data-hathor-nbc-threshold`
      (critical-health threshold) + `data-hathor-nbc-form` with the four
      world-state inputs.
- [ ] **Result** — `data-hathor-nbc-result` with `data-hathor-nbc-headline`
      (selected behavior + root status) and `data-hathor-nbc-branches`
      (`data-hathor-nbc-branch-row` carrying `data-branch` / `data-branch-status`,
      evaluated vs skipped).
- [ ] **Validation error** — `data-hathor-nbc-evaluate-error` for an
      out-of-range health value or a failed POST.

## Interactions

- [ ] **`data-hathor-nbc-threat`** (checkbox, `aria-label="threat detected"`).
- [ ] **`data-hathor-nbc-health`** (number input 0–100, `aria-label="health"`).
- [ ] **`data-hathor-nbc-weapon`** (checkbox, `aria-label="has weapon"`).
- [ ] **`data-hathor-nbc-noise`** (checkbox, `aria-label="heard noise"`).
- [ ] **`data-hathor-nbc-submit`** ("Evaluate behavior") — validates health then
      POSTs `{ worldState: { threatDetected, health, hasWeapon, heardNoise } }`;
      on 200 with a valid `result` renders the selected behavior + branch trace.
- [ ] **Route Map entries** — verify against
      `STUDIO_HATHOR_NPC_BEHAVIOR_CONTROL_ROUTE_MAP` (5 entries).
- [ ] **Quick-action links** — NPC Safety Guardrails
      (`/studio/hathor/npc-safety-guardrails`), Back to Studio (`/studio`).

## Data & contracts

- **Reads**: `GET /v1/admin/hathor/npc-behavior-control` (catalog: `summary`,
  `inputs`, `actions`, `healthCriticalThreshold`, `tree`).
- **Writes**: `POST /v1/admin/hathor/npc-behavior-control/evaluate` with the
  world state.
- **Realtime**: none.
- **Caching**: client fetch on mount, `cache: 'no-store'`,
  `buildBffAuthHeaders()`, `AbortController` on unmount.
- **Auth**: admin-scoped, fail-closed (401/403 → unauthorized); route is behind
  the signed-in + studio proxy gate.

## Cross-references

- Parent: [`../../studio-overview.md`](../../studio-overview.md)
- Component sources:
  - `apps/oshun/web/src/components/studio/StudioHathorNpcBehaviorControlWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioHathorNpcBehaviorControlRouteMap.ts`
- Siblings:
  [`./studio-hathor-npc-behavior-trees.md`](./studio-hathor-npc-behavior-trees.md),
  [`./studio-hathor-npc-safety-guardrails.md`](./studio-hathor-npc-safety-guardrails.md),
  [`./studio-hathor-npc-world-awareness.md`](./studio-hathor-npc-world-awareness.md)

## Open questions / known gaps

- [ ] Hathor is `unconfirmed-v1` per `WALKTHROUGH/matrix/routes.csv`; confirm
      whether the dedicated `/studio/hathor/*` admin lanes ship V1 or are
      internal-only.