@remix-gg/three 0.1.1

package/dist/assets.d.ts

@@ -0,0 +1,36 @@
+import { type AnimationClip, type BufferGeometry, type Group, type Material, type Texture } from 'three';
+/**
+ * Manifest values MUST be literal strings like `'assets/hero.glb'`.
+ *
+ * `remix publish` finds every asset a build references with
+ * `/(?:\.\/|\/)?assets\/([A-Za-z0-9._-]+)/g` over the bundled code and rewrites
+ * each one to its hosted CDN URL. A path built at runtime — `` `assets/${name}` ``
+ * — is invisible to that regex, so it uploads nothing and the published game
+ * 404s on a file that worked perfectly in dev.
+ */
+export type AssetManifest = {
+    textures?: Record<string, string>;
+    models?: Record<string, string>;
+    audio?: Record<string, string>;
+    json?: Record<string, string>;
+};
+export type Assets = {
+    texture(key: string): Texture;
+    /** A fresh clone every call — never mutate the cached original. */
+    model(key: string): Group;
+    animations(key: string): AnimationClip[];
+    sound(key: string): AudioBuffer;
+    json<T = unknown>(key: string): T;
+    load(manifest: AssetManifest, onProgress?: (loaded: number, total: number) => void): Promise<void>;
+    /**
+     * Every resource the cache owns. Pass it as `skip` to disposal so a restart
+     * never frees a shared asset out from under the next run.
+     */
+    readonly owned: ReadonlySet<Texture | BufferGeometry | Material>;
+};
+export type AssetsOptions = {
+    /** Supplied by the audio bus, which owns the AudioContext. */
+    decodeAudio?: (data: ArrayBuffer) => Promise<AudioBuffer>;
+};
+export declare function createAssets(options?: AssetsOptions): Assets;
+//# sourceMappingURL=assets.d.ts.map

package/dist/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,KAAK,EACV,KAAK,QAAQ,EAGb,KAAK,OAAO,EAEb,MAAM,OAAO,CAAA;AAId;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC9B,CAAA;AAED,MAAM,MAAM,MAAM,GAAG;IACnB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IAC7B,mEAAmE;IACnE,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAA;IACzB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,EAAE,CAAA;IACxC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAA;IAC/B,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAAA;IACjC,IAAI,CAAC,QAAQ,EAAE,aAAa,EAAE,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClG;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,OAAO,GAAG,cAAc,GAAG,QAAQ,CAAC,CAAA;CACjE,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,8DAA8D;IAC9D,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,WAAW,CAAC,CAAA;CAC1D,CAAA;AASD,wBAAgB,YAAY,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CA8GhE"}

package/dist/assets.js

@@ -0,0 +1,100 @@
+import { SRGBColorSpace, TextureLoader, } from 'three';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { clone as cloneSkinned } from 'three/addons/utils/SkeletonUtils.js';
+export function createAssets(options = {}) {
+    const loaded = {
+        textures: new Map(),
+        models: new Map(),
+        audio: new Map(),
+        json: new Map(),
+    };
+    const owned = new Set();
+    const textureLoader = new TextureLoader();
+    const gltfLoader = new GLTFLoader();
+    function require(map, key, kind) {
+        const value = map.get(key);
+        if (value === undefined) {
+            throw new Error(`Asset '${key}' is not a loaded ${kind}. Add it to the manifest passed to createGame.`);
+        }
+        return value;
+    }
+    function ownResources(root) {
+        root.traverse((node) => {
+            const renderable = node;
+            if (renderable.geometry)
+                owned.add(renderable.geometry);
+            const material = renderable.material;
+            if (!material)
+                return;
+            for (const entry of Array.isArray(material) ? material : [material]) {
+                owned.add(entry);
+                for (const value of Object.values(entry)) {
+                    if (value?.isTexture)
+                        owned.add(value);
+                }
+            }
+        });
+    }
+    async function loadTexture(key, url) {
+        const texture = await textureLoader.loadAsync(url);
+        // Colour textures are authored in sRGB; leaving three's default linear
+        // interpretation is why untagged textures look washed out.
+        texture.colorSpace = SRGBColorSpace;
+        texture.anisotropy = 4;
+        loaded.textures.set(key, texture);
+        owned.add(texture);
+    }
+    async function loadModel(key, url) {
+        // No Draco or KTX2: their decoders are side-loaded .wasm/.js files, and a
+        // published Remix game is a single self-contained HTML document.
+        const gltf = await gltfLoader.loadAsync(url);
+        loaded.models.set(key, { scene: gltf.scene, animations: gltf.animations });
+        ownResources(gltf.scene);
+    }
+    async function loadAudio(key, url) {
+        if (!options.decodeAudio)
+            return;
+        const response = await fetch(url);
+        if (!response.ok)
+            throw new Error(`Failed to load audio '${key}' from ${url}`);
+        loaded.audio.set(key, await options.decodeAudio(await response.arrayBuffer()));
+    }
+    async function loadJson(key, url) {
+        const response = await fetch(url);
+        if (!response.ok)
+            throw new Error(`Failed to load json '${key}' from ${url}`);
+        loaded.json.set(key, await response.json());
+    }
+    return {
+        texture: (key) => require(loaded.textures, key, 'texture'),
+        model(key) {
+            const entry = require(loaded.models, key, 'model');
+            // SkeletonUtils.clone, not Object3D.clone: the plain clone shares the
+            // skeleton, so two clones of a rigged model animate as one.
+            return cloneSkinned(entry.scene);
+        },
+        animations: (key) => require(loaded.models, key, 'model').animations,
+        sound: (key) => require(loaded.audio, key, 'sound'),
+        json: (key) => require(loaded.json, key, 'json'),
+        async load(manifest, onProgress) {
+            const jobs = [];
+            for (const [key, url] of Object.entries(manifest.textures ?? {}))
+                jobs.push(() => loadTexture(key, url));
+            for (const [key, url] of Object.entries(manifest.models ?? {}))
+                jobs.push(() => loadModel(key, url));
+            for (const [key, url] of Object.entries(manifest.audio ?? {}))
+                jobs.push(() => loadAudio(key, url));
+            for (const [key, url] of Object.entries(manifest.json ?? {}))
+                jobs.push(() => loadJson(key, url));
+            const total = jobs.length;
+            let done = 0;
+            onProgress?.(0, total);
+            await Promise.all(jobs.map(async (job) => {
+                await job();
+                done++;
+                onProgress?.(done, total);
+            }));
+        },
+        owned,
+    };
+}

package/dist/audio.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Two buses over one AudioContext: music and sfx.
+ *
+ * The separation exists because the platform's mute is not a volume control —
+ * `toggle_mute` is a player-level "this game is silent now" and must take
+ * effect within a frame, while the game keeps its own music/sfx balance
+ * untouched underneath so unmuting restores exactly what was there.
+ */
+export type PlaySfxOptions = {
+    volume?: number;
+    /** Playback rate. Randomising it slightly stops repeated hits sounding fake. */
+    rate?: number;
+    /** -1 left .. 1 right. */
+    pan?: number;
+};
+export type PlayMusicOptions = {
+    volume?: number;
+    loop?: boolean;
+    /** Seconds. */
+    fadeIn?: number;
+};
+export type AudioBus = {
+    /**
+     * Resumes the context. Mobile browsers start it suspended and only a real
+     * user gesture may resume it, so `createGame` calls this on the first press.
+     */
+    unlock(): Promise<void>;
+    decode(data: ArrayBuffer): Promise<AudioBuffer>;
+    playSfx(key: string, options?: PlaySfxOptions): void;
+    playMusic(key: string, options?: PlayMusicOptions): void;
+    stopMusic(fadeOut?: number): void;
+    musicVolume: number;
+    sfxVolume: number;
+    readonly muted: boolean;
+    setMuted(muted: boolean): void;
+    dispose(): void;
+};
+export type AudioOptions = {
+    sound: (key: string) => AudioBuffer | undefined;
+};
+export declare function createAudio(options: AudioOptions): AudioBus;
+//# sourceMappingURL=audio.d.ts.map

package/dist/audio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio.d.ts","sourceRoot":"","sources":["../src/audio.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0BAA0B;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,eAAe;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG;IACrB;;;OAGG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACvB,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC/C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI,CAAA;IACpD,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAA;IACxD,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;IAC9B,OAAO,IAAI,IAAI,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,CAAA;CAChD,CAAA;AASD,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,QAAQ,CAwJ3D"}

package/dist/audio.js

@@ -0,0 +1,150 @@
+export function createAudio(options) {
+    let graph = null;
+    let musicSource = null;
+    let musicVolume = 0.6;
+    let sfxVolume = 1;
+    let muted = false;
+    function ensure() {
+        if (graph)
+            return graph;
+        const Ctor = window.AudioContext ??
+            window.webkitAudioContext;
+        if (!Ctor)
+            throw new Error('Web Audio is unavailable in this runtime');
+        const context = new Ctor();
+        const master = context.createGain();
+        const music = context.createGain();
+        const sfx = context.createGain();
+        master.gain.value = muted ? 0 : 1;
+        music.gain.value = musicVolume;
+        sfx.gain.value = sfxVolume;
+        music.connect(master);
+        sfx.connect(master);
+        master.connect(context.destination);
+        graph = { context, master, music, sfx };
+        return graph;
+    }
+    const onVisibility = () => {
+        if (!graph)
+            return;
+        // Suspending on hide is not politeness: an iOS WebView that keeps an active
+        // context in the background gets its audio session killed outright.
+        if (document.visibilityState === 'hidden')
+            void graph.context.suspend();
+        else if (!muted)
+            void graph.context.resume();
+    };
+    document.addEventListener('visibilitychange', onVisibility);
+    return {
+        async unlock() {
+            const { context } = ensure();
+            if (context.state !== 'running')
+                await context.resume();
+        },
+        decode(data) {
+            return ensure().context.decodeAudioData(data);
+        },
+        playSfx(key, sfxOptions = {}) {
+            const buffer = options.sound(key);
+            if (!buffer || muted)
+                return;
+            const { context, sfx } = ensure();
+            if (context.state !== 'running')
+                return;
+            const source = context.createBufferSource();
+            source.buffer = buffer;
+            source.playbackRate.value = sfxOptions.rate ?? 1;
+            const gain = context.createGain();
+            gain.gain.value = sfxOptions.volume ?? 1;
+            if (sfxOptions.pan !== undefined && context.createStereoPanner) {
+                const panner = context.createStereoPanner();
+                panner.pan.value = Math.max(-1, Math.min(1, sfxOptions.pan));
+                source.connect(gain).connect(panner).connect(sfx);
+            }
+            else {
+                source.connect(gain).connect(sfx);
+            }
+            source.start();
+            // One-shots are fire-and-forget; without this the nodes stay referenced.
+            source.onended = () => {
+                source.disconnect();
+                gain.disconnect();
+            };
+        },
+        playMusic(key, musicOptions = {}) {
+            const buffer = options.sound(key);
+            if (!buffer)
+                return;
+            const { context, music } = ensure();
+            this.stopMusic(0);
+            const source = context.createBufferSource();
+            source.buffer = buffer;
+            source.loop = musicOptions.loop ?? true;
+            source.connect(music);
+            const target = musicOptions.volume ?? musicVolume;
+            const fade = musicOptions.fadeIn ?? 0;
+            if (fade > 0) {
+                music.gain.cancelScheduledValues(context.currentTime);
+                music.gain.setValueAtTime(0, context.currentTime);
+                music.gain.linearRampToValueAtTime(target, context.currentTime + fade);
+            }
+            else {
+                music.gain.value = target;
+            }
+            source.start();
+            musicSource = source;
+        },
+        stopMusic(fadeOut = 0) {
+            const source = musicSource;
+            if (!source || !graph)
+                return;
+            musicSource = null;
+            if (fadeOut <= 0) {
+                source.stop();
+                source.disconnect();
+                return;
+            }
+            const { context, music } = graph;
+            music.gain.cancelScheduledValues(context.currentTime);
+            music.gain.setValueAtTime(music.gain.value, context.currentTime);
+            music.gain.linearRampToValueAtTime(0, context.currentTime + fadeOut);
+            source.stop(context.currentTime + fadeOut);
+            source.onended = () => source.disconnect();
+        },
+        get musicVolume() {
+            return musicVolume;
+        },
+        set musicVolume(value) {
+            musicVolume = Math.max(0, value);
+            if (graph)
+                graph.music.gain.value = musicVolume;
+        },
+        get sfxVolume() {
+            return sfxVolume;
+        },
+        set sfxVolume(value) {
+            sfxVolume = Math.max(0, value);
+            if (graph)
+                graph.sfx.gain.value = sfxVolume;
+        },
+        get muted() {
+            return muted;
+        },
+        setMuted(next) {
+            muted = next;
+            if (!graph)
+                return;
+            // Ramp rather than snap: a hard gain step on a playing buffer clicks.
+            const { context, master } = graph;
+            master.gain.cancelScheduledValues(context.currentTime);
+            master.gain.setValueAtTime(master.gain.value, context.currentTime);
+            master.gain.linearRampToValueAtTime(next ? 0 : 1, context.currentTime + 0.05);
+        },
+        dispose() {
+            document.removeEventListener('visibilitychange', onVisibility);
+            this.stopMusic(0);
+            void graph?.context.close();
+            graph = null;
+        },
+    };
+}

package/dist/camera.d.ts

@@ -0,0 +1,72 @@
+import { type Box3, OrthographicCamera, PerspectiveCamera, Vector3 } from 'three';
+import type { Viewport } from './viewport.js';
+export type GameCamera = PerspectiveCamera | OrthographicCamera;
+/**
+ * A rig owns its camera's resize and per-frame motion, so `createGame` never
+ * has to guess what a game meant by "portrait".
+ *
+ * `resize` is the load-bearing half: it opens the frustum by `viewport.scale`
+ * so the design box stays fully visible at any aspect. Pick a rig once and use
+ * `fitBounds` instead of hand-tuning coordinates.
+ */
+export type CameraRig = {
+    readonly camera: GameCamera;
+    resize(viewport: Viewport): void;
+    update(dt: number): void;
+};
+export type PortraitRigOptions = {
+    /** Vertical field of view in degrees at the design aspect. */
+    fov?: number;
+    position?: Vector3;
+    lookAt?: Vector3;
+    near?: number;
+    far?: number;
+};
+/**
+ * The default: a perspective camera looking slightly down at the origin, framed
+ * so the design box's height is exactly what `fov` covers at the design aspect.
+ */
+export declare function portraitRig(options?: PortraitRigOptions): CameraRig;
+export type OrthoRigOptions = {
+    /** World units visible vertically across the design box. */
+    frustumHeight?: number;
+    /** Yaw around Y. `Math.PI / 4` with the default pitch gives isometric. */
+    heading?: number;
+    /** Elevation in radians. `Math.atan(1 / Math.SQRT2)` ~= 0.6155 for isometric. */
+    pitch?: number;
+    distance?: number;
+    lookAt?: Vector3;
+    near?: number;
+    far?: number;
+};
+/** Orthographic rig. Isometric is this rig with `heading: Math.PI / 4`. */
+export declare function orthoRig(options?: OrthoRigOptions): CameraRig;
+export type FollowRigOptions = {
+    offset?: Vector3;
+    lookOffset?: Vector3;
+    /** Seconds to close ~63% of the gap. 0 snaps. */
+    smoothing?: number;
+    /** Clamps the camera's focus point, e.g. so it never runs past the level. */
+    bounds?: Box3;
+    fov?: number;
+    near?: number;
+    far?: number;
+};
+/** Perspective camera that chases an object with frame-rate-independent easing. */
+export declare function followRig(target: Object3DLike, options?: FollowRigOptions): CameraRig;
+/** Structural minimum of `THREE.Object3D` that `followRig` needs. */
+type Object3DLike = {
+    position: Vector3;
+};
+export type FitBoundsOptions = {
+    /** Slack around the bounds. 1.1 leaves 10%. */
+    padding?: number;
+    lookAt?: Vector3;
+};
+/**
+ * Places `camera` so `bounds` fits on screen at the current viewport, along the
+ * camera's existing view direction. Call it after `rig.resize`.
+ */
+export declare function fitBounds(camera: GameCamera, bounds: Box3, viewport: Viewport, options?: FitBoundsOptions): void;
+export {};
+//# sourceMappingURL=camera.d.ts.map

package/dist/camera.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera.d.ts","sourceRoot":"","sources":["../src/camera.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAa,kBAAkB,EAAE,iBAAiB,EAAU,OAAO,EAAE,MAAM,OAAO,CAAA;AACpG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE7C,MAAM,MAAM,UAAU,GAAG,iBAAiB,GAAG,kBAAkB,CAAA;AAE/D;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAA;IAChC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,SAAS,CAwBvE;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,SAAS,CA2BjE;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,IAAI,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,mFAAmF;AACnF,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS,CAuCzF;AAED,qEAAqE;AACrE,KAAK,YAAY,GAAG;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAA;AAEzC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,IAAI,EACZ,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,gBAAqB,GAC7B,IAAI,CA0BN"}

package/dist/camera.js

@@ -0,0 +1,120 @@
+import { MathUtils, OrthographicCamera, PerspectiveCamera, Sphere, Vector3 } from 'three';
+/**
+ * The default: a perspective camera looking slightly down at the origin, framed
+ * so the design box's height is exactly what `fov` covers at the design aspect.
+ */
+export function portraitRig(options = {}) {
+    const fov = options.fov ?? 50;
+    const position = options.position ?? new Vector3(0, 6, 14);
+    const target = options.lookAt ?? new Vector3(0, 1.5, 0);
+    const camera = new PerspectiveCamera(fov, 1, options.near ?? 0.1, options.far ?? 300);
+    camera.position.copy(position);
+    camera.lookAt(target);
+    const distance = Math.max(position.distanceTo(target), 1e-3);
+    const baseHeight = 2 * distance * Math.tan(MathUtils.degToRad(fov) / 2);
+    return {
+        camera,
+        resize(viewport) {
+            camera.aspect = viewport.aspect;
+            // Widen the vertical FOV by scale.y. When the window is wider than the
+            // design box scale.y is 1 and the extra width comes free from `aspect`.
+            const visibleHeight = baseHeight * viewport.scale.y;
+            camera.fov = MathUtils.radToDeg(2 * Math.atan(visibleHeight / (2 * distance)));
+            camera.updateProjectionMatrix();
+        },
+        update() { },
+    };
+}
+/** Orthographic rig. Isometric is this rig with `heading: Math.PI / 4`. */
+export function orthoRig(options = {}) {
+    const frustumHeight = options.frustumHeight ?? 14;
+    const heading = options.heading ?? 0;
+    const pitch = options.pitch ?? 0.22;
+    const distance = options.distance ?? 40;
+    const target = options.lookAt ?? new Vector3();
+    const camera = new OrthographicCamera(-1, 1, 1, -1, options.near ?? 0.1, options.far ?? 200);
+    camera.position
+        .set(Math.sin(heading) * Math.cos(pitch), Math.sin(pitch), Math.cos(heading) * Math.cos(pitch))
+        .multiplyScalar(distance)
+        .add(target);
+    camera.lookAt(target);
+    return {
+        camera,
+        resize(viewport) {
+            const height = frustumHeight * viewport.scale.y;
+            const width = height * viewport.aspect;
+            camera.top = height / 2;
+            camera.bottom = -height / 2;
+            camera.right = width / 2;
+            camera.left = -width / 2;
+            camera.updateProjectionMatrix();
+        },
+        update() { },
+    };
+}
+/** Perspective camera that chases an object with frame-rate-independent easing. */
+export function followRig(target, options = {}) {
+    const offset = options.offset ?? new Vector3(0, 9, 12);
+    const lookOffset = options.lookOffset ?? new Vector3(0, 1, 0);
+    const smoothing = options.smoothing ?? 0.18;
+    const fov = options.fov ?? 50;
+    const camera = new PerspectiveCamera(fov, 1, options.near ?? 0.1, options.far ?? 300);
+    const focus = target.position.clone();
+    const desired = new Vector3();
+    const lookTarget = new Vector3();
+    const distance = Math.max(offset.length(), 1e-3);
+    const baseHeight = 2 * distance * Math.tan(MathUtils.degToRad(fov) / 2);
+    focus.copy(target.position);
+    if (options.bounds)
+        options.bounds.clampPoint(focus, focus);
+    camera.position.copy(focus).add(offset);
+    camera.lookAt(lookTarget.copy(focus).add(lookOffset));
+    return {
+        camera,
+        resize(viewport) {
+            camera.aspect = viewport.aspect;
+            camera.fov = MathUtils.radToDeg(2 * Math.atan((baseHeight * viewport.scale.y) / (2 * distance)));
+            camera.updateProjectionMatrix();
+        },
+        update(dt) {
+            desired.copy(target.position);
+            if (options.bounds)
+                options.bounds.clampPoint(desired, desired);
+            // Exponential smoothing on dt, not a fixed lerp factor: a fixed factor
+            // makes the camera lag differently at 60 Hz and 120 Hz.
+            const alpha = smoothing > 0 ? 1 - Math.exp(-dt / smoothing) : 1;
+            focus.lerp(desired, Math.min(alpha, 1));
+            camera.position.copy(focus).add(offset);
+            camera.lookAt(lookTarget.copy(focus).add(lookOffset));
+        },
+    };
+}
+/**
+ * Places `camera` so `bounds` fits on screen at the current viewport, along the
+ * camera's existing view direction. Call it after `rig.resize`.
+ */
+export function fitBounds(camera, bounds, viewport, options = {}) {
+    const padding = options.padding ?? 1.1;
+    const sphere = bounds.getBoundingSphere(new Sphere());
+    const center = options.lookAt ?? sphere.center;
+    const radius = Math.max(sphere.radius * padding, 1e-3);
+    if (camera instanceof OrthographicCamera) {
+        const halfHeight = (camera.top - camera.bottom) / 2;
+        const halfWidth = (camera.right - camera.left) / 2;
+        camera.zoom = Math.min(halfHeight / radius, halfWidth / radius);
+        camera.updateProjectionMatrix();
+        camera.lookAt(center);
+        return;
+    }
+    const vFov = MathUtils.degToRad(camera.fov);
+    // The horizontal half-angle is derived from the vertical one and the aspect;
+    // taking the max of the two required distances is what keeps a wide object
+    // from spilling off the sides of a narrow phone.
+    const hFov = 2 * Math.atan(Math.tan(vFov / 2) * viewport.aspect);
+    const distance = Math.max(radius / Math.sin(vFov / 2), radius / Math.sin(hFov / 2));
+    const direction = camera.position.clone().sub(center);
+    if (direction.lengthSq() < 1e-8)
+        direction.set(0, 0.4, 1);
+    camera.position.copy(center).addScaledVector(direction.normalize(), distance);
+    camera.lookAt(center);
+}

package/dist/collide.d.ts

@@ -0,0 +1,111 @@
+import { type Box3, Vector3 } from 'three';
+/**
+ * Collision QUERIES, not a physics engine.
+ *
+ * A solver is deliberately absent: `@dimforge/rapier3d-compat` is 2.0 MB of JS
+ * with the wasm inlined as base64, against a ~623 KB three baseline — it would
+ * roughly quadruple a published game. Portrait games (hop, stack, dodge,
+ * runner) need to know *what is in the way*, and that is composition over
+ * three's own `Box3`/`Vector3`. A game that genuinely needs a solver adds
+ * Rapier itself and drives it from `update(step)`, which is one line because
+ * the loop is already fixed-timestep.
+ */
+export type SweepResult = {
+    hit: boolean;
+    /** Fraction of the motion travelled before contact, 0..1. */
+    time: number;
+    normal: Vector3;
+};
+/**
+ * Swept AABB against a set of static boxes: how far `box` can move along
+ * `velocity` before it touches something, and the face it touched.
+ *
+ * This is the slab method. Discrete overlap tests are what let a fast-moving
+ * player tunnel straight through the floor on a slow frame; sweeping cannot.
+ *
+ * Contact is measured against `contactEpsilon`, and the three states a real
+ * game spends its time in all resolve here rather than in the caller:
+ *
+ * - **resting** (`box.min.y === obstacle.max.y`) reports a hit at `t = 0` with
+ *   an upward normal, so the caller can cancel gravity and stay grounded;
+ * - **sliding along** that same surface — no motion on the contact axis —
+ *   reports no hit, because touching is not overlapping;
+ * - **leaving** it (a jump) reports no hit, because the overlap window closed
+ *   before this step began.
+ */
+export declare function sweepAabb(box: Box3, velocity: Vector3, obstacles: readonly Box3[], contactEpsilon?: number): SweepResult;
+export type KinematicResult = {
+    /** Where the box's centre ended up. */
+    position: Vector3;
+    /** Velocity after cancelling the components that hit something. */
+    velocity: Vector3;
+    grounded: boolean;
+};
+export type KinematicOptions = {
+    /** Sweep/slide passes. 3 handles a corner; more is wasted work. */
+    maxIterations?: number;
+    /** Gap left at contact, in world units, so the next sweep starts outside. */
+    slop?: number;
+    /** How close counts as touching — contact, depenetration and grounding. */
+    contactEpsilon?: number;
+};
+/**
+ * The displacement that pushes `box` out of everything it is currently inside.
+ *
+ * A sweep cannot help a body that starts overlapping: there is no direction of
+ * travel that leaves the obstacle, so every step reports a contact at t=0 and
+ * the body never moves. Depenetration is the only way out, and games produce
+ * the state constantly — a player authored at `y = platformTop` straddles the
+ * surface by half its height, and anything spawned into a scene it did not
+ * measure lands inside something.
+ *
+ * Per obstacle: the smallest of the six axis-aligned exits (the minimum
+ * translation vector), applied immediately so the next obstacle is measured
+ * against the already-displaced box. Summing every obstacle's MTV instead — the
+ * obvious implementation — double-counts a body resting in a floor built from
+ * two adjacent tiles, because both tiles ask for the same upward push and the
+ * body pops out twice as far as it should.
+ *
+ * Bodies are pushed to exactly touching, not to touching-plus-a-nudge: contact
+ * is a band, and `sweepAabb` already treats a body flush against a surface as
+ * resting on it rather than stuck in it.
+ *
+ * Mutates nothing.
+ */
+export declare function depenetrate(box: Box3, obstacles: readonly Box3[], contactEpsilon?: number): Vector3;
+/**
+ * Moves a kinematic AABB through static geometry, sliding along contacts.
+ *
+ * The model, in the order it runs:
+ *
+ * 1. **Depenetrate.** Anything the body starts inside is escaped first, so the
+ *    sweep is always asked a question it can answer.
+ * 2. **Sweep and slide**, up to `maxIterations` times. A contact cancels the
+ *    component of the motion pointing into the surface and keeps the rest, so a
+ *    body resting on the ground still walks along it and a body against a wall
+ *    still slides.
+ * 3. **Probe for ground.** Grounded is a state — a surface within
+ *    `contactEpsilon` under the body — not just a normal seen this step.
+ *
+ * Mutates nothing: `box` is read, and the caller applies the returned position.
+ */
+export declare function resolveKinematic(box: Box3, velocity: Vector3, obstacles: readonly Box3[], options?: KinematicOptions): KinematicResult;
+/**
+ * Uniform-grid broadphase.
+ *
+ * Testing every candidate against every other is O(n^2) and a phone notices at
+ * a couple of hundred. Size cells around your typical object.
+ */
+export declare class Grid<T> {
+    private readonly cellSize;
+    private readonly cells;
+    constructor(cellSize: number);
+    insert(item: T, bounds: Box3): void;
+    /** Candidates overlapping `bounds`, deduplicated. Still needs a narrow test. */
+    query(bounds: Box3, out?: T[]): T[];
+    clear(): void;
+    private keysFor;
+}
+/** Indices of every box whose closest point is within `radius` of `center`. */
+export declare function overlapSphere(center: Vector3, radius: number, boxes: readonly Box3[]): number[];
+//# sourceMappingURL=collide.d.ts.map

package/dist/collide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collide.d.ts","sourceRoot":"","sources":["../src/collide.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAE1C;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,OAAO,CAAA;IACZ,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;CAChB,CAAA;AAqBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,IAAI,EACT,QAAQ,EAAE,OAAO,EACjB,SAAS,EAAE,SAAS,IAAI,EAAE,EAC1B,cAAc,SAAkB,GAC/B,WAAW,CA4Eb;AAID,MAAM,MAAM,eAAe,GAAG;IAC5B,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAA;IACjB,mEAAmE;IACnE,QAAQ,EAAE,OAAO,CAAA;IACjB,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,IAAI,EACT,SAAS,EAAE,SAAS,IAAI,EAAE,EAC1B,cAAc,SAAkB,GAC/B,OAAO,CAgCT;AA0BD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,IAAI,EACT,QAAQ,EAAE,OAAO,EACjB,SAAS,EAAE,SAAS,IAAI,EAAE,EAC1B,OAAO,GAAE,gBAAqB,GAC7B,eAAe,CA+CjB;AAED;;;;;GAKG;AACH,qBAAa,IAAI,CAAC,CAAC;IAGL,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAFrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;gBAElB,QAAQ,EAAE,MAAM;IAI7C,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,GAAG,IAAI;IAQnC,gFAAgF;IAChF,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,GAAE,CAAC,EAAO,GAAG,CAAC,EAAE;IAavC,KAAK,IAAI,IAAI;IAIb,OAAO,CAAE,OAAO;CAajB;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,MAAM,EAAE,CAW/F"}