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.

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
• 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-safety-guardrails.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.