@lagless/create 0.0.44 → 0.0.48

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

@@ -35,12 +35,13 @@ BodyType.KINEMATIC_VELOCITY  // 3 — moved by setting velocity directly
 
 ## Creating Bodies and Colliders
 
-Use `PhysicsWorldManager2d` to create physics bodies:
+Use `PhysicsWorldManager2d` to create physics bodies. The manager provides factory methods that return Rapier body/collider objects. You configure them via Rapier's native API, then store handles in the ECS `PhysicsRefs` component and register the collider for entity lookup.
 
 ```typescript
-import { ECSSystem, IECSSystem } from '@lagless/core';
+import { ECSSystem, IECSSystem, EntitiesManager } from '@lagless/core';
 import { PhysicsWorldManager2d } from '@lagless/physics2d';
 import { BodyType, CollisionLayers } from '@lagless/physics-shared';
+import { Transform2d, PhysicsRefs } from '../code-gen/core.js';
 
 @ECSSystem()
 export class SpawnSystem implements IECSSystem {
@@ -48,6 +49,7 @@ export class SpawnSystem implements IECSSystem {
     private readonly _physics: PhysicsWorldManager2d,
     private readonly _entities: EntitiesManager,
     private readonly _transform: Transform2d,
+    private readonly _physicsRefs: PhysicsRefs,
   ) {}
 
   update(tick: number): void {
@@ -56,45 +58,60 @@ export class SpawnSystem implements IECSSystem {
     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'),
-    });
+    // Set initial position in ECS (including prev for interpolation)
+    const t = this._transform.unsafe;
+    t.positionX[entity] = 100;
+    t.positionY[entity] = 200;
+    t.prevPositionX[entity] = 100;
+    t.prevPositionY[entity] = 200;
+    t.rotation[entity] = 0;
+    t.prevRotation[entity] = 0;
+
+    // Create a dynamic Rapier body and configure it
+    const body = this._physics.createDynamicBody();
+    body.setTranslation({ x: 100, y: 200 }, true);
+    body.setLinearDamping(5.0);
+
+    // Create a ball collider attached to the body
+    const groups = CollisionLayers.get('player');
+    const collider = this._physics.createBallCollider(20, body, groups);
+
+    // Store handles in ECS for later lookup
+    const pr = this._physicsRefs.unsafe;
+    pr.bodyHandle[entity] = body.handle;
+    pr.colliderHandle[entity] = collider.handle;
+    pr.bodyType[entity] = BodyType.DYNAMIC;
+    pr.collisionLayer[entity] = groups;
+
+    // Register collider→entity mapping (used by collision events)
+    this._physics.registerCollider(collider.handle, entity);
   }
 }
 ```
 
 ### Collider Shapes
 
+All collider factories take an optional `parent` body, `groups` (collision groups), and `activeEvents` bitmask:
+
 ```typescript
 // Circle
-{ type: 'ball', radius: 20 }
+this._physics.createBallCollider(radius, parent, groups, activeEvents);
 
-// Rectangle
-{ type: 'cuboid', hx: 50, hy: 25 }  // half-extents
+// Rectangle (half-extents)
+this._physics.createCuboidCollider(hx, hy, parent, groups, activeEvents);
 
 // Capsule
-{ type: 'capsule', halfHeight: 30, radius: 10 }
+this._physics.createCapsuleCollider(halfHeight, radius, parent, groups, activeEvents);
+
+// Convex polygon (returns null if hull computation fails)
+this._physics.createConvexHullCollider(new Float32Array([x1,y1, x2,y2, ...]), parent, groups, activeEvents);
 
-// Convex polygon
-{ type: 'convexHull', points: [x1,y1, x2,y2, ...] }
+// Triangle mesh (static geometry only)
+this._physics.createTrimeshCollider(vertices, indices, parent, groups, activeEvents);
+
+// Custom collider from a Rapier ColliderDesc
+const desc = this._physics.rapier.ColliderDesc.ball(10).setDensity(2.0).setFriction(0.5);
+this._physics.createColliderFromDesc(desc, parent);
 ```
 
 ## Collision Layers
@@ -199,9 +216,7 @@ You generally don't interact with this directly — it's managed by `PhysicsWorl
 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.
+3. `ColliderEntityMap` is rebuilt automatically
 
 ## State Transfer
 
@@ -217,7 +232,7 @@ This is handled automatically by the physics runner. You don't need to do anythi
 ```typescript
 import { ECSSystem, IECSSystem, AbstractInputProvider, ECSConfig, EntitiesManager } from '@lagless/core';
 import { MathOps } from '@lagless/math';
-import { PhysicsWorldManager2d, CollisionEvents2d } from '@lagless/physics2d';
+import { PhysicsWorldManager2d } from '@lagless/physics2d';
 import { BodyType } from '@lagless/physics-shared';
 import { Transform2d, PhysicsRefs, PlayerBody, PlayerFilter, MoveInput } from '../code-gen/core.js';
 
@@ -228,9 +243,9 @@ export class ApplyMoveInputSystem implements IECSSystem {
   constructor(
     private readonly _input: AbstractInputProvider,
     private readonly _physics: PhysicsWorldManager2d,
+    private readonly _physicsRefs: PhysicsRefs,
     private readonly _playerBody: PlayerBody,
     private readonly _filter: PlayerFilter,
-    private readonly _config: ECSConfig,
   ) {}
 
   update(tick: number): void {
@@ -244,11 +259,10 @@ export class ApplyMoveInputSystem implements IECSSystem {
         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,
-        });
+        // Get the Rapier body via its handle stored in PhysicsRefs
+        const body = this._physics.getBody(this._physicsRefs.unsafe.bodyHandle[entity]);
+        // Apply velocity directly on the Rapier body
+        body.setLinvel({ x: dirX * speed, y: dirY * speed }, true);
         break;
       }
     }

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

@@ -37,9 +37,13 @@ BodyType.KINEMATIC_VELOCITY  // 3 — moved by setting velocity
 
 ## Creating Bodies and Colliders
 
+The manager provides factory methods that return Rapier body/collider objects. You configure them via Rapier's native API, then store handles in the ECS `PhysicsRefs` component and register the collider for entity lookup.
+
 ```typescript
+import { ECSSystem, IECSSystem, EntitiesManager } from '@lagless/core';
 import { PhysicsWorldManager3d } from '@lagless/physics3d';
 import { BodyType, CollisionLayers } from '@lagless/physics-shared';
+import { Transform3d, PhysicsRefs } from '../code-gen/core.js';
 
 @ECSSystem()
 export class SpawnSystem implements IECSSystem {
@@ -47,6 +51,7 @@ export class SpawnSystem implements IECSSystem {
     private readonly _physics: PhysicsWorldManager3d,
     private readonly _entities: EntitiesManager,
     private readonly _transform: Transform3d,
+    private readonly _physicsRefs: PhysicsRefs,
   ) {}
 
   update(tick: number): void {
@@ -54,50 +59,74 @@ export class SpawnSystem implements IECSSystem {
     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'),
-    });
+    // Set initial position in ECS (including prev for interpolation)
+    const t = this._transform.unsafe;
+    t.positionX[entity] = 0;
+    t.positionY[entity] = 5;
+    t.positionZ[entity] = 0;
+    t.rotationX[entity] = 0;
+    t.rotationY[entity] = 0;
+    t.rotationZ[entity] = 0;
+    t.rotationW[entity] = 1;
+    t.prevPositionX[entity] = 0;
+    t.prevPositionY[entity] = 5;
+    t.prevPositionZ[entity] = 0;
+    t.prevRotationX[entity] = 0;
+    t.prevRotationY[entity] = 0;
+    t.prevRotationZ[entity] = 0;
+    t.prevRotationW[entity] = 1;
+
+    // Create a dynamic Rapier body and configure it
+    const body = this._physics.createDynamicBody();
+    body.setTranslation({ x: 0, y: 5, z: 0 }, true);
+    body.setRotation({ x: 0, y: 0, z: 0, w: 1 }, true);
+
+    // Create a ball collider attached to the body
+    const groups = CollisionLayers.get('player');
+    const collider = this._physics.createBallCollider(0.5, body, groups);
+
+    // Store handles in ECS for later lookup
+    const pr = this._physicsRefs.unsafe;
+    pr.bodyHandle[entity] = body.handle;
+    pr.colliderHandle[entity] = collider.handle;
+    pr.bodyType[entity] = BodyType.DYNAMIC;
+    pr.collisionLayer[entity] = groups;
+
+    // Register collider→entity mapping (used by collision events)
+    this._physics.registerCollider(collider.handle, entity);
   }
 }
 ```
 
 ### Collider Shapes (3D)
 
+All collider factories take an optional `parent` body, `groups` (collision groups), and `activeEvents` bitmask:
+
 ```typescript
 // Sphere
-{ type: 'ball', radius: 0.5 }
+this._physics.createBallCollider(radius, parent, groups, activeEvents);
 
-// Box
-{ type: 'cuboid', hx: 1, hy: 0.5, hz: 1 }  // half-extents
+// Box (half-extents, 3 dimensions)
+this._physics.createCuboidCollider(hx, hy, hz, parent, groups, activeEvents);
 
 // Capsule
-{ type: 'capsule', halfHeight: 0.5, radius: 0.3 }
+this._physics.createCapsuleCollider(halfHeight, radius, parent, groups, activeEvents);
+
+// Cylinder (3D only)
+this._physics.createCylinderCollider(halfHeight, radius, parent, groups, activeEvents);
 
-// Cylinder
-{ type: 'cylinder', halfHeight: 1.0, radius: 0.5 }
+// Cone (3D only)
+this._physics.createConeCollider(halfHeight, radius, parent, groups, activeEvents);
 
-// Convex hull
-{ type: 'convexHull', points: Float32Array }
+// Convex hull (returns null if hull computation fails)
+this._physics.createConvexHullCollider(new Float32Array([...]), parent, groups, activeEvents);
 
-// Triangle mesh (static only)
-{ type: 'trimesh', vertices: Float32Array, indices: Uint32Array }
+// Triangle mesh (static geometry only)
+this._physics.createTrimeshCollider(vertices, indices, parent, groups, activeEvents);
+
+// Custom collider from a Rapier ColliderDesc
+const desc = this._physics.rapier.ColliderDesc.ball(0.5).setDensity(2.0).setFriction(0.5);
+this._physics.createColliderFromDesc(desc, parent);
 ```
 
 ## Collision Layers and Events
@@ -281,11 +310,9 @@ export const systems = [
 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
+3. `ColliderEntityMap` is rebuilt automatically
 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()`:

package/templates/pixi-react/docs/09-recipes.md

@@ -360,3 +360,63 @@ export class ProjectileLifetimeSystem implements IECSSystem {
      this._arenaConfig.radius -= this._arenaConfig.shrinkRate;
    }
    ```
+<% if (simulationType === 'physics2d') { -%>
+
+## Add Procedural 2D Map
+
+1. **Install packages:**
+   ```bash
+   pnpm add @lagless/2d-map-generator @lagless/2d-map-renderer
+   ```
+
+2. **Define object types** in `simulation/src/lib/map-config/objects.ts`:
+   ```typescript
+   import type { MapObjectDef, MapObjectRegistry } from '@lagless/2d-map-generator';
+   import { RenderLayer, ShapeType, CANOPY_SENSOR_TAG } from '@lagless/2d-map-generator';
+
+   export enum ObjectType { Tree = 0 }
+
+   const TREE: MapObjectDef = {
+     typeId: ObjectType.Tree,
+     colliders: [
+       { shape: { type: ShapeType.Circle, radius: 30 } },
+       { shape: { type: ShapeType.Circle, radius: 128 }, isSensor: true, tag: CANOPY_SENSOR_TAG },
+     ],
+     visuals: [
+       { texture: 'tree-trunk', layer: RenderLayer.Ground },
+       { texture: 'tree-foliage', layer: RenderLayer.Canopy },
+     ],
+     scaleRange: [0.1, 0.2],
+     includeSensorsInBounds: true,
+   };
+
+   export const OBJECT_REGISTRY: MapObjectRegistry = new Map([[0, TREE]]);
+   ```
+
+3. **Create generator factory** in `simulation/src/lib/map-config/create-map-generator.ts`:
+   ```typescript
+   import { MapGenerator, BiomeFeature, ShoreFeature, GrassFeature,
+     ObjectPlacementFeature, PlacementKind, TerrainZone, STANDARD_BIOME,
+   } from '@lagless/2d-map-generator';
+   import { OBJECT_REGISTRY, ObjectType } from './objects.js';
+
+   export function createMapGenerator(): MapGenerator {
+     return new MapGenerator({ baseWidth: 720, baseHeight: 720, scale: 1, extension: 80, gridSize: 16 })
+       .addFeature(new BiomeFeature(), STANDARD_BIOME)
+       .addFeature(new ShoreFeature(), { inset: 48, divisions: 12, variation: 4 })
+       .addFeature(new GrassFeature(), { inset: 18, variation: 3 })
+       .addFeature(new ObjectPlacementFeature(), {
+         registry: OBJECT_REGISTRY,
+         stages: [{ kind: PlacementKind.Density, typeId: ObjectType.Tree, density: 100, terrainZone: TerrainZone.Grass }],
+       });
+   }
+   ```
+
+4. **Extend runner** — generate map + create physics colliders in constructor, call `capturePreStartState()` after.
+
+5. **Render** — use `MapTerrainRenderer` and `MapObjectRenderer` from `@lagless/2d-map-renderer`.
+
+6. **Canopy transparency** — use `extractCanopyZones()` + `isInsideCanopyZone()` per frame.
+
+> Full details: [docs/11-2d-map-generation.md](11-2d-map-generation.md)
+<% } -%>

package/templates/pixi-react/docs/10-common-mistakes.md

@@ -178,17 +178,12 @@ this._transform.unsafe.positionX[entity] = newX; // Physics will overwrite!
 ```
 **Correct:**
 ```typescript
-this._physics.setLinearVelocity(entity, { x: vx, y: vy });
+const body = this._physics.getBody(this._physicsRefs.unsafe.bodyHandle[entity]);
+body.setLinvel({ x: vx, y: vy }, true);
 // or
-this._physics.applyImpulse(entity, { x: fx, y: fy });
+body.applyImpulse({ x: fx, y: fy }, true);
 ```
-**Why:** PhysicsStep syncs Rapier→ECS, overwriting manual position changes. Move dynamic bodies via forces/velocity.
-
-### Forgetting updateSceneQueries After Restore
-
-The framework handles this automatically, but if you're doing custom Rapier operations:
-**Always** call `world.updateSceneQueries()` after `World.restoreSnapshot()`.
-**Why:** Restored worlds have empty QueryPipeline — ray casts and shape casts will miss all colliders.
+**Why:** PhysicsStep syncs Rapier→ECS, overwriting manual position changes. Move dynamic bodies via forces/velocity on the Rapier body.
 
 ## Multiplayer