@lagless/create 0.0.38 → 0.0.39

package/templates/pixi-react/docs/08-physics2d.md

@@ -0,0 +1,266 @@
+# Physics 2D (Rapier)
+
+## Overview
+
+`@lagless/physics2d` integrates [Rapier 2D](https://rapier.rs/) for deterministic rigid body physics. The framework manages Rapier world snapshots for rollback, body↔entity mapping, and transform synchronization.
+
+## Auto-Prepended Components
+
+When `simulationType: physics2d` is set in `ecs.yaml`, codegen auto-prepends:
+
+**Transform2d** (6 float32 fields):
+- `positionX`, `positionY` — current position
+- `rotation` — current rotation (radians)
+- `prevPositionX`, `prevPositionY` — previous position (for interpolation)
+- `prevRotation` — previous rotation
+
+**PhysicsRefs** (4 fields):
+- `bodyHandle: float64` — Rapier rigid body handle
+- `colliderHandle: float64` — Rapier collider handle
+- `bodyType: uint8` — body type enum (Dynamic, Fixed, etc.)
+- `collisionLayer: uint16` — collision layer bitmask
+
+**Do NOT declare these manually** — they are auto-prepended by codegen.
+
+## Body Types
+
+```typescript
+import { BodyType } from '@lagless/physics-shared';
+
+BodyType.DYNAMIC             // 0 — affected by forces and collisions
+BodyType.FIXED               // 1 — immovable (walls, ground)
+BodyType.KINEMATIC_POSITION  // 2 — moved by setting position directly
+BodyType.KINEMATIC_VELOCITY  // 3 — moved by setting velocity directly
+```
+
+## Creating Bodies and Colliders
+
+Use `PhysicsWorldManager2d` to create physics bodies:
+
+```typescript
+import { ECSSystem, IECSSystem } from '@lagless/core';
+import { PhysicsWorldManager2d } from '@lagless/physics2d';
+import { BodyType, CollisionLayers } from '@lagless/physics-shared';
+
+@ECSSystem()
+export class SpawnSystem implements IECSSystem {
+  constructor(
+    private readonly _physics: PhysicsWorldManager2d,
+    private readonly _entities: EntitiesManager,
+    private readonly _transform: Transform2d,
+  ) {}
+
+  update(tick: number): void {
+    // Create entity
+    const entity = this._entities.createEntity();
+    this._entities.addComponent(entity, Transform2d);
+    this._entities.addComponent(entity, PhysicsRefs);
+
+    // Set initial position
+    this._transform.set(entity, {
+      positionX: 100, positionY: 200,
+      prevPositionX: 100, prevPositionY: 200,
+      rotation: 0, prevRotation: 0,
+    });
+
+    // Create physics body + collider
+    this._physics.createBody(entity, {
+      bodyType: BodyType.DYNAMIC,
+      position: { x: 100, y: 200 },
+      rotation: 0,
+    });
+
+    this._physics.createCollider(entity, {
+      shape: { type: 'ball', radius: 20 },
+      density: 1.0,
+      friction: 0.5,
+      restitution: 0.3,
+      collisionLayer: CollisionLayers.get('player'),
+    });
+  }
+}
+```
+
+### Collider Shapes
+
+```typescript
+// Circle
+{ type: 'ball', radius: 20 }
+
+// Rectangle
+{ type: 'cuboid', hx: 50, hy: 25 }  // half-extents
+
+// Capsule
+{ type: 'capsule', halfHeight: 30, radius: 10 }
+
+// Convex polygon
+{ type: 'convexHull', points: [x1,y1, x2,y2, ...] }
+```
+
+## Collision Layers
+
+Named collision groups (max 16 layers). Control which objects collide with which.
+
+```typescript
+import { CollisionLayers } from '@lagless/physics-shared';
+
+// Register layers (call once at startup):
+CollisionLayers.register('player');
+CollisionLayers.register('wall');
+CollisionLayers.register('projectile');
+CollisionLayers.register('pickup');
+
+// Get layer value:
+const playerLayer = CollisionLayers.get('player');
+
+// Interaction groups — which layers collide:
+CollisionLayers.setInteraction('player', 'wall', true);
+CollisionLayers.setInteraction('player', 'projectile', true);
+CollisionLayers.setInteraction('projectile', 'wall', true);
+CollisionLayers.setInteraction('player', 'pickup', true);
+// player↔player collision:
+CollisionLayers.setInteraction('player', 'player', true);
+```
+
+## Collision Events
+
+Drain collision events in a system each tick:
+
+```typescript
+import { CollisionEvents2d } from '@lagless/physics2d';
+
+@ECSSystem()
+export class CollisionSystem implements IECSSystem {
+  constructor(
+    private readonly _collisionEvents: CollisionEvents2d,
+  ) {}
+
+  update(tick: number): void {
+    // Drain events (must be called every tick)
+    this._collisionEvents.drain();
+
+    // Process collision start events
+    for (let i = 0; i < this._collisionEvents.startCount; i++) {
+      const entityA = this._collisionEvents.startEntityA[i];
+      const entityB = this._collisionEvents.startEntityB[i];
+      // Handle collision between entityA and entityB
+    }
+
+    // Process collision end events
+    for (let i = 0; i < this._collisionEvents.endCount; i++) {
+      const entityA = this._collisionEvents.endEntityA[i];
+      const entityB = this._collisionEvents.endEntityB[i];
+      // Handle separation
+    }
+  }
+}
+```
+
+### Collision Events and Determinism
+
+Collision events are **ephemeral** — they are cleared each tick in `drain()` and regenerated on re-simulation after rollback. No snapshot storage needed. The Rapier EventQueue is stateless between ticks.
+
+## Physics Step System
+
+The physics step system advances the Rapier world and syncs transforms:
+
+```typescript
+import { ECSSystem, IECSSystem } from '@lagless/core';
+import { PhysicsWorldManager2d } from '@lagless/physics2d';
+
+@ECSSystem()
+export class PhysicsStepSystem implements IECSSystem {
+  constructor(
+    private readonly _physics: PhysicsWorldManager2d,
+  ) {}
+
+  update(tick: number): void {
+    this._physics.step();
+    // Rapier positions → ECS Transform2d (automatic)
+  }
+}
+```
+
+The `step()` method:
+1. Steps the Rapier world with the configured timestep
+2. Syncs Rapier body positions/rotations → ECS Transform2d component
+3. Drains collision events
+
+## ColliderEntityMap — Handle↔Entity Mapping
+
+Rapier uses Float64 handles to identify bodies and colliders. The `ColliderEntityMap` maps these to entity IDs.
+
+**Critical:** Rapier handles are Float64 values where the bit pattern encodes an arena index. `handle | 0` gives 0 for denormalized floats — **never** use bitwise OR for conversion. The framework uses `handleToIndex()` with Float64Array→Uint32Array reinterpretation.
+
+You generally don't interact with this directly — it's managed by `PhysicsWorldManager2d`.
+
+## Rollback
+
+On rollback:
+1. ArrayBuffer is restored → ECS state reverts
+2. Rapier world snapshot is restored → physics state reverts
+3. `updateSceneQueries()` is called → QueryPipeline is rebuilt
+
+**Critical fix applied:** `World.restoreSnapshot()` creates a world with an **empty** QueryPipeline (not serialized). The framework calls `updateSceneQueries()` after restore to fix this. Without it, ray casts and shape casts fail on the first tick after rollback.
+
+## State Transfer
+
+After `applyExternalState()` (late join / reconnect):
+1. Rapier world snapshot is applied alongside ArrayBuffer
+2. `ColliderEntityMap` is rebuilt by iterating all entities with PhysicsRefs
+3. Collision layers are re-applied
+
+This is handled automatically by the physics runner. You don't need to do anything special.
+
+## Complete Physics System Example
+
+```typescript
+import { ECSSystem, IECSSystem, AbstractInputProvider, ECSConfig, EntitiesManager } from '@lagless/core';
+import { MathOps } from '@lagless/math';
+import { PhysicsWorldManager2d, CollisionEvents2d } from '@lagless/physics2d';
+import { BodyType } from '@lagless/physics-shared';
+import { Transform2d, PhysicsRefs, PlayerBody, PlayerFilter, MoveInput } from '../code-gen/core.js';
+
+const finite = (v: number): number => Number.isFinite(v) ? v : 0;
+
+@ECSSystem()
+export class ApplyMoveInputSystem implements IECSSystem {
+  constructor(
+    private readonly _input: AbstractInputProvider,
+    private readonly _physics: PhysicsWorldManager2d,
+    private readonly _playerBody: PlayerBody,
+    private readonly _filter: PlayerFilter,
+    private readonly _config: ECSConfig,
+  ) {}
+
+  update(tick: number): void {
+    const rpcs = this._input.collectTickRPCs(tick, MoveInput);
+    for (const rpc of rpcs) {
+      const slot = rpc.meta.playerSlot;
+      let dirX = MathOps.clamp(finite(rpc.data.directionX), -1, 1);
+      let dirY = MathOps.clamp(finite(rpc.data.directionY), -1, 1);
+
+      for (const entity of this._filter) {
+        if (this._playerBody.unsafe.playerSlot[entity] !== slot) continue;
+
+        const speed = 300;
+        // Apply velocity to Rapier body
+        this._physics.setLinearVelocity(entity, {
+          x: dirX * speed,
+          y: dirY * speed,
+        });
+        break;
+      }
+    }
+  }
+}
+```
+
+## Tips
+
+- **Dynamic bodies** are moved by forces/impulses/velocity — never set position directly
+- **Kinematic bodies** are moved by setting position or velocity — not affected by forces
+- **Fixed bodies** never move — use for walls, ground, boundaries
+- **Substeps** — Rapier can run multiple sub-steps per tick for stability. Configure in physics config.
+- **Gravity** — set in physics world config. Default is (0, 0) for top-down games.
+- **CCD** — continuous collision detection prevents tunneling through thin walls at high speeds.

package/templates/pixi-react/docs/08-physics3d.md

@@ -0,0 +1,312 @@
+# Physics 3D (Rapier)
+
+## Overview
+
+`@lagless/physics3d` integrates [Rapier 3D](https://rapier.rs/) for deterministic rigid body physics. The framework manages Rapier world snapshots for rollback, body↔entity mapping, and transform synchronization.
+
+For character controllers, see also `@lagless/character-controller-3d`.
+
+## Auto-Prepended Components
+
+When `simulationType: physics3d` is set in `ecs.yaml`, codegen auto-prepends:
+
+**Transform3d** (14 float32 fields):
+- `positionX`, `positionY`, `positionZ` — current position
+- `rotationX`, `rotationY`, `rotationZ`, `rotationW` — current rotation (quaternion)
+- `prevPositionX`, `prevPositionY`, `prevPositionZ` — previous position
+- `prevRotationX`, `prevRotationY`, `prevRotationZ`, `prevRotationW` — previous rotation
+
+**PhysicsRefs** (4 fields):
+- `bodyHandle: float64` — Rapier rigid body handle
+- `colliderHandle: float64` — Rapier collider handle
+- `bodyType: uint8` — body type enum
+- `collisionLayer: uint16` — collision layer bitmask
+
+**Do NOT declare these manually** — they are auto-prepended by codegen.
+
+## Body Types
+
+```typescript
+import { BodyType } from '@lagless/physics-shared';
+
+BodyType.DYNAMIC             // 0 — affected by forces and collisions
+BodyType.FIXED               // 1 — immovable (walls, ground)
+BodyType.KINEMATIC_POSITION  // 2 — moved by setting position
+BodyType.KINEMATIC_VELOCITY  // 3 — moved by setting velocity
+```
+
+## Creating Bodies and Colliders
+
+```typescript
+import { PhysicsWorldManager3d } from '@lagless/physics3d';
+import { BodyType, CollisionLayers } from '@lagless/physics-shared';
+
+@ECSSystem()
+export class SpawnSystem implements IECSSystem {
+  constructor(
+    private readonly _physics: PhysicsWorldManager3d,
+    private readonly _entities: EntitiesManager,
+    private readonly _transform: Transform3d,
+  ) {}
+
+  update(tick: number): void {
+    const entity = this._entities.createEntity();
+    this._entities.addComponent(entity, Transform3d);
+    this._entities.addComponent(entity, PhysicsRefs);
+
+    this._transform.set(entity, {
+      positionX: 0, positionY: 5, positionZ: 0,
+      rotationX: 0, rotationY: 0, rotationZ: 0, rotationW: 1,
+      prevPositionX: 0, prevPositionY: 5, prevPositionZ: 0,
+      prevRotationX: 0, prevRotationY: 0, prevRotationZ: 0, prevRotationW: 1,
+    });
+
+    this._physics.createBody(entity, {
+      bodyType: BodyType.DYNAMIC,
+      position: { x: 0, y: 5, z: 0 },
+      rotation: { x: 0, y: 0, z: 0, w: 1 },
+    });
+
+    this._physics.createCollider(entity, {
+      shape: { type: 'ball', radius: 0.5 },
+      density: 1.0,
+      friction: 0.5,
+      restitution: 0.3,
+      collisionLayer: CollisionLayers.get('player'),
+    });
+  }
+}
+```
+
+### Collider Shapes (3D)
+
+```typescript
+// Sphere
+{ type: 'ball', radius: 0.5 }
+
+// Box
+{ type: 'cuboid', hx: 1, hy: 0.5, hz: 1 }  // half-extents
+
+// Capsule
+{ type: 'capsule', halfHeight: 0.5, radius: 0.3 }
+
+// Cylinder
+{ type: 'cylinder', halfHeight: 1.0, radius: 0.5 }
+
+// Convex hull
+{ type: 'convexHull', points: Float32Array }
+
+// Triangle mesh (static only)
+{ type: 'trimesh', vertices: Float32Array, indices: Uint32Array }
+```
+
+## Collision Layers and Events
+
+Same API as 2D — see [08-physics2d.md](08-physics2d.md) for `CollisionLayers` and `CollisionEvents` documentation. Use `CollisionEvents3d` instead of `CollisionEvents2d`.
+
+## Physics Step System
+
+```typescript
+@ECSSystem()
+export class PhysicsStepSystem implements IECSSystem {
+  constructor(private readonly _physics: PhysicsWorldManager3d) {}
+
+  update(tick: number): void {
+    this._physics.step();
+    // Rapier 3D positions/rotations → ECS Transform3d (automatic)
+  }
+}
+```
+
+## Character Controller (KCC)
+
+The `@lagless/character-controller-3d` library provides deterministic character movement using Rapier's KinematicCharacterController.
+
+### Setup
+
+```typescript
+import { CharacterControllerManager } from '@lagless/character-controller-3d';
+
+// Create manager (in runner setup or first system tick):
+const kccManager = new CharacterControllerManager(physicsWorld, {
+  offset: 0.01,           // skin width
+  maxSlopeClimbAngle: 0.8, // ~45 degrees
+  maxSlopeSlideAngle: 0.6, // ~34 degrees
+  stepHeight: 0.3,
+  snapToGround: 0.3,
+});
+```
+
+### Movement System
+
+```typescript
+@ECSSystem()
+export class CharacterMovementSystem implements IECSSystem {
+  constructor(
+    private readonly _kcc: CharacterControllerManager,
+    private readonly _input: AbstractInputProvider,
+    private readonly _transform: Transform3d,
+    private readonly _filter: PlayerFilter,
+    private readonly _config: ECSConfig,
+  ) {}
+
+  update(tick: number): void {
+    const rpcs = this._input.collectTickRPCs(tick, MoveInput);
+    for (const rpc of rpcs) {
+      let dirX = MathOps.clamp(finite(rpc.data.directionX), -1, 1);
+      let dirZ = MathOps.clamp(finite(rpc.data.directionZ), -1, 1);
+      const cameraYaw = finite(rpc.data.cameraYaw);
+
+      for (const entity of this._filter) {
+        if (this._playerBody.unsafe.playerSlot[entity] !== rpc.meta.playerSlot) continue;
+
+        // Rotate input by camera yaw
+        const sinYaw = MathOps.sin(cameraYaw);
+        const cosYaw = MathOps.cos(cameraYaw);
+        const worldX = dirX * cosYaw - dirZ * sinYaw;
+        const worldZ = dirX * sinYaw + dirZ * cosYaw;
+
+        const speed = 5.0;
+        const dt = this._config.frameLength;
+
+        // Move character via KCC
+        this._kcc.computeMovement(entity, {
+          x: worldX * speed * dt,
+          y: -9.81 * dt, // gravity
+          z: worldZ * speed * dt,
+        });
+
+        // Apply movement result
+        const result = this._kcc.getMovementResult(entity);
+        this._kcc.applyMovement(entity, result);
+
+        // Check grounding
+        const grounded = this._kcc.isGrounded(entity);
+        break;
+      }
+    }
+  }
+}
+```
+
+### Rollback with KCC
+
+After rollback, character controllers must be recreated:
+
+```typescript
+// The physics runner handles this automatically via recreateAll()
+// after Rapier world snapshot restore
+```
+
+## Animation Controller
+
+The `@lagless/animation-controller` library provides deterministic animation state machines.
+
+### AnimationStateMachine
+
+```typescript
+import { AnimationStateMachine } from '@lagless/animation-controller';
+
+const fsm = new AnimationStateMachine({
+  states: {
+    idle: { animation: 'idle', loop: true },
+    walk: { animation: 'walk', loop: true },
+    run: { animation: 'run', loop: true },
+    jump: { animation: 'jump', loop: false },
+  },
+  transitions: [
+    { from: 'idle', to: 'walk', condition: (ctx) => ctx.speed > 0.1 },
+    { from: 'walk', to: 'run', condition: (ctx) => ctx.speed > 3.0 },
+    { from: 'walk', to: 'idle', condition: (ctx) => ctx.speed < 0.1 },
+    { from: 'run', to: 'walk', condition: (ctx) => ctx.speed < 3.0 },
+    { from: '*', to: 'jump', condition: (ctx) => !ctx.grounded },
+    { from: 'jump', to: 'idle', condition: (ctx) => ctx.grounded },
+  ],
+  initialState: 'idle',
+  crossfadeDuration: 0.2,
+});
+```
+
+### LocomotionBlendCalculator
+
+Blends between idle/walk/run based on speed:
+
+```typescript
+import { LocomotionBlendCalculator } from '@lagless/animation-controller';
+
+const locomotion = new LocomotionBlendCalculator({
+  walkSpeed: 2.0,
+  runSpeed: 5.0,
+});
+
+// Each tick:
+const blend = locomotion.calculate(currentSpeed);
+// blend.idle, blend.walk, blend.run — weights summing to 1.0
+```
+
+### AnimationViewAdapter
+
+Connects deterministic animation state to 3D engine (BabylonJS, Three.js):
+
+```typescript
+import { AnimationViewAdapter } from '@lagless/animation-controller';
+
+const adapter = new AnimationViewAdapter(fsm, {
+  playAnimation: (name, options) => { /* play in 3D engine */ },
+  stopAnimation: (name) => { /* stop in 3D engine */ },
+  setWeight: (name, weight) => { /* blend weight */ },
+});
+
+// Each frame:
+adapter.update(deltaTime);
+```
+
+## System Execution Order for 3D
+
+```typescript
+export const systems = [
+  SavePrevTransformSystem,       // 1. Store prev positions/rotations
+  PlayerConnectionSystem,        // 2. Handle join/leave
+  ApplyMoveInputSystem,          // 3. Read inputs
+  CharacterMovementSystem,       // 4. KCC movement (before physics step)
+  PhysicsStepSystem,             // 5. Step Rapier, sync transforms
+  AnimationSystem,               // 6. Update animation FSM (after physics)
+  PlayerLeaveSystem,             // 7. Cleanup
+  HashVerificationSystem,        // 8. Always last
+];
+```
+
+## Rollback
+
+On rollback:
+1. ArrayBuffer is restored → ECS state reverts
+2. Rapier 3D world snapshot is restored → physics state reverts
+3. `updateSceneQueries()` is called → QueryPipeline is rebuilt
+4. KCC controllers are recreated via `recreateAll()`
+
+**Critical fix:** `World.restoreSnapshot()` creates a world with an empty QueryPipeline. The framework calls `updateSceneQueries()` after restore. Without this, `computeColliderMovement()` queries fail on the first tick after rollback.
+
+## State Transfer
+
+After `applyExternalState()`:
+1. Rapier 3D world snapshot is applied alongside ArrayBuffer
+2. `ColliderEntityMap` is rebuilt by iterating all entities with PhysicsRefs
+3. KCC controllers are recreated
+4. Collision layers are re-applied
+
+Handled automatically by the physics runner.
+
+## Rapier Handle Encoding
+
+Rapier WASM handles are **Float64** values where the bit pattern encodes an arena index in the low 32 bits.
+- Handle `0` = float64 `0.0`, handle `1` = float64 `5e-324` (Number.MIN_VALUE)
+- **NEVER** use `handle | 0` — gives 0 for all denormalized floats
+- The framework uses `handleToIndex()` with Float64Array→Uint32Array reinterpretation
+
+## Tips
+
+- **Gravity:** default is (0, -9.81, 0) for 3D. Set in physics config.
+- **Quaternion rotation:** rotationW=1 for identity rotation. Set all 4 components.
+- **KCC offset:** small positive value (0.01) prevents character from getting stuck in geometry
+- **System order matters:** KCC movement must run BEFORE PhysicsStep
+- **Animation updates** should run AFTER physics to use final position/velocity