---
path: /studio/hathor/npc-world-awareness
surface: studio
domain: hathor
auth: signed-in + studio entitlement
source: apps/oshun/web/src/app/studio/hathor/npc-world-awareness/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 World Awareness

## Purpose

Admin lane console for the `@hathor/llm-npc` WorldAwarenessManager
spatial-perception engine. From the NPC's position and a seeded scene of objects
and characters, the engine computes 3D distance, flags what lies inside the 120°
visual field, drops anything beyond 50 m, sorts by distance, and surfaces the
nearest character, the objects in reach, and any threats. Admin-scoped and
fail-closed.

## Entry points

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

## Layout regions

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

- **Workspace** (`StudioHathorNpcWorldAwarenessWorkspace`,
  `data-hathor-npc-world-awareness-workspace`):
  - `<h1>` `WorkspaceHeading` — "Hathor NPC World Awareness Workspace"
  - Summary `<p data-hathor-npc-world-awareness-summary>`
  - Catalog state, then the **Seeded scene** list (`data-hathor-nwa-scene`) and
    the perception form + result.
- **Route Map panel** (`<section data-hathor-npc-world-awareness-route-map>`,
  `<h2>Route Map</h2>`): 5 entries from
  `STUDIO_HATHOR_NPC_WORLD_AWARENESS_ROUTE_MAP` (path + purpose).
- **Quick-action lane** (`className="quickAction"` Links): NPC Memory System,
  Back to Studio workspace index.

## States

- [ ] **Loading** — `<p data-hathor-nwa-loading>` "Loading perception engine…".
- [ ] **Unauthorized** — `data-hathor-nwa-unauthorized` on 401/403 (admin-scope).
- [ ] **Error** — `data-hathor-nwa-error` on a non-OK catalog response or network
      failure.
- [ ] **Ready (form)** — the seeded scene list + `data-hathor-nwa-perceive-form`
      with the NPC position and reach inputs.
- [ ] **Result** — `data-hathor-nwa-result` with `data-hathor-nwa-nearest`,
      `data-hathor-nwa-threats`, `data-hathor-nwa-interactable`,
      `data-hathor-nwa-visible-count`, and the per-object / per-character lists.
- [ ] **Validation error** — `data-hathor-nwa-perceive-error` for non-numeric
      position/reach or a failed POST.

## Interactions

- [ ] **`data-hathor-nwa-pos-x` / `-pos-y` / `-pos-z`** (inputs,
      `aria-label="npc x/y/z"`) — the NPC position.
- [ ] **`data-hathor-nwa-reach`** (input, `aria-label="reach"`) — interactable
      reach in metres.
- [ ] **`data-hathor-nwa-perceive-submit`** ("Run perception") — validates the
      coordinates and reach, then POSTs
      `{ npcPosition, npcOrientation, objects, characters, interactableMaxDistance }`
      (objects/characters are the seeded scene); on 200 with a valid `perception`
      renders the read-out.
- [ ] **Route Map entries** — verify against
      `STUDIO_HATHOR_NPC_WORLD_AWARENESS_ROUTE_MAP` (5 entries).
- [ ] **Quick-action links** — NPC Memory System
      (`/studio/hathor/npc-memory-system`), Back to Studio (`/studio`).

## Data & contracts

- **Reads**: `GET /v1/admin/hathor/npc-world-awareness` (catalog: `limits`,
  `characterTypes`, `emotions`).
- **Writes**: `POST /v1/admin/hathor/npc-world-awareness/perceive` with the NPC
  position + seeded scene.
- **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/StudioHathorNpcWorldAwarenessWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioHathorNpcWorldAwarenessRouteMap.ts`
- Siblings:
  [`./studio-hathor-npc-memory-system.md`](./studio-hathor-npc-memory-system.md),
  [`./studio-hathor-npc-behavior-control.md`](./studio-hathor-npc-behavior-control.md),
  [`./studio-hathor-npc-emotional-state.md`](./studio-hathor-npc-emotional-state.md)

## Open questions / known gaps

- [ ] The scene (objects + characters) is seeded in the component; confirm
      whether operators should be able to supply a custom scene rather than only
      varying the NPC position and reach.
- [ ] Hathor is `unconfirmed-v1` per `WALKTHROUGH/matrix/routes.csv`; confirm
      whether the dedicated `/studio/hathor/*` admin lanes ship V1 or are
      internal-only.