@driftengine/core 3.61.0

package/dist/physics/ribbonSurface.d.ts

@@ -0,0 +1,239 @@
+/**
+ * "Where is the ground in this column, and which way does it face?"
+ *
+ * The AABB strip a ribbon builds keeps a character inside the world; it is a poor
+ * description of the *surface*, because a world-axis box over a banked strip has
+ * a flat top at the height of the strip's highest corner. Stand on that and you
+ * hover through every corner in the game.
+ *
+ * So the two are split. Boxes stop you falling through; this answers what you
+ * are standing on, exactly, from the curve itself.
+ *
+ * The cost of "exactly" is a nearest-point search along a spline, which is not
+ * something to do from scratch inside a fixed tick. A uniform grid of seed arc
+ * lengths turns it into a lookup plus a handful of Newton steps — a fixed count,
+ * so two machines get bit-identical answers, which the replay contract requires.
+ */
+import { Spline } from '../geometry/spline.ts';
+import type { RibbonHole } from '../geometry/ribbon.ts';
+export interface SurfaceHit {
+    /** Height of the surface in the queried column. */
+    y: number;
+    normalX: number;
+    normalY: number;
+    normalZ: number;
+    /** Direction of travel at the nearest point on the centreline. */
+    tangentX: number;
+    tangentY: number;
+    tangentZ: number;
+    /** Arc length of that nearest point. How far along the route you are. */
+    distanceM: number;
+    /** Signed offset from the centreline, positive to the character's right. */
+    lateralM: number;
+    /** Half the surface's width here — how much room is left before the edge. */
+    halfWidthM: number;
+    bankRad: number;
+    /**
+     * Which way *up* looks here — the ruled surface's own normal, not the
+     * cross-section's.
+     *
+     * A separate field because it answers a separate question. `normal` is the
+     * ground a character stands on and every movement rule is tuned against it: how
+     * steep is this to walk, which way does gravity pull along it, is it floor or
+     * is it wall. That question is about the cross-section, and its answer is the
+     * same all the way across the deck.
+     *
+     * This one is about how the surface *looks* where you are standing on it, and
+     * on a deck whose bank rolls it is a very different number: the ruled surface
+     * climbs far more steeply along the route near its edges than the centreline
+     * does — 57° measured on one chicane against the centreline's 11°, and
+     * past vertical on a chute. Correct geometry, and correct for orienting a body
+     * that has to look like it is on the deck. Fed to the walking rules instead it
+     * takes the ground away: a character met a chicane's edge as a wall and fell down
+     * it at 20 m/s a hand's width above the deck, never landing, which is exactly
+     * what flying looks like.
+     */
+    tiltX: number;
+    tiltY: number;
+    tiltZ: number;
+}
+export declare function createSurfaceHit(): SurfaceHit;
+/**
+ * Anything that can answer "where is the ground here?".
+ *
+ * The seam a controller depends on, rather than on `RibbonSurface` itself: a
+ * game with heightmap terrain, or a test with three lines of arithmetic, is a
+ * valid ground surface and neither should have to build a spline to say so.
+ */
+export interface GroundSurface {
+    /**
+     * @param atY Height of whatever is asking, so a route that passes over itself
+     * can answer with the deck *under* them rather than the highest one in the
+     * column. Omitted means "the highest", which is right for a caller that has
+     * no position — a generator placing a lamp, say.
+     */
+    sample(x: number, z: number, out: SurfaceHit, atY?: number): boolean;
+    /**
+     * The **highest** floor in this column whose face lies in `[loY, hiY)`, exactly.
+     *
+     * A second question, not a variant of the first, and the reason it cannot be
+     * expressed as one: `sample` scores candidates by nearness to the asker and
+     * breaks ties *against* whatever is above them, because what you are standing
+     * on is the thing under your feet. "Is there a floor in the way" asks about a
+     * band that is entirely above the asker, so that scoring is pointed at the
+     * exact answer wanted — a deck a metre up loses to the deck underfoot and the
+     * caller is told the column is clear.
+     *
+     * So this is a filter and not a score: every face in the band qualifies, the
+     * highest wins, and nothing outside the band can outrank anything inside it.
+     * No reference height, no tie-break, nothing to tune.
+     *
+     * Half-open on purpose. A caller testing "between my step ceiling and my head"
+     * owns both of its own bounds, and a face exactly at head height is one the
+     * body passes under rather than into.
+     */
+    sampleBand(x: number, z: number, out: SurfaceHit, loY: number, hiY: number): boolean;
+}
+export interface RibbonSurfaceOptions {
+    /** Side of a seed grid cell, metres. */
+    cellM?: number;
+    /** Stretches of arc length where there is no surface at all. */
+    holes?: readonly RibbonHole[];
+    /**
+     * Extra width, each side, that still counts as being over the surface.
+     * A character is a box, not a point, and the edge should be forgiving by about
+     * half of one.
+     */
+    marginM?: number;
+    /**
+     * How far the *mesh* keeps deck past the start of a hole, metres — one cross-section step.
+     *
+     * A hole is authored as a span of arc length and a ribbon's geometry cannot cut exactly
+     * there. `buildRibbon` keeps the cross-section that *borders* a hole, deliberately, so the
+     * deck before it gets its end cap in the right place instead of stopping a step short — so
+     * the drawn lip can reach a full step into the authored span. A surface that does not know
+     * that figure reports no ground under deck a character can plainly see and is standing on.
+     *
+     * Defaults to the ribbon builder's own default step, so a caller who has not changed the
+     * step does not have to say so; a caller who has must pass it, or the two disagree by the
+     * difference.
+     */
+    holeEdgeM?: number;
+    /**
+     * Width of the raised trim down each edge, metres, and how far it stands proud.
+     *
+     * A kerb is drawn as its own ribbon over the outermost band of the deck, lifted a
+     * few centimetres — and a surface that does not know about it reports the deck's
+     * height under geometry the player can plainly see they are standing on, so their
+     * feet sink into it. The two figures are the same ones the kerb ribbon is built from,
+     * passed here so the drawn trim and the walkable floor cannot disagree.
+     *
+     * Zero by default, which is every consumer that has no trim: the arithmetic below is
+     * skipped entirely rather than adding zero.
+     */
+    edgeBandM?: number;
+    edgeLiftM?: number;
+}
+export declare class RibbonSurface {
+    private readonly spline;
+    private readonly holes;
+    private readonly margin;
+    private readonly holeEdge;
+    /** Raised trim down each edge; see `RibbonSurfaceOptions.edgeBandM`. */
+    private readonly edgeBand;
+    private readonly edgeLift;
+    /**
+     * The mesh's own cross-section pitch, derived exactly as `buildRibbon` derives
+     * it, so this surface can name the intervals the mesh really drew.
+     */
+    private readonly meshStep;
+    private readonly cell;
+    private readonly originX;
+    private readonly originZ;
+    private readonly cellsX;
+    private readonly cellsZ;
+    /**
+     * Candidate arc lengths per cell — `SEEDS_PER_CELL` slots each, -1 where
+     * unused.
+     */
+    private readonly seeds;
+    private readonly scratch;
+    /** Second scratch: the swept normal needs a neighbour without losing `scratch`. */
+    private readonly frame;
+    constructor(spline: Spline, options?: RibbonSurfaceOptions);
+    /**
+     * Record an arc length as a candidate for one cell.
+     *
+     * Slots hold *distinct passes*: an arc length close to one already held
+     * replaces it if nearer, and only a genuinely separate stretch of route takes
+     * a new slot. Without that rule all three slots fill with neighbouring
+     * samples from the same pass and the structure buys nothing.
+     */
+    private offer;
+    /**
+     * Is this arc length inside a hole — measured as the *mesh* cuts one, not as the plan
+     * states one?
+     *
+     * `buildRibbon` lays a whole number of equal steps along the spline and draws the quad
+     * between two consecutive cross-sections exactly when that quad's **midpoint** lies
+     * outside the authored hole. So the drawn deck is a union of whole step intervals, and
+     * a hole boundary falling mid-interval leaves the whole interval drawn. This asks the
+     * mesh's own question, in the mesh's own words, and cannot drift from it.
+     *
+     * It used to shrink every hole by a **full step at each end regardless of alignment**,
+     * which is that overhang's worst case rather than its actual size: where a boundary
+     * already sits on the step grid the mesh overhangs by nothing at all, and the surface
+     * was handing out up to a step of deck that was never drawn — at *every* gap, ramp and
+     * platform run. It showed up everywhere as the same report: every pad ending and every
+     * ribbon ending carried a phantom area the player could walk out onto without falling.
+     * Measured live on one route (`blocks` at 216–246 m, mesh pitch 1.9935 m): a character
+     * stood still at 245.8 m over open air with this answering a metre of deck under them.
+     *
+     * Exact costs one floor and one multiply.
+     */
+    private inHole;
+    /**
+     * How the surface *looks* where it is being stood on — see `SurfaceHit.tilt`.
+     *
+     * A cross-section's own normal describes the *centreline*, and it is the same
+     * answer all the way across the deck — which is only true while the section
+     * is carried along unchanged. Where the bank rolls, the surface a character
+     * stands on is a ruled one, and near its edges it climbs far more steeply
+     * along the route than the centreline does: measured on one camber reversal,
+     * 33° at the edge against the 11° the centreline reports. Everything that reads
+     * this then believes a hill is gentle when it is not — the body stands bolt
+     * upright on it instead of following the surface's own tilt, and the same
+     * understatement decides step limits and grip.
+     *
+     * So it is built from both of the surface's own tangents. Across is `right`;
+     * along is the centreline's tangent plus however fast `right` itself is
+     * turning, times how far out you are — the term that is exactly zero on a
+     * straight or evenly-banked stretch, and the whole story on a rolling one. The
+     * derivative is a symmetric difference over a fixed span, so it costs two
+     * spline samples and cannot vary between machines.
+     */
+    private sweptNormal;
+    /**
+     * Ask what the surface is doing in the column above/below `(x, z)`.
+     *
+     * Returns false where there is no surface — off the edge, past either end, or
+     * over a hole — and leaves `out` untouched in that case.
+     */
+    sample(x: number, z: number, out: SurfaceHit, atY?: number): boolean;
+    /** See `GroundSurface.sampleBand`: the highest pass in the band, exactly. */
+    sampleBand(x: number, z: number, out: SurfaceHit, loY: number, hiY: number): boolean;
+    /**
+     * Index of this column's seed slots, or -1 where the grid does not reach.
+     *
+     * Shared by both queries so the two can never disagree about which cell a
+     * column falls in.
+     */
+    private cellBase;
+    /**
+     * Refine one candidate seed and report whether it lands on the surface.
+     *
+     * Split out so the query can try several; on its own this is the original
+     * single-seed search.
+     */
+    private trySeed;
+}