@daneren2005/shared-memory-physics 1.7.1 → 1.7.3

package/README.md

@@ -19,7 +19,7 @@ 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        |
+| `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?`, `blocksPath?` | –                          | `Uint32Array` – what shape, what collides with |
 | `interpolation` | `interpolate`                                | –                          | `Float32Array` – where to *draw* it            |
@@ -59,8 +59,8 @@ 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
-runs, so `save()` returns `x` / `y` and `angle`, while a reloaded entity gets its size back from your own
-template rather than the save.
+runs, so `save()` returns `x` / `y` and includes `angle` only when it is nonzero. An omitted angle defaults
+to `0` on load, while a reloaded entity gets its size back from your own template rather than the save.
 
 `x` / `y` are the **centre** of the box, not a corner: the box is rotated about that point and collision
 projects out from it in both directions. `angle` is in **radians** counter-clockwise from the +x axis, and
@@ -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.

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/components/transform-component.d.ts

@@ -18,7 +18,7 @@ export interface TransformConfig {
 export interface TransformSerialization {
     x: number;
     y: number;
-    angle: number;
+    angle?: number;
 }
 export declare const TRANSFORM_X_INDEX = 0;
 export declare const TRANSFORM_Y_INDEX = 1;

package/dist/index.d.ts

@@ -23,7 +23,7 @@ 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';