@daneren2005/shared-memory-physics 1.3.0 → 1.5.0

package/README.md

@@ -362,6 +362,39 @@ A no-op for an entity with no velocity or no interpolation, or while the system
 by hand rather than through `PhysicsSystem`? Call the underlying `startSpawnInterpolation(entity, { stepMs,
 stepFraction, tick })` directly.
 
+### A moving death: `dieAtImpact`
+
+The same lag runs the other way at the end of a life. A fast entity moves a whole step at a time and, with
+`continuousCollisionDetection` on, is killed the run its *swept path* first crosses what it hits - which can be a
+near-full stride before its step actually lands there. Remove it on the spot and the render, itself a step behind,
+draws it blinking out well short of the target. A bullet dies in mid-air.
+
+`dieAtImpact` fixes it as the mirror of the spawn seeding: instead of `callbacks.entityDied`, a collision callback
+calls it to **end the dying entity's current segment on the exact point it struck** (`CollisionBroadphase.contactPoint`,
+the same entry fraction the sweep already refines) and **defer the kill by one run** - the one extra step the render
+needs to play that last stride onto the impact before the entity is gone:
+
+```ts
+onCollision(world, self, other, queries, callbacks) {
+  // `self` (a fast sensor bullet) just swept through `other`.  Draw it reaching `other`, then die - rather than
+  // vanishing a stride short.
+  world.dieAtImpact(self, other);
+
+  // Gameplay still happens now: the hit lands this run, only the visual removal waits.
+  callbacks.emitEntityEvent(other.entityId, 'hit');
+}
+```
+
+Either side of the pair can be the one to kill - `dieAtImpact(dying, other)` takes whichever carried the fatal
+role, working out that entity's own approach from its velocity. The struck entity is marked with a runtime `dying`
+bit (`BODY_DYING_FLAG`) that leaves it out of the broadphase at once, so nothing runs into it again while it plays
+out, and it is removed at the top of its next update. The bit lives in shared memory, so any worker stepping the
+entity honours it. Nothing clears it - a dying entity is gone a run later.
+
+`dieAtImpact` is set on the world every run by `createPhysicsUpdate`; keep a `callbacks.entityDied` fallback if you
+call `onCollision` by hand without a `preRun`. It moves position only - raise your own hit or score event on the
+spot, as above.
+
 ### The cost
 
 32 bytes per interpolated entity, three extra writes per entity per physics step, and a per-frame pass of one
@@ -458,7 +491,9 @@ value another thread also touches with the atomics from `@daneren2005/shared-mem
 the two entities in front of it - to credit a third for a kill, say - a callback can walk
 `queries[COLLIDABLE_QUERY]`, the full collidable list. Anything that has to happen on the main thread goes
 through `callbacks`: `entityDied`, `entityComponentChanged`, `createEntity`, and `emitEntityEvent` for an
-event of your own - the same one the move above reports itself through.
+event of your own - the same one the move above reports itself through. To kill a *fast* mover on impact and
+still have it drawn reaching what it hit, call `world.dieAtImpact(dying, other)` in place of `entityDied` - see
+[`dieAtImpact`](#a-moving-death-dieatimpact).
 
 **What collides.** Everything with a transform and a `body`, not only the entities the system moves, so a
 ship can run into a station that has no velocity of its own. Shapes that only just touch do not count as
@@ -632,14 +667,44 @@ body just swept, while the two-argument form (and every non-continuous body) tes
 
 ## Spatial queries
 
-`SpatialIndex` answers the other kind of question about where things are - who is in this area, and what is
-the closest thing to this point - for the systems that are not about collisions at all: targeting, aggro
-range, spawning somewhere clear, area effects. It is the same R-tree the broadphase is built on, without the
-collide categories or the shape tests.
+`PhysicalWorld` keeps every transformed entity in a live, shared `SharedSpatialMap`. The physics worker updates
+the entry immediately after it writes a final position, while entity add/remove and transform/body component
+changes are tracked on the main thread. That makes the same index available for occasional main-thread checks
+such as picking an entity under the mouse, and for worker systems that would otherwise rebuild an index for only
+a few queries:
+
+```ts
+import { PhysicalWorld, physicsRegistry } from '@daneren2005/shared-memory-physics';
+
+const world = new PhysicalWorld(physicsRegistry, {
+  spatial: { gridSize: 50, maxEntities: 100_000 },
+});
+
+const clicked = world.findNearestSpatial(mouseX, mouseY, 0);
+const nearby = world.searchSpatialAround(x, y, 100, 100);
+```
 
-Build one from anything shaped like a query result and it reads the transform (and the body, to know which
-outline that transform describes) off each entity. Only the transform is needed, so it indexes anything with
-a place in the world rather than only what collides:
+`searchSpatial`, `searchSpatialAround`, `findNearestSpatial`, and `findNearbySpatial` return live entities and
+accept entity filters. Shape-aware axis-aligned bounds are stored: rotated rectangles and capsules occupy the
+box around their actual outline. A direct transform/body edit outside the physics update must be followed by
+`world.updateSpatialEntity(entity)`. A custom physics wrapper that changes a transform after calling the library
+update can call `updateSpatialMap(workerWorld, entityId, components)` instead.
+
+`PhysicsSystem` requires a `PhysicalWorld` (or another `BaseWorld` that implements `PhysicalWorldSource`) and
+automatically shares its map with the physics worker. Another worker system can receive the same map by calling
+`addPhysicalWorldData(sourceWorld, runWorld)` from its system's `addDataToWorld`, then `getSpatialMap(runWorld)` in
+its update. The worker world must come from `@daneren2005/shared-memory-ecs` 1.5.1 or newer so it carries the
+shared heap used to reconstruct the map handle.
+
+The live map is intentionally not the collision or bulk-query hot path. `CollisionBroadphase` and
+`SpatialIndex` still use Flatbush snapshots: packing one immutable R-tree per run is faster when that run will
+make a large number of queries. Use the live map for continuous availability and sparse queries; use
+`SpatialIndex` for query-heavy systems such as targeting every entity every tick.
+
+`SpatialIndex` is the same R-tree the collision broadphase is built on, without collide categories or shape
+tests. Build one from anything shaped like a query result and it reads the transform (and the body, to know which
+outline that transform describes) off each entity. Only the transform is needed, so it indexes anything with a
+place in the world rather than only what collides:
 
 ```ts
 import { SpatialIndex } from '@daneren2005/shared-memory-physics';

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

@@ -30,8 +30,11 @@ 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 const BODY_DYING_FLAG = 16;
 export declare function bodyShape(body: Uint32Array): number;
 export declare function isSensor(body: Uint32Array): boolean;
 export declare function isContinuous(body: Uint32Array): boolean;
+export declare function isDying(body: Uint32Array): boolean;
+export declare function markDying(body: Uint32Array): void;
 export declare const bodyDefinition: ComponentDefinition<BodyComponent, Uint32Array, BodyConfig>;
 export default bodyDefinition;

package/dist/index.d.ts

@@ -4,8 +4,8 @@ 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, 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 { default as bodyDefinition, canCollide, isSensor, isContinuous, isDying, markDying, 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_DYING_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';
@@ -15,14 +15,16 @@ export { INTERPOLATION_X_INDEX, INTERPOLATION_Y_INDEX, INTERPOLATION_PREV_X_INDE
 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 { default as PhysicalWorld, addPhysicalWorldData, getSpatialMap } from './world';
+export type { PhysicalSystemWorld, PhysicalWorldData, PhysicalWorldSource, PhysicalWorldEntity, PhysicalWorldFilter, PhysicalWorldOptions, } from './world';
 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';
 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 { default as physicsUpdate, createPhysicsUpdate, POSITION_UPDATED_EVENT, updateSpatialMap } from './systems/physics-update';
+export type { DeathInterpolationEntity, 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';