@daneren2005/shared-memory-physics 0.0.1 → 1.1.0

package/README.md

@@ -14,11 +14,12 @@ npm install @daneren2005/shared-memory-physics @daneren2005/shared-memory-ecs @d
 
 ## Components
 
-| Component   | Config                                       | Serialization              | Block                                          |
-| ----------- | -------------------------------------------- | -------------------------- | ---------------------------------------------- |
-| `transform` | `width`, `height`, `angle?` / `radius`       | `x`, `y`                   | `Float32Array` – where, how big, facing        |
-| `velocity`  | –                                            | `velocityX?`, `velocityY?` | `Float32Array` – world units per second        |
-| `body`      | `shape?`, `collideCategory?`, `collideMask?` | –                          | `Uint32Array` – what shape, what collides with |
+| Component       | Config                                       | Serialization              | Block                                          |
+| --------------- | -------------------------------------------- | -------------------------- | ---------------------------------------------- |
+| `transform`     | `width`, `height`, `angle?` / `radius`       | `x`, `y`                   | `Float32Array` – where, how big, facing        |
+| `velocity`      | –                                            | `velocityX?`, `velocityY?` | `Float32Array` – world units per second        |
+| `body`          | `shape?`, `collideCategory?`, `collideMask?` | –                          | `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`
 rather than `x` / `y` (which already belong to the transform). Either velocity axis on its own is enough to
@@ -36,6 +37,10 @@ nothing here writes it - it is yours to set, usually from the heading, and colli
 `height` are the unrotated size; a box with no area never overlaps anything, not even another box sharing its
 exact position.
 
+`interpolation` is where to **draw** an entity, which stops being the same thing as where it is the moment
+physics runs less often than the screen refreshes. It is opt-in per entity (`interpolate: true`) and filled in
+by [`InterpolationSystem`](#interpolation) - see that section for what it costs and what it buys.
+
 The `body` is what makes an entity collidable, and a size loads one just as it loads a transform - so
 everything with a place in the world collides with everything else until you say otherwise. All of it is
 defining config out of your own template, which is why `save` returns nothing for it: a reloaded entity gets
@@ -121,17 +126,77 @@ 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.
 
-Each axis an entity actually moved along is reported back to the main thread as a `component-property-updated`
-event, so anything you keep keyed off position can follow a move rather than having to poll the block:
+### The step
+
+`PhysicsSystem` runs on a fixed step of **50ms** unless you say otherwise (`DEFAULT_PHYSICS_STEP_MS`). Collision
+is by a distance the whole of it, so running it 20 times a second rather than 60 is two thirds less of the frame
+spent on it for a simulation that is no less correct - only coarser. What that costs is smoothness, which is
+what [`InterpolationSystem`](#interpolation) is for.
+
+```ts
+new PhysicsSystem(world, { deltaBetweenRuns: 0 });   // back to every frame
+```
+
+The step has one real ceiling: a move is swept where it *ends*, so **a longer step is a longer move, and a move
+longer than the thing in its way is thick goes clean through it**. At 50ms an entity crossing 300 units a second
+covers 15 of them per step, so anything it must be stopped by has to be thicker than that. A game with genuinely
+fast entities either keeps the step short or makes its walls thick.
+
+The system accumulates frame time and runs once it has a step's worth, so a 16ms frame runs physics on roughly
+every third one and hands it the whole 50ms. Nothing is lost and nothing is run twice.
+
+`PhysicsSystem` also stamps each run with a `tick`, which is what the interpolation block is published under.
+A game that subclasses the system to attach per-run data of its own **must call `super.addDataToWorld(world)`**:
+
+```ts
+class GamePhysicsSystem extends PhysicsSystem<Components, GameComponents, GameWorld> {
+	addDataToWorld(world: GameWorld): void {
+		super.addDataToWorld(world);   // without this, nothing gets a tick
+		world.bounds = this.bounds;
+	}
+}
+```
+
+`GameWorld` extends `PhysicsWorld` (which is `ComponentSystemWorld` plus that `tick`) rather than
+`ComponentSystemWorld` 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
+rather than having to poll every block:
 
 ```ts
-entity.on('component-property-updated', (componentName, prop, value) => {
-	// 'transform', 'x', 12.5
+import { POSITION_UPDATED_EVENT } from '@daneren2005/shared-memory-physics';
+
+const physics = world.addSystem(new PhysicsSystem(world));
+
+physics.on(POSITION_UPDATED_EVENT, (entityIds: Array<number>) => {
+	for(const eid of entityIds) {
+		const transform = world.getEntityByEid(eid)?.components.transform;
+		// transform.x / transform.y are where it ended up
+	}
 });
 ```
 
-An axis that did not move says nothing, so a world of still entities stays quiet - and so does an entity held
-against something it cannot move past.
+Nearly every entity moves on nearly every run, so this is the one thing a physics system must not report an
+entity at a time: an event object apiece in the worker, cloned across the boundary, then a lookup and an emit
+apiece on the main thread costs more, at a few thousand entities, than moving them did. One array of ids
+costs one listener call for the whole run.
+
+No position travels with the id, because there is no need: the transform is a `SharedArrayBuffer` block, so
+the position the worker wrote is already on the main thread by the time the event lands - read it off the
+entity (or straight off the block). The move is not reported as a property change either, so a listener on
+`component-property-updated` never hears about positions.
+
+An entity that did not move is not in the list, so a world of still entities stays quiet - and so does one
+held against something it cannot move past.
+
+**A run only reports at all when something is listening.** The bill for this event is paid in the worker - an id
+per moved entity pushed into the run's event array, and that array structured-cloned back across the boundary -
+so `PhysicsSystem` checks per run whether it has a listener and tells the update not to bother when it does not.
+That matters most for a game rendering from [`interpolation`](#interpolation), which wants nothing to do with an
+event that fires at the physics rate: it is the rate that game is drawing *around*. Nothing has to be
+configured for it, but `reportMoves: true` forces it on for a listener attached somewhere the system cannot see
+it, and `reportMoves: false` turns it off regardless.
 
 The move is written with `addAtomicFloat32` rather than a plain `+=`, so a game system on another thread can
 add to the same position in the same instant without either move being lost.
@@ -160,13 +225,130 @@ world.addSystem(new PhysicsSystem(world, {
 Without a `getWorker` (or where Web Workers / `SharedArrayBuffer` are unavailable) the exact same
 `physicsUpdate` runs in-process on the main thread instead.
 
+## Interpolation
+
+A 50ms physics step against a 16ms frame means the transform only changes on one frame in three, and an entity
+drawn straight off it visibly stutters. `InterpolationSystem` fills in a **render position** that changes every
+frame instead, by blending between the two positions physics published either side of its last step:
+
+```
+render = prev + (current - prev) * alpha
+```
+
+Every position it writes is therefore one the simulation actually produced - somewhere on the segment between
+two real ones, never a guess past the end of one. There is nothing to tune and no case where it draws something
+that did not happen: an entity that stopped against a wall is drawn easing into the wall and stopping, and one
+that turned a corner is drawn turning the corner rather than carrying on into its old heading for a frame and
+being snapped back. The cost is **one step of latency, always** - what is on screen is where the world was a
+step ago.
+
+```ts
+import { InterpolationSystem, PhysicsSystem } from '@daneren2005/shared-memory-physics';
+
+world.addSystem(new PhysicsSystem<Components>(world, { getWorker }));
+world.addSystem(new InterpolationSystem<Components>(world));
+
+world.loadEntity({ x: 0, y: 0, width: 10, height: 10, velocityX: 100, interpolate: true });
+```
+
+It takes no configuration and is not wired to the physics system. Everything it needs - the two positions, how
+much simulated time lies between them, and whether that pair is new - is published into the block by whichever
+run wrote it, so a game that retunes `deltaBetweenRuns` mid-flight is followed with nothing told to this system.
+
+Then draw from `interpolation` instead of `transform`, keeping the size and facing where they have always been:
+
+```ts
+const { x, y } = entity.components.interpolation ?? entity.components.transform!;
+const { width, height, angle } = entity.components.transform!;
+```
+
+Draw from it **every frame**, not from `position-updated`. That event fires once per physics step, which is
+exactly the cadence interpolation exists to hide - a sprite moved by it would be as choppy as one reading the
+transform. Once nothing is listening to it, `PhysicsSystem` stops reporting moves at all and the whole event
+costs nothing; see [the note above](#the-step).
+
+**Only rendering should read it.** Range checks, targeting, AI steering, "can I build here" and anything you
+persist all want `transform` - the real position. The render position is a function of local frame timing, so
+two machines drawing the same simulation at 144Hz and 30Hz hold *different* numbers in it at the same tick;
+anything that branches on it stops being deterministic. Nothing in this library ever reads it back, which is
+what keeps the simulation itself unaffected.
+
+### A slow physics run costs latency and nothing else
+
+This is the property the whole thing is for, and it is worth being explicit about because it is easy to build
+something that looks right and does not have it. **If a physics run takes longer than a frame, nothing about the
+motion changes** - it is drawn a little further behind, at exactly the same speed. A worker that consistently
+takes 30ms to come back costs 30ms of latency, which is not something an eye can see; only *variance* in how
+late it is can be seen at all.
+
+That works because the pacing is driven by the steps that have **landed** in the block, not by the physics
+system's own accumulator. The accumulator resets when a run is *posted*, and on a worker thread that is not when
+its results arrive - a run posted with 14ms of leftover and taking 30ms to come back leaves a whole frame where
+the accumulator says "0.3 of the way into the new step" while the block still holds the one before it, so the
+entity is drawn 0.3 along a segment it was drawn 0.96 along last frame. Backwards, then a lurch forward, on
+every step.
+
+For the same reason each run publishes **how much simulated time it covered** rather than that being assumed to
+be the step: a run that comes back late leaves more than a step's worth banked, and the next one covers two at
+once. Dividing that segment by the step would draw it at double speed.
+
+Ordering against the physics system is only a preference - after it means a step is picked up on the frame it
+happened rather than the one after, which is one frame of latency and nothing else.
+
+### What it does not need
+
+- **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.
+- **Velocity changes, collisions and coming to rest** are all just steps the simulation took, and are drawn as
+  they happened.
+
+### What it does need: `snapEntity`
+
+A teleport and a long move are the same two numbers, so this is the one thing blending cannot work out for
+itself. Write a transform directly and the entity is drawn sliding the whole way there over the next step:
+
+```ts
+import { snapEntity } from '@daneren2005/shared-memory-physics';
+
+entity.components.transform!.x = 500;
+snapEntity(entity);   // drawn at 500 on the very next frame
+```
+
+### The cost
+
+32 bytes per interpolated entity, three extra writes per entity per physics step, and a per-frame pass of one
+lerp per entity on the main thread - order 0.2ms at 10,000 entities. An entity without the component pays
+nothing at all. `forceMainThread: false` plus a `getWorker` moves the pass to a worker for worlds large enough
+that it shows up in a profile, at the price of the render position being one frame stale; because consumers only
+ever read `interpolation.x`, that is a constructor flag rather than a migration.
+
+Physics writes `prev` and then the transform on the worker thread while the main thread reads both, so the block
+carries a tick stamp that is written **last**, with a release store. The update reads it on either side of its
+own reads and drops the frame if it changed, rather than blending a `prev` from one step against a transform
+from another - which is the one mismatch that would draw an entity moving backwards.
+
 ## Collisions
 
-`createPhysicsUpdate` builds an update that, right after moving each entity, tells a callback of yours what
-that entity has moved into. The callback runs wherever the update runs - on the worker thread, in the same
-pass as the movement - so it cannot be handed to `PhysicsSystem` at construction time: functions do not
-survive `postMessage`. It reaches the worker by being baked into a module that both the worker file and the
-main thread import.
+`createPhysicsUpdate` builds an update whose entities notice each other: every move is swept against whatever
+is in front of it, so nothing is ever moved into anything else, and a callback of yours is told what each
+entity ran into. The callback runs wherever the update runs - on the worker thread, in the same pass as the
+movement - so it cannot be handed to `PhysicsSystem` at construction time: functions do not survive
+`postMessage`. It reaches the worker by being baked into a module that both the worker file and the main
+thread import.
+
+The callback is optional and the [sweep](#stopping-at-the-edge) is not. `createPhysicsUpdate()` with nothing
+asked of it at all is movement that comes to rest against walls, terrain and other units and says nothing
+about any of it:
+
+```ts
+// Stopped by everything, responds to nothing.
+export const gamePhysicsUpdate = createPhysicsUpdate<Components>();
+```
+
+Movement that walks straight through the world is the bare [`physicsUpdate`](#using-physicsupdate-in-your-own-system)
+instead, which is also the only one that costs nothing per entity for the collidable query.
 
 ```ts
 // game-physics-update.ts - imported by *both* the worker file and the system below
@@ -227,7 +409,8 @@ Writes go straight into shared memory, so a callback can bounce an entity by fli
 value another thread also touches with the atomics from `@daneren2005/shared-memory-objects`. To reach past
 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`.
+through `callbacks`: `entityDied`, `entityComponentChanged`, `createEntity`, and `emitEntityEvent` for an
+event of your own - the same one the move above reports itself through.
 
 **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
@@ -239,14 +422,17 @@ An entity is never moved into another one. Before anything is written to the tra
 against everything along its path, and the entity is put down on the edge of whatever is in the way - then
 `onCollision` runs for it, exactly as it would if the two had ended up overlapping.
 
+This is every update `createPhysicsUpdate` builds, with or without a callback: where an entity is allowed to
+end up is physics' decision, and what the game does about the contact is a separate one.
+
 ```ts
-// A ship at x = 0 and a station at x = 30, both 10 wide, with a velocity that asks for 100 in this run.
+// A ship at x = 0 and a station at x = 30, both 10 wide, with a velocity that asks for 25 in this run.
 world.update(1000);
-console.log(ship.components.transform!.x); // ~20, their edges touching - not 100, and never 25
+console.log(ship.components.transform!.x); // ~20, their edges touching - not 25, and never inside it
 ```
 
-The whole path is one decision rather than one per entity found along it, so a mover closing on two units in a
-line comes to rest against the *near* one however the two happened to come up, and only the near one is
+The move is one decision over everything it lands on rather than one per entity, so a mover ending up on top of
+two units comes to rest against the *near* one however the two happened to come up, and only the near one is
 reported as a collision - the far one was never reached. An entity wedged between two at the same moment gets a
 call for each.
 
@@ -259,13 +445,18 @@ 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.
 
-Contact is found by walking the path and then halving in on it, rather than solved: three shapes at any
+**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
 rotation to one another have no single formula for when a pair first touches, while the overlap test the
 narrowphase already has answers it for any pair anywhere. The position an entity is put down at is always one
-that tested clear, so it is genuinely outside everything - within about `1e-4` of world units of touching. A
-move long enough to cross many times the size of what is in the way runs out of that walk's step budget, and
-can still pass clean through something very thin; a fixed `deltaBetweenRuns` is the cure if that is ever a real
-prospect in your game.
+that tested clear, so it is genuinely outside everything - within about `1e-4` world units of touching.
+
+The trade for that is **a move long enough to carry an entity clean past something is not stopped by it**: by
+the time the move is out there is nothing left to land on. That takes a single run covering more ground than the
+thing in the way is thick, so at any normal frame rate it does not arise - a ship crossing 100 units a second
+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.
 
 ### Collision filtering
 
@@ -355,11 +546,90 @@ 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.
 
+## 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.
+
+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';
+
+const index = new SpatialIndex(queries.collidable);
+```
+
+Nothing reads the blocks after that, so the index is a **snapshot** of where everything was when it was
+built - build one per run, in `preRun`, and let every entity in that run search it.
+
+| Query                                              | Answers                                              |
+| -------------------------------------------------- | ---------------------------------------------------- |
+| `search(minX, minY, maxX, maxY, filter?)`           | everything whose box reaches into that one            |
+| `searchAround(x, y, reachX, reachY, filter?)`       | the same, written from the middle out                 |
+| `findNearest(x, y, maxDistance?, filter?)`          | the closest one, or `undefined`                       |
+| `findNearby(x, y, maxResults, maxDistance?, filter?)` | the closest `maxResults`, nearest first             |
+
+Every one of them takes a `filter`, run per candidate the tree turns up, and hands it the whole entity -
+`{ entityId, components }` - so it can read back any block that came along with the query. That is where the
+things the index cannot know go: the searcher's own id, which side something is on, whether it is worth
+shooting at.
+
+```ts
+const target = index.findNearest(x, y, 150, other => other.entityId !== entityId && isEnemy(other));
+```
+
+`findNearest` walks the tree in distance order rather than searching a box and sorting what comes back, so
+ask it directly rather than building the sort yourself - it settles as soon as the nearest box is reached, and
+`maxDistance` stops it walking the rest of the world when the answer is that there is nobody. Distance is
+measured to an entity's **box**, not to its centre, so a large target is as near as its nearest edge and
+`maxDistance` reads as a range past the hull.
+
+## Examples
+
+Three runnable examples live in [`examples/`](./examples), rendered with [Phaser](https://phaser.io) (a dev
+dependency - it is not part of the library) and driven by plain HTML controls beside the canvas:
+
+```sh
+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
+  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
+  a direct before-and-after on the same running scene: the same simulation, drawn six frames at a time instead
+  of one.
+
+Every page has a **physics step** slider (starting at the library's own 50ms) and an **interpolate rendering**
+toggle, so the trade the [interpolation section](#interpolation) describes can be looked at rather than
+reasoned about.
+
+The examples import the library as `@daneren2005/shared-memory-physics`, aliased at the source next door, so
+the code reads the way a game's would and editing a system hot-reloads the running page. `npm start` also
+serves the two [cross-origin isolation](https://developer.mozilla.org/en-US/docs/Web/API/crossOriginIsolated)
+headers `SharedArrayBuffer` needs, so physics genuinely runs on a worker there; where a browser will not hand
+one out, the ECS runs the same update in-process instead and the **Run physics in a worker** toggle says so.
+
+The walls the examples bounce off are ordinary entities - a transform and a body, no velocity - so they are
+stopped against by the same sweep that stops anything against anything.
+
+Every push to `dev` or `production` publishes them to GitHub Pages, both to the same place - so the site shows
+whichever branch pushed last, which is what you want while the examples are changing faster than releases are
+cut. See [`.github/workflows/pages.yml`](./.github/workflows/pages.yml) for the one-time repository setting it
+needs, and for the one line to drop when it should go back to publishing releases only.
+
 ## Building
 
 ```sh
 npm install
-npm run build      # emits dist/ (js + d.ts)
+npm run build            # emits dist/ (js + d.ts)
+npm run build:examples   # emits examples/dist/
 npm run type-check
 npm test
 ```

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

@@ -0,0 +1,32 @@
+import type { ComponentDefinition } from '@daneren2005/shared-memory-ecs';
+import type { TransformComponent } from './transform-component';
+export interface InterpolationComponent {
+    index: number;
+    x: number;
+    y: number;
+    prevX: number;
+    prevY: number;
+}
+export interface InterpolationConfig {
+    interpolate?: boolean;
+    x?: number;
+    y?: number;
+}
+export declare const INTERPOLATION_X_INDEX = 0;
+export declare const INTERPOLATION_Y_INDEX = 1;
+export declare const INTERPOLATION_PREV_X_INDEX = 2;
+export declare const INTERPOLATION_PREV_Y_INDEX = 3;
+export declare const INTERPOLATION_PROGRESS_INDEX = 4;
+export declare const INTERPOLATION_SYNCED_TICK_INDEX = 5;
+export declare const INTERPOLATION_DURATION_INDEX = 6;
+export declare const INTERPOLATION_TICK_INDEX = 7;
+export declare const INTERPOLATION_SIZE = 8;
+export declare const interpolationDefinition: ComponentDefinition<InterpolationComponent, Float32Array, InterpolationConfig>;
+export interface SnappableEntity {
+    components: {
+        transform?: TransformComponent;
+        interpolation?: InterpolationComponent;
+    };
+}
+export declare function snapEntity(entity: SnappableEntity): void;
+export default interpolationDefinition;

package/dist/components/registry.d.ts

@@ -1,18 +1,30 @@
 import { type BodyComponent } from './body-component';
+import { type InterpolationComponent } from './interpolation-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>;
+    interpolation: import("@daneren2005/shared-memory-ecs").ComponentDefinition<InterpolationComponent, Float32Array<ArrayBufferLike>, import("./interpolation-component").InterpolationConfig, object>;
 };
 export type PhysicsComponents = {
     transform: TransformComponent;
     velocity: VelocityComponent;
     body: BodyComponent;
+    interpolation: InterpolationComponent;
+};
+export type InterpolationComponents = {
+    transform: TransformComponent;
+    interpolation: InterpolationComponent;
 };
 export type PhysicsUpdateComponents = {
     transform: Float32Array;
     velocity: Float32Array;
     body?: Uint32Array;
+    interpolation?: Float32Array;
+};
+export type InterpolationUpdateComponents = {
+    transform: Float32Array;
+    interpolation: Float32Array;
 };

package/dist/index.d.ts

@@ -7,12 +7,20 @@ export type { VelocityComponent, VelocityConfig, VelocitySerialization, } from '
 export { default as bodyDefinition, canCollide } 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_SIZE, } from './components/body-component';
 export type { BodyComponent, BodyConfig, } from './components/body-component';
+export { default as interpolationDefinition, snapEntity } 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 { physicsRegistry } from './components/registry';
-export type { PhysicsComponents, PhysicsUpdateComponents } from './components/registry';
-export { shapesOverlap, shapeHalfWidth, shapeHalfHeight, shapeIsEmpty, shapeMinHalfExtent, shapeRadius, capsuleHalfLength, boundsHalfWidth, boundsHalfHeight, orientedBoxesOverlap, segmentSegmentDistanceSquared, segmentBoxDistanceSquared, pointSegmentDistanceSquared, } from './math/shapes';
+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 { default as CollisionBroadphase, COLLIDABLE_QUERY } from './systems/collision';
 export type { CollisionComponents, CollisionEntity, CollisionFunction, MovingEntity, SweepResult } from './systems/collision';
-export { default as physicsUpdate, createPhysicsUpdate } from './systems/physics-update';
-export type { PhysicsUpdateFunction, PhysicsUpdateMetadata, PhysicsUpdateOptions } from './systems/physics-update';
-export { default as PhysicsSystem } from './systems/physics-system';
+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 PhysicsSystem, DEFAULT_PHYSICS_STEP_MS } from './systems/physics-system';
 export type { PhysicsSystemConfig } from './systems/physics-system';
+export { default as interpolationUpdate } from './systems/interpolation-update';
+export { default as InterpolationSystem } from './systems/interpolation-system';
+export type { InterpolationSystemConfig } from './systems/interpolation-system';