ugly-game 0.1.0 → 0.2.0

package/dist/ir.d.ts

@@ -0,0 +1,152 @@
+import { type Input, type SimState } from './playSim';
+import { type Probe, type CaptureResult } from './capture';
+export declare const IR_VERSION = 2;
+export interface IRMeta {
+    irVersion: number;
+    app: string;
+    page: string;
+    buildId: string;
+    sessionId: string;
+    startedAtMs: number;
+    seed: number;
+    ua: string;
+}
+export interface IREntity {
+    id: string;
+    kind: string;
+    role?: string;
+    materialId?: string;
+    meshRef?: string;
+    attachedTo?: string;
+}
+export interface IRMaterial {
+    id: string;
+    color?: string;
+    roughness?: number;
+    metalness?: number;
+    emissive?: string;
+    emissiveIntensity?: number;
+    maps?: {
+        slot: string;
+        name: string;
+        wrapS?: string;
+        wrapT?: string;
+        repeat?: [number, number];
+        size?: [number, number];
+    }[];
+}
+export interface IRLight {
+    id: string;
+    type: string;
+    color: string;
+    intensity: number;
+    pos?: [number, number, number];
+}
+export interface IRSceneManifest {
+    entities: IREntity[];
+    materials: IRMaterial[];
+    lights: IRLight[];
+}
+export interface IRSnapshot {
+    meta: IRMeta;
+    scene: IRSceneManifest;
+    startFrame: number;
+    startRngState: number;
+    startState: SimState;
+    inputs: Input[];
+    keyframes: {
+        f: number;
+        s: SimState;
+        rngState: number;
+    }[];
+    renderProbes?: RenderProbe[];
+    reason: 'error' | 'feedback' | 'manual';
+    note?: string;
+    capturedAtFrame: number;
+}
+/** A render/audio-layer measurement sampled from the LIVE scene (mesh + mixer + audio
+ *  context) — the things deterministic replay can't reconstruct because they live in the
+ *  GLB/mixer/WebAudio, not the sim. Captured sparsely (keyframe-like) by the client/harness;
+ *  `analyzeTrajectory` reads them to catch bugs the sim is structurally blind to (a
+ *  character that visibly shrinks when an animation plays, TTS that "speaks" with no audio). */
+export interface RenderProbe {
+    frame: number;
+    charScale?: number;
+    headY?: number;
+    gait?: 0 | 1 | 2;
+    ttsSpeaking?: boolean;
+    audioPlaying?: boolean;
+}
+export interface IRAnomaly {
+    severity: 'warn' | 'error';
+    code: string;
+    msg: string;
+    frames?: [number, number];
+    detail?: unknown;
+}
+export declare class IRRecorder {
+    meta: IRMeta;
+    scene: IRSceneManifest;
+    startState: SimState;
+    startFrame: number;
+    startRngState: number;
+    inputs: Input[];
+    keyframes: {
+        f: number;
+        s: SimState;
+        rngState: number;
+    }[];
+    renderProbes: RenderProbe[];
+    private cap;
+    private keyEvery;
+    constructor(meta: Omit<IRMeta, 'irVersion'>, startState: SimState, capFrames?: number, keyEvery?: number);
+    registerEntity(e: IREntity): void;
+    registerMaterial(m: IRMaterial): void;
+    registerLight(l: IRLight): void;
+    /** Record a render/audio-layer probe (see RenderProbe). Kept bounded like the input
+     *  window; dropped oldest-first when it exceeds the frame cap. */
+    recordRenderProbe(p: RenderProbe): void;
+    /** Record one tick. `state`/`rngState` are the sim + RNG state AFTER this step
+     *  (== the start of the next frame), stored periodically as a replay/seek anchor. */
+    recordTick(inp: Input, state: SimState, rngState: number): void;
+    /** Keep the LAST ~cap frames (a debug capture wants the run leading up to the issue).
+     *  Re-anchor the window to the latest keyframe ≤ the new start — carrying its sim +
+     *  RNG state — so the trimmed window still replays exactly. */
+    private reanchor;
+    snapshot(reason: IRSnapshot['reason'], note?: string): IRSnapshot;
+}
+/** Reconstruct the full state trajectory from the anchor (startState + rng) + input
+ *  stream, in a single O(n) pass. Same in the browser and Node — the CLI/agent calls
+ *  this to inspect any frame, and re-runs it after a fix to confirm. */
+export declare function replayTrajectory(snap: IRSnapshot): SimState[];
+/** Trim a snapshot to fit `maxBytes` (the D1 row ceiling a report rides in) by
+ *  re-anchoring to the latest keyframe that fits — dropping OLDEST frames first, and
+ *  carrying that keyframe's sim + RNG state so the result still replays exactly. */
+export declare function capIRSnapshot(snap: IRSnapshot, maxBytes?: number): IRSnapshot;
+export type CaptureLevel = 'hash' | 'counters' | 'entity' | 'full';
+export interface CaptureFilter {
+    region?: [number, number, number, number];
+    kinds?: number[];
+}
+/** A leveled + filtered probe over a reconstructed playSim state: hash (a per-tick fingerprint) →
+ *  counters (aggregate) → entity (per-body pose) → full (per-body pose + velocity). Reusable pattern:
+ *  a game supplies one of these to captureWindow/captureIR for its own state. */
+export declare function playProbe(level: CaptureLevel, filter?: CaptureFilter): Probe<SimState>;
+/** Replay the IR and CAPTURE detail at a chosen level + filter over an absolute-frame window — the IR's
+ *  leveled, filterable extraction, riding the shared capture.ts engine. `from`/`to` are ABSOLUTE frames
+ *  (default = the whole recorded window), clamped to what's recorded. Offline; zero live cost. */
+export declare function captureIR(snap: IRSnapshot, opts: {
+    level: CaptureLevel;
+    from?: number;
+    to?: number;
+    filter?: CaptureFilter;
+    probe?: Probe<SimState>;
+}): CaptureResult;
+/** A few built-in INVARIANT checks (the two live bugs are the first test cases).
+ *  The real value is agent-queryable data + replay; these are sanity assertions, not
+ *  the product. Runs the deterministic replay, then inspects the reconstructed states. */
+export declare function analyzeIR(snap: IRSnapshot): IRAnomaly[];
+/** The invariant checks, over any reconstructed trajectory. Exported so the ugly-game
+ *  CLI (and tests) can run them on a replayed run — and so they act as REGRESSION
+ *  GUARDS: feed a buggy trajectory (drifting camera / flat mouth) and they fire. */
+export declare function analyzeTrajectory(T: SimState[], inputs: Input[], scene: IRSceneManifest, probes?: RenderProbe[]): IRAnomaly[];

package/dist/ir.js

@@ -0,0 +1,287 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// ugly-game IR (intermediate representation) — v2, replay-based
+//
+// The debuggability moat: a structured, AI-parseable record of a run so an agent
+// can diagnose from DATA (and re-run it), not screenshots. Because the sim is
+// deterministic (playSim), the IR is TINY and truly replayable: a scene *manifest*
+// (entities/materials/lights) + the RNG *seed* + the per-tick *input stream* +
+// periodic state *keyframes* (seek anchors). The dynamic state is not stored — it's
+// RECONSTRUCTED by re-running playSim.step over the input stream, identically in the
+// browser or in Node (the ugly-game CLI). Re-running after a code fix proves the fix.
+//
+// v2 lives in the demo (the sim is /play-specific). It graduates to the ugly-game
+// package + the owned ECS once the theory holds; the manifest is the shim that
+// stands in for the ECS component snapshot until the ECS exists.
+// ─────────────────────────────────────────────────────────────────────────────
+import { step, rngFromState, NO_INPUT, cloneState, SPEED, CLIP_BASE } from './playSim';
+import { captureWindow } from './capture';
+import { fnv1a } from './stateTree';
+export const IR_VERSION = 2;
+// ─── Recorder (client-side) ──────────────────────────────────────────────────
+export class IRRecorder {
+    meta;
+    scene = { entities: [], materials: [], lights: [] };
+    startState;
+    startFrame = 0;
+    startRngState;
+    inputs = [];
+    keyframes = [];
+    renderProbes = [];
+    cap;
+    keyEvery;
+    constructor(meta, startState, capFrames = 3600, keyEvery = 300) {
+        this.meta = { irVersion: IR_VERSION, ...meta };
+        this.startState = cloneState(startState);
+        this.startRngState = meta.seed >>> 0; // RNG state at frame 0 == the seed
+        this.cap = capFrames;
+        this.keyEvery = keyEvery;
+    }
+    registerEntity(e) { if (!this.scene.entities.some((x) => x.id === e.id))
+        this.scene.entities.push(e); }
+    registerMaterial(m) { if (!this.scene.materials.some((x) => x.id === m.id))
+        this.scene.materials.push(m); }
+    registerLight(l) { if (!this.scene.lights.some((x) => x.id === l.id))
+        this.scene.lights.push(l); }
+    /** Record a render/audio-layer probe (see RenderProbe). Kept bounded like the input
+     *  window; dropped oldest-first when it exceeds the frame cap. */
+    recordRenderProbe(p) {
+        this.renderProbes.push(p);
+        const floor = this.startFrame;
+        while (this.renderProbes.length && this.renderProbes[0].frame < floor)
+            this.renderProbes.shift();
+    }
+    /** Record one tick. `state`/`rngState` are the sim + RNG state AFTER this step
+     *  (== the start of the next frame), stored periodically as a replay/seek anchor. */
+    recordTick(inp, state, rngState) {
+        this.inputs.push(inp);
+        const abs = this.startFrame + this.inputs.length; // absolute frame count after this tick
+        if (abs % this.keyEvery === 0)
+            this.keyframes.push({ f: abs, s: cloneState(state), rngState });
+        if (this.inputs.length > this.cap)
+            this.reanchor();
+    }
+    /** Keep the LAST ~cap frames (a debug capture wants the run leading up to the issue).
+     *  Re-anchor the window to the latest keyframe ≤ the new start — carrying its sim +
+     *  RNG state — so the trimmed window still replays exactly. */
+    reanchor() {
+        const abs = this.startFrame + this.inputs.length;
+        const windowStart = abs - this.cap;
+        let kf = null;
+        for (const k of this.keyframes)
+            if (k.f <= windowStart && k.f > this.startFrame)
+                kf = k;
+        if (!kf)
+            return; // no interior keyframe yet — keep the full window
+        this.inputs = this.inputs.slice(kf.f - this.startFrame);
+        this.startState = cloneState(kf.s);
+        this.startRngState = kf.rngState;
+        this.startFrame = kf.f;
+        this.keyframes = this.keyframes.filter((k) => k.f >= kf.f);
+    }
+    snapshot(reason, note) {
+        const snap = { meta: this.meta, scene: this.scene, startFrame: this.startFrame, startRngState: this.startRngState, startState: this.startState, inputs: this.inputs.slice(), keyframes: this.keyframes.slice(), reason, capturedAtFrame: this.startFrame + this.inputs.length };
+        if (this.renderProbes.length)
+            snap.renderProbes = this.renderProbes.slice();
+        if (note !== undefined)
+            snap.note = note;
+        return snap;
+    }
+}
+// ─── Replay + analysis (shared by client & CLI; the moat) ────────────────────
+/** Reconstruct the full state trajectory from the anchor (startState + rng) + input
+ *  stream, in a single O(n) pass. Same in the browser and Node — the CLI/agent calls
+ *  this to inspect any frame, and re-runs it after a fix to confirm. */
+export function replayTrajectory(snap) {
+    const s = cloneState(snap.startState);
+    const rng = rngFromState(snap.startRngState);
+    const out = [];
+    for (let i = 0; i < snap.inputs.length; i++) {
+        step(s, snap.inputs[i] ?? NO_INPUT, rng, snap.startFrame + i);
+        out.push(cloneState(s));
+    }
+    return out;
+}
+/** Trim a snapshot to fit `maxBytes` (the D1 row ceiling a report rides in) by
+ *  re-anchoring to the latest keyframe that fits — dropping OLDEST frames first, and
+ *  carrying that keyframe's sim + RNG state so the result still replays exactly. */
+export function capIRSnapshot(snap, maxBytes = 600_000) {
+    if (JSON.stringify(snap).length <= maxBytes)
+        return snap;
+    for (let i = snap.keyframes.length - 1; i >= 0; i--) {
+        const kf = snap.keyframes[i];
+        const drop = kf.f - snap.startFrame;
+        if (drop <= 0)
+            continue;
+        const trimmed = { ...snap, startFrame: kf.f, startRngState: kf.rngState, startState: kf.s, inputs: snap.inputs.slice(drop), keyframes: snap.keyframes.filter((k) => k.f >= kf.f) };
+        if (snap.renderProbes)
+            trimmed.renderProbes = snap.renderProbes.filter((p) => p.frame >= kf.f);
+        if (JSON.stringify(trimmed).length <= maxBytes)
+            return trimmed;
+    }
+    return snap; // no keyframe to anchor to — send as-is (best effort)
+}
+const rnd = (v) => Math.round(v * 1000) / 1000;
+/** A leveled + filtered probe over a reconstructed playSim state: hash (a per-tick fingerprint) →
+ *  counters (aggregate) → entity (per-body pose) → full (per-body pose + velocity). Reusable pattern:
+ *  a game supplies one of these to captureWindow/captureIR for its own state. */
+export function playProbe(level, filter = {}) {
+    return (s, tick) => {
+        if (level === 'hash')
+            return [{ tick, hash: fnv1a(`${rnd(s.x)},${rnd(s.z)},${rnd(s.y)},${s.gait},${s.bodies.length}`) }];
+        if (level === 'counters') {
+            let sp = 0;
+            for (const b of s.bodies)
+                sp += Math.hypot(b.vx, b.vy, b.vz);
+            return [{ tick, bodies: s.bodies.length, x: rnd(s.x), z: rnd(s.z), y: rnd(s.y), gait: s.gait, avgSpeed: rnd(sp / Math.max(1, s.bodies.length)) }];
+        }
+        const rows = [];
+        for (let i = 0; i < s.bodies.length; i++) {
+            const b = s.bodies[i];
+            if (filter.kinds && !filter.kinds.includes(b.kind))
+                continue;
+            if (filter.region && !(b.x >= filter.region[0] && b.z >= filter.region[1] && b.x <= filter.region[2] && b.z <= filter.region[3]))
+                continue;
+            if (level === 'entity')
+                rows.push({ tick, i, x: rnd(b.x), y: rnd(b.y), z: rnd(b.z), kind: b.kind, held: b.held ? 1 : 0 });
+            else
+                rows.push({ tick, i, x: rnd(b.x), y: rnd(b.y), z: rnd(b.z), vx: rnd(b.vx), vy: rnd(b.vy), vz: rnd(b.vz), kind: b.kind, r: rnd(b.r), held: b.held ? 1 : 0 });
+        }
+        return rows;
+    };
+}
+/** Replay the IR and CAPTURE detail at a chosen level + filter over an absolute-frame window — the IR's
+ *  leveled, filterable extraction, riding the shared capture.ts engine. `from`/`to` are ABSOLUTE frames
+ *  (default = the whole recorded window), clamped to what's recorded. Offline; zero live cost. */
+export function captureIR(snap, opts) {
+    const from = Math.max(0, (opts.from ?? snap.startFrame) - snap.startFrame);
+    const to = Math.min(snap.inputs.length, (opts.to ?? (snap.startFrame + snap.inputs.length)) - snap.startFrame);
+    const rng = rngFromState(snap.startRngState);
+    const advance = (s, tick) => { step(s, snap.inputs[tick] ?? NO_INPUT, rng, snap.startFrame + tick); };
+    return captureWindow(cloneState(snap.startState), cloneState, advance, from, to, opts.probe ?? playProbe(opts.level, opts.filter ?? {}), { label: snap.meta.page, level: opts.level });
+}
+/** A few built-in INVARIANT checks (the two live bugs are the first test cases).
+ *  The real value is agent-queryable data + replay; these are sanity assertions, not
+ *  the product. Runs the deterministic replay, then inspects the reconstructed states. */
+export function analyzeIR(snap) {
+    return analyzeTrajectory(replayTrajectory(snap), snap.inputs, snap.scene, snap.renderProbes);
+}
+/** The invariant checks, over any reconstructed trajectory. Exported so the ugly-game
+ *  CLI (and tests) can run them on a replayed run — and so they act as REGRESSION
+ *  GUARDS: feed a buggy trajectory (drifting camera / flat mouth) and they fire. */
+export function analyzeTrajectory(T, inputs, scene, probes) {
+    const out = [];
+    if (T.length < 4)
+        return out;
+    // 1) Camera "size drift": camDist must not change on ticks with no zoom input.
+    for (let f = 1; f < T.length; f++) {
+        if ((inputs[f]?.dzoom ?? 0) === 0 && Math.abs(T[f].camDist - T[f - 1].camDist) > 1e-6) {
+            out.push({ severity: 'error', code: 'camera-distance-drift', msg: `camDist changed with no zoom input at frame ${f} (${T[f - 1].camDist.toFixed(3)}→${T[f].camDist.toFixed(3)}) — objects would appear to resize`, frames: [f - 1, f] });
+            break;
+        }
+    }
+    // 2) Mouth flat while speaking → "talking does nothing".
+    const speaking = T.map((s, f) => ({ f, s })).filter((x) => x.s.speaking);
+    if (speaking.length >= 6) {
+        const vals = speaking.map((x) => x.s.mClose);
+        const range = Math.max(...vals) - Math.min(...vals);
+        if (range < 0.02)
+            out.push({ severity: 'error', code: 'mouth-flat-while-speaking', msg: `mouth influence flat (range ${range.toFixed(3)}) across ${speaking.length} speaking frames — driver not reaching the morph`, detail: { range } });
+    }
+    // 3) Texture tiling sanity (static manifest — the cyber-floor mis-tile).
+    for (const m of scene.materials)
+        for (const map of m.maps ?? []) {
+            if (map.repeat && map.repeat[0] <= 1.01 && map.repeat[1] <= 1.01) {
+                const ent = scene.entities.find((e) => e.materialId === m.id);
+                if (ent && /ground|floor|disc|plane/i.test(ent.kind))
+                    out.push({ severity: 'warn', code: 'texture-under-tiled', msg: `material '${m.id}' (${map.slot}) on '${ent.kind}' has repeat ${map.repeat[0]}×${map.repeat[1]} — likely stretched on a large surface`, detail: { material: m.id, repeat: map.repeat } });
+            }
+        }
+    // 4) PHYSICS invariants — the classic core-gaming bug classes, caught from the IR
+    //    (deterministic replay reconstructs every body's position each frame).
+    const finite = (b) => Number.isFinite(b.x) && Number.isFinite(b.y) && Number.isFinite(b.z) && Number.isFinite(b.vx) && Number.isFinite(b.vy) && Number.isFinite(b.vz);
+    outer: for (let f = 0; f < T.length; f++) {
+        const bs = T[f].bodies;
+        for (let i = 0; i < bs.length; i++) {
+            const b = bs[i];
+            if (!finite(b)) {
+                out.push({ severity: 'error', code: 'physics-nan', msg: `body ${i} has a non-finite value at frame ${f} — solver blew up`, frames: [f, f], detail: { body: i } });
+                break outer;
+            }
+            if (Math.hypot(b.vx, b.vy, b.vz) > 400) {
+                out.push({ severity: 'error', code: 'physics-explosion', msg: `body ${i} velocity ${Math.hypot(b.vx, b.vy, b.vz).toFixed(0)}m/s at frame ${f} — instability`, frames: [f, f], detail: { body: i } });
+                break outer;
+            }
+            if (b.y < -0.5) {
+                out.push({ severity: 'error', code: 'physics-fell-through-floor', msg: `body ${i} at y=${b.y.toFixed(2)} at frame ${f} — tunneled through the ground`, frames: [f, f], detail: { body: i } });
+                break outer;
+            }
+            for (let j = i + 1; j < bs.length; j++) {
+                const c = bs[j];
+                if (b.held || c.held || b.kind !== 0 || c.kind !== 0)
+                    continue; // objects only; debris/projectiles are transient
+                const d = Math.hypot(c.x - b.x, c.y - b.y, c.z - b.z);
+                const pen = b.r + c.r - d;
+                if (pen > 0.25 * Math.min(b.r, c.r)) {
+                    out.push({ severity: 'error', code: 'physics-penetration', msg: `bodies ${i}+${j} penetrate ${pen.toFixed(3)}m at frame ${f} — collision not resolved`, frames: [f, f], detail: { a: i, b: j, penetration: +pen.toFixed(3) } });
+                    break outer;
+                }
+            }
+        }
+    }
+    // spawn leak — projectiles/fragments must be reclaimed, so the body count stays bounded.
+    const maxBodies = Math.max(...T.map((s) => s.bodies.length));
+    if (maxBodies > 55)
+        out.push({ severity: 'error', code: 'physics-body-leak', msg: `body count peaked at ${maxBodies} — spawned projectiles/fragments not being reclaimed (expiry broken?)`, detail: { maxBodies } });
+    // 5) ANIMATION + SEMANTIC INTENT — the "it doesn't look right" bugs. These compare what
+    //    the game INTENDS (jump lifts you; feet match speed; shooting needs a weapon) with
+    //    what actually happened — the class of bug a state-only IR can't reason about.
+    const NT = T.length;
+    // jump must physically lift the character (not a render-only arc).
+    for (let i = 0; i < NT; i++) {
+        if (inputs[i]?.jump && T[i].jumpF >= 0) {
+            let maxY = 0;
+            for (let f = i; f < NT && T[f].jumpF >= 0; f++)
+                maxY = Math.max(maxY, T[f].y);
+            if (maxY < 0.3) {
+                out.push({ severity: 'error', code: 'jump-not-physical', msg: `jump at frame ${i} but character Y peaked at ${maxY.toFixed(2)}m — render-only arc, no vertical physics`, frames: [i, i] });
+                break;
+            }
+        }
+    }
+    // moonwalk: feet ground-speed (CLIP_BASE·animRate) must match actual move speed.
+    let maxSlip = 0, slipF = -1;
+    for (let f = 0; f < NT; f++) {
+        const g = T[f].gait;
+        if (g === 0)
+            continue;
+        const slip = Math.abs(SPEED[g] - CLIP_BASE[g] * T[f].animRate);
+        if (slip > maxSlip) {
+            maxSlip = slip;
+            slipF = f;
+        }
+    }
+    if (maxSlip > 0.3)
+        out.push({ severity: 'error', code: 'anim-foot-slip', msg: `locomotion foot-slip ${maxSlip.toFixed(2)} m/s @f${slipF} — feet cadence ≠ move speed (moonwalk); sync animRate to speed`, frames: [slipF, slipF], detail: { slip: +maxSlip.toFixed(2) } });
+    // shooting with no weapon — bullets from nothing (needs a semantic role in the scene).
+    if (inputs.some((x) => x.shoot) && !scene.entities.some((e) => e.role === 'weapon'))
+        out.push({ severity: 'error', code: 'weapon-missing', msg: `projectiles fired but no entity has role 'weapon' — bullets spawn from the body`, detail: { entities: scene.entities.length } });
+    // 6) RENDER-LAYER checks — over the live probes (things replay can't reconstruct).
+    if (probes && probes.length >= 3) {
+        // anim-size-change: the character's uniform scale must not pop when an animation plays.
+        // (idle inflating bone scale to 1.176 while locomotion clips reset it to 1.0 → shrink-on-move.)
+        const sc = probes.map((p) => p.charScale).filter((v) => typeof v === 'number');
+        if (sc.length >= 3) {
+            const lo = Math.min(...sc), hi = Math.max(...sc);
+            if (lo > 0 && hi / lo - 1 > 0.05) {
+                const at = probes.find((p) => p.charScale === lo)?.frame ?? -1;
+                out.push({ severity: 'error', code: 'anim-size-change', msg: `character render-scale varies ${((hi / lo - 1) * 100).toFixed(0)}% across animations (${lo.toFixed(3)}→${hi.toFixed(3)}) — the rig visibly resizes when a clip plays; strip scale tracks so only pose animates`, frames: [at, at], detail: { min: +lo.toFixed(3), max: +hi.toFixed(3) } });
+            }
+        }
+        // tts-no-audio: the app reports it is speaking but the audio graph makes no sound.
+        const spoke = probes.filter((p) => p.ttsSpeaking);
+        if (spoke.length >= 3 && spoke.every((p) => p.audioPlaying === false)) {
+            out.push({ severity: 'error', code: 'tts-no-audio', msg: `TTS reported speaking on ${spoke.length} probes but the audio graph never played — visemes animate silently (audio context suspended / not unlocked)`, frames: [spoke[0].frame, spoke[spoke.length - 1].frame], detail: { speakingProbes: spoke.length } });
+        }
+    }
+    return out;
+}

package/dist/kcc.d.ts

@@ -0,0 +1,47 @@
+export declare const GRAVITY = 24, MOVE_SPEED = 6, JUMP_V = 9, STEP_H = 0.55, CHAR_R = 0.4, SNAP = 0.35;
+export interface Box {
+    minx: number;
+    miny: number;
+    minz: number;
+    maxx: number;
+    maxy: number;
+    maxz: number;
+}
+export interface Char {
+    x: number;
+    y: number;
+    z: number;
+    vx: number;
+    vy: number;
+    vz: number;
+    grounded: 0 | 1;
+    r: number;
+}
+export interface KccState {
+    boxes: Box[];
+    ch: Char;
+    tick: number;
+}
+export interface KccInput {
+    mv: number;
+    strafe: number;
+    yaw: number;
+    jump: 0 | 1;
+}
+export declare const NO_KCC_INPUT: KccInput;
+export declare const box: (minx: number, miny: number, minz: number, maxx: number, maxy: number, maxz: number) => Box;
+export interface Contact {
+    pen: number;
+    nx: number;
+    ny: number;
+    nz: number;
+}
+/** Sphere-vs-AABB overlap → penetration depth + outward normal, or null if disjoint. */
+export declare function sphereBox(cx: number, cy: number, cz: number, r: number, b: Box): Contact | null;
+/** One deterministic physics tick: gravity/jump → vertical move → horizontal move+slide → step-up → ground snap. */
+export declare function kccStep(s: KccState, inp: KccInput): void;
+export declare function initChar(x: number, y: number, z: number): Char;
+export declare function cloneKcc(s: KccState): KccState;
+export declare function hashKcc(s: KccState): string;
+export declare function anyPenetration(s: KccState): number;
+export declare function buildLevel(): KccState;