@zylem/game-lib 0.6.4 → 0.8.0

package/README.md

@@ -15,10 +15,24 @@ This library is intended for hobbyist developers who want to play with 3D web te
 The goal is to give you tools to build simple 3D games. It's basically comprised of:
 
 - Rendering via ThreeJS with some capability to handle postprocessing built-in. [ThreeJS](https://threejs.org/)
-- Collision handling, triggers, and rigid body physics via RapierRS [RapierRS](https://rapier.rs/)
+- Collision handling, triggers, and rigid body physics simulated in WebAssembly (Rapier compiled to WASM via [@zylem/runtime](https://www.npmjs.com/package/@zylem/runtime), driven through [@zylem/behaviors](https://www.npmjs.com/package/@zylem/behaviors))
 - Game state management with Valtio [Valtio](https://valtio.dev/)
 - Simplified input handling (gamepad, keyboard, mouse)
 
+**Architecture layers**
+
+Zylem is split into three packages, each a strict layer over the one below:
+
+| Layer | Package | Owns |
+| --- | --- | --- |
+| Game framework | `@zylem/game-lib` | Three.js rendering, input, assets, stages, game state |
+| Simulation | `@zylem/behaviors` | `createSimulation()`, entity registry, behavior FSMs, event translation, runtime ownership |
+| Runtime | `@zylem/runtime` | WASM module: ECS + Rapier physics, slot-indexed input/render/snapshot/event buffers |
+
+Each frame, game-lib forwards behavior inputs into the simulation, calls `simulation.update(delta)` (fixed-timestep physics inside WASM), then syncs interpolated render poses onto Three.js objects. Disposal follows the same chain: `Game.dispose()` → `Simulation.dispose()` → WASM stage destroy.
+
+Games normally never touch the runtime directly; for debug tooling there is an escape hatch: `game.experimental.getRuntime()` returns the underlying `Simulation`.
+
 > Note: This project is still in alpha. There are unfinished features and some APIs that may change.
 
 ## Installation
@@ -39,7 +53,9 @@ npm install @zylem/game-lib
  * the ball can be controlled with the arrow keys or gamepad
  * the ball cannot go outside the boundaries
  */
-import { createGame, createSphere, WorldBoundary2DBehavior } from '@zylem/game-lib';
+import { createGame } from '@zylem/game-lib/core';
+import { createSphere } from '@zylem/game-lib/entity';
+import { WorldBoundary2DBehavior } from '@zylem/game-lib/behavior';
 
 // Creates a sphere (movement capabilities are built-in)
 const ball = createSphere();

package/dist/actions.d.ts

@@ -1,19 +1,329 @@
-import { T as TransformState } from './entity-vj-HTjzU.js';
-export { A as Action, c as createTransformStore, i as getPosition, H as getRotation, j as getVelocity, m as move, h as moveForwardXY, a as moveX, e as moveXY, f as moveXZ, b as moveY, d as moveZ, r as resetTransformStore, g as resetVelocity, t as rotateEuler, p as rotateInDirection, u as rotateX, v as rotateY, q as rotateYEuler, x as rotateZ, s as setPosition, k as setPositionX, l as setPositionY, n as setPositionZ, G as setRotation, C as setRotationDegrees, E as setRotationDegreesX, D as setRotationDegreesY, F as setRotationDegreesZ, z as setRotationX, y as setRotationY, B as setRotationZ, o as wrapAround3D, w as wrapAroundXY } from './entity-vj-HTjzU.js';
-export { c as callFunc, d as delay, m as moveBy, a as moveTo, o as onPress, b as onRelease, p as parallel, e as repeat, f as repeatForever, r as rotateBy, s as sequence, t as throttle } from './composition-BASvMKrW.js';
-import { RigidBody } from '@dimforge/rapier3d-compat';
-export { g as globalChange, a as globalChanges, v as variableChange, b as variableChanges } from './global-change-2JvMaz44.js';
-import 'three';
-import 'bitecs';
+import { A as Action, G as GameEntity } from './entity-BdSI8CL3.js';
+export { x as getRotation, i as rotateEuler, r as rotateInDirection, j as rotateX, k as rotateY, h as rotateYEuler, l as rotateZ, w as setRotation, q as setRotationDegrees, u as setRotationDegreesX, t as setRotationDegreesY, v as setRotationDegreesZ, n as setRotationX, m as setRotationY, o as setRotationZ } from './entity-BdSI8CL3.js';
+import { Object3D } from 'three';
+import { TransformState } from '@zylem/behaviors/core';
+export { TransformState, createTransformStore, getPosition, getVelocity, move, moveForwardXY, moveX, moveXY, moveXZ, moveY, moveZ, resetVelocity, setPosition, setPositionX, setPositionY, setPositionZ, wrapAround3D, wrapAroundXY } from '@zylem/behaviors/core';
+import './vector-CiSHbivc.js';
+import './material-9vJ6SZaI.js';
+import 'three/webgpu';
+import './collision-builder-jF-toPIl.js';
+import './base-node-life-cycle-D2NuN1VB.js';
+import './stage-transition-CmGpV4tc.js';
+import './events.js';
 import 'mitt';
-import './behavior-descriptor-BXnVR8Ki.js';
 
+/** Minimal entity shape for opacity helpers (avoids GameEntity generic variance). */
+type OpacityEntity = {
+    group?: Object3D | null;
+    mesh?: Object3D | null;
+};
 /**
- * Entity that can have transformations applied from a store
+ * Sets opacity on every fadeable material under an entity's visual root.
+ */
+declare function resetEntityOpacity(entity: OpacityEntity, opacity?: number, transparent?: boolean): void;
+interface MoveByOptions {
+    /** X displacement (default: 0) */
+    x?: number;
+    /** Y displacement (default: 0) */
+    y?: number;
+    /** Z displacement (default: 0) */
+    z?: number;
+    /** Duration in milliseconds */
+    duration: number;
+}
+/**
+ * Move an entity by a displacement over a duration.
+ * Distributes the movement as velocity each frame so physics stays in sync.
+ *
+ * @example
+ * ```ts
+ * entity.runAction(moveBy({ x: 10, duration: 500 }));
+ * ```
+ */
+declare function moveBy(opts: MoveByOptions): Action;
+interface MoveToOptions {
+    /** Target X position */
+    x: number;
+    /** Target Y position */
+    y: number;
+    /** Target Z position */
+    z: number;
+    /** Duration in milliseconds */
+    duration: number;
+}
+/**
+ * Move an entity to an absolute position over a duration.
+ * Calculates displacement from the entity's position on the first tick.
+ *
+ * @example
+ * ```ts
+ * entity.runAction(moveTo({ x: 0, y: 10, z: 0, duration: 2000 }));
+ * ```
+ */
+declare function moveTo(opts: MoveToOptions): Action;
+interface RotateByOptions {
+    /** X rotation in degrees (default: 0) */
+    x?: number;
+    /** Y rotation in degrees (default: 0) */
+    y?: number;
+    /** Z rotation in degrees (default: 0) */
+    z?: number;
+    /** Duration in milliseconds */
+    duration: number;
+}
+/**
+ * Rotate an entity by euler angles (degrees) over a duration.
+ *
+ * @example
+ * ```ts
+ * entity.runAction(rotateBy({ y: 360, duration: 2000 }));
+ * ```
+ */
+declare function rotateBy(opts: RotateByOptions): Action;
+/**
+ * Wait for a duration. Useful inside `sequence()`.
+ *
+ * @param ms Duration in milliseconds
+ * @example
+ * ```ts
+ * entity.runAction(sequence(moveBy({ x: 5, duration: 1000 }), delay(500), moveBy({ y: 3, duration: 1000 })));
+ * ```
+ */
+declare function delay(ms: number): Action;
+/**
+ * Call a function immediately. Completes in one frame.
+ * Useful inside `sequence()` for side effects.
+ *
+ * @example
+ * ```ts
+ * entity.runAction(sequence(moveBy({ x: 5, duration: 1000 }), callFunc(() => console.log('done'))));
+ * ```
+ */
+declare function callFunc(fn: () => void): Action;
+interface FadeOpacityOptions {
+    /** Starting opacity (default: 1) */
+    from?: number;
+    /** Ending opacity (default: 0) */
+    to?: number;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Optional Object3D roots to traverse; defaults to entity.group ?? entity.mesh */
+    targets?: Object3D[];
+    /** When complete and `to >= 1`, restore transparent=false on affected materials */
+    restoreOpaque?: boolean;
+}
+/**
+ * Fade material opacity on an entity (or explicit targets) over a duration.
+ *
+ * @example
+ * ```ts
+ * entity.runAction(fadeOpacity({ from: 0, to: 1, duration: 400, restoreOpaque: true }));
+ * ```
+ */
+declare function fadeOpacity(opts: FadeOpacityOptions): Action;
+
+interface ThrottleOptions {
+    /** Interval in milliseconds between ready cycles */
+    duration: number;
+}
+/**
+ * A repeating timer that becomes ready every N milliseconds.
+ * Register with `entity.action(throttle(...))`.
+ *
+ * @example
+ * ```ts
+ * const t = entity.action(throttle({ duration: 500 }));
+ * entity.onUpdate(() => {
+ *   if (t.ready) { t.consume(); // do something every 500ms }
+ * });
+ * ```
+ */
+declare function throttle(opts: ThrottleOptions): ThrottleAction;
+declare class ThrottleAction implements Action {
+    readonly duration: number;
+    done: boolean;
+    persistent: boolean;
+    ready: boolean;
+    private elapsed;
+    /** @param durationMs Duration in milliseconds */
+    constructor(durationMs: number);
+    tick(_entity: GameEntity<any>, delta: number): void;
+    /** Consume the ready state and reset the timer */
+    consume(): void;
+    reset(): void;
+}
+/**
+ * Detects the rising edge of a boolean signal (press).
+ * Call `.check(isPressed)` each frame in your onUpdate; `.triggered` is
+ * true for one frame on press.
+ *
+ * @example
+ * ```ts
+ * const press = entity.action(onPress());
+ * entity.onUpdate(({ inputs }) => {
+ *   press.check(inputs.p1.buttons.A.pressed);
+ *   if (press.triggered) { // do something once on press }
+ * });
+ * ```
+ */
+declare function onPress(): OnPressAction;
+declare class OnPressAction implements Action {
+    readonly duration: number;
+    done: boolean;
+    persistent: boolean;
+    triggered: boolean;
+    private wasPressed;
+    tick(): void;
+    /**
+     * Feed the current pressed state. Sets `.triggered = true` on the
+     * frame where `isPressed` transitions from false to true.
+     */
+    check(isPressed: boolean): void;
+    reset(): void;
+}
+/**
+ * Detects the falling edge of a boolean signal (release).
+ * Call `.check(isPressed)` each frame; `.triggered` is true for one frame
+ * on release.
+ *
+ * @example
+ * ```ts
+ * const release = entity.action(onRelease());
+ * entity.onUpdate(({ inputs }) => {
+ *   release.check(inputs.p1.buttons.A.pressed);
+ *   if (release.triggered) { // do something once on release }
+ * });
+ * ```
+ */
+declare function onRelease(): OnReleaseAction;
+declare class OnReleaseAction implements Action {
+    readonly duration: number;
+    done: boolean;
+    persistent: boolean;
+    triggered: boolean;
+    private wasPressed;
+    tick(): void;
+    /**
+     * Feed the current pressed state. Sets `.triggered = true` on the
+     * frame where `isPressed` transitions from true to false.
+     */
+    check(isPressed: boolean): void;
+    reset(): void;
+}
+
+/**
+ * Run actions in order, one after another.
+ *
+ * @example
+ * ```ts
+ * entity.runAction(sequence(
+ *   moveBy({ x: 5, duration: 1000 }),
+ *   delay(500),
+ *   moveBy({ y: 3, duration: 1000 }),
+ * ));
+ * ```
+ */
+declare function sequence(...actions: Action[]): Action;
+/**
+ * Run all actions simultaneously. Done when all children are done.
+ *
+ * @example
+ * ```ts
+ * entity.runAction(parallel(
+ *   moveBy({ x: 5, duration: 1000 }),
+ *   rotateBy({ y: 360, duration: 1000 }),
+ * ));
+ * ```
+ */
+declare function parallel(...actions: Action[]): Action;
+/**
+ * Repeat an action a fixed number of times.
+ *
+ * @example
+ * ```ts
+ * entity.runAction(repeat(moveBy({ x: 2, duration: 500 }), 5));
+ * ```
+ */
+declare function repeat(action: Action, times: number): Action;
+/**
+ * Repeat an action forever. Never completes.
+ *
+ * @example
+ * ```ts
+ * enemy.runAction(repeatForever(
+ *   sequence(moveBy({ x: 3, duration: 2000 }), moveBy({ x: -3, duration: 2000 })),
+ * ));
+ * ```
+ */
+declare function repeatForever(action: Action): Action;
+
+/**
+ * Structural slice of the simulation body facade used to flush transform
+ * intents. `SimulationBody` satisfies this shape.
+ */
+interface TransformableBodyLike {
+    linvel(): {
+        x: number;
+        y: number;
+        z: number;
+    };
+    translation(): {
+        x: number;
+        y: number;
+        z: number;
+    };
+    setLinvel(velocity: {
+        x: number;
+        y: number;
+        z: number;
+    }, wakeUp: boolean): void;
+    setTranslation(translation: {
+        x: number;
+        y: number;
+        z: number;
+    }, wakeUp: boolean): void;
+    setRotation(rotation: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    }, wakeUp: boolean): void;
+    setAngvel(velocity: {
+        x: number;
+        y: number;
+        z: number;
+    }, wakeUp: boolean): void;
+}
+/**
+ * Minimal slice of the WASM stage runtime used to apply transform intents via
+ * FFI. Kept structural so this module need not import the full runtime type.
+ */
+interface RuntimeTransformTarget {
+    getLinearVelocity(slot: number, out?: [number, number, number]): [number, number, number] | null;
+    setLinearVelocity(slot: number, x: number, y: number, z: number): boolean;
+    setAngularVelocity(slot: number, x: number, y: number, z: number): boolean;
+    setRotation(slot: number, x: number, y: number, z: number, w: number): boolean;
+    setPosition(slot: number, x: number, y: number, z: number): boolean;
+    getPose(slot: number): {
+        position: [number, number, number];
+        rotation: [number, number, number, number];
+    } | null;
+}
+/**
+ * Entity that can have transformations applied from a store.
+ *
+ * When `body` (the simulation body facade) is present the intents flush
+ * through it; otherwise, if the entity carries a live WASM slot
+ * (`runtimeHandle` >= 0 + `wasmStageRef`), they flush through the runtime's
+ * FFI setters directly.
  */
 interface TransformableEntity {
-    body: RigidBody | null;
+    body: TransformableBodyLike | null;
     transformStore?: TransformState;
+    /** Live WASM slot handle, or -1 when not runtime-attached. */
+    runtimeHandle?: number;
+    /** Runtime adapter the entity is attached to, if any. */
+    wasmStageRef?: RuntimeTransformTarget | null;
 }
 /**
  * Apply accumulated transformations from the store to the physics body.
@@ -31,4 +341,4 @@ interface TransformableEntity {
  */
 declare function applyTransformChanges(entity: TransformableEntity, store: TransformState): void;
 
-export { TransformState, applyTransformChanges };
+export { Action, type FadeOpacityOptions, type MoveByOptions, type MoveToOptions, type OpacityEntity, type RotateByOptions, type ThrottleOptions, applyTransformChanges, callFunc, delay, fadeOpacity, moveBy, moveTo, onPress, onRelease, parallel, repeat, repeatForever, resetEntityOpacity, rotateBy, sequence, throttle };