@driftengine/physics 3.61.0

package/dist/colliderSet.d.ts

@@ -0,0 +1,239 @@
+import type { Aabb } from './collide/index.ts';
+import type { ConvexShape } from './shape.ts';
+/**
+ * One slot's packed bounds in bytes, for a reader walking `data` a slot at a time.
+ *
+ * **The stride is otherwise private and stays that way.** This exists because
+ * `fingerprintColliders` has to step slot by slot to skip the dead ones, and a literal 24 over
+ * there would be a second place for the packing to be wrong — which is the failure the `bounds`
+ * accessor already exists to prevent.
+ */
+export declare const STRIDE_BYTES: number;
+/** A world obstacle: its bounds, and optionally the volume it really is. */
+export interface Collider extends Aabb {
+    /** Points in world space — static shapes are baked, not transformed per query. */
+    shape?: ConvexShape | undefined;
+}
+/** Wrap a world-space shape in the bounds the broad phase needs. */
+export declare function colliderFromShape(shape: ConvexShape): Collider;
+/**
+ * The collider of a drawn box, exactly where it is drawn.
+ *
+ * Same centre and half-extents a mesh builder takes, so a game that draws a
+ * box gets its collision from the same numbers — nothing authored twice. The
+ * shape routes the touch through the shape sweep, which is what lets a lid sit
+ * flush with a walkable surface: the old world-axis path fought a body for the
+ * ground it stood on, and lids had to be sunk out of reach to compensate.
+ */
+export declare function boxCollider(cx: number, cy: number, cz: number, hx: number, hy: number, hz: number): Collider;
+/**
+ * What a collider set costs, in bytes, split so a streaming budget can act on it.
+ *
+ * A single number would not answer the question a budget asks, which is what to drop.
+ */
+export interface ColliderBytes {
+    /**
+     * The packed bounds, the query stamps and the owners. Exact.
+     *
+     * **What was allocated, not what is used.** The arrays double as they grow and a free list
+     * recycles slots without ever shrinking them, so this is the memory actually held — which is
+     * what a budget needs and what `count` would misreport.
+     */
+    readonly slots: number;
+    /** The distinct shape payloads reachable from live slots. Exact. */
+    readonly shapes: number;
+    /** The spatial hash: its buckets and their entries. Part measured, part estimated. */
+    readonly index: number;
+    /** The three above. */
+    readonly total: number;
+}
+export declare class ColliderSet {
+    static readonly MAX_HITS = 512;
+    /**
+     * The group the constructor's own colliders belong to, which `add` never mints and `remove`
+     * refuses.
+     *
+     * **Reserved because of the slots nothing inserts.** The constructor skips an `undefined` entry
+     * without putting it in any cell, and still counts it — so those slots are live and are in no
+     * bucket, and a removal that reached one would walk buckets it was never written to. Keeping the
+     * constructor's slots in a group nothing can drop puts that case out of reach instead of making
+     * it survivable.
+     *
+     * **A set meant to stream is constructed empty** and takes everything through `add`, which is
+     * what the refusal points at when it fires.
+     */
+    static readonly BASE_GROUP: ColliderGroup;
+    /**
+     * The packed bounds, six floats a slot.
+     *
+     * **A reference to this is valid until the next `add`**, which may reallocate. `bounds()` is the
+     * reader that survives both that and a change of packing.
+     *
+     * **Its length is `capacity`, not `count`.** Those are equal on a set that has never had
+     * `remove` called on it, which is every set built the old way; after a removal the live slots
+     * are sparse and a walk of `0..count` reads the wrong ones. Walk `0..capacity` and skip
+     * `!liveAt(i)`.
+     */
+    data: Float32Array;
+    private readonly cellSize;
+    private readonly cells;
+    private shapes;
+    /** Per-query stamp, so a box spanning several cells is reported once. */
+    private seen;
+    private stamp;
+    /** Slots allocated, live or not. */
+    private slots;
+    /** Slots in use. `count` reads this. */
+    private live;
+    /**
+     * Who holds each slot: `-1` for a free one, otherwise the group.
+     *
+     * One array for both liveness and provenance, which is what `bytes`, `liveAt` and the
+     * fingerprint each need, at four bytes a slot instead of a flag array beside a group array.
+     */
+    private owner;
+    private readonly freeSlots;
+    /**
+     * Each group's slots, for the only operation that needs them.
+     *
+     * **A `Map`, and `remove` is its only reader.** `fingerprint.ts` states the rule this respects:
+     * nothing feeding a hash may iterate a `Map` or a `Set`, because insertion order would leak into
+     * the answer.
+     */
+    private readonly groups;
+    private nextGroup;
+    constructor(boxes: readonly Collider[], cellSize?: number);
+    /** How many colliders the set holds. */
+    get count(): number;
+    /** How many slots are allocated, live or not. The true bound of a walk over `data`. */
+    get capacity(): number;
+    /** Whether slot `index` holds a collider. Every slot of a set that has never had `remove`
+     *  called on it does. */
+    liveAt(index: number): boolean;
+    /**
+     * Take a batch of colliders and hand back the handle that drops them again.
+     *
+     * **The grid is updated for these colliders and for no others**, which is the whole point: a
+     * consumer whose world streams was rebuilding a set at every region crossing, at about 2.1 µs a
+     * box, and paying a whole frame for it.
+     *
+     * Slots come off the free list before the arrays grow, so a set that loads a ring of regions
+     * around a player settles at the ring's high-water mark instead of climbing with distance
+     * travelled. Live indices are untouched by this: a slot already in use stays where it is.
+     */
+    add(boxes: readonly Collider[]): ColliderGroup;
+    /**
+     * Take everything in another set as one group, without hashing any of it again.
+     *
+     * **Copy and offset instead of recompute.** One `Float32Array.set` moves the packed bounds, the
+     * shapes are copied by reference, and each of the source's buckets is appended to this set's
+     * with a constant added to every index. Nothing is floored, no shape bounds are recomputed, and
+     * the result queries identically to a one-shot build of the union.
+     *
+     * **It appends past everything and skips the free list**, because a constant offset is what
+     * makes the bucket remap a copy: source slot `i` has to land at `base + i` and nothing may
+     * disturb that.
+     *
+     * **Which is exactly why the source's holes come across as holes.** A source that has had
+     * `remove` called on it — every streamed set — cannot be compacted on the way in, because
+     * skipping its holes would make the offset a function of position. Copying them while calling
+     * them live would be worse: those slots carry the bytes of colliders that were deleted, and a
+     * set reporting them would have resurrected geometry a consumer believed was gone. So liveness
+     * is copied with the bytes, the holes land on this set's free list, and the next `add` fills
+     * them. **Requiring a dense source instead** was the other option and was rejected: it would
+     * refuse the only input this was asked for.
+     *
+     * What a churned source does cost is its dead slots as bytes copied and space held until the
+     * free list drains them. Bounded, visible in `bytes()`, and not a leak.
+     *
+     * **A copy and not a move.** The source is unchanged and stays usable, which is what lets a
+     * caller keep a prototype region and stamp it more than once.
+     *
+     * `join(a, b, c)` is this in a loop, which is why there is no second method for it.
+     */
+    absorb(other: ColliderSet): ColliderGroup;
+    /**
+     * Drop a group and everything in it.
+     *
+     * Refuses the base group and a group it does not hold; a streamer double-freeing a region is a
+     * bug, and a silent no-op hides it until the memory it was meant to release turns up in a
+     * budget.
+     */
+    remove(group: ColliderGroup): void;
+    /** The volume collider `index` really is, or undefined where it is its box. */
+    shapeAt(index: number): ConvexShape | undefined;
+    /**
+     * The packed bounds of collider `index`, written into `out`. Allocation-free.
+     *
+     * `data` is public and the stride is not. A reader outside this file that decodes
+     * `data[i * 6 + 1]` by hand keeps working right up until the packing changes, and
+     * then reports confident nonsense rather than failing.
+     */
+    bounds(index: number, out: Aabb): void;
+    query(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, out: Int32Array): number;
+    /**
+     * What this set costs in memory.
+     *
+     * **Because a consumer can count its own bytes and cannot see the engine's**, which makes a
+     * streaming budget half-measurable: the question "does the ring of regions around the player fit
+     * on a phone" has no answer without this.
+     *
+     * O(n) over slots and over the index, and it allocates a `Set` to count each distinct shape
+     * once. Not a per-frame call.
+     */
+    bytes(): ColliderBytes;
+    /**
+     * How many bucket entries name a slot nothing holds. Always zero.
+     *
+     * **The one defect in this structure that has no symptom of its own**, which is why it gets a
+     * check of its own. A `remove` that misses a bucket entry leaves the slot marked dead — so the
+     * fingerprint skips it and is right, and nothing walks it by index — while the stale entry goes
+     * on naming it: `query` returns it, and the sweep reads its stale bounds and collides with
+     * geometry that is gone. No measurement of frame time, query cost or hash can see that.
+     *
+     * O(total entries) and not something to call in a frame. For tests and for the streaming check.
+     */
+    auditCells(): number;
+    /**
+     * Unhook slots from every cell they occupy, then free them.
+     *
+     * **The same triple loop `insert` uses**, so the two cannot disagree about which cells a box
+     * occupies — which is the disagreement that would leave an entry behind. A bucket entry goes by
+     * swapping the last one into its place and popping, because bucket order carries no meaning, and
+     * an emptied bucket leaves `cells` so a dropped region costs a `Map.get` that misses instead of
+     * a scan.
+     *
+     * **Slots are freed in descending order** so the last-in-first-out pop hands them back
+     * ascending: a region added after another is dropped then lands on a contiguous run of that
+     * region's slots. Incidental locality and not a guarantee — see the compaction note in the
+     * design if a churned set's query cost ever drifts.
+     */
+    private drop;
+    /**
+     * Room for `n` slots, growing by doubling.
+     *
+     * **The shape is `island.ts`'s `ensureBodies`, with one difference worth naming**: that one
+     * allocates and discards, because it rebuilds its arrays from scratch every tick, and these
+     * carry a world that has to survive the growth. So they copy.
+     *
+     * A grown `seen` is zero-filled by the allocation, which is the same thing `add` writes on a
+     * recycled slot and for the same reason.
+     */
+    private ensureCapacity;
+    private insert;
+}
+/**
+ * A handle to one batch of colliders, so a region can be dropped without naming its members.
+ *
+ * Opaque on purpose: it is an integer today and the only thing a caller may do with it is hand it
+ * back.
+ */
+export type ColliderGroup = number;
+/**
+ * The stamp a query marks with next, or 0 meaning `seen` has to be cleared first.
+ *
+ * **Its own function because it cannot be reached by driving `query`.** The condition needs 2^31
+ * queries, which no test will do, so the decision is asserted where it is made rather than through
+ * the behaviour it protects.
+ */
+export declare function stampAfter(previous: number): number;