@daneren2005/shared-memory-physics 1.4.0 → 1.6.0

package/README.md

@@ -18,8 +18,9 @@ npm install @daneren2005/shared-memory-physics @daneren2005/shared-memory-ecs @d
 
 | Component       | Config                                       | Serialization              | Block                                          |
 | --------------- | -------------------------------------------- | -------------------------- | ---------------------------------------------- |
+| `dynamics`      | -                                            | `accelerationX?`, `accelerationY?`, `mass?` | `Float32Array` - acceleration and inverse mass |
 | `transform`     | `width`, `height`, `angle?` / `radius`       | `x`, `y`, `angle`          | `Float32Array` – where, how big, facing        |
-| `velocity`      | –                                            | `velocityX?`, `velocityY?` | `Float32Array` – world units per second        |
+| `velocity`      | –                                            | `velocityX?`, `velocityY?`, `damping?` | `Float32Array` – world units per second        |
 | `body`          | `shape?`, `collideCategory?`, `collideMask?`, `sensor?`, `continuousCollisionDetection?` | –                          | `Uint32Array` – what shape, what collides with |
 | `interpolation` | `interpolate`                                | –                          | `Float32Array` – where to *draw* it            |
 
@@ -27,6 +28,34 @@ Entity configs are flat and shared across every component, so velocity is keyed
 rather than `x` / `y` (which already belong to the transform). Either velocity axis on its own is enough to
 load one, and the missing one defaults to `0`.
 
+`damping` is optional linear damping in fraction of speed per second: with it set, a mover started once bleeds
+speed off every step and coasts to a stop instead of gliding forever. It is applied implicitly as
+`velocity / (1 + damping * seconds)`, so it stays stable at any step size and never reverses direction. It
+defaults to `0` (no damping) and must be finite and at least zero. An explicit velocity assignment (a queued
+`queueVelocity`, or writing `velocityX` directly) is authoritative for that step and bypasses damping until the
+entity coasts again.
+
+```ts
+const shot = world.loadEntity({ x: 0, y: 0, radius: 3, velocityX: 400, damping: 2 });
+```
+
+`accelerationX` / `accelerationY` are persistent world units per second squared. Either one (or `mass`) loads a
+`dynamics` component; missing acceleration axes default to `0` and mass defaults to `1`. Physics uses
+semi-implicit Euler: it changes velocity by `acceleration * seconds` first, then moves by that new velocity in
+the same fixed step. That puts gravity on the physics backend instead of tying it to render frames:
+
+```ts
+world.loadEntity({
+  x: 0, y: 0, width: 20, height: 40,
+  velocityX: 0, velocityY: 0,
+  accelerationY: 1600,
+});
+```
+
+Mass is stored as inverse mass and round-trips through `save`; persistent acceleration does not depend on it.
+Mass must be finite and greater than zero, and acceleration must be finite. An entity without `dynamics` has
+effective mass `1` when a force or impulse is queued for it.
+
 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
@@ -52,14 +81,15 @@ its shape and categories back from the template rather than from the save. See
 
 ## Body shapes
 
-An entity is one of three shapes, and all three live in the same transform - so which one it is changes what
-that width and height *mean* rather than where they are kept:
+An entity is one of four shapes. The transform still owns its position, size and angle; a polygon additionally
+has a `polygon` component holding its outline:
 
 | `shape`           | Config                                | What it is                                                    |
 | ----------------- | ------------------------------------- | ------------------------------------------------------------- |
 | `SHAPE_RECTANGLE` | `width`, `height`                     | a `width` x `height` box turned to `angle` – the default      |
 | `SHAPE_CIRCLE`    | `radius`                              | a circle of diameter `width`, which `angle` does not affect   |
 | `SHAPE_CAPSULE`   | `width`, `height`, `shape`             | `width` from end to end, `height` thick, lying along `angle`  |
+| `SHAPE_POLYGON`   | `vertices`                             | a convex 3-16 vertex outline, scaled and turned by its transform |
 
 ```ts
 import { SHAPE_CAPSULE } from '@daneren2005/shared-memory-physics';
@@ -67,21 +97,30 @@ import { SHAPE_CAPSULE } from '@daneren2005/shared-memory-physics';
 world.loadEntity({ x: 0, y: 0, width: 10, height: 4 });                          // a rectangle
 world.loadEntity({ x: 0, y: 0, radius: 5 });                                     // a circle
 world.loadEntity({ x: 0, y: 0, width: 40, height: 10, shape: SHAPE_CAPSULE });   // a capsule
+world.loadEntity({ x: 0, y: 0, vertices: [[-8, -6], [10, 0], [-8, 6]] });       // a triangle
 ```
 
+Polygon vertices are local to the entity. They must describe a convex boundary in clockwise or counter-clockwise
+order; concave, collinear, non-finite, and out-of-range outlines throw during loading. Their bounding box becomes
+the transform's initial `width` and `height`, and the stored vertices are normalized around that box's centre.
+Changing the transform size therefore scales the polygon, while `angle` rotates it around that centre. Give
+`vertices` by themselves rather than alongside `radius` or `width`/`height`.
+
 `radius` is the same size said differently: it loads as a `width` and a `height` of the diameter, so there is
 still only one size in the block however the config spelled it. Giving both a `radius` and a `width` throws
 rather than one quietly winning. A config that says nothing about its `shape` is read off the size it gave - a
-`radius` describes a circle, anything else a rectangle - so **only capsules have to name their shape**, and an
+`vertices` describes a polygon, `radius` describes a circle, and anything else a rectangle - so **only capsules
+have to name their shape**, and an
 unrecognised one throws rather than quietly becoming a rectangle.
 
 A capsule's `width` is its **whole** length, caps included, and it lies along the way the entity faces: a 40x10
 capsule is a 30-long core with a 5 radius cap at each end, and it is the same 10 thick all the way down. One
 told it is no longer than it is wide collapses to a circle rather than turning itself inside out.
 
-Because a circle is a capsule whose core has no length, all three shapes are *an oriented core grown by a
+Because a circle is a capsule whose core has no length, the three primitive shapes are *an oriented core grown by a
 radius* - a box with no radius, a point, or a segment - which leaves only three overlap tests rather than one
-per pairing: box against box (the separating axis test), core against core, and core against box. Touching
+per primitive pairing: box against box (the separating axis test), core against core, and core against box.
+Those fast paths remain unchanged; only a pair involving a polygon enters the polygon separating-axis test. Touching
 exactly still counts as **not** overlapping, whichever pair it is, and a shape with no area never overlaps
 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.
@@ -92,7 +131,9 @@ such direction. It splits the same three ways off the same geometry, so the dire
 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
+`shapesOverlap` and `contactNormal` are the allocation-free primitive-shape functions. Their polygon counterparts
+are `polygonShapesOverlap` and `polygonContactNormal`, which additionally take the polygon component blocks.
+`shapeHalfWidth` / `shapeHalfHeight` (the axis-aligned box a shape is
 indexed under), `shapeRadius`, `shapeIsEmpty`, `capsuleHalfLength`, and the distance primitives underneath -
 `segmentSegmentDistanceSquared`, `segmentBoxDistanceSquared` and `pointSegmentDistanceSquared`, each of which
 takes an optional `out` vector and fills it with the gap it measured. `orientedBoxesOverlap`, `boundsHalfWidth`
@@ -119,8 +160,9 @@ console.log(entity.components.transform!.x); // 0
 
 ## PhysicsSystem
 
-`PhysicsSystem` moves every entity that has both a `transform` and a `velocity`, integrating velocity into
-position once per run - and, once you give it an update built by [`createPhysicsUpdate`](#collisions), tells
+`PhysicsSystem` moves every entity that has both a `transform` and a `velocity`, integrating optional acceleration
+and queued commands into velocity and then velocity into position once per run - and, once you give it an update built by
+[`createPhysicsUpdate`](#collisions), tells
 you which entities have run into each other. It is generic over your full component map, so your world passes
 straight in:
 
@@ -133,8 +175,49 @@ await world.init();
 world.update(1000); // one second: the entity above is now at x = 10
 ```
 
-`elapsedTime` is in milliseconds (what `BaseWorld#update` is driven with) and velocity is in world units per
-**second**, so a run covering 16ms moves an entity 16/1000ths of its velocity.
+`elapsedTime` is in milliseconds (what `BaseWorld#update` is driven with), velocity is in world units per
+**second**, and acceleration is in world units per **second squared**. A run covering 16ms first adds 16/1000ths
+of the acceleration to velocity, then moves 16/1000ths of that updated velocity.
+
+### Dynamics commands
+
+Queue forces, impulses, or velocity assignments on the `PhysicsSystem` that owns the mover. A force acts for the
+duration of the next physics run; an impulse changes velocity once without being scaled by that run's duration.
+Both are divided by the entity's mass. A velocity assignment replaces only the axes it names, after acceleration,
+force, and impulse integration but before movement, so it is exact and independent of mass:
+
+```ts
+const physics = world.addSystem(new PhysicsSystem(world));
+
+physics.queueForce(entity, 0, 20);       // next run: acceleration += force / mass
+physics.queueImpulse(entity, 12, -40);   // next run: velocity += impulse / mass
+physics.queueVelocity(entity, { velocityY: -980 }); // next run: set y without changing x
+```
+
+The methods also accept an entity id. Forces and impulses queued for the same entity before dispatch are summed;
+the last velocity assignment for each axis wins. Zero force/impulse vectors and empty velocity assignments are
+ignored. Non-finite values throw immediately.
+
+Commands have a strict run boundary. A command queued before dispatch belongs to that run and is consumed once.
+A command queued while a worker run is in flight belongs to the following run. A command is still consumed if
+its entity is absent from the mover query because it was removed, filtered, scoped out, or in a skipped group;
+queue it again when the entity becomes eligible. In a sharded simulation, queue on the system whose mover filter
+owns the entity.
+
+The same methods are available on `world` inside a `createPhysicsUpdate` collision callback, with entity ids:
+
+```ts
+onCollision(world, self, other, queries, callbacks, contact) {
+  world.queueVelocity(self.entityId, {
+    velocityX: contact.normalX * 480,
+    velocityY: -720,
+  });
+}
+```
+
+Callback commands always target the next run and survive between runs in either backend. They combine with
+commands queued through `PhysicsSystem`: forces and impulses add together, while a newer main-thread velocity
+assignment replaces a callback assignment on each axis it names.
 
 ### The step
 
@@ -167,8 +250,8 @@ class GamePhysicsSystem extends PhysicsSystem<Components, GameComponents, GameWo
 }
 ```
 
-`GameWorld` extends `PhysicsWorld` (which is `ComponentSystemWorld` plus that `tick`) rather than
-`ComponentSystemWorld` directly.
+`GameWorld` extends `PhysicsWorld` (which is `EntityWorkerSystemWorld` plus that `tick`) rather than
+`EntityWorkerSystemWorld` directly.
 
 A run's moves are reported back to the main thread as a single `position-updated` event **on the system**,
 carrying the ids of everything that moved, so anything you keep keyed off position can follow the moves
@@ -218,10 +301,10 @@ lives in your game and is handed to the system through `getWorker`:
 
 ```ts
 // physics.worker.ts
-import { createComponentWorker } from '@daneren2005/shared-memory-ecs';
+import { createEntitySystemWorker } from '@daneren2005/shared-memory-ecs';
 import { physicsUpdate } from '@daneren2005/shared-memory-physics';
 
-createComponentWorker(self, physicsUpdate);
+createEntitySystemWorker(self, physicsUpdate);
 ```
 
 ```ts
@@ -362,6 +445,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, contact) {
+  // `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
@@ -400,7 +516,6 @@ instead, which is also the only one that costs nothing per entity for the collid
 // game-physics-update.ts - imported by *both* the worker file and the system below
 import {
 	createPhysicsUpdate,
-	VELOCITY_X_INDEX,
 	VELOCITY_Y_INDEX,
 	type PhysicsUpdateComponents,
 } from '@daneren2005/shared-memory-physics';
@@ -412,10 +527,9 @@ export type GameUpdateComponents = PhysicsUpdateComponents & { health?: Float32A
 export const gamePhysicsUpdate = createPhysicsUpdate<Components, GameUpdateComponents>({
 	// Extra components to send along to the callback, on top of the transform and velocity.
 	optional: ['health'],
-	onCollision(world, self, other, queries, callbacks) {
-		// `self` just moved into `other`.  Bounce it back off whatever it hit...
-		self.components.velocity[VELOCITY_X_INDEX] *= -1;
-		self.components.velocity[VELOCITY_Y_INDEX] *= -1;
+	onCollision(world, self, other, queries, callbacks, contact) {
+		// `self` just moved into `other`. Throw it away from the contact on the next run.
+		world.queueImpulse(self.entityId, contact.normalX * 40, contact.normalY * 40);
 
 		// ...and take a bite out of the thing it ran into, if that is something with health.
 		const health = other.components.health;
@@ -429,10 +543,10 @@ export const gamePhysicsUpdate = createPhysicsUpdate<Components, GameUpdateCompo
 
 ```ts
 // physics.worker.ts
-import { createComponentWorker } from '@daneren2005/shared-memory-ecs';
+import { createEntitySystemWorker } from '@daneren2005/shared-memory-ecs';
 import { gamePhysicsUpdate } from './game-physics-update';
 
-createComponentWorker(self, gamePhysicsUpdate);
+createEntitySystemWorker(self, gamePhysicsUpdate);
 ```
 
 ```ts
@@ -445,12 +559,28 @@ 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.
 
+The final `contact` argument carries the unit normal at first touch as `normalX` and `normalY`. It points from
+`other` toward `self`; negate both values when applying it to `other`. This is the same shape-accurate direction
+used by native bounce, including rotated rectangles, circles, capsules, and polygons. A continuous sensor that
+crossed an entire target gets the normal where it entered, not from wherever its step ended after passing through.
+Exactly coincident shapes have no unique direction and report `(0, 0)`.
+
+```ts
+onCollision(world, self, other, queries, callbacks, contact) {
+  // Screen coordinates grow downwards, so a normal pointing up means self landed on other.
+  if (contact.normalY < -0.5) {
+    self.components.velocity[VELOCITY_Y_INDEX] = 0;
+  }
+}
+```
+
 **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
+and is not something to depend on. The normal follows that same ordering and always points away from `other`.
+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
@@ -458,7 +588,14 @@ 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).
+
+For a dynamics response that does not touch raw blocks, the callback world has `queueForce`, `queueImpulse`, and
+`queueVelocity`. They take an entity id and retain the command inside whichever backend is running, including a
+worker. A callback happens after this run's move, so its command is integrated at the start of the next run;
+deferring it also makes the outcome independent of which side of the pair updated first.
 
 **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
@@ -493,6 +630,22 @@ Two details worth knowing:
   forwards each run, so it reports no position change while it pushes - but it does keep reporting the
   collision for as long as it keeps pushing.
 
+By default, the sweep changes position but leaves velocity alone for an entity without `bounciness`, preserving
+the original behavior for games that implement their own response. Set `stopVelocityOnContact: true` on
+`createPhysicsUpdate` to opt into a non-bouncing solid response: physics removes only the velocity component
+pointing into the contact normal, so bodies stop naturally against floors, ceilings, walls, and slopes while
+keeping their motion along the surface.
+
+```ts
+export const gamePhysicsUpdate = createPhysicsUpdate<Components>({
+  stopVelocityOnContact: true,
+});
+```
+
+This applies to both sides of each solid contact when they have velocity. Sensors still pass through, and an
+entity with a `bounciness` component keeps its configured bounce instead; `bounciness: 0` remains equivalent to
+removing the inward velocity component.
+
 **What it costs.** A move is checked where it *ends*, so a clear one - which is nearly every move - is a single
 shape test against each thing near where it lands, and nothing more. Only a move that is genuinely stopping
 somewhere pays for working out where: contact is then halved in on rather than solved, since three shapes at any
@@ -601,6 +754,11 @@ it rather than adding a second system - the block offsets it reads are exported
 import { physicsUpdate, TRANSFORM_X_INDEX, VELOCITY_X_INDEX } from '@daneren2005/shared-memory-physics';
 ```
 
+Both `physicsUpdate` and updates built by `createPhysicsUpdate` integrate `dynamics` automatically. A custom
+update that replaces library movement owns that step too: request `dynamics` through the system's `optional`
+components and call `integrateDynamics(world, entityId, components.velocity, components.dynamics)` before
+turning velocity into movement.
+
 `CollisionBroadphase` is available the same way, for a system that wants the collision detection without the
 movement. Build one per run from a list of `{ entityId, components }` and how many **seconds** the run covers
 (that is what sizes the room left for movement), then ask it what any given entity is overlapping:
@@ -608,10 +766,17 @@ movement. Build one per run from a list of `{ entityId, components }` and how ma
 ```ts
 import { CollisionBroadphase, COLLIDABLE_QUERY } from '@daneren2005/shared-memory-physics';
 
-const broadphase = new CollisionBroadphase(queries[COLLIDABLE_QUERY], world.elapsedTime / 1000);
+const broadphase = new CollisionBroadphase(
+  queries[COLLIDABLE_QUERY],
+  world.elapsedTime / 1000,
+  world.dynamicsCommands,
+);
 broadphase.forEachOverlapping({ entityId, components }, other => { /* ... */ });
 ```
 
+The third argument is optional, but a custom update that applies queued commands in the same run must pass it so
+the index leaves enough travel room for the resulting velocity.
+
 `sweep` is the other half, for a system that moves things itself and wants the same
 [stopping at the edge](#stopping-at-the-edge). Hand it the move you were about to make and it says how much of
 it is available, along with whatever the rest of it would have run into:
@@ -632,14 +797,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

@@ -1,4 +1,5 @@
 import type { ComponentDefinition } from '@daneren2005/shared-memory-ecs';
+import type { PolygonVertex } from './polygon-component';
 export interface BodyComponent {
     index: number;
     shape: number;
@@ -10,6 +11,7 @@ export interface BodyComponent {
 export declare const SHAPE_RECTANGLE = 1;
 export declare const SHAPE_CIRCLE = 2;
 export declare const SHAPE_CAPSULE = 3;
+export declare const SHAPE_POLYGON = 4;
 export declare const DEFAULT_COLLIDE_CATEGORY = 1;
 export declare const DEFAULT_COLLIDE_MASK = 4294967295;
 export declare function canCollide(categoryA: number, maskA: number, categoryB: number, maskB: number): boolean;
@@ -18,6 +20,7 @@ export interface BodyConfig {
     height?: number;
     shape?: number;
     radius?: number;
+    vertices?: ReadonlyArray<PolygonVertex>;
     collideCategory?: number;
     collideMask?: number;
     sensor?: boolean;
@@ -27,11 +30,14 @@ 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_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_SHAPE_MASK = 7;
+export declare const BODY_SENSOR_FLAG = 8;
+export declare const BODY_CCD_FLAG = 16;
+export declare const BODY_DYING_FLAG = 32;
 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/components/dynamics-component.d.ts

@@ -0,0 +1,19 @@
+import type { ComponentDefinition } from '@daneren2005/shared-memory-ecs';
+export interface DynamicsComponent {
+    index: number;
+    accelerationX: number;
+    accelerationY: number;
+    mass: number;
+}
+export interface DynamicsConfig {
+    accelerationX?: number;
+    accelerationY?: number;
+    mass?: number;
+}
+export type DynamicsSerialization = DynamicsConfig;
+export declare const DYNAMICS_ACCELERATION_X_INDEX = 0;
+export declare const DYNAMICS_ACCELERATION_Y_INDEX = 1;
+export declare const DYNAMICS_INVERSE_MASS_INDEX = 2;
+export declare const DYNAMICS_SIZE = 3;
+export declare const dynamicsDefinition: ComponentDefinition<DynamicsComponent, Float32Array, DynamicsConfig, DynamicsSerialization>;
+export default dynamicsDefinition;

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

@@ -0,0 +1,22 @@
+import type { ComponentDefinition } from '@daneren2005/shared-memory-ecs';
+export type PolygonVertex = readonly [x: number, y: number];
+export interface PolygonConfig {
+    vertices?: ReadonlyArray<PolygonVertex>;
+}
+export interface PolygonComponent {
+    index: number;
+    readonly block: Float32Array;
+    readonly vertexCount: number;
+}
+export declare const MAX_POLYGON_VERTICES = 16;
+export declare const POLYGON_VERTEX_COUNT_INDEX = 0;
+export declare const POLYGON_VERTICES_INDEX = 1;
+export declare const POLYGON_SIZE: number;
+export interface PreparedPolygon {
+    width: number;
+    height: number;
+    vertices: Array<number>;
+}
+export declare const polygonDefinition: ComponentDefinition<PolygonComponent, Float32Array, PolygonConfig>;
+export declare function preparePolygon(vertices: ReadonlyArray<PolygonVertex> | undefined): PreparedPolygon;
+export default polygonDefinition;

package/dist/components/registry.d.ts

@@ -1,20 +1,26 @@
 import { type BodyComponent } from './body-component';
 import { type BouncinessComponent } from './bounciness-component';
+import { type DynamicsComponent } from './dynamics-component';
 import { type InterpolationComponent } from './interpolation-component';
+import { type PolygonComponent } from './polygon-component';
 import { type TransformComponent } from './transform-component';
 import { type VelocityComponent } from './velocity-component';
 export declare const physicsRegistry: {
     transform: import("@daneren2005/shared-memory-ecs").ComponentDefinition<TransformComponent, Float32Array<ArrayBufferLike>, import("./transform-component").TransformConfig, import("./transform-component").TransformSerialization>;
     velocity: import("@daneren2005/shared-memory-ecs").ComponentDefinition<VelocityComponent, Float32Array<ArrayBufferLike>, import("./velocity-component").VelocityConfig, import("./velocity-component").VelocityConfig>;
     body: import("@daneren2005/shared-memory-ecs").ComponentDefinition<BodyComponent, Uint32Array<ArrayBufferLike>, import("./body-component").BodyConfig, object>;
+    polygon: import("@daneren2005/shared-memory-ecs").ComponentDefinition<PolygonComponent, Float32Array<ArrayBufferLike>, import("./polygon-component").PolygonConfig, object>;
     bounciness: import("@daneren2005/shared-memory-ecs").ComponentDefinition<BouncinessComponent, Float32Array<ArrayBufferLike>, import("./bounciness-component").BouncinessConfig, object>;
+    dynamics: import("@daneren2005/shared-memory-ecs").ComponentDefinition<DynamicsComponent, Float32Array<ArrayBufferLike>, import("./dynamics-component").DynamicsConfig, import("./dynamics-component").DynamicsConfig>;
     interpolation: import("@daneren2005/shared-memory-ecs").ComponentDefinition<InterpolationComponent, Float32Array<ArrayBufferLike>, import("./interpolation-component").InterpolationConfig, object>;
 };
 export type PhysicsComponents = {
     transform: TransformComponent;
     velocity: VelocityComponent;
     body: BodyComponent;
+    polygon: PolygonComponent;
     bounciness: BouncinessComponent;
+    dynamics: DynamicsComponent;
     interpolation: InterpolationComponent;
 };
 export type InterpolationComponents = {
@@ -25,7 +31,9 @@ export type PhysicsUpdateComponents = {
     transform: Float32Array;
     velocity: Float32Array;
     body?: Uint32Array;
+    polygon?: Float32Array;
     bounciness?: Float32Array;
+    dynamics?: Float32Array;
     interpolation?: Float32Array;
     entity?: Uint32Array;
 };

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

@@ -1,4 +1,5 @@
 import type { ComponentDefinition } from '@daneren2005/shared-memory-ecs';
+import { type PolygonVertex } from './polygon-component';
 export interface TransformComponent {
     index: number;
     x: number;
@@ -12,6 +13,7 @@ export interface TransformConfig {
     height: number;
     angle?: number;
     radius?: number;
+    vertices?: ReadonlyArray<PolygonVertex>;
 }
 export interface TransformSerialization {
     x: number;

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

@@ -3,14 +3,17 @@ export interface VelocityComponent {
     index: number;
     velocityX: number;
     velocityY: number;
+    damping: number;
 }
 export interface VelocityConfig {
     velocityX?: number;
     velocityY?: number;
+    damping?: number;
 }
 export type VelocitySerialization = VelocityConfig;
 export declare const VELOCITY_X_INDEX = 0;
 export declare const VELOCITY_Y_INDEX = 1;
-export declare const VELOCITY_SIZE = 2;
+export declare const VELOCITY_DAMPING_INDEX = 2;
+export declare const VELOCITY_SIZE = 3;
 export declare const velocityDefinition: ComponentDefinition<VelocityComponent, Float32Array, VelocityConfig, VelocitySerialization>;
 export default velocityDefinition;

package/dist/index.d.ts

@@ -2,11 +2,17 @@ export { default as transformDefinition } from './components/transform-component
 export { TRANSFORM_X_INDEX, TRANSFORM_Y_INDEX, TRANSFORM_WIDTH_INDEX, TRANSFORM_HEIGHT_INDEX, TRANSFORM_ANGLE_INDEX, TRANSFORM_SIZE, } from './components/transform-component';
 export type { TransformComponent, TransformConfig, TransformSerialization, } from './components/transform-component';
 export { default as velocityDefinition } from './components/velocity-component';
-export { VELOCITY_X_INDEX, VELOCITY_Y_INDEX, VELOCITY_SIZE, } from './components/velocity-component';
+export { VELOCITY_X_INDEX, VELOCITY_Y_INDEX, VELOCITY_DAMPING_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 dynamicsDefinition } from './components/dynamics-component';
+export { DYNAMICS_ACCELERATION_X_INDEX, DYNAMICS_ACCELERATION_Y_INDEX, DYNAMICS_INVERSE_MASS_INDEX, DYNAMICS_SIZE, } from './components/dynamics-component';
+export type { DynamicsComponent, DynamicsConfig, DynamicsSerialization, } from './components/dynamics-component';
+export { default as bodyDefinition, canCollide, isSensor, isContinuous, isDying, markDying, bodyShape } from './components/body-component';
+export { SHAPE_RECTANGLE, SHAPE_CIRCLE, SHAPE_CAPSULE, SHAPE_POLYGON, 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 polygonDefinition, preparePolygon } from './components/polygon-component';
+export { MAX_POLYGON_VERTICES, POLYGON_VERTEX_COUNT_INDEX, POLYGON_VERTICES_INDEX, POLYGON_SIZE, } from './components/polygon-component';
+export type { PolygonComponent, PolygonConfig, PolygonVertex, PreparedPolygon } from './components/polygon-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';
@@ -15,16 +21,21 @@ 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 { polygonShapesOverlap, polygonContactNormal } from './math/polygons';
 export { default as CollisionBroadphase, COLLIDABLE_QUERY } from './systems/collision';
-export type { CollisionComponents, CollisionEntity, CollisionFunction, MoveResult, MovingEntity, SweepResult } from './systems/collision';
+export type { CollisionComponents, CollisionContact, 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 { PhysicsGroupConfig, PhysicsUpdateFunction, PhysicsUpdateMetadata, PhysicsUpdateOptions, PhysicsWorld } from './systems/physics-update';
+export { default as physicsUpdate, createPhysicsUpdate, POSITION_UPDATED_EVENT, updateSpatialMap } from './systems/physics-update';
+export type { DeathInterpolationEntity, PhysicsCallbackWorld, 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 type { PhysicsSystemConfig, VelocityAssignment } from './systems/physics-system';
+export { default as integrateDynamics } from './systems/dynamics';
+export type { DynamicsCommand, DynamicsCommandBuffer, DynamicsCommandQueue, DynamicsCommands, DynamicsWorld } from './systems/dynamics';
 export { default as interpolationUpdate } from './systems/interpolation-update';
 export { default as InterpolationSystem } from './systems/interpolation-system';
 export type { InterpolationSystemConfig } from './systems/interpolation-system';