@daneren2005/shared-memory-physics 1.2.1 → 1.3.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.
 
@@ -85,10 +86,17 @@ exactly still counts as **not** overlapping, whichever pair it is, and a shape w
 anything. Which of the two sizes decides that depends on the shape: a circle with no height is a perfectly
 good circle, while a rectangle with no height is nothing at all.
 
+`contactNormal` answers the other half of a contact: the unit direction one shape is pushed off the other,
+written into a `{ x, y }` you pass in, and `false` when the two are exactly on top of each other and there is no
+such direction. It splits the same three ways off the same geometry, so the direction is the face that was
+actually hit at the angle the pair is turned to - not the nearest world axis. This is what the native bounce
+reflects around; a game reaching for its own response can use it the same way.
+
 `shapesOverlap` is exported, along with `shapeHalfWidth` / `shapeHalfHeight` (the axis-aligned box a shape is
 indexed under), `shapeRadius`, `shapeIsEmpty`, `capsuleHalfLength`, and the distance primitives underneath -
-`segmentSegmentDistanceSquared`, `segmentBoxDistanceSquared` and `pointSegmentDistanceSquared`.
-`orientedBoxesOverlap`, `boundsHalfWidth` and `boundsHalfHeight` are still there and still rectangle-only.
+`segmentSegmentDistanceSquared`, `segmentBoxDistanceSquared` and `pointSegmentDistanceSquared`, each of which
+takes an optional `out` vector and fills it with the gap it measured. `orientedBoxesOverlap`, `boundsHalfWidth`
+and `boundsHalfHeight` are still there and still rectangle-only.
 
 ## Registering
 
@@ -301,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.
 
@@ -318,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
@@ -401,11 +445,13 @@ world.addSystem(new PhysicsSystem<Components, GameUpdateComponents>(world, {
 `createPhysicsUpdate` stamps what it needs onto the function it returns, so `optional` and the collidable
 query come across with `updateFunction` and never have to be repeated on the system.
 
-**Per entity, not per pair.** The callback fires for the entity that *moved*, once for each thing it ended up
-on top of. `self` is that entity, with every block the system asked for; `other` is what it hit, where only
-`transform` is guaranteed. Two moving entities that run into each other therefore get one call each with the
-roles swapped - which is what lets a callback act on itself and leave the other side to its own call. An
-entity with no velocity is never `self`, because the system never moves it, but it is still found as `other`.
+**Once per pair, per run.** Both sides of a contact find it - one by sweeping into it, the other by overlapping
+it on its own turn - and the callback fires once, for whichever got there first. `self` is that entity, with
+every block the system asked for; `other` is the one it hit, where only `transform` is guaranteed. **The other
+side gets no call of its own**, so a callback that only touches `self` leaves it untouched: apply damage, tag a
+kill, or raise an event for *both* entities in the one call. Which of the two is `self` follows update order
+and is not something to depend on. An entity with no velocity is never `self`, because the system never moves
+it, but it is still found as `other`.
 
 Writes go straight into shared memory, so a callback can bounce an entity by flipping its velocity, or push a
 value another thread also touches with the atomics from `@daneren2005/shared-memory-objects`. To reach past
@@ -460,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
@@ -515,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
@@ -548,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
@@ -600,8 +682,8 @@ npm start          # http://127.0.0.1:8080
 ```
 
 - **Bouncing circles** - circles with a random position and heading, reflected off each other and off the
-  walls by an `onCollision` that mirrors the velocity about the contact normal.
-- **Bouncing rectangles** - the same, on boxes of random width and height, where the normal is the axis the
+  walls by the native bounce, which mirrors the velocity about the contact normal.
+- **Bouncing rectangles** - the same, on boxes of random width and height, where the normal is the face the
   two are least through each other on rather than the line between their centres.
 - **Walking into a wall** - one unit between two boxes, turned around on a timer so it presses into each of
   them in turn. It starts on a deliberately long 100ms physics step, so turning **interpolate rendering** off 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/registry.d.ts

@@ -27,6 +27,7 @@ export type PhysicsUpdateComponents = {
     body?: Uint32Array;
     bounciness?: Float32Array;
     interpolation?: Float32Array;
+    entity?: Uint32Array;
 };
 export type InterpolationUpdateComponents = {
     transform: Float32Array;

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,18 +4,19 @@ 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, shapeHalfWidth, shapeHalfHeight, shapeIsEmpty, shapeRadius, capsuleHalfLength, boundsHalfWidth, boundsHalfHeight, orientedBoxesOverlap, segmentSegmentDistanceSquared, segmentBoxDistanceSquared, pointSegmentDistanceSquared, } from './math/shapes';
+export { shapesOverlap, contactNormal, shapeHalfWidth, shapeHalfHeight, shapeIsEmpty, shapeRadius, capsuleHalfLength, boundsHalfWidth, boundsHalfHeight, orientedBoxesOverlap, segmentSegmentDistanceSquared, segmentBoxDistanceSquared, pointSegmentDistanceSquared, } from './math/shapes';
+export type { Vector } from './math/shapes';
 export { default as CollisionBroadphase, COLLIDABLE_QUERY } from './systems/collision';
 export type { CollisionComponents, CollisionEntity, CollisionFunction, MoveResult, MovingEntity, SweepResult } from './systems/collision';
 export { default as SpatialIndex } from './systems/spatial-index';