@zylem/game-lib 0.7.0 → 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

package/dist/actions.d.ts

@@ -1,12 +1,14 @@
-import { A as Action, G as GameEntity } from './entity-DNkYKfdp.js';
-export { H as getRotation, t as rotateEuler, r as rotateInDirection, u as rotateX, v as rotateY, s as rotateYEuler, w as rotateZ, F as setRotation, B as setRotationDegrees, D as setRotationDegreesX, C as setRotationDegreesY, E as setRotationDegreesZ, y as setRotationX, x as setRotationY, z as setRotationZ } from './entity-DNkYKfdp.js';
+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, resetTransformStore, resetVelocity, setPosition, setPositionX, setPositionY, setPositionZ, wrapAround3D, wrapAroundXY } from '@zylem/behaviors/core';
-import { RigidBody } from '@dimforge/rapier3d-compat';
-import './material-Wz83vTTp.js';
+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 './base-node-life-cycle-CnJ-7zX-.js';
+import './collision-builder-jF-toPIl.js';
+import './base-node-life-cycle-D2NuN1VB.js';
+import './stage-transition-CmGpV4tc.js';
 import './events.js';
 import 'mitt';
 
@@ -256,11 +258,72 @@ declare function repeat(action: Action, times: number): Action;
 declare function repeatForever(action: Action): Action;
 
 /**
- * Entity that can have transformations applied from a store
+ * 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.

package/dist/actions.js

@@ -1 +1 @@
-import{a as C}from"./chunk-FM5TBEPO.js";import{a as G,b as D,c as P,d as R,e as I,f as X,g as Y,h as B,i as Z,j,k as V,l as q,m as F,n as S,o as _}from"./chunk-XRP4JJXL.js";var c=class{duration;done=!1;persistent=!1;elapsed=0;constructor(t){this.duration=t/1e3}tick(t,i){if(this.done)return;this.elapsed+=i;let n=this.duration>0?Math.min(this.elapsed/this.duration,1):1;this.onTick(t,i,n),this.elapsed>=this.duration&&(this.done=!0)}reset(){this.elapsed=0,this.done=!1}};import{setVelocityIntent as w}from"@zylem/behaviors/core";function A(e){let t=[];for(let i of e)i.traverse(n=>{if(!n.isMesh)return;let r=n,o=s=>{!("opacity"in s)||!("transparent"in s)||t.push(s)};Array.isArray(r.material)?r.material.forEach(o):r.material&&o(r.material)});return t}function E(e,t){if(t&&t.length>0)return t;let i=e.group??e.mesh;return i?[i]:[]}function U(e,t=1,i=!1){let n=E(e,void 0);for(let r of A(n))r.transparent=i,r.opacity=t,r.needsUpdate=!0}function H(e){return new l(e)}var l=class extends c{dx;dy;dz;constructor(t){super(t.duration),this.dx=t.x??0,this.dy=t.y??0,this.dz=t.z??0}onTick(t,i,n){if(this.duration<=0)return;let r=this.dx/this.duration,o=this.dy/this.duration,s=this.dz/this.duration,a=t.transformStore;a&&w(a,"actions",{x:r,y:o,z:s},{mode:"add"})}};function J(e){return new d(e)}var d=class extends c{targetX;targetY;targetZ;dx=0;dy=0;dz=0;initialized=!1;constructor(t){super(t.duration),this.targetX=t.x,this.targetY=t.y,this.targetZ=t.z}onTick(t,i,n){if(this.duration<=0)return;if(!this.initialized){let u=t.getPosition?.(),k=u?.x??0,M=u?.y??0,T=u?.z??0;this.dx=this.targetX-k,this.dy=this.targetY-M,this.dz=this.targetZ-T,this.initialized=!0}let r=this.dx/this.duration,o=this.dy/this.duration,s=this.dz/this.duration,a=t.transformStore;a&&w(a,"actions",{x:r,y:o,z:s},{mode:"add"})}reset(){super.reset(),this.initialized=!1}};function K(e){return new p(e)}var p=class extends c{rx;ry;rz;constructor(t){super(t.duration);let i=Math.PI/180;this.rx=(t.x??0)*i,this.ry=(t.y??0)*i,this.rz=(t.z??0)*i}onTick(t,i,n){if(this.duration<=0)return;let r=this.rx/this.duration,o=this.ry/this.duration,s=this.rz/this.duration,a=t.transformStore;a.angularVelocity.x+=r,a.angularVelocity.y+=o,a.angularVelocity.z+=s,a.dirty.angularVelocity=!0}};function L(e){return new m(e)}var m=class extends c{constructor(t){super(t)}onTick(){}};function N(e){return new h(e)}var h=class extends c{fn;called=!1;constructor(t){super(0),this.fn=t}onTick(){this.called||(this.fn(),this.called=!0)}reset(){super.reset(),this.called=!1}};function Q(e){return new f(e)}var f=class extends c{from;to;targets;restoreOpaque;materials=null;finalized=!1;constructor(t){super(t.duration),this.from=t.from??1,this.to=t.to??0,this.targets=t.targets,this.restoreOpaque=t.restoreOpaque??!1}onTick(t,i,n){if(!this.materials){this.materials=A(E(t,this.targets));for(let o of this.materials)o.transparent=!0,o.needsUpdate=!0}let r=this.from+(this.to-this.from)*n;for(let o of this.materials)o.opacity=r;if(n>=1&&!this.finalized&&(this.finalized=!0,this.restoreOpaque&&this.to>=1))for(let o of this.materials)o.transparent=!1,o.needsUpdate=!0}reset(){super.reset(),this.materials=null,this.finalized=!1}};function W(e){return new y(e.duration)}var y=class{duration;done=!1;persistent=!0;ready=!1;elapsed=0;constructor(t){this.duration=t/1e3}tick(t,i){this.elapsed+=i,this.elapsed>=this.duration&&(this.ready=!0)}consume(){this.ready=!1,this.elapsed=0}reset(){this.elapsed=0,this.ready=!1}};function $(){return new b}var b=class{duration=1/0;done=!1;persistent=!0;triggered=!1;wasPressed=!1;tick(){this.triggered=!1}check(t){t&&!this.wasPressed&&(this.triggered=!0),this.wasPressed=t}reset(){this.triggered=!1,this.wasPressed=!1}};function tt(){return new v}var v=class{duration=1/0;done=!1;persistent=!0;triggered=!1;wasPressed=!1;tick(){this.triggered=!1}check(t){!t&&this.wasPressed&&(this.triggered=!0),this.wasPressed=t}reset(){this.triggered=!1,this.wasPressed=!1}};function et(...e){return new x(e)}var x=class{duration;done=!1;persistent=!1;actions;currentIndex=0;constructor(t){this.actions=t,this.duration=t.reduce((i,n)=>i+n.duration,0)}tick(t,i){if(this.done||this.actions.length===0){this.done=!0;return}let n=i;for(;n>0&&this.currentIndex<this.actions.length;){let r=this.actions[this.currentIndex];if(r.tick(t,n),r.done){let o=r.duration,s=r.elapsed??o;n=Math.max(0,s-o),this.currentIndex++}else n=0}this.currentIndex>=this.actions.length&&(this.done=!0)}reset(){this.currentIndex=0,this.done=!1;for(let t of this.actions)t.reset()}};function it(...e){return new g(e)}var g=class{duration;done=!1;persistent=!1;actions;constructor(t){this.actions=t,this.duration=Math.max(0,...t.map(i=>i.duration))}tick(t,i){if(this.done)return;let n=!0;for(let r of this.actions)r.done||r.tick(t,i),r.done||(n=!1);n&&(this.done=!0)}reset(){this.done=!1;for(let t of this.actions)t.reset()}};function rt(e,t){return new O(e,t)}var O=class{duration;done=!1;persistent=!1;action;totalTimes;currentCount=0;constructor(t,i){this.action=t,this.totalTimes=i,this.duration=t.duration*i}tick(t,i){this.done||(this.action.tick(t,i),this.action.done&&(this.currentCount++,this.currentCount>=this.totalTimes?this.done=!0:this.action.reset()))}reset(){this.currentCount=0,this.done=!1,this.action.reset()}};function nt(e){return new z(e)}var z=class{duration=1/0;done=!1;persistent=!1;action;constructor(t){this.action=t}tick(t,i){this.action.tick(t,i),this.action.done&&this.action.reset()}reset(){this.done=!1,this.action.reset()}};import{createTransformStore as yt,resetTransformStore as bt}from"@zylem/behaviors/core";import{move as gt,moveX as Ot,moveY as zt,moveZ as wt,moveXY as At,moveXZ as Et,resetVelocity as kt,moveForwardXY as Mt,getPosition as Tt,getVelocity as Gt,setPosition as Dt,setPositionX as Pt,setPositionY as Rt,setPositionZ as It,wrapAroundXY as Xt,wrapAround3D as Yt}from"@zylem/behaviors/core";export{C as applyTransformChanges,N as callFunc,yt as createTransformStore,L as delay,Q as fadeOpacity,Tt as getPosition,_ as getRotation,Gt as getVelocity,gt as move,H as moveBy,Mt as moveForwardXY,J as moveTo,Ot as moveX,At as moveXY,Et as moveXZ,zt as moveY,wt as moveZ,$ as onPress,tt as onRelease,it as parallel,rt as repeat,nt as repeatForever,U as resetEntityOpacity,bt as resetTransformStore,kt as resetVelocity,K as rotateBy,P as rotateEuler,G as rotateInDirection,I as rotateX,R as rotateY,D as rotateYEuler,X as rotateZ,et as sequence,Dt as setPosition,Pt as setPositionX,Rt as setPositionY,It as setPositionZ,F as setRotation,S as setRotationDegrees,j as setRotationDegreesX,B as setRotationDegreesY,q as setRotationDegreesZ,Z as setRotationX,Y as setRotationY,V as setRotationZ,W as throttle,Yt as wrapAround3D,Xt as wrapAroundXY};
+import{A as Q,B as R,C as S,D as T,E as U,a as q,b as r,c as s,d as t,e as u,f as v,g as w,h as x,i as y,j as z,k as A,l as B,m as C,n as D,o as E,p as F,q as G,r as H,s as I,t as J,u as K,v as L,w as M,x as N,y as O,z as P}from"./chunk-IPWUDOV5.js";import{a as p}from"./chunk-BH53MBAZ.js";import{a,b,c,d,e,f,g,h,i,j,k,l,m,n,o}from"./chunk-XRP4JJXL.js";export{p as applyTransformChanges,v as callFunc,E as createTransformStore,u as delay,w as fadeOpacity,N as getPosition,o as getRotation,O as getVelocity,F as move,r as moveBy,M as moveForwardXY,s as moveTo,G as moveX,J as moveXY,K as moveXZ,H as moveY,I as moveZ,y as onPress,z as onRelease,B as parallel,C as repeat,D as repeatForever,q as resetEntityOpacity,L as resetVelocity,t as rotateBy,c as rotateEuler,a as rotateInDirection,e as rotateX,d as rotateY,b as rotateYEuler,f as rotateZ,A as sequence,P as setPosition,Q as setPositionX,R as setPositionY,S as setPositionZ,m as setRotation,n as setRotationDegrees,j as setRotationDegreesX,h as setRotationDegreesY,l as setRotationDegreesZ,i as setRotationX,g as setRotationY,k as setRotationZ,x as throttle,U as wrapAround3D,T as wrapAroundXY};