@daneren2005/shared-memory-physics 1.7.0 → 1.7.2

package/README.md

@@ -93,7 +93,7 @@ has a `polygon` component holding its outline:
 | ----------------- | ------------------------------------- | ------------------------------------------------------------- |
 | `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_CAPSULE`   | `width`, `height`, `shape`             | a pill along its longer side, as thick as its shorter side    |
 | `SHAPE_POLYGON`   | `vertices`                             | a convex 3-16 vertex outline, scaled and turned by its transform |
 
 ```ts
@@ -108,8 +108,18 @@ world.loadEntity({ x: 0, y: 0, vertices: [[-8, -6], [10, 0], [-8, 6]] });
 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`.
+Changing the transform size therefore scales the polygon, while `angle` rotates it around that centre. `vertices`
+cannot be given alongside `radius`.
+
+Give `width` and `height` with the `vertices` when the outline should sit tighter than the box the entity is sized
+by - a sprite with the hull drawn inside it, say. The box then stays that size, the vertices are offsets from the
+entity's centre rather than from their own bounds, and every one must lie inside the box (the broadphase indexes
+the box, so an outline poking out of it would miss contacts):
+
+```ts
+// A 40x40 sprite whose triangular hull fills only part of it; x/y and the drawn size stay the sprite's.
+world.loadEntity({ x: 0, y: 0, width: 40, height: 40, vertices: [[-12, -15], [14, 0], [-12, 15]] });
+```
 
 `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
@@ -118,9 +128,10 @@ rather than one quietly winning. A config that says nothing about its `shape` is
 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.
+A capsule lies along its **longer** side, caps included: a 40x10 capsule is a 30-long core along the way the entity
+faces with a 5 radius cap at each end, the same 10 thick all the way down, and a 10x40 one is that same pill turned
+a quarter, running along the entity's height instead - handy for art drawn nose-up. `capsuleCoreAngle` gives the
+angle the core lies at. One as long as it is wide is a circle.
 
 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
@@ -139,7 +150,7 @@ reflects around; a game reaching for its own response can use it the same way.
 `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 -
+indexed under), `shapeRadius`, `shapeIsEmpty`, `capsuleHalfLength`, `capsuleCoreAngle`, 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`
 and `boundsHalfHeight` are still there and still rectangle-only.
@@ -348,10 +359,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. 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.
+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:
@@ -489,15 +505,15 @@ spot, as above.
 
 The renderer retains the last coherent target while physics publishes a new step, so an overlapping read can keep advancing without freezing a frame.
 
-44 bytes per interpolated entity, four publication writes per entity per physics step, and a per-frame pass of one
+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 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; otherwise it continues
-toward the cached target.
+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/interpolation-component.d.ts

@@ -14,6 +14,8 @@ export interface InterpolationComponent {
     targetX: number;
     targetY: number;
     syncedStepDuration: number;
+    previousX: number;
+    previousY: number;
 }
 export interface InterpolationConfig {
     interpolate?: boolean;
@@ -31,7 +33,13 @@ 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_SIZE = 11;
+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/components/polygon-component.d.ts

@@ -2,6 +2,8 @@ import type { ComponentDefinition } from '@daneren2005/shared-memory-ecs';
 export type PolygonVertex = readonly [x: number, y: number];
 export interface PolygonConfig {
     vertices?: ReadonlyArray<PolygonVertex>;
+    width?: number;
+    height?: number;
 }
 export interface PolygonComponent {
     index: number;
@@ -18,5 +20,5 @@ export interface PreparedPolygon {
     vertices: Array<number>;
 }
 export declare const polygonDefinition: ComponentDefinition<PolygonComponent, Float32Array, PolygonConfig>;
-export declare function preparePolygon(vertices: ReadonlyArray<PolygonVertex> | undefined): PreparedPolygon;
+export declare function preparePolygon(vertices: ReadonlyArray<PolygonVertex> | undefined, boxWidth?: number, boxHeight?: number): PreparedPolygon;
 export default polygonDefinition;

package/dist/index.d.ts

@@ -17,13 +17,13 @@ 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_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_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';
 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 { shapesOverlap, contactNormal, shapeHalfWidth, shapeHalfHeight, shapeIsEmpty, shapeRadius, capsuleHalfLength, capsuleCoreAngle, 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';
@@ -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';