@zylem/behaviors 0.5.5 → 0.5.8

package/dist/{chunk-B2ERQ6HD.js → chunk-DGDNFX43.js}

@@ -146,28 +146,45 @@ var FirstPersonPresentation = class {
       );
     }
     const vm = this.viewmodels.get(entityUuid);
-    if (vm && perspective?.initialPosition && state) {
+    if (vm && state && (vm.cameraObject || perspective?.initialPosition)) {
       this.positionViewmodel(vm, perspective, state, runtime);
     }
   }
   /**
    * Position a viewmodel entity relative to the camera's eye position and rotation.
+   * Prefer `cameraObject` parenting for jitter-free follow during movement.
    */
   positionViewmodel(vm, perspective, state, runtime) {
+    const entity = vm.entity;
+    const group = entity?.group;
+    if (vm.cameraObject && group) {
+      if (entity) {
+        entity.skipRenderPoseSync = true;
+      }
+      if (group.parent !== vm.cameraObject) {
+        vm.cameraObject.add(group);
+      }
+      group.position.copy(vm.offset);
+      if (vm.rotation) {
+        group.rotation.copy(vm.rotation);
+      } else {
+        group.rotation.set(0, 0, 0);
+      }
+      return;
+    }
     const eyePos = perspective.initialPosition;
     if (!eyePos) return;
     _viewmodelQuat.setFromEuler(
       _viewmodelEuler.set(state.pitch, state.yaw, 0, "YXZ")
     );
+    _offset.copy(vm.offset).applyQuaternion(_viewmodelQuat);
     if (vm.rotation) {
       _viewmodelLocalQuat.setFromEuler(vm.rotation);
       _viewmodelQuat.multiply(_viewmodelLocalQuat);
     }
-    _offset.copy(vm.offset).applyQuaternion(_viewmodelQuat);
     const wx = eyePos.x + _offset.x;
     const wy = eyePos.y + _offset.y;
     const wz = eyePos.z + _offset.z;
-    const entity = vm.entity;
     const handle = entity?.runtimeHandle ?? -1;
     if (handle >= 0) {
       runtime.setPosition(handle, wx, wy, wz);
@@ -179,9 +196,9 @@ var FirstPersonPresentation = class {
         _viewmodelQuat.w
       );
     }
-    if (entity?.group) {
-      entity.group.position.set(wx, wy, wz);
-      entity.group.quaternion.copy(_viewmodelQuat);
+    if (group) {
+      group.position.set(wx, wy, wz);
+      group.quaternion.copy(_viewmodelQuat);
     }
   }
   /** Cleanup */
@@ -227,6 +244,8 @@ var FirstPersonBehaviorSystem = class {
         gameEntity.firstPersonState = createFirstPersonStateComponent();
       }
       if (options.perspective && !this.presentation.hasPerspective(gameEntity.uuid)) {
+        const eyeHeight = options.eyeHeight ?? defaultOptions.eyeHeight;
+        options.perspective.setEyeHeight?.(eyeHeight);
         this.presentation.setPerspective(gameEntity.uuid, options.perspective);
       }
       if (options.viewmodel && !this.presentation.hasViewmodel(gameEntity.uuid)) {
@@ -301,4 +320,4 @@ export {
   FirstPersonPresentation,
   FirstPersonBehavior
 };
-//# sourceMappingURL=chunk-B2ERQ6HD.js.map
+//# sourceMappingURL=chunk-DGDNFX43.js.map

package/dist/chunk-DGDNFX43.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lib/behaviors/first-person/first-person-fsm.ts","../src/lib/behaviors/first-person/first-person.system.ts","../src/lib/behaviors/first-person/first-person.descriptor.ts"],"sourcesContent":["/**\n * First Person Controller Finite State Machine\n *\n * Manages state transitions for first-person movement:\n * - Idle: Standing still\n * - Walking: Moving at walk speed\n * - Running: Moving at run/sprint speed\n */\n\nimport { SyncStateMachine, t } from '../../core/utility/sync-state-machine';\nimport type { FirstPersonInputComponent, FirstPersonStateComponent } from './components';\n\n/**\n * First-person movement states\n */\nexport enum FirstPersonState {\n\tIdle = 'idle',\n\tWalking = 'walking',\n\tRunning = 'running',\n}\n\n/**\n * Events that trigger state transitions\n */\nexport enum FirstPersonEvent {\n\tWalk = 'walk',\n\tRun = 'run',\n\tStop = 'stop',\n}\n\n/**\n * Context for the FSM\n */\nexport interface FirstPersonContext {\n\tinput: FirstPersonInputComponent;\n\tstate: FirstPersonStateComponent;\n}\n\n/**\n * First Person Controller FSM\n */\nexport class FirstPersonFSM {\n\tmachine: SyncStateMachine<FirstPersonState, FirstPersonEvent, never>;\n\n\tconstructor(private ctx: FirstPersonContext) {\n\t\tthis.machine = new SyncStateMachine<FirstPersonState, FirstPersonEvent, never>(\n\t\t\tFirstPersonState.Idle,\n\t\t\t[\n\t\t\t\t// Idle transitions\n\t\t\t\tt(FirstPersonState.Idle, FirstPersonEvent.Walk, FirstPersonState.Walking),\n\t\t\t\tt(FirstPersonState.Idle, FirstPersonEvent.Run, FirstPersonState.Running),\n\t\t\t\tt(FirstPersonState.Idle, FirstPersonEvent.Stop, FirstPersonState.Idle),\n\n\t\t\t\t// Walking transitions\n\t\t\t\tt(FirstPersonState.Walking, FirstPersonEvent.Run, FirstPersonState.Running),\n\t\t\t\tt(FirstPersonState.Walking, FirstPersonEvent.Stop, FirstPersonState.Idle),\n\t\t\t\tt(FirstPersonState.Walking, FirstPersonEvent.Walk, FirstPersonState.Walking),\n\n\t\t\t\t// Running transitions\n\t\t\t\tt(FirstPersonState.Running, FirstPersonEvent.Walk, FirstPersonState.Walking),\n\t\t\t\tt(FirstPersonState.Running, FirstPersonEvent.Stop, FirstPersonState.Idle),\n\t\t\t\tt(FirstPersonState.Running, FirstPersonEvent.Run, FirstPersonState.Running),\n\t\t\t],\n\t\t);\n\t}\n\n\t/** Get the current state */\n\tgetState(): FirstPersonState {\n\t\treturn this.machine.getState();\n\t}\n\n\t/** Dispatch an event to the FSM */\n\tdispatch(event: FirstPersonEvent): void {\n\t\tif (this.machine.can(event)) {\n\t\t\tthis.machine.syncDispatch(event);\n\t\t}\n\t}\n\n\t/** Get the current yaw from context */\n\tgetYaw(): number {\n\t\treturn this.ctx.state.yaw;\n\t}\n\n\t/** Get the current pitch from context */\n\tgetPitch(): number {\n\t\treturn this.ctx.state.pitch;\n\t}\n\n\t/**\n\t * Update FSM based on current input and state.\n\t */\n\tupdate(input: FirstPersonInputComponent, state: FirstPersonStateComponent): void {\n\t\tthis.ctx.input = input;\n\t\tthis.ctx.state = state;\n\n\t\tconst hasMovement = Math.abs(input.moveX) > 0.1 || Math.abs(input.moveZ) > 0.1;\n\n\t\tif (hasMovement) {\n\t\t\tif (input.sprint) {\n\t\t\t\tthis.dispatch(FirstPersonEvent.Run);\n\t\t\t} else {\n\t\t\t\tthis.dispatch(FirstPersonEvent.Walk);\n\t\t\t}\n\t\t} else {\n\t\t\tthis.dispatch(FirstPersonEvent.Stop);\n\t\t}\n\t}\n}\n","/**\n * First Person Presentation System\n *\n * Presentation-only companion to the wasm `first_person` Stage behavior:\n * - Syncs the FirstPersonPerspective eye position from the runtime pose\n * - Applies the runtime's yaw/pitch (from the behavior snapshot) to the\n *   perspective so the camera matches the simulated look state\n * - Positions an optional viewmodel entity relative to the camera\n *\n * All movement/look simulation happens in the wasm runtime; this system only\n * reads poses and snapshots.\n */\n\nimport { Vector3, Quaternion, Euler, type Object3D } from 'three';\nimport type { FirstPersonPerspective } from '../../camera/perspectives/first-person-perspective';\nimport type {\n\tBehaviorRuntime,\n\tStagePose,\n\tStageBehaviorSnapshot,\n} from '../../runtime/wasm-stage-runtime';\nimport type {\n\tFirstPersonMovementComponent,\n\tFirstPersonInputComponent,\n\tFirstPersonStateComponent,\n} from './components';\nimport type { TransformState } from '../../capabilities/transform-store';\n\n/**\n * Entity interface for the first-person controller.\n * Entities with this behavior have these components attached.\n */\nexport interface FirstPersonEntity {\n\tuuid: string;\n\ttransformStore: TransformState;\n\tfirstPerson: FirstPersonMovementComponent;\n\t$fps: FirstPersonInputComponent;\n\tfirstPersonState: FirstPersonStateComponent;\n}\n\n/**\n * Viewmodel configuration for an entity that follows the camera.\n */\nexport interface ViewmodelConfig {\n\t/** The entity whose visual group should be positioned relative to the camera. */\n\tentity: any;\n\t/** Offset from the eye position in camera-local space (right, down, forward). */\n\toffset: Vector3;\n\t/** Additional rotation applied to the viewmodel in local space (Euler angles in radians). */\n\trotation?: Euler;\n\t/**\n\t * When set, the viewmodel group is parented to this Object3D (typically the\n\t * Three.js camera) and kept at the local offset/rotation. This avoids\n\t * world-space teleport jitter from physics pose sync fighting the camera.\n\t */\n\tcameraObject?: Object3D;\n}\n// Reusable temporaries (avoid per-frame allocations)\nconst _viewmodelQuat = new Quaternion();\nconst _viewmodelLocalQuat = new Quaternion();\nconst _viewmodelEuler = new Euler();\nconst _offset = new Vector3();\nconst _pose: StagePose = { position: [0, 0, 0], rotation: [0, 0, 0, 1] };\nconst _snapshot = {} as StageBehaviorSnapshot;\n\n/**\n * Presentation system driven by runtime pose + snapshot reads.\n */\nexport class FirstPersonPresentation {\n\tprivate perspectives = new Map<string, FirstPersonPerspective>();\n\tprivate viewmodels = new Map<string, ViewmodelConfig>();\n\n\t/**\n\t * Associate a FirstPersonPerspective with an entity (by uuid).\n\t * Called once by the descriptor system when the behavior is initialized.\n\t */\n\tsetPerspective(entityUuid: string, perspective: FirstPersonPerspective): void {\n\t\tthis.perspectives.set(entityUuid, perspective);\n\t}\n\n\thasPerspective(entityUuid: string): boolean {\n\t\treturn this.perspectives.has(entityUuid);\n\t}\n\n\t/**\n\t * Attach a viewmodel (weapon/item) to an entity.\n\t * The viewmodel entity's group will be positioned relative to the camera each frame.\n\t */\n\tsetViewmodel(entityUuid: string, config: ViewmodelConfig): void {\n\t\tthis.viewmodels.set(entityUuid, config);\n\t}\n\n\thasViewmodel(entityUuid: string): boolean {\n\t\treturn this.viewmodels.has(entityUuid);\n\t}\n\n\t/**\n\t * Sync camera + viewmodel for one entity from the runtime state.\n\t */\n\tsyncEntity(\n\t\tentityUuid: string,\n\t\truntime: BehaviorRuntime,\n\t\thandle: number,\n\t\tmovement: FirstPersonMovementComponent,\n\t\tstate: FirstPersonStateComponent | undefined,\n\t): void {\n\t\tconst perspective = this.perspectives.get(entityUuid);\n\t\tconst pose = runtime.getPose(handle, _pose);\n\t\tconst snapshot = runtime.readSnapshot(handle, _snapshot);\n\n\t\tif (perspective && snapshot) {\n\t\t\tperspective.setLook?.(snapshot.yaw, snapshot.pitch);\n\t\t\tif (state) {\n\t\t\t\tstate.yaw = snapshot.yaw;\n\t\t\t\tstate.pitch = snapshot.pitch;\n\t\t\t\tstate.currentSpeed = snapshot.speed;\n\t\t\t}\n\t\t}\n\n\t\tif (perspective?.initialPosition && pose) {\n\t\t\tperspective.initialPosition.set(\n\t\t\t\tpose.position[0],\n\t\t\t\tpose.position[1] + movement.eyeHeight,\n\t\t\t\tpose.position[2],\n\t\t\t);\n\t\t}\n\n\t\tconst vm = this.viewmodels.get(entityUuid);\n\t\tif (vm && state && (vm.cameraObject || perspective?.initialPosition)) {\n\t\t\tthis.positionViewmodel(vm, perspective!, state, runtime);\n\t\t}\n\t}\n\n\t/**\n\t * Position a viewmodel entity relative to the camera's eye position and rotation.\n\t * Prefer `cameraObject` parenting for jitter-free follow during movement.\n\t */\n\tprivate positionViewmodel(\n\t\tvm: ViewmodelConfig,\n\t\tperspective: FirstPersonPerspective,\n\t\tstate: FirstPersonStateComponent,\n\t\truntime: BehaviorRuntime,\n\t): void {\n\t\tconst entity = vm.entity;\n\t\tconst group = entity?.group as Object3D | undefined;\n\n\t\t// Camera-parented path: local transform only — stays locked to the rendered view.\n\t\tif (vm.cameraObject && group) {\n\t\t\tif (entity) {\n\t\t\t\tentity.skipRenderPoseSync = true;\n\t\t\t}\n\t\t\tif (group.parent !== vm.cameraObject) {\n\t\t\t\tvm.cameraObject.add(group);\n\t\t\t}\n\t\t\tgroup.position.copy(vm.offset);\n\t\t\tif (vm.rotation) {\n\t\t\t\tgroup.rotation.copy(vm.rotation);\n\t\t\t} else {\n\t\t\t\tgroup.rotation.set(0, 0, 0);\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\n\t\tconst eyePos = perspective.initialPosition;\n\t\tif (!eyePos) return;\n\n\t\t// Look rotation only for the offset (matches camera-parented path).\n\t\t_viewmodelQuat.setFromEuler(\n\t\t\t_viewmodelEuler.set(state.pitch, state.yaw, 0, 'YXZ'),\n\t\t);\n\t\t_offset.copy(vm.offset).applyQuaternion(_viewmodelQuat);\n\n\t\t// Mesh orientation: look * viewmodel local fix\n\t\tif (vm.rotation) {\n\t\t\t_viewmodelLocalQuat.setFromEuler(vm.rotation);\n\t\t\t_viewmodelQuat.multiply(_viewmodelLocalQuat);\n\t\t}\n\n\t\tconst wx = eyePos.x + _offset.x;\n\t\tconst wy = eyePos.y + _offset.y;\n\t\tconst wz = eyePos.z + _offset.z;\n\n\t\t// Move the runtime body (if registered) so physics stays in sync\n\t\tconst handle = (entity?.runtimeHandle ?? -1) as number;\n\t\tif (handle >= 0) {\n\t\t\truntime.setPosition(handle, wx, wy, wz);\n\t\t\truntime.setRotation(\n\t\t\t\thandle,\n\t\t\t\t_viewmodelQuat.x, _viewmodelQuat.y, _viewmodelQuat.z, _viewmodelQuat.w,\n\t\t\t);\n\t\t}\n\n\t\t// Also set the group directly for immediate visual update\n\t\tif (group) {\n\t\t\tgroup.position.set(wx, wy, wz);\n\t\t\tgroup.quaternion.copy(_viewmodelQuat);\n\t\t}\n\t}\n\n\t/** Cleanup */\n\tdestroy(): void {\n\t\tthis.perspectives.clear();\n\t\tthis.viewmodels.clear();\n\t}\n}\n","/**\n * First Person Controller Behavior Descriptor\n *\n * Type-safe descriptor for the first-person controller behavior system.\n * Provides entity.use() API for FPS movement and camera control.\n */\n\nimport { Euler, type Object3D } from 'three';\nimport { defineBehavior } from '../behavior-descriptor';\nimport type { BehaviorEntityLink, BehaviorSystem } from '../behavior-system';\nimport type { FirstPersonPerspective } from '../../camera/perspectives/first-person-perspective';\nimport { Vec3Input, VEC3_ZERO, toThreeVector3 } from '../../core/vector';\nimport {\n\tFirstPersonPresentation,\n\ttype FirstPersonEntity,\n\ttype ViewmodelConfig,\n} from './first-person.system';\nimport { FirstPersonState } from './first-person-fsm';\nimport {\n\tcreateFirstPersonMovementComponent,\n\tcreateFirstPersonInputComponent,\n\tcreateFirstPersonStateComponent,\n} from './components';\nimport {\n\tSTAGE_INPUT_BUTTON_RUN,\n\treadBehaviorSnapshot,\n\ttype BehaviorRuntime,\n} from '../../runtime/wasm-stage-runtime';\n\n/**\n * First-person controller behavior options (typed for entity.use() autocomplete).\n */\nexport interface FirstPersonBehaviorOptions {\n\t/** Base walking speed (default: 8) */\n\twalkSpeed?: number;\n\t/** Sprint/run speed (default: 16) */\n\trunSpeed?: number;\n\t/** Look sensitivity multiplier (default: 2) */\n\tlookSensitivity?: number;\n\t/** Eye height offset above entity position (default: 1.7) */\n\teyeHeight?: number;\n\t/** The FirstPersonPerspective to drive (from camera.getPerspective()) */\n\tperspective?: FirstPersonPerspective;\n\t/** Optional viewmodel (weapon/item) to position relative to the camera */\n\tviewmodel?: {\n\t\tentity: any;\n\t\toffset: Vec3Input;\n\t\trotation?: Euler;\n\t\t/** Parent the viewmodel to this Object3D (e.g. the Three.js camera) for jitter-free follow. */\n\t\tcameraObject?: Object3D;\n\t};\n}\n\nconst defaultOptions: FirstPersonBehaviorOptions = {\n\twalkSpeed: 8,\n\trunSpeed: 16,\n\tlookSensitivity: 2,\n\teyeHeight: 1.7,\n};\n\nconst FIRST_PERSON_BEHAVIOR_KEY = Symbol.for(\n\t'zylem:behavior:first-person-controller',\n);\n\n/**\n * Forwards look/move input into the wasm runtime and syncs the camera\n * perspective + optional viewmodel from the runtime's pose/snapshot\n * (presentation only — the Rust `first_person` behavior owns simulation).\n */\nclass FirstPersonBehaviorSystem implements BehaviorSystem {\n\tprivate presentation = new FirstPersonPresentation();\n\tprivate attachedRuntimeSlots = new Set<number>();\n\n\tconstructor(\n\t\tprivate wasmStage: BehaviorRuntime | null,\n\t\tprivate getBehaviorLinks?: (key: symbol) => Iterable<BehaviorEntityLink>,\n\t) {}\n\n\tupdate(_ecs: unknown, _delta: number): void {\n\t\tconst links = this.getBehaviorLinks?.(FIRST_PERSON_BEHAVIOR_KEY);\n\t\tif (!links) return;\n\n\t\tfor (const link of links) {\n\t\t\tconst gameEntity = link.entity as any;\n\t\t\tconst fpsRef = link.ref as any;\n\n\t\t\tconst options = fpsRef.options as FirstPersonBehaviorOptions;\n\n\t\t\t// Initialize components (once)\n\t\t\tif (!gameEntity.firstPerson) {\n\t\t\t\tgameEntity.firstPerson = createFirstPersonMovementComponent(options);\n\t\t\t}\n\t\t\tif (!gameEntity.$fps) {\n\t\t\t\tgameEntity.$fps = createFirstPersonInputComponent();\n\t\t\t}\n\t\t\tif (!gameEntity.firstPersonState) {\n\t\t\t\tgameEntity.firstPersonState = createFirstPersonStateComponent();\n\t\t\t}\n\n\t\t\t// Wire up perspective (once)\n\t\t\tif (options.perspective && !this.presentation.hasPerspective(gameEntity.uuid)) {\n\t\t\t\tconst eyeHeight = options.eyeHeight ?? defaultOptions.eyeHeight!;\n\t\t\t\toptions.perspective.setEyeHeight?.(eyeHeight);\n\t\t\t\tthis.presentation.setPerspective(gameEntity.uuid, options.perspective);\n\t\t\t}\n\n\t\t\t// Wire up viewmodel (once)\n\t\t\tif (options.viewmodel && !this.presentation.hasViewmodel(gameEntity.uuid)) {\n\t\t\t\tthis.presentation.setViewmodel(gameEntity.uuid, {\n\t\t\t\t\t...options.viewmodel,\n\t\t\t\t\toffset: toThreeVector3(options.viewmodel.offset, VEC3_ZERO),\n\t\t\t\t} as ViewmodelConfig);\n\t\t\t}\n\n\t\t\tconst handle = (gameEntity.runtimeHandle ?? -1) as number;\n\t\t\tif (!this.wasmStage || handle < 0) continue;\n\n\t\t\tthis.ensureWasmAttached(handle, options);\n\t\t\tfpsRef.__wasmStage = this.wasmStage;\n\t\t\tfpsRef.__entity = gameEntity;\n\t\t\tconst input = gameEntity.$fps;\n\t\t\tif (input) {\n\t\t\t\tthis.wasmStage.writeInputAxes(handle, input.moveX ?? 0, input.moveZ ?? 0);\n\t\t\t\tthis.wasmStage.writeInputLook(handle, input.lookX ?? 0, input.lookY ?? 0);\n\t\t\t\tthis.wasmStage.writeInputButton(handle, STAGE_INPUT_BUTTON_RUN, !!input.sprint);\n\t\t\t}\n\n\t\t\tthis.presentation.syncEntity(\n\t\t\t\tgameEntity.uuid,\n\t\t\t\tthis.wasmStage,\n\t\t\t\thandle,\n\t\t\t\tgameEntity.firstPerson,\n\t\t\t\tgameEntity.firstPersonState,\n\t\t\t);\n\t\t}\n\t}\n\n\tprivate ensureWasmAttached(handle: number, options: FirstPersonBehaviorOptions): void {\n\t\tif (!this.wasmStage || this.attachedRuntimeSlots.has(handle)) return;\n\t\tthis.wasmStage.attachFirstPerson(handle, {\n\t\t\twalkSpeed: options.walkSpeed ?? defaultOptions.walkSpeed!,\n\t\t\trunSpeed: options.runSpeed ?? defaultOptions.runSpeed!,\n\t\t\teyeHeight: options.eyeHeight ?? defaultOptions.eyeHeight!,\n\t\t\tlookSensitivity: options.lookSensitivity ?? defaultOptions.lookSensitivity!,\n\t\t});\n\t\tthis.attachedRuntimeSlots.add(handle);\n\t}\n\n\tdestroy(_ecs: unknown): void {\n\t\tthis.presentation.destroy();\n\t\tthis.attachedRuntimeSlots.clear();\n\t}\n}\n\n/**\n * FirstPersonBehavior - typed descriptor for first-person movement and camera control.\n *\n * Provides complete first-person controller including:\n * - WASD movement relative to camera yaw\n * - Mouse look driving a FirstPersonPerspective\n * - Optional viewmodel positioning (weapon/item following camera)\n * - Walk/run state tracking via FSM\n *\n * @example\n * ```typescript\n * import { FirstPersonBehavior } from \"@zylem/game-lib/behavior\";\n * import { createCamera, Perspectives, FirstPersonPerspective } from \"@zylem/game-lib/core\";\n * import { createActor } from \"@zylem/game-lib/entity\";\n *\n * const fpsCamera = createCamera({ perspective: Perspectives.FirstPerson, ... });\n * const fps = fpsCamera.getPerspective<FirstPersonPerspective>();\n *\n * const player = createActor({ name: 'player', ... });\n * const controller = player.use(FirstPersonBehavior, {\n *   perspective: fps,\n *   walkSpeed: 8,\n *   runSpeed: 16,\n *   lookSensitivity: 2,\n * });\n *\n * // In update loop - write input, behavior handles the rest\n * player.onUpdate(({ inputs }) => {\n *   player.$fps.moveX = inputs.p1.axes.Horizontal.value;\n *   player.$fps.moveZ = inputs.p1.axes.Vertical.value;\n *   player.$fps.lookX = inputs.p1.axes.SecondaryHorizontal.value;\n *   player.$fps.lookY = inputs.p1.axes.SecondaryVertical.value;\n *   player.$fps.sprint = inputs.p1.shoulders.LTrigger.held > 0;\n * });\n * ```\n */\nexport const FirstPersonBehavior = defineBehavior<\n\tFirstPersonBehaviorOptions,\n\t{\n\t\tgetState: () => FirstPersonState;\n\t\tgetYaw: () => number;\n\t\tgetPitch: () => number;\n\t\tattachViewmodel: (entity: any, offset: Vec3Input) => void;\n\t},\n\tFirstPersonEntity\n>({\n\tname: 'first-person-controller',\n\tdefaultOptions,\n\tsystemFactory: (ctx) =>\n\t\tnew FirstPersonBehaviorSystem(ctx.wasmStage ?? null, ctx.getBehaviorLinks),\n\t// Handles read the runtime snapshot buffer (previous-step values). The\n\t// Rust behavior is the single source of truth.\n\tcreateHandle: (ref) => ({\n\t\tgetState: () => {\n\t\t\tconst snapshot = readBehaviorSnapshot(ref);\n\t\t\tif (!snapshot) return FirstPersonState.Idle;\n\t\t\tif (snapshot.speed <= 0.01) return FirstPersonState.Idle;\n\t\t\tconst walkSpeed = ref.options.walkSpeed ?? defaultOptions.walkSpeed!;\n\t\t\treturn snapshot.speed > walkSpeed\n\t\t\t\t? FirstPersonState.Running\n\t\t\t\t: FirstPersonState.Walking;\n\t\t},\n\t\tgetYaw: () => readBehaviorSnapshot(ref)?.yaw ?? 0,\n\t\tgetPitch: () => readBehaviorSnapshot(ref)?.pitch ?? 0,\n\t\tattachViewmodel: (entity: any, offset: Vec3Input) => {\n\t\t\tif (ref.options) {\n\t\t\t\tref.options.viewmodel = { entity, offset };\n\t\t\t}\n\t\t},\n\t}),\n});\n"],"mappings":"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","names":["FirstPersonState","FirstPersonEvent"]}

package/dist/core.d.ts

@@ -4,7 +4,7 @@ export { P as PhysicsBodyComponent, T as TransformComponent, c as createPhysicsB
 export { E as EntityWithBody, M as MoveableBodyLike, a as MoveableEntity, V as Vector, g as getPosition, b as getVelocity, m as makeMoveable, c as move, d as moveForwardXY, e as moveX, f as moveXY, h as moveXZ, i as moveY, j as moveZ, r as resetVelocity, s as setPosition, k as setPositionX, l as setPositionY, n as setPositionZ, w as wrapAround3D, o as wrapAroundXY } from './moveable-BdFmI3s1.js';
 export { V as VEC2_ONE, a as VEC2_ZERO, b as VEC3_ONE, c as VEC3_ZERO, d as Vec2, e as Vec2Components, f as Vec2Input, g as Vec3, h as Vec3Components, i as Vec3Input, j as isVec2Input, k as isVec3Input, n as normalizeVec2, l as normalizeVec3, t as toThreeVector2, m as toThreeVector3 } from './vector-DjhLUrak.js';
 export { S as SyncStateMachine } from './sync-state-machine-CZyspBpj.js';
-export { F as FirstPersonPerspective } from './first-person-perspective-C9Mptl0-.js';
+export { F as FirstPersonPerspective } from './first-person-perspective-BxFHgFln.js';
 export { ILogger, ITransition, SyncCallback, t } from 'typescript-fsm';
 export { STAGE_EVENT_STRIDE, STAGE_INPUT_STRIDE, STAGE_RENDER_STRIDE, STAGE_SNAPSHOT_STRIDE, StageWasmExports } from '@zylem/runtime';
 import 'three';

package/dist/{first-person-perspective-C9Mptl0-.d.ts → first-person-perspective-BxFHgFln.d.ts}

@@ -18,6 +18,8 @@ interface FirstPersonPerspective {
     look(deltaYaw: number, deltaPitch: number): void;
     /** Set absolute yaw and pitch. */
     setLook?(yaw: number, pitch: number): void;
+    /** Set eye height above the followed target. */
+    setEyeHeight?(height: number): void;
 }
 
 export type { FirstPersonPerspective as F };

package/dist/first-person.d.ts

@@ -1,8 +1,8 @@
 import { F as FirstPersonInputComponent, b as FirstPersonStateComponent, a as FirstPersonMovementComponent } from './components-qWwOsvwh.js';
 export { c as createFirstPersonInputComponent, d as createFirstPersonMovementComponent, e as createFirstPersonStateComponent } from './components-qWwOsvwh.js';
 import { S as SyncStateMachine } from './sync-state-machine-CZyspBpj.js';
-import { Vector3, Euler } from 'three';
-import { F as FirstPersonPerspective } from './first-person-perspective-C9Mptl0-.js';
+import { Vector3, Euler, Object3D } from 'three';
+import { F as FirstPersonPerspective } from './first-person-perspective-BxFHgFln.js';
 import { Z as TransformState, e as BehaviorRuntime, a as BehaviorDescriptor } from './behavior-system-HEt67el5.js';
 import { i as Vec3Input } from './vector-DjhLUrak.js';
 import 'typescript-fsm';
@@ -95,6 +95,12 @@ interface ViewmodelConfig {
     offset: Vector3;
     /** Additional rotation applied to the viewmodel in local space (Euler angles in radians). */
     rotation?: Euler;
+    /**
+     * When set, the viewmodel group is parented to this Object3D (typically the
+     * Three.js camera) and kept at the local offset/rotation. This avoids
+     * world-space teleport jitter from physics pose sync fighting the camera.
+     */
+    cameraObject?: Object3D;
 }
 /**
  * Presentation system driven by runtime pose + snapshot reads.
@@ -120,6 +126,7 @@ declare class FirstPersonPresentation {
     syncEntity(entityUuid: string, runtime: BehaviorRuntime, handle: number, movement: FirstPersonMovementComponent, state: FirstPersonStateComponent | undefined): void;
     /**
      * Position a viewmodel entity relative to the camera's eye position and rotation.
+     * Prefer `cameraObject` parenting for jitter-free follow during movement.
      */
     private positionViewmodel;
     /** Cleanup */
@@ -145,6 +152,8 @@ interface FirstPersonBehaviorOptions {
         entity: any;
         offset: Vec3Input;
         rotation?: Euler;
+        /** Parent the viewmodel to this Object3D (e.g. the Three.js camera) for jitter-free follow. */
+        cameraObject?: Object3D;
     };
 }
 /**

package/dist/first-person.js

@@ -4,7 +4,7 @@ import {
   FirstPersonFSM,
   FirstPersonPresentation,
   FirstPersonState
-} from "./chunk-B2ERQ6HD.js";
+} from "./chunk-DGDNFX43.js";
 import {
   createFirstPersonInputComponent,
   createFirstPersonMovementComponent,

package/dist/index.d.ts

@@ -36,7 +36,7 @@ import './sync-state-machine-CZyspBpj.js';
 import 'typescript-fsm';
 import './vector-DjhLUrak.js';
 import './entity-types-DhfsZbSK.js';
-import './first-person-perspective-C9Mptl0-.js';
+import './first-person-perspective-BxFHgFln.js';
 import './moveable-BdFmI3s1.js';
 import 'three/webgpu';
 

package/dist/index.js

@@ -138,7 +138,7 @@ import {
   FirstPersonFSM,
   FirstPersonPresentation,
   FirstPersonState
-} from "./chunk-B2ERQ6HD.js";
+} from "./chunk-DGDNFX43.js";
 import {
   createFirstPersonInputComponent,
   createFirstPersonMovementComponent,

package/package.json

@@ -1,160 +1,162 @@
 {
-  "name": "@zylem/behaviors",
-  "version": "0.5.5",
-  "type": "module",
-  "description": "Tree-shakable Zylem behavior descriptors, systems, coordinators, and runtime-agnostic behavior helpers.",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+ssh://git@github.com/zylem-game-lib/behaviors.git"
-  },
-  "engines": {
-    "node": ">=22.12.0",
-    "pnpm": ">=10.32.1"
-  },
-  "sideEffects": false,
-  "files": [
-    "dist"
-  ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./core": {
-      "types": "./dist/core.d.ts",
-      "import": "./dist/core.js"
-    },
-    "./destructible-prebake": {
-      "types": "./dist/destructible-prebake.d.ts",
-      "import": "./dist/destructible-prebake.js"
-    },
-    "./cooldown": {
-      "types": "./dist/cooldown.d.ts",
-      "import": "./dist/cooldown.js"
-    },
-    "./destructible-3d": {
-      "types": "./dist/destructible-3d.d.ts",
-      "import": "./dist/destructible-3d.js"
-    },
-    "./first-person": {
-      "types": "./dist/first-person.d.ts",
-      "import": "./dist/first-person.js"
-    },
-    "./jumper-2d": {
-      "types": "./dist/jumper-2d.d.ts",
-      "import": "./dist/jumper-2d.js"
-    },
-    "./jumper-3d": {
-      "types": "./dist/jumper-3d.d.ts",
-      "import": "./dist/jumper-3d.js"
-    },
-    "./particle-emitter": {
-      "types": "./dist/particle-emitter.d.ts",
-      "import": "./dist/particle-emitter.js"
-    },
-    "./particle-emitter/presets": {
-      "types": "./dist/particle-emitter/presets.d.ts",
-      "import": "./dist/particle-emitter/presets.js"
-    },
-    "./platformer-2d": {
-      "types": "./dist/platformer-2d.d.ts",
-      "import": "./dist/platformer-2d.js"
-    },
-    "./platformer-3d": {
-      "types": "./dist/platformer-3d.d.ts",
-      "import": "./dist/platformer-3d.js"
-    },
-    "./ricochet-2d": {
-      "types": "./dist/ricochet-2d.d.ts",
-      "import": "./dist/ricochet-2d.js"
-    },
-    "./ricochet-3d": {
-      "types": "./dist/ricochet-3d.d.ts",
-      "import": "./dist/ricochet-3d.js"
-    },
-    "./runtime-2d": {
-      "types": "./dist/runtime-2d.d.ts",
-      "import": "./dist/runtime-2d.js"
-    },
-    "./screen-visibility": {
-      "types": "./dist/screen-visibility.d.ts",
-      "import": "./dist/screen-visibility.js"
-    },
-    "./screen-wrap": {
-      "types": "./dist/screen-wrap.d.ts",
-      "import": "./dist/screen-wrap.js"
-    },
-    "./shooter-2d": {
-      "types": "./dist/shooter-2d.d.ts",
-      "import": "./dist/shooter-2d.js"
-    },
-    "./thruster": {
-      "types": "./dist/thruster.d.ts",
-      "import": "./dist/thruster.js"
-    },
-    "./top-down-movement": {
-      "types": "./dist/top-down-movement.d.ts",
-      "import": "./dist/top-down-movement.js"
-    },
-    "./world-boundary-2d": {
-      "types": "./dist/world-boundary-2d.d.ts",
-      "import": "./dist/world-boundary-2d.js"
-    },
-    "./world-boundary-3d": {
-      "types": "./dist/world-boundary-3d.d.ts",
-      "import": "./dist/world-boundary-3d.js"
-    },
-    "./coordinators/boundary-ricochet": {
-      "types": "./dist/coordinators/boundary-ricochet.d.ts",
-      "import": "./dist/coordinators/boundary-ricochet.js"
-    },
-    "./coordinators/boundary-ricochet-3d": {
-      "types": "./dist/coordinators/boundary-ricochet-3d.d.ts",
-      "import": "./dist/coordinators/boundary-ricochet-3d.js"
-    },
-    "./coordinators/first-person-shooter": {
-      "types": "./dist/coordinators/first-person-shooter.d.ts",
-      "import": "./dist/coordinators/first-person-shooter.js"
-    },
-    "./coordinators/multidirectional-space-shooter": {
-      "types": "./dist/coordinators/multidirectional-space-shooter.d.ts",
-      "import": "./dist/coordinators/multidirectional-space-shooter.js"
-    },
-    "./coordinators/top-down-shooter": {
-      "types": "./dist/coordinators/top-down-shooter.d.ts",
-      "import": "./dist/coordinators/top-down-shooter.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "dependencies": {
-    "@dgreenheck/three-pinata": "^2.0.1",
-    "@zylem/runtime": "link:../runtime",
-    "comlink": "^4.4.2",
-    "typescript-fsm": "^1.6.0",
-    "valtio": "^2.1.7"
-  },
-  "peerDependencies": {
-    "three": "^0.185.0"
-  },
-  "devDependencies": {
-    "@clack/prompts": "^1.6.0",
-    "@types/node": "^20.19.13",
-    "@types/three": "^0.185.0",
-    "happy-dom": "^18.0.1",
-    "tsup": "^8.5.1",
-    "typescript": "5.8.2",
-    "vitest": "^4.0.9"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "scripts": {
-    "zylem": "node --experimental-strip-types ./scripts/zylem-runner.ts",
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest --reporter=verbose"
-  }
-}
+	"name": "@zylem/behaviors",
+	"version": "0.5.8",
+	"type": "module",
+	"description": "Tree-shakable Zylem behavior descriptors, systems, coordinators, and runtime-agnostic behavior helpers.",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+ssh://git@github.com/zylem-game-lib/behaviors.git"
+	},
+	"engines": {
+		"node": ">=22.12.0",
+		"pnpm": ">=10.32.1"
+	},
+	"sideEffects": false,
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./core": {
+			"types": "./dist/core.d.ts",
+			"import": "./dist/core.js"
+		},
+		"./destructible-prebake": {
+			"types": "./dist/destructible-prebake.d.ts",
+			"import": "./dist/destructible-prebake.js"
+		},
+		"./cooldown": {
+			"types": "./dist/cooldown.d.ts",
+			"import": "./dist/cooldown.js"
+		},
+		"./destructible-3d": {
+			"types": "./dist/destructible-3d.d.ts",
+			"import": "./dist/destructible-3d.js"
+		},
+		"./first-person": {
+			"types": "./dist/first-person.d.ts",
+			"import": "./dist/first-person.js"
+		},
+		"./jumper-2d": {
+			"types": "./dist/jumper-2d.d.ts",
+			"import": "./dist/jumper-2d.js"
+		},
+		"./jumper-3d": {
+			"types": "./dist/jumper-3d.d.ts",
+			"import": "./dist/jumper-3d.js"
+		},
+		"./particle-emitter": {
+			"types": "./dist/particle-emitter.d.ts",
+			"import": "./dist/particle-emitter.js"
+		},
+		"./particle-emitter/presets": {
+			"types": "./dist/particle-emitter/presets.d.ts",
+			"import": "./dist/particle-emitter/presets.js"
+		},
+		"./platformer-2d": {
+			"types": "./dist/platformer-2d.d.ts",
+			"import": "./dist/platformer-2d.js"
+		},
+		"./platformer-3d": {
+			"types": "./dist/platformer-3d.d.ts",
+			"import": "./dist/platformer-3d.js"
+		},
+		"./ricochet-2d": {
+			"types": "./dist/ricochet-2d.d.ts",
+			"import": "./dist/ricochet-2d.js"
+		},
+		"./ricochet-3d": {
+			"types": "./dist/ricochet-3d.d.ts",
+			"import": "./dist/ricochet-3d.js"
+		},
+		"./runtime-2d": {
+			"types": "./dist/runtime-2d.d.ts",
+			"import": "./dist/runtime-2d.js"
+		},
+		"./screen-visibility": {
+			"types": "./dist/screen-visibility.d.ts",
+			"import": "./dist/screen-visibility.js"
+		},
+		"./screen-wrap": {
+			"types": "./dist/screen-wrap.d.ts",
+			"import": "./dist/screen-wrap.js"
+		},
+		"./shooter-2d": {
+			"types": "./dist/shooter-2d.d.ts",
+			"import": "./dist/shooter-2d.js"
+		},
+		"./thruster": {
+			"types": "./dist/thruster.d.ts",
+			"import": "./dist/thruster.js"
+		},
+		"./top-down-movement": {
+			"types": "./dist/top-down-movement.d.ts",
+			"import": "./dist/top-down-movement.js"
+		},
+		"./world-boundary-2d": {
+			"types": "./dist/world-boundary-2d.d.ts",
+			"import": "./dist/world-boundary-2d.js"
+		},
+		"./world-boundary-3d": {
+			"types": "./dist/world-boundary-3d.d.ts",
+			"import": "./dist/world-boundary-3d.js"
+		},
+		"./coordinators/boundary-ricochet": {
+			"types": "./dist/coordinators/boundary-ricochet.d.ts",
+			"import": "./dist/coordinators/boundary-ricochet.js"
+		},
+		"./coordinators/boundary-ricochet-3d": {
+			"types": "./dist/coordinators/boundary-ricochet-3d.d.ts",
+			"import": "./dist/coordinators/boundary-ricochet-3d.js"
+		},
+		"./coordinators/first-person-shooter": {
+			"types": "./dist/coordinators/first-person-shooter.d.ts",
+			"import": "./dist/coordinators/first-person-shooter.js"
+		},
+		"./coordinators/multidirectional-space-shooter": {
+			"types": "./dist/coordinators/multidirectional-space-shooter.d.ts",
+			"import": "./dist/coordinators/multidirectional-space-shooter.js"
+		},
+		"./coordinators/top-down-shooter": {
+			"types": "./dist/coordinators/top-down-shooter.d.ts",
+			"import": "./dist/coordinators/top-down-shooter.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"scripts": {
+		"zylem": "node --experimental-strip-types ./scripts/zylem-runner.ts",
+		"build": "tsup",
+		"dev": "tsup --watch",
+		"typecheck": "tsc --noEmit",
+		"test": "vitest --reporter=verbose",
+		"prepublishOnly": "pnpm run build && vitest run"
+	},
+	"dependencies": {
+		"@dgreenheck/three-pinata": "^2.0.1",
+		"@zylem/runtime": "^0.2.5",
+		"comlink": "^4.4.2",
+		"typescript-fsm": "^1.6.0",
+		"valtio": "^2.1.7"
+	},
+	"peerDependencies": {
+		"three": "^0.185.0"
+	},
+	"devDependencies": {
+		"@clack/prompts": "^1.6.0",
+		"@types/node": "^20.19.13",
+		"@types/three": "^0.185.0",
+		"happy-dom": "^18.0.1",
+		"tsup": "^8.5.1",
+		"typescript": "5.8.2",
+		"vitest": "^4.0.9"
+	},
+	"packageManager": "pnpm@10.33.0",
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

package/dist/chunk-B2ERQ6HD.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/lib/behaviors/first-person/first-person-fsm.ts","../src/lib/behaviors/first-person/first-person.system.ts","../src/lib/behaviors/first-person/first-person.descriptor.ts"],"sourcesContent":["/**\n * First Person Controller Finite State Machine\n *\n * Manages state transitions for first-person movement:\n * - Idle: Standing still\n * - Walking: Moving at walk speed\n * - Running: Moving at run/sprint speed\n */\n\nimport { SyncStateMachine, t } from '../../core/utility/sync-state-machine';\nimport type { FirstPersonInputComponent, FirstPersonStateComponent } from './components';\n\n/**\n * First-person movement states\n */\nexport enum FirstPersonState {\n\tIdle = 'idle',\n\tWalking = 'walking',\n\tRunning = 'running',\n}\n\n/**\n * Events that trigger state transitions\n */\nexport enum FirstPersonEvent {\n\tWalk = 'walk',\n\tRun = 'run',\n\tStop = 'stop',\n}\n\n/**\n * Context for the FSM\n */\nexport interface FirstPersonContext {\n\tinput: FirstPersonInputComponent;\n\tstate: FirstPersonStateComponent;\n}\n\n/**\n * First Person Controller FSM\n */\nexport class FirstPersonFSM {\n\tmachine: SyncStateMachine<FirstPersonState, FirstPersonEvent, never>;\n\n\tconstructor(private ctx: FirstPersonContext) {\n\t\tthis.machine = new SyncStateMachine<FirstPersonState, FirstPersonEvent, never>(\n\t\t\tFirstPersonState.Idle,\n\t\t\t[\n\t\t\t\t// Idle transitions\n\t\t\t\tt(FirstPersonState.Idle, FirstPersonEvent.Walk, FirstPersonState.Walking),\n\t\t\t\tt(FirstPersonState.Idle, FirstPersonEvent.Run, FirstPersonState.Running),\n\t\t\t\tt(FirstPersonState.Idle, FirstPersonEvent.Stop, FirstPersonState.Idle),\n\n\t\t\t\t// Walking transitions\n\t\t\t\tt(FirstPersonState.Walking, FirstPersonEvent.Run, FirstPersonState.Running),\n\t\t\t\tt(FirstPersonState.Walking, FirstPersonEvent.Stop, FirstPersonState.Idle),\n\t\t\t\tt(FirstPersonState.Walking, FirstPersonEvent.Walk, FirstPersonState.Walking),\n\n\t\t\t\t// Running transitions\n\t\t\t\tt(FirstPersonState.Running, FirstPersonEvent.Walk, FirstPersonState.Walking),\n\t\t\t\tt(FirstPersonState.Running, FirstPersonEvent.Stop, FirstPersonState.Idle),\n\t\t\t\tt(FirstPersonState.Running, FirstPersonEvent.Run, FirstPersonState.Running),\n\t\t\t],\n\t\t);\n\t}\n\n\t/** Get the current state */\n\tgetState(): FirstPersonState {\n\t\treturn this.machine.getState();\n\t}\n\n\t/** Dispatch an event to the FSM */\n\tdispatch(event: FirstPersonEvent): void {\n\t\tif (this.machine.can(event)) {\n\t\t\tthis.machine.syncDispatch(event);\n\t\t}\n\t}\n\n\t/** Get the current yaw from context */\n\tgetYaw(): number {\n\t\treturn this.ctx.state.yaw;\n\t}\n\n\t/** Get the current pitch from context */\n\tgetPitch(): number {\n\t\treturn this.ctx.state.pitch;\n\t}\n\n\t/**\n\t * Update FSM based on current input and state.\n\t */\n\tupdate(input: FirstPersonInputComponent, state: FirstPersonStateComponent): void {\n\t\tthis.ctx.input = input;\n\t\tthis.ctx.state = state;\n\n\t\tconst hasMovement = Math.abs(input.moveX) > 0.1 || Math.abs(input.moveZ) > 0.1;\n\n\t\tif (hasMovement) {\n\t\t\tif (input.sprint) {\n\t\t\t\tthis.dispatch(FirstPersonEvent.Run);\n\t\t\t} else {\n\t\t\t\tthis.dispatch(FirstPersonEvent.Walk);\n\t\t\t}\n\t\t} else {\n\t\t\tthis.dispatch(FirstPersonEvent.Stop);\n\t\t}\n\t}\n}\n","/**\n * First Person Presentation System\n *\n * Presentation-only companion to the wasm `first_person` Stage behavior:\n * - Syncs the FirstPersonPerspective eye position from the runtime pose\n * - Applies the runtime's yaw/pitch (from the behavior snapshot) to the\n *   perspective so the camera matches the simulated look state\n * - Positions an optional viewmodel entity relative to the camera\n *\n * All movement/look simulation happens in the wasm runtime; this system only\n * reads poses and snapshots.\n */\n\nimport { Vector3, Quaternion, Euler } from 'three';\nimport type { FirstPersonPerspective } from '../../camera/perspectives/first-person-perspective';\nimport type {\n\tBehaviorRuntime,\n\tStagePose,\n\tStageBehaviorSnapshot,\n} from '../../runtime/wasm-stage-runtime';\nimport type {\n\tFirstPersonMovementComponent,\n\tFirstPersonInputComponent,\n\tFirstPersonStateComponent,\n} from './components';\nimport type { TransformState } from '../../capabilities/transform-store';\n\n/**\n * Entity interface for the first-person controller.\n * Entities with this behavior have these components attached.\n */\nexport interface FirstPersonEntity {\n\tuuid: string;\n\ttransformStore: TransformState;\n\tfirstPerson: FirstPersonMovementComponent;\n\t$fps: FirstPersonInputComponent;\n\tfirstPersonState: FirstPersonStateComponent;\n}\n\n/**\n * Viewmodel configuration for an entity that follows the camera.\n */\nexport interface ViewmodelConfig {\n\t/** The entity whose visual group should be positioned relative to the camera. */\n\tentity: any;\n\t/** Offset from the eye position in camera-local space (right, down, forward). */\n\toffset: Vector3;\n\t/** Additional rotation applied to the viewmodel in local space (Euler angles in radians). */\n\trotation?: Euler;\n}\n\n// Reusable temporaries (avoid per-frame allocations)\nconst _viewmodelQuat = new Quaternion();\nconst _viewmodelLocalQuat = new Quaternion();\nconst _viewmodelEuler = new Euler();\nconst _offset = new Vector3();\nconst _pose: StagePose = { position: [0, 0, 0], rotation: [0, 0, 0, 1] };\nconst _snapshot = {} as StageBehaviorSnapshot;\n\n/**\n * Presentation system driven by runtime pose + snapshot reads.\n */\nexport class FirstPersonPresentation {\n\tprivate perspectives = new Map<string, FirstPersonPerspective>();\n\tprivate viewmodels = new Map<string, ViewmodelConfig>();\n\n\t/**\n\t * Associate a FirstPersonPerspective with an entity (by uuid).\n\t * Called once by the descriptor system when the behavior is initialized.\n\t */\n\tsetPerspective(entityUuid: string, perspective: FirstPersonPerspective): void {\n\t\tthis.perspectives.set(entityUuid, perspective);\n\t}\n\n\thasPerspective(entityUuid: string): boolean {\n\t\treturn this.perspectives.has(entityUuid);\n\t}\n\n\t/**\n\t * Attach a viewmodel (weapon/item) to an entity.\n\t * The viewmodel entity's group will be positioned relative to the camera each frame.\n\t */\n\tsetViewmodel(entityUuid: string, config: ViewmodelConfig): void {\n\t\tthis.viewmodels.set(entityUuid, config);\n\t}\n\n\thasViewmodel(entityUuid: string): boolean {\n\t\treturn this.viewmodels.has(entityUuid);\n\t}\n\n\t/**\n\t * Sync camera + viewmodel for one entity from the runtime state.\n\t */\n\tsyncEntity(\n\t\tentityUuid: string,\n\t\truntime: BehaviorRuntime,\n\t\thandle: number,\n\t\tmovement: FirstPersonMovementComponent,\n\t\tstate: FirstPersonStateComponent | undefined,\n\t): void {\n\t\tconst perspective = this.perspectives.get(entityUuid);\n\t\tconst pose = runtime.getPose(handle, _pose);\n\t\tconst snapshot = runtime.readSnapshot(handle, _snapshot);\n\n\t\tif (perspective && snapshot) {\n\t\t\tperspective.setLook?.(snapshot.yaw, snapshot.pitch);\n\t\t\tif (state) {\n\t\t\t\tstate.yaw = snapshot.yaw;\n\t\t\t\tstate.pitch = snapshot.pitch;\n\t\t\t\tstate.currentSpeed = snapshot.speed;\n\t\t\t}\n\t\t}\n\n\t\tif (perspective?.initialPosition && pose) {\n\t\t\tperspective.initialPosition.set(\n\t\t\t\tpose.position[0],\n\t\t\t\tpose.position[1] + movement.eyeHeight,\n\t\t\t\tpose.position[2],\n\t\t\t);\n\t\t}\n\n\t\tconst vm = this.viewmodels.get(entityUuid);\n\t\tif (vm && perspective?.initialPosition && state) {\n\t\t\tthis.positionViewmodel(vm, perspective, state, runtime);\n\t\t}\n\t}\n\n\t/**\n\t * Position a viewmodel entity relative to the camera's eye position and rotation.\n\t */\n\tprivate positionViewmodel(\n\t\tvm: ViewmodelConfig,\n\t\tperspective: FirstPersonPerspective,\n\t\tstate: FirstPersonStateComponent,\n\t\truntime: BehaviorRuntime,\n\t): void {\n\t\tconst eyePos = perspective.initialPosition;\n\t\tif (!eyePos) return;\n\n\t\t// Build camera rotation quaternion\n\t\t_viewmodelQuat.setFromEuler(\n\t\t\t_viewmodelEuler.set(state.pitch, state.yaw, 0, 'YXZ'),\n\t\t);\n\n\t\t// Compose with the viewmodel's local rotation (model orientation fix)\n\t\tif (vm.rotation) {\n\t\t\t_viewmodelLocalQuat.setFromEuler(vm.rotation);\n\t\t\t_viewmodelQuat.multiply(_viewmodelLocalQuat);\n\t\t}\n\n\t\t// Transform the local offset into world space\n\t\t_offset.copy(vm.offset).applyQuaternion(_viewmodelQuat);\n\n\t\tconst wx = eyePos.x + _offset.x;\n\t\tconst wy = eyePos.y + _offset.y;\n\t\tconst wz = eyePos.z + _offset.z;\n\n\t\tconst entity = vm.entity;\n\n\t\t// Move the runtime body (if registered) so physics stays in sync\n\t\tconst handle = (entity?.runtimeHandle ?? -1) as number;\n\t\tif (handle >= 0) {\n\t\t\truntime.setPosition(handle, wx, wy, wz);\n\t\t\truntime.setRotation(\n\t\t\t\thandle,\n\t\t\t\t_viewmodelQuat.x, _viewmodelQuat.y, _viewmodelQuat.z, _viewmodelQuat.w,\n\t\t\t);\n\t\t}\n\n\t\t// Also set the group directly for immediate visual update\n\t\tif (entity?.group) {\n\t\t\tentity.group.position.set(wx, wy, wz);\n\t\t\tentity.group.quaternion.copy(_viewmodelQuat);\n\t\t}\n\t}\n\n\t/** Cleanup */\n\tdestroy(): void {\n\t\tthis.perspectives.clear();\n\t\tthis.viewmodels.clear();\n\t}\n}\n","/**\n * First Person Controller Behavior Descriptor\n *\n * Type-safe descriptor for the first-person controller behavior system.\n * Provides entity.use() API for FPS movement and camera control.\n */\n\nimport { Euler } from 'three';\nimport { defineBehavior } from '../behavior-descriptor';\nimport type { BehaviorEntityLink, BehaviorSystem } from '../behavior-system';\nimport type { FirstPersonPerspective } from '../../camera/perspectives/first-person-perspective';\nimport { Vec3Input, VEC3_ZERO, toThreeVector3 } from '../../core/vector';\nimport {\n\tFirstPersonPresentation,\n\ttype FirstPersonEntity,\n\ttype ViewmodelConfig,\n} from './first-person.system';\nimport { FirstPersonState } from './first-person-fsm';\nimport {\n\tcreateFirstPersonMovementComponent,\n\tcreateFirstPersonInputComponent,\n\tcreateFirstPersonStateComponent,\n} from './components';\nimport {\n\tSTAGE_INPUT_BUTTON_RUN,\n\treadBehaviorSnapshot,\n\ttype BehaviorRuntime,\n} from '../../runtime/wasm-stage-runtime';\n\n/**\n * First-person controller behavior options (typed for entity.use() autocomplete).\n */\nexport interface FirstPersonBehaviorOptions {\n\t/** Base walking speed (default: 8) */\n\twalkSpeed?: number;\n\t/** Sprint/run speed (default: 16) */\n\trunSpeed?: number;\n\t/** Look sensitivity multiplier (default: 2) */\n\tlookSensitivity?: number;\n\t/** Eye height offset above entity position (default: 1.7) */\n\teyeHeight?: number;\n\t/** The FirstPersonPerspective to drive (from camera.getPerspective()) */\n\tperspective?: FirstPersonPerspective;\n\t/** Optional viewmodel (weapon/item) to position relative to the camera */\n\tviewmodel?: { entity: any; offset: Vec3Input; rotation?: Euler };\n}\n\nconst defaultOptions: FirstPersonBehaviorOptions = {\n\twalkSpeed: 8,\n\trunSpeed: 16,\n\tlookSensitivity: 2,\n\teyeHeight: 1.7,\n};\n\nconst FIRST_PERSON_BEHAVIOR_KEY = Symbol.for(\n\t'zylem:behavior:first-person-controller',\n);\n\n/**\n * Forwards look/move input into the wasm runtime and syncs the camera\n * perspective + optional viewmodel from the runtime's pose/snapshot\n * (presentation only — the Rust `first_person` behavior owns simulation).\n */\nclass FirstPersonBehaviorSystem implements BehaviorSystem {\n\tprivate presentation = new FirstPersonPresentation();\n\tprivate attachedRuntimeSlots = new Set<number>();\n\n\tconstructor(\n\t\tprivate wasmStage: BehaviorRuntime | null,\n\t\tprivate getBehaviorLinks?: (key: symbol) => Iterable<BehaviorEntityLink>,\n\t) {}\n\n\tupdate(_ecs: unknown, _delta: number): void {\n\t\tconst links = this.getBehaviorLinks?.(FIRST_PERSON_BEHAVIOR_KEY);\n\t\tif (!links) return;\n\n\t\tfor (const link of links) {\n\t\t\tconst gameEntity = link.entity as any;\n\t\t\tconst fpsRef = link.ref as any;\n\n\t\t\tconst options = fpsRef.options as FirstPersonBehaviorOptions;\n\n\t\t\t// Initialize components (once)\n\t\t\tif (!gameEntity.firstPerson) {\n\t\t\t\tgameEntity.firstPerson = createFirstPersonMovementComponent(options);\n\t\t\t}\n\t\t\tif (!gameEntity.$fps) {\n\t\t\t\tgameEntity.$fps = createFirstPersonInputComponent();\n\t\t\t}\n\t\t\tif (!gameEntity.firstPersonState) {\n\t\t\t\tgameEntity.firstPersonState = createFirstPersonStateComponent();\n\t\t\t}\n\n\t\t\t// Wire up perspective (once)\n\t\t\tif (options.perspective && !this.presentation.hasPerspective(gameEntity.uuid)) {\n\t\t\t\tthis.presentation.setPerspective(gameEntity.uuid, options.perspective);\n\t\t\t}\n\n\t\t\t// Wire up viewmodel (once)\n\t\t\tif (options.viewmodel && !this.presentation.hasViewmodel(gameEntity.uuid)) {\n\t\t\t\tthis.presentation.setViewmodel(gameEntity.uuid, {\n\t\t\t\t\t...options.viewmodel,\n\t\t\t\t\toffset: toThreeVector3(options.viewmodel.offset, VEC3_ZERO),\n\t\t\t\t} as ViewmodelConfig);\n\t\t\t}\n\n\t\t\tconst handle = (gameEntity.runtimeHandle ?? -1) as number;\n\t\t\tif (!this.wasmStage || handle < 0) continue;\n\n\t\t\tthis.ensureWasmAttached(handle, options);\n\t\t\tfpsRef.__wasmStage = this.wasmStage;\n\t\t\tfpsRef.__entity = gameEntity;\n\t\t\tconst input = gameEntity.$fps;\n\t\t\tif (input) {\n\t\t\t\tthis.wasmStage.writeInputAxes(handle, input.moveX ?? 0, input.moveZ ?? 0);\n\t\t\t\tthis.wasmStage.writeInputLook(handle, input.lookX ?? 0, input.lookY ?? 0);\n\t\t\t\tthis.wasmStage.writeInputButton(handle, STAGE_INPUT_BUTTON_RUN, !!input.sprint);\n\t\t\t}\n\n\t\t\tthis.presentation.syncEntity(\n\t\t\t\tgameEntity.uuid,\n\t\t\t\tthis.wasmStage,\n\t\t\t\thandle,\n\t\t\t\tgameEntity.firstPerson,\n\t\t\t\tgameEntity.firstPersonState,\n\t\t\t);\n\t\t}\n\t}\n\n\tprivate ensureWasmAttached(handle: number, options: FirstPersonBehaviorOptions): void {\n\t\tif (!this.wasmStage || this.attachedRuntimeSlots.has(handle)) return;\n\t\tthis.wasmStage.attachFirstPerson(handle, {\n\t\t\twalkSpeed: options.walkSpeed ?? defaultOptions.walkSpeed!,\n\t\t\trunSpeed: options.runSpeed ?? defaultOptions.runSpeed!,\n\t\t\teyeHeight: options.eyeHeight ?? defaultOptions.eyeHeight!,\n\t\t\tlookSensitivity: options.lookSensitivity ?? defaultOptions.lookSensitivity!,\n\t\t});\n\t\tthis.attachedRuntimeSlots.add(handle);\n\t}\n\n\tdestroy(_ecs: unknown): void {\n\t\tthis.presentation.destroy();\n\t\tthis.attachedRuntimeSlots.clear();\n\t}\n}\n\n/**\n * FirstPersonBehavior - typed descriptor for first-person movement and camera control.\n *\n * Provides complete first-person controller including:\n * - WASD movement relative to camera yaw\n * - Mouse look driving a FirstPersonPerspective\n * - Optional viewmodel positioning (weapon/item following camera)\n * - Walk/run state tracking via FSM\n *\n * @example\n * ```typescript\n * import { FirstPersonBehavior } from \"@zylem/game-lib/behavior\";\n * import { createCamera, Perspectives, FirstPersonPerspective } from \"@zylem/game-lib/core\";\n * import { createActor } from \"@zylem/game-lib/entity\";\n *\n * const fpsCamera = createCamera({ perspective: Perspectives.FirstPerson, ... });\n * const fps = fpsCamera.getPerspective<FirstPersonPerspective>();\n *\n * const player = createActor({ name: 'player', ... });\n * const controller = player.use(FirstPersonBehavior, {\n *   perspective: fps,\n *   walkSpeed: 8,\n *   runSpeed: 16,\n *   lookSensitivity: 2,\n * });\n *\n * // In update loop - write input, behavior handles the rest\n * player.onUpdate(({ inputs }) => {\n *   player.$fps.moveX = inputs.p1.axes.Horizontal.value;\n *   player.$fps.moveZ = inputs.p1.axes.Vertical.value;\n *   player.$fps.lookX = inputs.p1.axes.SecondaryHorizontal.value;\n *   player.$fps.lookY = inputs.p1.axes.SecondaryVertical.value;\n *   player.$fps.sprint = inputs.p1.shoulders.LTrigger.held > 0;\n * });\n * ```\n */\nexport const FirstPersonBehavior = defineBehavior<\n\tFirstPersonBehaviorOptions,\n\t{\n\t\tgetState: () => FirstPersonState;\n\t\tgetYaw: () => number;\n\t\tgetPitch: () => number;\n\t\tattachViewmodel: (entity: any, offset: Vec3Input) => void;\n\t},\n\tFirstPersonEntity\n>({\n\tname: 'first-person-controller',\n\tdefaultOptions,\n\tsystemFactory: (ctx) =>\n\t\tnew FirstPersonBehaviorSystem(ctx.wasmStage ?? null, ctx.getBehaviorLinks),\n\t// Handles read the runtime snapshot buffer (previous-step values). The\n\t// Rust behavior is the single source of truth.\n\tcreateHandle: (ref) => ({\n\t\tgetState: () => {\n\t\t\tconst snapshot = readBehaviorSnapshot(ref);\n\t\t\tif (!snapshot) return FirstPersonState.Idle;\n\t\t\tif (snapshot.speed <= 0.01) return FirstPersonState.Idle;\n\t\t\tconst walkSpeed = ref.options.walkSpeed ?? defaultOptions.walkSpeed!;\n\t\t\treturn snapshot.speed > walkSpeed\n\t\t\t\t? FirstPersonState.Running\n\t\t\t\t: FirstPersonState.Walking;\n\t\t},\n\t\tgetYaw: () => readBehaviorSnapshot(ref)?.yaw ?? 0,\n\t\tgetPitch: () => readBehaviorSnapshot(ref)?.pitch ?? 0,\n\t\tattachViewmodel: (entity: any, offset: Vec3Input) => {\n\t\t\tif (ref.options) {\n\t\t\t\tref.options.viewmodel = { entity, offset };\n\t\t\t}\n\t\t},\n\t}),\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAeO,IAAK,mBAAL,kBAAKA,sBAAL;AACN,EAAAA,kBAAA,UAAO;AACP,EAAAA,kBAAA,aAAU;AACV,EAAAA,kBAAA,aAAU;AAHC,SAAAA;AAAA,GAAA;AASL,IAAK,mBAAL,kBAAKC,sBAAL;AACN,EAAAA,kBAAA,UAAO;AACP,EAAAA,kBAAA,SAAM;AACN,EAAAA,kBAAA,UAAO;AAHI,SAAAA;AAAA,GAAA;AAiBL,IAAM,iBAAN,MAAqB;AAAA,EAG3B,YAAoB,KAAyB;AAAzB;AACnB,SAAK,UAAU,IAAI;AAAA,MAClB;AAAA,MACA;AAAA;AAAA,YAEC,yBAAE,mBAAuB,mBAAuB,uBAAwB;AAAA,YACxE,yBAAE,mBAAuB,iBAAsB,uBAAwB;AAAA,YACvE,yBAAE,mBAAuB,mBAAuB,iBAAqB;AAAA;AAAA,YAGrE,yBAAE,yBAA0B,iBAAsB,uBAAwB;AAAA,YAC1E,yBAAE,yBAA0B,mBAAuB,iBAAqB;AAAA,YACxE,yBAAE,yBAA0B,mBAAuB,uBAAwB;AAAA;AAAA,YAG3E,yBAAE,yBAA0B,mBAAuB,uBAAwB;AAAA,YAC3E,yBAAE,yBAA0B,mBAAuB,iBAAqB;AAAA,YACxE,yBAAE,yBAA0B,iBAAsB,uBAAwB;AAAA,MAC3E;AAAA,IACD;AAAA,EACD;AAAA,EApBoB;AAAA,EAFpB;AAAA;AAAA,EAyBA,WAA6B;AAC5B,WAAO,KAAK,QAAQ,SAAS;AAAA,EAC9B;AAAA;AAAA,EAGA,SAAS,OAA+B;AACvC,QAAI,KAAK,QAAQ,IAAI,KAAK,GAAG;AAC5B,WAAK,QAAQ,aAAa,KAAK;AAAA,IAChC;AAAA,EACD;AAAA;AAAA,EAGA,SAAiB;AAChB,WAAO,KAAK,IAAI,MAAM;AAAA,EACvB;AAAA;AAAA,EAGA,WAAmB;AAClB,WAAO,KAAK,IAAI,MAAM;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,OAAkC,OAAwC;AAChF,SAAK,IAAI,QAAQ;AACjB,SAAK,IAAI,QAAQ;AAEjB,UAAM,cAAc,KAAK,IAAI,MAAM,KAAK,IAAI,OAAO,KAAK,IAAI,MAAM,KAAK,IAAI;AAE3E,QAAI,aAAa;AAChB,UAAI,MAAM,QAAQ;AACjB,aAAK,SAAS,eAAoB;AAAA,MACnC,OAAO;AACN,aAAK,SAAS,iBAAqB;AAAA,MACpC;AAAA,IACD,OAAO;AACN,WAAK,SAAS,iBAAqB;AAAA,IACpC;AAAA,EACD;AACD;;;AC9FA,SAAS,SAAS,YAAY,aAAa;AAuC3C,IAAM,iBAAiB,IAAI,WAAW;AACtC,IAAM,sBAAsB,IAAI,WAAW;AAC3C,IAAM,kBAAkB,IAAI,MAAM;AAClC,IAAM,UAAU,IAAI,QAAQ;AAC5B,IAAM,QAAmB,EAAE,UAAU,CAAC,GAAG,GAAG,CAAC,GAAG,UAAU,CAAC,GAAG,GAAG,GAAG,CAAC,EAAE;AACvE,IAAM,YAAY,CAAC;AAKZ,IAAM,0BAAN,MAA8B;AAAA,EAC5B,eAAe,oBAAI,IAAoC;AAAA,EACvD,aAAa,oBAAI,IAA6B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMtD,eAAe,YAAoB,aAA2C;AAC7E,SAAK,aAAa,IAAI,YAAY,WAAW;AAAA,EAC9C;AAAA,EAEA,eAAe,YAA6B;AAC3C,WAAO,KAAK,aAAa,IAAI,UAAU;AAAA,EACxC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,aAAa,YAAoB,QAA+B;AAC/D,SAAK,WAAW,IAAI,YAAY,MAAM;AAAA,EACvC;AAAA,EAEA,aAAa,YAA6B;AACzC,WAAO,KAAK,WAAW,IAAI,UAAU;AAAA,EACtC;AAAA;AAAA;AAAA;AAAA,EAKA,WACC,YACA,SACA,QACA,UACA,OACO;AACP,UAAM,cAAc,KAAK,aAAa,IAAI,UAAU;AACpD,UAAM,OAAO,QAAQ,QAAQ,QAAQ,KAAK;AAC1C,UAAM,WAAW,QAAQ,aAAa,QAAQ,SAAS;AAEvD,QAAI,eAAe,UAAU;AAC5B,kBAAY,UAAU,SAAS,KAAK,SAAS,KAAK;AAClD,UAAI,OAAO;AACV,cAAM,MAAM,SAAS;AACrB,cAAM,QAAQ,SAAS;AACvB,cAAM,eAAe,SAAS;AAAA,MAC/B;AAAA,IACD;AAEA,QAAI,aAAa,mBAAmB,MAAM;AACzC,kBAAY,gBAAgB;AAAA,QAC3B,KAAK,SAAS,CAAC;AAAA,QACf,KAAK,SAAS,CAAC,IAAI,SAAS;AAAA,QAC5B,KAAK,SAAS,CAAC;AAAA,MAChB;AAAA,IACD;AAEA,UAAM,KAAK,KAAK,WAAW,IAAI,UAAU;AACzC,QAAI,MAAM,aAAa,mBAAmB,OAAO;AAChD,WAAK,kBAAkB,IAAI,aAAa,OAAO,OAAO;AAAA,IACvD;AAAA,EACD;AAAA;AAAA;AAAA;AAAA,EAKQ,kBACP,IACA,aACA,OACA,SACO;AACP,UAAM,SAAS,YAAY;AAC3B,QAAI,CAAC,OAAQ;AAGb,mBAAe;AAAA,MACd,gBAAgB,IAAI,MAAM,OAAO,MAAM,KAAK,GAAG,KAAK;AAAA,IACrD;AAGA,QAAI,GAAG,UAAU;AAChB,0BAAoB,aAAa,GAAG,QAAQ;AAC5C,qBAAe,SAAS,mBAAmB;AAAA,IAC5C;AAGA,YAAQ,KAAK,GAAG,MAAM,EAAE,gBAAgB,cAAc;AAEtD,UAAM,KAAK,OAAO,IAAI,QAAQ;AAC9B,UAAM,KAAK,OAAO,IAAI,QAAQ;AAC9B,UAAM,KAAK,OAAO,IAAI,QAAQ;AAE9B,UAAM,SAAS,GAAG;AAGlB,UAAM,SAAU,QAAQ,iBAAiB;AACzC,QAAI,UAAU,GAAG;AAChB,cAAQ,YAAY,QAAQ,IAAI,IAAI,EAAE;AACtC,cAAQ;AAAA,QACP;AAAA,QACA,eAAe;AAAA,QAAG,eAAe;AAAA,QAAG,eAAe;AAAA,QAAG,eAAe;AAAA,MACtE;AAAA,IACD;AAGA,QAAI,QAAQ,OAAO;AAClB,aAAO,MAAM,SAAS,IAAI,IAAI,IAAI,EAAE;AACpC,aAAO,MAAM,WAAW,KAAK,cAAc;AAAA,IAC5C;AAAA,EACD;AAAA;AAAA,EAGA,UAAgB;AACf,SAAK,aAAa,MAAM;AACxB,SAAK,WAAW,MAAM;AAAA,EACvB;AACD;;;ACtIA,IAAM,iBAA6C;AAAA,EAClD,WAAW;AAAA,EACX,UAAU;AAAA,EACV,iBAAiB;AAAA,EACjB,WAAW;AACZ;AAEA,IAAM,4BAA4B,uBAAO;AAAA,EACxC;AACD;AAOA,IAAM,4BAAN,MAA0D;AAAA,EAIzD,YACS,WACA,kBACP;AAFO;AACA;AAAA,EACN;AAAA,EAFM;AAAA,EACA;AAAA,EALD,eAAe,IAAI,wBAAwB;AAAA,EAC3C,uBAAuB,oBAAI,IAAY;AAAA,EAO/C,OAAO,MAAe,QAAsB;AAC3C,UAAM,QAAQ,KAAK,mBAAmB,yBAAyB;AAC/D,QAAI,CAAC,MAAO;AAEZ,eAAW,QAAQ,OAAO;AACzB,YAAM,aAAa,KAAK;AACxB,YAAM,SAAS,KAAK;AAEpB,YAAM,UAAU,OAAO;AAGvB,UAAI,CAAC,WAAW,aAAa;AAC5B,mBAAW,cAAc,mCAAmC,OAAO;AAAA,MACpE;AACA,UAAI,CAAC,WAAW,MAAM;AACrB,mBAAW,OAAO,gCAAgC;AAAA,MACnD;AACA,UAAI,CAAC,WAAW,kBAAkB;AACjC,mBAAW,mBAAmB,gCAAgC;AAAA,MAC/D;AAGA,UAAI,QAAQ,eAAe,CAAC,KAAK,aAAa,eAAe,WAAW,IAAI,GAAG;AAC9E,aAAK,aAAa,eAAe,WAAW,MAAM,QAAQ,WAAW;AAAA,MACtE;AAGA,UAAI,QAAQ,aAAa,CAAC,KAAK,aAAa,aAAa,WAAW,IAAI,GAAG;AAC1E,aAAK,aAAa,aAAa,WAAW,MAAM;AAAA,UAC/C,GAAG,QAAQ;AAAA,UACX,QAAQ,eAAe,QAAQ,UAAU,QAAQ,SAAS;AAAA,QAC3D,CAAoB;AAAA,MACrB;AAEA,YAAM,SAAU,WAAW,iBAAiB;AAC5C,UAAI,CAAC,KAAK,aAAa,SAAS,EAAG;AAEnC,WAAK,mBAAmB,QAAQ,OAAO;AACvC,aAAO,cAAc,KAAK;AAC1B,aAAO,WAAW;AAClB,YAAM,QAAQ,WAAW;AACzB,UAAI,OAAO;AACV,aAAK,UAAU,eAAe,QAAQ,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC;AACxE,aAAK,UAAU,eAAe,QAAQ,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC;AACxE,aAAK,UAAU,iBAAiB,QAAQ,wBAAwB,CAAC,CAAC,MAAM,MAAM;AAAA,MAC/E;AAEA,WAAK,aAAa;AAAA,QACjB,WAAW;AAAA,QACX,KAAK;AAAA,QACL;AAAA,QACA,WAAW;AAAA,QACX,WAAW;AAAA,MACZ;AAAA,IACD;AAAA,EACD;AAAA,EAEQ,mBAAmB,QAAgB,SAA2C;AACrF,QAAI,CAAC,KAAK,aAAa,KAAK,qBAAqB,IAAI,MAAM,EAAG;AAC9D,SAAK,UAAU,kBAAkB,QAAQ;AAAA,MACxC,WAAW,QAAQ,aAAa,eAAe;AAAA,MAC/C,UAAU,QAAQ,YAAY,eAAe;AAAA,MAC7C,WAAW,QAAQ,aAAa,eAAe;AAAA,MAC/C,iBAAiB,QAAQ,mBAAmB,eAAe;AAAA,IAC5D,CAAC;AACD,SAAK,qBAAqB,IAAI,MAAM;AAAA,EACrC;AAAA,EAEA,QAAQ,MAAqB;AAC5B,SAAK,aAAa,QAAQ;AAC1B,SAAK,qBAAqB,MAAM;AAAA,EACjC;AACD;AAsCO,IAAM,sBAAsB,eASjC;AAAA,EACD,MAAM;AAAA,EACN;AAAA,EACA,eAAe,CAAC,QACf,IAAI,0BAA0B,IAAI,aAAa,MAAM,IAAI,gBAAgB;AAAA;AAAA;AAAA,EAG1E,cAAc,CAAC,SAAS;AAAA,IACvB,UAAU,MAAM;AACf,YAAM,WAAW,qBAAqB,GAAG;AACzC,UAAI,CAAC,SAAU;AACf,UAAI,SAAS,SAAS,KAAM;AAC5B,YAAM,YAAY,IAAI,QAAQ,aAAa,eAAe;AAC1D,aAAO,SAAS,QAAQ;AAAA,IAGzB;AAAA,IACA,QAAQ,MAAM,qBAAqB,GAAG,GAAG,OAAO;AAAA,IAChD,UAAU,MAAM,qBAAqB,GAAG,GAAG,SAAS;AAAA,IACpD,iBAAiB,CAAC,QAAa,WAAsB;AACpD,UAAI,IAAI,SAAS;AAChB,YAAI,QAAQ,YAAY,EAAE,QAAQ,OAAO;AAAA,MAC1C;AAAA,IACD;AAAA,EACD;AACD,CAAC;","names":["FirstPersonState","FirstPersonEvent"]}