@driftengine/core 3.61.0

package/dist/geometry/pixelFont.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A 5x7 pixel font, as bitmasks.
+ *
+ * Glyphs are built rather than loaded, for the same reasons the cursor is: no
+ * asset, no request, no licence, and — the one that matters — a shape the
+ * renderer can *extrude*. A font file gives you outlines to rasterise; a grid
+ * of cells gives you boxes to light, which is what makes text belong in a
+ * flat-shaded world instead of floating over it.
+ *
+ * Five by seven is the smallest grid that carries a legible uppercase alphabet
+ * with digits. Anything smaller starts guessing between 8, B and 6 at a glance,
+ * which is exactly the glance a notification gets.
+ *
+ * Each glyph is seven rows, each row five bits, most significant bit leftmost.
+ */
+export declare const GLYPH_WIDTH = 5;
+export declare const GLYPH_HEIGHT = 7;
+/** Blank columns between glyphs, in cells. */
+export declare const GLYPH_SPACING = 1;
+/**
+ * Rows for one character. Lower case is folded to upper: this is a display
+ * face for short shouted strings, and a 5x7 grid has no room for descenders.
+ */
+export declare function glyphRows(character: string): readonly number[];
+export declare function hasGlyph(character: string): boolean;
+/** Width of a string in cells, spacing included, excluding the trailing gap. */
+export declare function measureText(text: string): number;
+/** How many lit cells a string needs, which is how many boxes it costs. */
+export declare function countCells(text: string): number;
+/**
+ * Walk every lit cell of a string.
+ *
+ * Coordinates are in cells, origin at the string's left baseline: x increases
+ * right, y increases *up*, so the caller works in the same handedness as the
+ * rest of the engine rather than in text-editor coordinates.
+ *
+ * `charIndex` comes along because per-character animation is the whole point —
+ * a message where every letter arrives at once is a label, and one where they
+ * arrive in sequence is an event.
+ */
+/**
+ * Every horizontal run of lit cells, as one span each.
+ *
+ * **Because a box per cell is most of a world.** A consumer measured their village at 2,662,324
+ * triangles of which **1,195,296 — forty-five per cent — were the lettering** on 169 street plates
+ * and 830 house numbers, one box of twelve triangles at each of 65,271 lit cells. A run of three
+ * lit cells side by side is three boxes with four interior faces between them that nothing can ever
+ * see, and one box the same shape outside.
+ *
+ * **Horizontal only, and that is a measurement rather than a simplification.** Against that
+ * consumer's own 1,168 strings, merging runs takes 65,271 cells to 42,631 boxes, and a greedy
+ * rectangle merge over two dimensions gives *exactly the same number* — in a glyph five cells wide
+ * there is nothing vertical left to win, and the second pass would be code that never pays.
+ *
+ * A run never crosses a glyph, because the cursor advances by `GLYPH_WIDTH + GLYPH_SPACING` and
+ * that spacing is a column of unlit cells.
+ */
+export declare function forEachRun(text: string, visit: (x: number, y: number, width: number, charIndex: number) => void): void;
+export declare function forEachCell(text: string, visit: (x: number, y: number, charIndex: number) => void): void;

package/dist/geometry/pixelFont.js

@@ -0,0 +1,179 @@
+/**
+ * A 5x7 pixel font, as bitmasks.
+ *
+ * Glyphs are built rather than loaded, for the same reasons the cursor is: no
+ * asset, no request, no licence, and — the one that matters — a shape the
+ * renderer can *extrude*. A font file gives you outlines to rasterise; a grid
+ * of cells gives you boxes to light, which is what makes text belong in a
+ * flat-shaded world instead of floating over it.
+ *
+ * Five by seven is the smallest grid that carries a legible uppercase alphabet
+ * with digits. Anything smaller starts guessing between 8, B and 6 at a glance,
+ * which is exactly the glance a notification gets.
+ *
+ * Each glyph is seven rows, each row five bits, most significant bit leftmost.
+ */
+export const GLYPH_WIDTH = 5;
+export const GLYPH_HEIGHT = 7;
+/** Blank columns between glyphs, in cells. */
+export const GLYPH_SPACING = 1;
+const GLYPHS = {
+    ' ': [0, 0, 0, 0, 0, 0, 0],
+    A: [0b01110, 0b10001, 0b10001, 0b11111, 0b10001, 0b10001, 0b10001],
+    B: [0b11110, 0b10001, 0b10001, 0b11110, 0b10001, 0b10001, 0b11110],
+    C: [0b01110, 0b10001, 0b10000, 0b10000, 0b10000, 0b10001, 0b01110],
+    D: [0b11110, 0b10001, 0b10001, 0b10001, 0b10001, 0b10001, 0b11110],
+    E: [0b11111, 0b10000, 0b10000, 0b11110, 0b10000, 0b10000, 0b11111],
+    F: [0b11111, 0b10000, 0b10000, 0b11110, 0b10000, 0b10000, 0b10000],
+    G: [0b01110, 0b10001, 0b10000, 0b10111, 0b10001, 0b10001, 0b01111],
+    H: [0b10001, 0b10001, 0b10001, 0b11111, 0b10001, 0b10001, 0b10001],
+    I: [0b01110, 0b00100, 0b00100, 0b00100, 0b00100, 0b00100, 0b01110],
+    J: [0b00111, 0b00010, 0b00010, 0b00010, 0b00010, 0b10010, 0b01100],
+    K: [0b10001, 0b10010, 0b10100, 0b11000, 0b10100, 0b10010, 0b10001],
+    L: [0b10000, 0b10000, 0b10000, 0b10000, 0b10000, 0b10000, 0b11111],
+    M: [0b10001, 0b11011, 0b10101, 0b10101, 0b10001, 0b10001, 0b10001],
+    N: [0b10001, 0b11001, 0b10101, 0b10011, 0b10001, 0b10001, 0b10001],
+    O: [0b01110, 0b10001, 0b10001, 0b10001, 0b10001, 0b10001, 0b01110],
+    P: [0b11110, 0b10001, 0b10001, 0b11110, 0b10000, 0b10000, 0b10000],
+    Q: [0b01110, 0b10001, 0b10001, 0b10001, 0b10101, 0b10010, 0b01101],
+    R: [0b11110, 0b10001, 0b10001, 0b11110, 0b10100, 0b10010, 0b10001],
+    S: [0b01111, 0b10000, 0b10000, 0b01110, 0b00001, 0b00001, 0b11110],
+    T: [0b11111, 0b00100, 0b00100, 0b00100, 0b00100, 0b00100, 0b00100],
+    U: [0b10001, 0b10001, 0b10001, 0b10001, 0b10001, 0b10001, 0b01110],
+    V: [0b10001, 0b10001, 0b10001, 0b10001, 0b10001, 0b01010, 0b00100],
+    W: [0b10001, 0b10001, 0b10001, 0b10101, 0b10101, 0b11011, 0b10001],
+    X: [0b10001, 0b10001, 0b01010, 0b00100, 0b01010, 0b10001, 0b10001],
+    Y: [0b10001, 0b10001, 0b01010, 0b00100, 0b00100, 0b00100, 0b00100],
+    Z: [0b11111, 0b00001, 0b00010, 0b00100, 0b01000, 0b10000, 0b11111],
+    '0': [0b01110, 0b10001, 0b10011, 0b10101, 0b11001, 0b10001, 0b01110],
+    '1': [0b00100, 0b01100, 0b00100, 0b00100, 0b00100, 0b00100, 0b01110],
+    '2': [0b01110, 0b10001, 0b00001, 0b00010, 0b00100, 0b01000, 0b11111],
+    '3': [0b11111, 0b00010, 0b00100, 0b00010, 0b00001, 0b10001, 0b01110],
+    '4': [0b00010, 0b00110, 0b01010, 0b10010, 0b11111, 0b00010, 0b00010],
+    '5': [0b11111, 0b10000, 0b11110, 0b00001, 0b00001, 0b10001, 0b01110],
+    '6': [0b00110, 0b01000, 0b10000, 0b11110, 0b10001, 0b10001, 0b01110],
+    '7': [0b11111, 0b00001, 0b00010, 0b00100, 0b01000, 0b01000, 0b01000],
+    '8': [0b01110, 0b10001, 0b10001, 0b01110, 0b10001, 0b10001, 0b01110],
+    '9': [0b01110, 0b10001, 0b10001, 0b01111, 0b00001, 0b00010, 0b01100],
+    '.': [0, 0, 0, 0, 0, 0b01100, 0b01100],
+    ',': [0, 0, 0, 0, 0b01100, 0b01100, 0b11000],
+    ':': [0, 0b01100, 0b01100, 0, 0b01100, 0b01100, 0],
+    '!': [0b00100, 0b00100, 0b00100, 0b00100, 0b00100, 0, 0b00100],
+    '?': [0b01110, 0b10001, 0b00001, 0b00010, 0b00100, 0, 0b00100],
+    '-': [0, 0, 0, 0b11111, 0, 0, 0],
+    '+': [0, 0b00100, 0b00100, 0b11111, 0b00100, 0b00100, 0],
+    '/': [0b00001, 0b00010, 0b00010, 0b00100, 0b01000, 0b01000, 0b10000],
+    "'": [0b00100, 0b00100, 0, 0, 0, 0, 0],
+    '(': [0b00010, 0b00100, 0b01000, 0b01000, 0b01000, 0b00100, 0b00010],
+    ')': [0b01000, 0b00100, 0b00010, 0b00010, 0b00010, 0b00100, 0b01000],
+    '%': [0b11001, 0b11010, 0b00010, 0b00100, 0b01000, 0b01011, 0b10011],
+    '·': [0, 0, 0, 0b01100, 0b01100, 0, 0],
+    '×': [0, 0b10001, 0b01010, 0b00100, 0b01010, 0b10001, 0],
+    /**
+     * A solid cell. Not a letter — it is how a caller builds a *plate*: a run of
+     * these behind a word makes a keycap, which is the only way to say "this is a
+     * key you press" without a second asset pipeline.
+     */
+    '█': [0b11111, 0b11111, 0b11111, 0b11111, 0b11111, 0b11111, 0b11111],
+};
+/** Anything the font does not have. Better a visible box than a silent gap. */
+const MISSING = [0b11111, 0b10001, 0b10001, 0b10001, 0b10001, 0b10001, 0b11111];
+/**
+ * Rows for one character. Lower case is folded to upper: this is a display
+ * face for short shouted strings, and a 5x7 grid has no room for descenders.
+ */
+export function glyphRows(character) {
+    const upper = character.toUpperCase();
+    return GLYPHS[upper] ?? GLYPHS[character] ?? MISSING;
+}
+export function hasGlyph(character) {
+    return GLYPHS[character.toUpperCase()] !== undefined;
+}
+/** Width of a string in cells, spacing included, excluding the trailing gap. */
+export function measureText(text) {
+    if (text.length === 0)
+        return 0;
+    return text.length * (GLYPH_WIDTH + GLYPH_SPACING) - GLYPH_SPACING;
+}
+/** How many lit cells a string needs, which is how many boxes it costs. */
+export function countCells(text) {
+    let cells = 0;
+    for (const character of text) {
+        for (const row of glyphRows(character)) {
+            for (let x = 0; x < GLYPH_WIDTH; x++) {
+                if ((row & (1 << (GLYPH_WIDTH - 1 - x))) !== 0)
+                    cells++;
+            }
+        }
+    }
+    return cells;
+}
+/**
+ * Walk every lit cell of a string.
+ *
+ * Coordinates are in cells, origin at the string's left baseline: x increases
+ * right, y increases *up*, so the caller works in the same handedness as the
+ * rest of the engine rather than in text-editor coordinates.
+ *
+ * `charIndex` comes along because per-character animation is the whole point —
+ * a message where every letter arrives at once is a label, and one where they
+ * arrive in sequence is an event.
+ */
+/**
+ * Every horizontal run of lit cells, as one span each.
+ *
+ * **Because a box per cell is most of a world.** A consumer measured their village at 2,662,324
+ * triangles of which **1,195,296 — forty-five per cent — were the lettering** on 169 street plates
+ * and 830 house numbers, one box of twelve triangles at each of 65,271 lit cells. A run of three
+ * lit cells side by side is three boxes with four interior faces between them that nothing can ever
+ * see, and one box the same shape outside.
+ *
+ * **Horizontal only, and that is a measurement rather than a simplification.** Against that
+ * consumer's own 1,168 strings, merging runs takes 65,271 cells to 42,631 boxes, and a greedy
+ * rectangle merge over two dimensions gives *exactly the same number* — in a glyph five cells wide
+ * there is nothing vertical left to win, and the second pass would be code that never pays.
+ *
+ * A run never crosses a glyph, because the cursor advances by `GLYPH_WIDTH + GLYPH_SPACING` and
+ * that spacing is a column of unlit cells.
+ */
+export function forEachRun(text, visit) {
+    let cursor = 0;
+    let charIndex = 0;
+    for (const character of text) {
+        const rows = glyphRows(character);
+        for (let row = 0; row < rows.length; row++) {
+            const bits = rows[row] ?? 0;
+            const y = GLYPH_HEIGHT - 1 - row;
+            let runStart = -1;
+            for (let x = 0; x <= GLYPH_WIDTH; x++) {
+                const lit = x < GLYPH_WIDTH && (bits & (1 << (GLYPH_WIDTH - 1 - x))) !== 0;
+                if (lit && runStart < 0)
+                    runStart = x;
+                else if (!lit && runStart >= 0) {
+                    visit(cursor + runStart, y, x - runStart, charIndex);
+                    runStart = -1;
+                }
+            }
+        }
+        cursor += GLYPH_WIDTH + GLYPH_SPACING;
+        charIndex++;
+    }
+}
+export function forEachCell(text, visit) {
+    let cursor = 0;
+    let charIndex = 0;
+    for (const character of text) {
+        const rows = glyphRows(character);
+        for (let row = 0; row < rows.length; row++) {
+            const bits = rows[row] ?? 0;
+            // Row 0 is the top of the glyph, so it is the highest y.
+            const y = GLYPH_HEIGHT - 1 - row;
+            for (let x = 0; x < GLYPH_WIDTH; x++) {
+                if ((bits & (1 << (GLYPH_WIDTH - 1 - x))) !== 0)
+                    visit(cursor + x, y, charIndex);
+            }
+        }
+        cursor += GLYPH_WIDTH + GLYPH_SPACING;
+        charIndex++;
+    }
+}

package/dist/geometry/ribbon.d.ts

@@ -0,0 +1,101 @@
+/**
+ * A banked surface swept along a spline: the drawn slab and the colliders that
+ * stop you falling through it.
+ *
+ * Collision is the mesh: every drawn triangle of the deck becomes a wedge with
+ * the slab's depth under it, so the geometry a player sees is exactly the
+ * geometry that stops them — banked, climbing, or twisted. The exact ground
+ * they *stand* on still comes from `RibbonSurface`, which answers from the
+ * curve itself; the wedges keep a body out of the slab from every other
+ * direction.
+ */
+import type { MeshData } from '../render/mesh.ts';
+import type { Vec3 } from '../math/color.ts';
+import type { Collider } from '@driftengine/physics';
+import { Spline } from './spline.ts';
+/** A stretch of arc length where the surface simply is not there. */
+export interface RibbonHole {
+    fromM: number;
+    toM: number;
+}
+export interface RibbonOptions {
+    color: Vec3;
+    emissive?: number;
+    /** Distance between cross-sections. Smaller is smoother and heavier. */
+    stepM?: number;
+    /** Depth of the slab below the surface. */
+    thicknessM?: number;
+    /** Interruptions: an unbridged track is a jump, and jumps are the point. */
+    holes?: readonly RibbonHole[];
+    /**
+     * Called per cross-section to vary the surface along the route.
+     *
+     * Writes the colour into `out` and returns the emissive strength. The hook
+     * exists so a generator can give each stretch its own material without
+     * building a separate ribbon per segment — a route in one flat tone reads as
+     * a painted strip rather than as something built.
+     */
+    shade?: (distanceM: number, out: Vec3) => number;
+    /**
+     * Build only a band along one edge instead of the whole surface.
+     *
+     * For kerbs: a strip this wide, inset from the chosen edge and lifted clear,
+     * with the surface's own banking. Doing it as a second ribbon rather than as
+     * geometry bolted on afterwards means the kerb follows the bank exactly, and
+     * it is the banking that makes an edge hard to read without one.
+     */
+    edgeBandM?: number;
+    edgeSide?: -1 | 1;
+    /**
+     * Build a band between two *absolute* lateral offsets instead of edge-relative
+     * ones — for anything painted at a particular place across the surface rather
+     * than along its edge.
+     *
+     * The alternative is to lay a row of small boxes along the route, and it does
+     * not work: an axis-aligned box cannot follow a curve, so the row steps into a
+     * zigzag and reads as a staircase of holes rather than as a marking. Built as a
+     * ribbon it follows the centreline and the bank exactly, for free.
+     */
+    lateralFromM?: number;
+    lateralToM?: number;
+    /** Restrict the build to a stretch of the curve. */
+    fromM?: number;
+    toM?: number;
+    /** Raise the whole band by this much, so a kerb stands proud of the surface. */
+    liftM?: number;
+    /**
+     * How far below the drawn surface the collider hulls' tops sit, metres.
+     *
+     * A consumer's ground query rides the *smooth* curve; the hulls are the
+     * *faceted* mesh, and at a crest a facet ridge stands a few centimetres
+     * proud of the curve — each ridge a micro-wall under a character's feet if the
+     * hulls are exactly flush. The give hands the top few centimetres to the
+     * smooth query and everything beneath to the hull: a tolerance between two
+     * representations of the same surface, not a hole in the world — the slab's
+     * sides and underside stay exactly where they are drawn. Zero means flush.
+     */
+    colliderGiveM?: number;
+}
+/**
+ * Spacing of the cross-sections a ribbon's mesh is built from, metres.
+ *
+ * Exported because it is not only the builder's business: `RibbonSurface` has to know it to
+ * agree with the geometry at a hole's edge, where the mesh deliberately keeps the bordering
+ * section. A copy of this number in the physics module is a copy that drifts.
+ */
+export declare const RIBBON_STEP_M = 2;
+/**
+ * Default collider give: comfortably past the sagitta of a `RIBBON_STEP_M`
+ * facet at the tightest curvature a route reaches (a hairpin near 6 m radius:
+ * 2² / (8 · 6) ≈ 0.08), because a give that only just covers the facet error
+ * still brushes the character at every ridge — felt as braking on exactly the
+ * curves a route wants taken at speed. Small enough that nothing passes
+ * through the gap: it is backed by solid hull immediately beneath, and only
+ * the top eases — sides and underside collide exactly where they are drawn.
+ */
+export declare const RIBBON_COLLIDER_GIVE_M = 0.15;
+export interface RibbonMesh {
+    mesh: MeshData;
+    colliders: Collider[];
+}
+export declare function buildRibbon(spline: Spline, options: RibbonOptions): RibbonMesh;