@daneren2005/shared-memory-physics 1.2.2 → 1.4.0

package/README.md

@@ -18,9 +18,9 @@ npm install @daneren2005/shared-memory-physics @daneren2005/shared-memory-ecs @d
 
 | Component       | Config                                       | Serialization              | Block                                          |
 | --------------- | -------------------------------------------- | -------------------------- | ---------------------------------------------- |
-| `transform`     | `width`, `height`, `angle?` / `radius`       | `x`, `y`                   | `Float32Array` – where, how big, facing        |
+| `transform`     | `width`, `height`, `angle?` / `radius`       | `x`, `y`, `angle`          | `Float32Array` – where, how big, facing        |
 | `velocity`      | –                                            | `velocityX?`, `velocityY?` | `Float32Array` – world units per second        |
-| `body`          | `shape?`, `collideCategory?`, `collideMask?` | –                          | `Uint32Array` – what shape, what collides with |
+| `body`          | `shape?`, `collideCategory?`, `collideMask?`, `sensor?`, `continuousCollisionDetection?` | –                          | `Uint32Array` – what shape, what collides with |
 | `interpolation` | `interpolate`                                | –                          | `Float32Array` – where to *draw* it            |
 
 Entity configs are flat and shared across every component, so velocity is keyed as `velocityX` / `velocityY`
@@ -30,12 +30,13 @@ load one, and the missing one defaults to `0`.
 The transform is split in two. **Config** is what your entity template says - `width` and `height` are
 required, `angle` defaults to `0` - and a size is what loads the component at all: a config with neither a
 width nor a height does not get a transform. **Serialization** is the live state that changes as the world
-runs, so `save()` returns only `x` / `y` and a reloaded entity gets its size and starting facing back from
-your own template rather than the save.
+runs, so `save()` returns `x` / `y` and `angle`, while a reloaded entity gets its size back from your own
+template rather than the save.
 
 `x` / `y` are the **centre** of the box, not a corner: the box is rotated about that point and collision
 projects out from it in both directions. `angle` is in **radians** counter-clockwise from the +x axis, and
-nothing here writes it - it is yours to set, usually from the heading, and collision reads it. `width` /
+the physics never writes it - it is yours to set, usually from the heading, and collision reads it - but it
+round-trips through `save` so a turned entity comes back facing the same way. `width` /
 `height` are the unrotated size; a box with no area never overlaps anything, not even another box sharing its
 exact position.
 
@@ -308,8 +309,9 @@ happened rather than the one after, which is one frame of latency and nothing el
 
 - **Pause and `timeScale`** are free. `BaseWorld#runUpdate` skips every system while paused and scales the
   elapsed time it hands them, so the pacing stops and slows with the simulation on its own.
-- **Spawns** are free. The block is seeded from the entity's config, so something added between steps is drawn
-  standing where it was put rather than sliding in from the origin.
+- **Spawns at rest** are free. The block is seeded from the entity's config, so something added between steps is
+  drawn standing where it was put rather than sliding in from the origin. A spawn *already moving* is the one case
+  that needs a hand - see [`startInterpolation`](#a-moving-spawn-startinterpolation) below.
 - **Velocity changes, collisions and coming to rest** are all just steps the simulation took, and are drawn as
   they happened.
 
@@ -325,6 +327,41 @@ entity.components.transform!.x = 500;
 snapEntity(entity);   // drawn at 500 on the very next frame
 ```
 
+### A moving spawn: `startInterpolation`
+
+Blending has only one position for a brand-new entity - where it spawned - so it holds there until the first
+physics step gives it a second, up to a whole step later. For anything at rest that is exactly right (the bullet
+above stands where it was put). For something spawned *already moving* - a bullet leaving a barrel - that step of
+stillness reads as the shot hanging in the air before it goes.
+
+`startInterpolation` fixes it by **opening the render at the spawn point** and moving it out along the entity's own
+velocity at its true speed, **jumping the transform forward** to where that motion reaches by the time the first
+real step lands. So the entity is drawn leaving the spawn in its true direction from the very next frame, and the
+seeded segment hands straight over to the first step with no seam. How far it jumps - and how long the seeded
+segment lasts - is whatever is left of the current step, since that is when the first run lands:
+
+```ts
+const bullet = world.loadEntity({
+  x: 0, y: 0, velocityX: 400, velocityY: 0, radius: 3, interpolate: true,
+});
+physics.startInterpolation(bullet);   // drawn from the spawn point and moving out, not parked there until the first step
+```
+
+It reads the step and the accumulator off the system, so there is nothing to pass.
+
+**The jump skips a collision sweep.** It is a real move of the transform, applied without sweeping the span it
+covers, so the entity skips forward up to a step: it can **tunnel** through anything within that span of the spawn,
+and it runs that far ahead of where its velocity alone would have put it from then on. This is a deliberate trade
+for **spawned projectiles**, where leaving the muzzle instantly matters more than that first sweep - a shot fired
+*into* a target still lands inside it and is caught and killed by the next run's overlap test; only something thin
+enough to sit entirely within that jumped span is passed through uncaught. Reach for it on bullets and the like,
+not on something that must never skip a step of collision. Because the transform is jumped to the segment's end,
+the render is still never drawn ahead of the simulation.
+
+A no-op for an entity with no velocity or no interpolation, or while the system steps every frame. Driving physics
+by hand rather than through `PhysicsSystem`? Call the underlying `startSpawnInterpolation(entity, { stepMs,
+stepFraction, tick })` directly.
+
 ### The cost
 
 32 bytes per interpolated entity, three extra writes per entity per physics step, and a per-frame pass of one
@@ -469,6 +506,17 @@ thing in the way is thick, so at any normal frame rate it does not arise - a shi
 moves 1.6 of them per frame at 60fps. A fixed `deltaBetweenRuns` puts a ceiling on it if your game has anything
 fast enough to care.
 
+**Continuous collision detection** lifts that ceiling for the bodies that need it, without slowing down the
+ones that do not. Set `continuousCollisionDetection: true` on a body and its own move is tested along the whole
+path it swept this run rather than only where the step ends - so a bullet that steps clean past a target still
+comes to rest against it (or, if it is a sensor, still reports the pass through it). It is one extra swept-shape
+test per candidate and only for that body: every other body stays on the single end-of-move test. Each shape
+sweeps to a single covering shape - a rectangle to an oriented box spanning start to end, a circle or capsule to
+a capsule down its path - chosen to be a superset of the ground actually covered, so a contact is reported early
+at worst, never missed. A continuous body comes straight to rest at its first contact and does not corner-slide,
+which is the behaviour a fast thing wants anyway. Reach for it on the small, fast things that tunnel - bullets,
+thrown weapons - and leave it off everything else.
+
 ### Collision filtering
 
 Every body collides **as** a `collideCategory` and **with** a `collideMask`, both plain 32-bit fields. The
@@ -524,6 +572,26 @@ than off both. The pair is never missed, just attributed to the side that moved
 the entity that moves first gets the clear road: it takes its whole move, and the second one is the one that
 comes to rest against it.
 
+### Scoping a system to a group
+
+Categories decide which *kinds* of body collide; `scope` decides which *world* they collide in. A game that
+runs several independent groups at once - solar systems around the same origin, floors of a dungeon - gives
+each group its own `PhysicsSystem` with a `scope`, and each one then only ever sees, moves, or collides against
+the entities that pass it:
+
+```ts
+world.addSystem(new PhysicsSystem<Components>(world, {
+	updateFunction: gamePhysicsUpdate,
+	scope: entity => entity.components.solarSystem?.solarSystemId === solId,
+}));
+```
+
+Unlike a category rule - which every body in the world is still weighed against - a scoped-out body never
+enters this system's broadphase at all, so two groups whose boxes overlap around a shared origin cannot collide
+across the boundary, and the tree each run builds is only as big as its own group. `scope` is separate from the
+sharding `filter` (which narrows only *which* movers a worker steps, still sweeping the whole world so one
+simulation can spread across cores); an entity handed both has to pass each to be moved.
+
 ## Using physicsUpdate in your own system
 
 `physicsUpdate` is a plain `EntityUpdateFunction`, so a game that already has its own movement system can call
@@ -557,6 +625,11 @@ transform[TRANSFORM_Y_INDEX] += moveY * fraction;
 `blocking` is what the entity came to rest *against*, which `forEachOverlapping` will not report from that
 resting place: the two are touching rather than through each other.
 
+Both honour a body's `continuousCollisionDetection` flag. `sweep` picks it up on its own - a continuous body's
+move is swept along its whole path. `forEachOverlapping` needs the move handed to it, since it runs after the
+entity has already been put down: `forEachOverlapping(self, handle, moveX, moveY)` tests the path a continuous
+body just swept, while the two-argument form (and every non-continuous body) tests only where it now stands.
+
 ## Spatial queries
 
 `SpatialIndex` answers the other kind of question about where things are - who is in this area, and what is

package/dist/components/body-component.d.ts

@@ -5,6 +5,7 @@ export interface BodyComponent {
     collideCategory: number;
     collideMask: number;
     sensor: boolean;
+    continuousCollisionDetection: boolean;
 }
 export declare const SHAPE_RECTANGLE = 1;
 export declare const SHAPE_CIRCLE = 2;
@@ -20,12 +21,17 @@ export interface BodyConfig {
     collideCategory?: number;
     collideMask?: number;
     sensor?: boolean;
+    continuousCollisionDetection?: boolean;
 }
-export declare const BODY_SHAPE_INDEX = 0;
+export declare const BODY_FLAGS_INDEX = 0;
 export declare const BODY_CATEGORY_INDEX = 1;
 export declare const BODY_MASK_INDEX = 2;
-export declare const BODY_SENSOR_INDEX = 3;
-export declare const BODY_SIZE = 4;
+export declare const BODY_SIZE = 3;
+export declare const BODY_SHAPE_MASK = 3;
+export declare const BODY_SENSOR_FLAG = 4;
+export declare const BODY_CCD_FLAG = 8;
+export declare function bodyShape(body: Uint32Array): number;
 export declare function isSensor(body: Uint32Array): boolean;
+export declare function isContinuous(body: Uint32Array): boolean;
 export declare const bodyDefinition: ComponentDefinition<BodyComponent, Uint32Array, BodyConfig>;
 export default bodyDefinition;

package/dist/components/interpolation-component.d.ts

@@ -1,11 +1,16 @@
 import type { ComponentDefinition } from '@daneren2005/shared-memory-ecs';
 import type { TransformComponent } from './transform-component';
+import type { VelocityComponent } from './velocity-component';
 export interface InterpolationComponent {
     index: number;
     x: number;
     y: number;
     prevX: number;
     prevY: number;
+    progress: number;
+    syncedTick: number;
+    duration: number;
+    tick: number;
 }
 export interface InterpolationConfig {
     interpolate?: boolean;
@@ -29,4 +34,17 @@ export interface SnappableEntity {
     };
 }
 export declare function snapEntity(entity: SnappableEntity): void;
+export interface SpawnableEntity {
+    components: {
+        transform?: TransformComponent;
+        velocity?: VelocityComponent;
+        interpolation?: InterpolationComponent;
+    };
+}
+export interface SpawnInterpolationOptions {
+    stepMs: number;
+    stepFraction: number;
+    tick: number;
+}
+export declare function startSpawnInterpolation(entity: SpawnableEntity, options: SpawnInterpolationOptions): void;
 export default interpolationDefinition;

package/dist/components/transform-component.d.ts

@@ -16,6 +16,7 @@ export interface TransformConfig {
 export interface TransformSerialization {
     x: number;
     y: number;
+    angle: number;
 }
 export declare const TRANSFORM_X_INDEX = 0;
 export declare const TRANSFORM_Y_INDEX = 1;

package/dist/index.d.ts

@@ -4,15 +4,15 @@ export type { TransformComponent, TransformConfig, TransformSerialization, } fro
 export { default as velocityDefinition } from './components/velocity-component';
 export { VELOCITY_X_INDEX, VELOCITY_Y_INDEX, VELOCITY_SIZE, } from './components/velocity-component';
 export type { VelocityComponent, VelocityConfig, VelocitySerialization, } from './components/velocity-component';
-export { default as bodyDefinition, canCollide, isSensor } from './components/body-component';
-export { SHAPE_RECTANGLE, SHAPE_CIRCLE, SHAPE_CAPSULE, DEFAULT_COLLIDE_CATEGORY, DEFAULT_COLLIDE_MASK, BODY_SHAPE_INDEX, BODY_CATEGORY_INDEX, BODY_MASK_INDEX, BODY_SENSOR_INDEX, BODY_SIZE, } from './components/body-component';
+export { default as bodyDefinition, canCollide, isSensor, isContinuous, bodyShape } from './components/body-component';
+export { SHAPE_RECTANGLE, SHAPE_CIRCLE, SHAPE_CAPSULE, DEFAULT_COLLIDE_CATEGORY, DEFAULT_COLLIDE_MASK, BODY_FLAGS_INDEX, BODY_SHAPE_MASK, BODY_SENSOR_FLAG, BODY_CCD_FLAG, BODY_CATEGORY_INDEX, BODY_MASK_INDEX, BODY_SIZE, } from './components/body-component';
 export type { BodyComponent, BodyConfig, } from './components/body-component';
 export { default as bouncinessDefinition } from './components/bounciness-component';
 export { BOUNCINESS_INDEX, BOUNCINESS_SIZE, } from './components/bounciness-component';
 export type { BouncinessComponent, BouncinessConfig, } from './components/bounciness-component';
-export { default as interpolationDefinition, snapEntity } from './components/interpolation-component';
+export { default as interpolationDefinition, snapEntity, startSpawnInterpolation } from './components/interpolation-component';
 export { INTERPOLATION_X_INDEX, INTERPOLATION_Y_INDEX, INTERPOLATION_PREV_X_INDEX, INTERPOLATION_PREV_Y_INDEX, INTERPOLATION_PROGRESS_INDEX, INTERPOLATION_SYNCED_TICK_INDEX, INTERPOLATION_DURATION_INDEX, INTERPOLATION_TICK_INDEX, INTERPOLATION_SIZE, } from './components/interpolation-component';
-export type { InterpolationComponent, InterpolationConfig, SnappableEntity, } from './components/interpolation-component';
+export type { InterpolationComponent, InterpolationConfig, SnappableEntity, SpawnableEntity, SpawnInterpolationOptions, } from './components/interpolation-component';
 export { physicsRegistry } from './components/registry';
 export type { PhysicsComponents, PhysicsUpdateComponents, InterpolationComponents, InterpolationUpdateComponents, } from './components/registry';
 export { shapesOverlap, contactNormal, shapeHalfWidth, shapeHalfHeight, shapeIsEmpty, shapeRadius, capsuleHalfLength, boundsHalfWidth, boundsHalfHeight, orientedBoxesOverlap, segmentSegmentDistanceSquared, segmentBoxDistanceSquared, pointSegmentDistanceSquared, } from './math/shapes';
@@ -22,7 +22,7 @@ export type { CollisionComponents, CollisionEntity, CollisionFunction, MoveResul
 export { default as SpatialIndex } from './systems/spatial-index';
 export type { SpatialComponents, SpatialEntity, SpatialFilter } from './systems/spatial-index';
 export { default as physicsUpdate, createPhysicsUpdate, POSITION_UPDATED_EVENT } from './systems/physics-update';
-export type { PhysicsUpdateFunction, PhysicsUpdateMetadata, PhysicsUpdateOptions, PhysicsWorld } from './systems/physics-update';
+export type { PhysicsGroupConfig, PhysicsUpdateFunction, PhysicsUpdateMetadata, PhysicsUpdateOptions, PhysicsWorld } from './systems/physics-update';
 export { default as PhysicsSystem, DEFAULT_PHYSICS_STEP_MS } from './systems/physics-system';
 export type { PhysicsSystemConfig } from './systems/physics-system';
 export { default as interpolationUpdate } from './systems/interpolation-update';