@daneren2005/shared-memory-physics 1.6.3 → 1.7.1

package/README.md

@@ -21,7 +21,7 @@ npm install @daneren2005/shared-memory-physics @daneren2005/shared-memory-ecs @d
 | `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?`, `damping?` | `Float32Array` – world units per second        |
-| `body`          | `shape?`, `collideCategory?`, `collideMask?`, `sensor?`, `continuousCollisionDetection?` | –                          | `Uint32Array` – what shape, what collides with |
+| `body`          | `shape?`, `collideCategory?`, `collideMask?`, `sensor?`, `continuousCollisionDetection?`, `blocksPath?` | –                          | `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`
@@ -79,6 +79,11 @@ defining config out of your own template, which is why `save` returns nothing fo
 its shape and categories back from the template rather than from the save. See
 [Body shapes](#body-shapes) for `shape` and [Collision filtering](#collision-filtering) for the other two.
 
+`blocksPath` marks a body as something pathfinding should route around - a wall or a building rather than another
+mover. The physics never reads it; it is a flag in the same packed word for a game's own navigation to query
+(`body.blocksPath`, or `blocksPath(block)` off a raw block). It defaults to `false`, and a body carrying it is
+assumed never to move, so a navigation structure can be updated only when such bodies are added or removed.
+
 ## Body shapes
 
 An entity is one of four shapes. The transform still owns its position, size and angle; a polygon additionally
@@ -322,10 +327,10 @@ Without a `getWorker` (or where Web Workers / `SharedArrayBuffer` are unavailabl
 
 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:
+frame instead, by consuming published simulation time while advancing toward the last coherent target:
 
 ```
-render = prev + (current - prev) * alpha
+render += (target - render) * (frameDuration / remainingDuration)
 ```
 
 Normally every position it writes lies on the latest simulation segment. If worker scheduling lets several
@@ -343,10 +348,15 @@ 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. Physics marks that publication dirty before changing either endpoint and stamps it complete only
-after both are ready, so rendering holds its previous position for a frame if it catches the worker mid-write.
+It takes no configuration. Physics publishes the transform, step duration, cumulative simulated time, and a tick
+stamp. Rendering caches each coherent target and its timing. If it catches physics mid-write, it continues
+consuming the cached segment until another complete snapshot is available.
+
+A worker publishes a run entity by entity while the main thread renders, so one frame can find some entities of a
+run at its new step and the rest at the old one - two ships flying in formation would then drift apart on screen.
+Each entity therefore keeps the publication it replaced, and `InterpolationSystem` snapshots every
+`PhysicsSystem`'s committed tick once per frame: a publication newer than its run's commit is drawn from the
+previous one until the whole run has landed. Both systems must share the same world object for this to apply.
 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:
@@ -482,16 +492,17 @@ spot, as above.
 
 ### The cost
 
-44 bytes per interpolated entity, four extra writes per entity per physics step, and a per-frame pass of one
+The renderer retains the last coherent target while physics publishes a new step, so an overlapping read can keep advancing without freezing a frame.
+
+68 bytes per interpolated entity, ten publication 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.
+Physics marks the tick dirty before changing timing and position, then publishes the completed tick with
+a release store. The reader accepts a new snapshot only when its tick reads match and its run has committed;
+otherwise it reads the previous publication, and failing that continues toward the cached target.
 
 ## Collisions
 

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

@@ -7,6 +7,7 @@ export interface BodyComponent {
     collideMask: number;
     sensor: boolean;
     continuousCollisionDetection: boolean;
+    blocksPath: boolean;
 }
 export declare const SHAPE_RECTANGLE = 1;
 export declare const SHAPE_CIRCLE = 2;
@@ -25,6 +26,7 @@ export interface BodyConfig {
     collideMask?: number;
     sensor?: boolean;
     continuousCollisionDetection?: boolean;
+    blocksPath?: boolean;
 }
 export declare const BODY_FLAGS_INDEX = 0;
 export declare const BODY_CATEGORY_INDEX = 1;
@@ -34,9 +36,11 @@ 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 const BODY_BLOCKS_PATH_FLAG = 64;
 export declare function bodyShape(body: Uint32Array): number;
 export declare function isSensor(body: Uint32Array): boolean;
 export declare function isContinuous(body: Uint32Array): boolean;
+export declare function blocksPath(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>;

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

@@ -5,15 +5,17 @@ export interface InterpolationComponent {
     index: number;
     x: number;
     y: number;
-    prevX: number;
-    prevY: number;
-    progress: number;
     syncedTick: number;
     duration: number;
     tick: number;
     totalDuration: number;
     syncedDuration: number;
     remainingDuration: number;
+    targetX: number;
+    targetY: number;
+    syncedStepDuration: number;
+    previousX: number;
+    previousY: number;
 }
 export interface InterpolationConfig {
     interpolate?: boolean;
@@ -22,16 +24,22 @@ export interface InterpolationConfig {
 }
 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_TOTAL_DURATION_INDEX = 8;
-export declare const INTERPOLATION_SYNCED_DURATION_INDEX = 9;
-export declare const INTERPOLATION_REMAINING_DURATION_INDEX = 10;
-export declare const INTERPOLATION_SIZE = 11;
+export declare const INTERPOLATION_SYNCED_TICK_INDEX = 2;
+export declare const INTERPOLATION_DURATION_INDEX = 3;
+export declare const INTERPOLATION_TICK_INDEX = 4;
+export declare const INTERPOLATION_TOTAL_DURATION_INDEX = 5;
+export declare const INTERPOLATION_SYNCED_DURATION_INDEX = 6;
+export declare const INTERPOLATION_REMAINING_DURATION_INDEX = 7;
+export declare const INTERPOLATION_TARGET_X_INDEX = 8;
+export declare const INTERPOLATION_TARGET_Y_INDEX = 9;
+export declare const INTERPOLATION_SYNCED_STEP_DURATION_INDEX = 10;
+export declare const INTERPOLATION_CHANNEL_INDEX = 11;
+export declare const INTERPOLATION_PREVIOUS_X_INDEX = 12;
+export declare const INTERPOLATION_PREVIOUS_Y_INDEX = 13;
+export declare const INTERPOLATION_PREVIOUS_DURATION_INDEX = 14;
+export declare const INTERPOLATION_PREVIOUS_TOTAL_DURATION_INDEX = 15;
+export declare const INTERPOLATION_PREVIOUS_TICK_INDEX = 16;
+export declare const INTERPOLATION_SIZE = 17;
 export declare const interpolationDefinition: ComponentDefinition<InterpolationComponent, Float32Array, InterpolationConfig>;
 export interface SnappableEntity {
     components: {

package/dist/index.d.ts

@@ -7,8 +7,8 @@ export type { VelocityComponent, VelocityConfig, VelocitySerialization, } from '
 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 { default as bodyDefinition, canCollide, isSensor, isContinuous, blocksPath, 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_BLOCKS_PATH_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';
@@ -17,7 +17,7 @@ export { default as bouncinessDefinition } from './components/bounciness-compone
 export { BOUNCINESS_INDEX, BOUNCINESS_SIZE, } from './components/bounciness-component';
 export type { BouncinessComponent, BouncinessConfig, } from './components/bounciness-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_TOTAL_DURATION_INDEX, INTERPOLATION_SYNCED_DURATION_INDEX, INTERPOLATION_REMAINING_DURATION_INDEX, INTERPOLATION_SIZE, } from './components/interpolation-component';
+export { INTERPOLATION_X_INDEX, INTERPOLATION_Y_INDEX, INTERPOLATION_SYNCED_TICK_INDEX, INTERPOLATION_DURATION_INDEX, INTERPOLATION_TICK_INDEX, INTERPOLATION_TOTAL_DURATION_INDEX, INTERPOLATION_SYNCED_DURATION_INDEX, INTERPOLATION_REMAINING_DURATION_INDEX, INTERPOLATION_TARGET_X_INDEX, INTERPOLATION_TARGET_Y_INDEX, INTERPOLATION_SYNCED_STEP_DURATION_INDEX, INTERPOLATION_CHANNEL_INDEX, INTERPOLATION_PREVIOUS_X_INDEX, INTERPOLATION_PREVIOUS_Y_INDEX, INTERPOLATION_PREVIOUS_DURATION_INDEX, INTERPOLATION_PREVIOUS_TOTAL_DURATION_INDEX, INTERPOLATION_PREVIOUS_TICK_INDEX, INTERPOLATION_SIZE, } 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';
@@ -37,5 +37,6 @@ export type { PhysicsSystemConfig, VelocityAssignment } from './systems/physics-
 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 type { InterpolationWorld } from './systems/interpolation-update';
 export { default as InterpolationSystem } from './systems/interpolation-system';
 export type { InterpolationSystemConfig } from './systems/interpolation-system';