Quickstart: Breathe Life into the Void

In your React frontend, mount the CharacterRenderer3D component. It consumes a MetaHumanState value that you keep in sync (via store, controller, or your own state strategy).

```tsx import { CharacterRenderer3D } from "@aeion/spatial"; import type { MetaHumanState } from "@aeion/spatial";

function MyExperience({ characterState, }: { characterState: MetaHumanState | null; }) { return ( <CharacterRenderer3D characterId="char_999" characterState={characterState} quality="high" // "low" | "medium" | "high" shadows={true} enableAutomaticLOD={true} smoothing={0.15} onDistanceChange={(dist) => { / drive LOD or fade-out decisions / }} /> ); } ```

The renderer automatically:

• Builds canonical V2 geometry — math-generated procedural mesh; no artist-authored 3D models required
• Attaches a multi-layer PBR skin shader — base + subsurface scattering + blood flow + sweat/dirt overlays
• Runs autonomic microdynamics — blinking, breathing, micro-saccades, pupil hippus
• Drives emotional facial morphs — FACS-mapped morphs respond to the limbic system's PAD state
• Manages LOD — full detail close-in; simplified mesh at distance (controlled by quality + enableAutomaticLOD)

Procedural character generation:

• No artist 3D models required
• Unlimited variations via parametric genome
• Lightweight asset footprint vs scanned MetaHuman alternatives
• Sub-100ms generation per character

Instead of micromanaging animations, set goals — the prefrontal cortex plans the action sequence.

```typescript await cognitiveArchitectureService.setGoal(brain.id, { goalId: "welcome_visitor", description: "Greet the new visitor and offer assistance", preconditions: { visitorPresent: true, characterIdle: true }, desiredEffects: { visitorEngaged: true, visitorGreeted: true, }, priority: 80, deadline: Date.now() + 30_000, });

// The character will: // 1. Detect the visitor via the sensory cortex // 2. Plan a path through available actions (turn-toward, approach, smile, wave, speak-greeting) // 3. Execute the sequence via the motor cortex // 4. Re-plan if the visitor moves ```

Common action categories the engine ships with:

• Locomotion — walk-toward, run-toward, turn, stop, sit, stand
• Communication — smile, wave, nod, frown, speak (via lipsync + voice services)
• Manipulation — pick-up, put-down, hand-over, point-at
• Social — approach, retreat, observe, mirror-posture

Custom actions — register your own with preconditions + effects on the cognitiveArchitectureService. Action registries are per-character-system, so different archetypes can have different action vocabularies.

Plan visualization — Admin → Spatial → Characters → [character] → Plan View shows the current goal + planned action sequence + step progress. Useful for debugging unexpected behavior.

The cognitive architecture service exposes character state for monitoring + debugging via the admin surface.

Per-character live state available:

• pad: { pleasure, arousal, dominance } — current emotional state
• currentGoal: { id, description, progress }
• currentAction: { name, progress, blockedBy? }
• lastMemoryRecall: { episodeId, similarity }
• sensorState: { visibleObjects, audibleSpeakers }
• locomotionState: { position, velocity, facing }

Admin dashboard surfaces:

• Character roster — all active characters in the scene
• Per-character state — PAD visualized as an octahedron, current emotion label
• Behavior trace — last N actions with timing + outcome
• Memory recall log — what memories were retrieved when
• Plan visualization — current GOAP plan + step progress
• Health metrics — frame time, render cost, CPU/GPU profile

Recording + replay:

• Every action + state change emits an event that the temporal log captures
• Replay sessions deterministically (useful for debugging "this NPC did X" player reports)
• Export sessions for QA / training data / behavioral research

Performance targets:

• 50+ concurrent NPCs per scene at 60 FPS on consumer hardware (M1, Ryzen 5 + integrated GPU)
• Aggressive LOD scales to 200+ background NPCs alongside 5-10 fully-cognitive foreground NPCs
• Profile via Admin → Spatial → Performance