@uppercut-labs/ps1-backgrounds 0.1.0

package/dist/runtime.js

@@ -0,0 +1,415 @@
+import * as THREE from "three";
+import { Kit } from "./kit.js";
+const motionModes = ["ambient", "fixed", "cinematic", "still"];
+const qualityModes = ["auto", "high", "low"];
+const activeHosts = new WeakMap();
+function isMotion(value) { return motionModes.includes(value); }
+function isQuality(value) { return qualityModes.includes(value); }
+function resolveElement(element) {
+    if (element === undefined)
+        return document.body;
+    if (typeof element === "string") {
+        const match = document.querySelector(element);
+        if (!(match instanceof HTMLElement))
+            throw new Error(`Background element not found: ${element}`);
+        return match;
+    }
+    if (!(element instanceof HTMLElement))
+        throw new Error("Background element must be an HTMLElement or CSS selector");
+    return element;
+}
+function posterFor(scene) {
+    if (scene.poster)
+        return scene.poster;
+    const colors = scene.palette;
+    const title = scene.title.replace(/[&<>"']/g, (character) => ({
+        "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;",
+    })[character] ?? character);
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 360" preserveAspectRatio="xMidYMid slice"><defs><linearGradient id="g" x2="0" y2="1"><stop stop-color="${colors.sky}"/><stop offset="1" stop-color="${colors.body}"/></linearGradient></defs><rect width="640" height="360" fill="url(#g)"/><path d="M0 290 110 215 205 260 320 175 430 250 535 190 640 245V360H0Z" fill="${colors.stone}"/><path d="M0 325 140 265 250 310 370 238 505 295 640 260" fill="none" stroke="${colors.accent}" stroke-width="5"/><circle cx="505" cy="105" r="36" fill="${colors.light}"/><text x="26" y="330" fill="${colors.light}" font-family="monospace" font-size="24">${title}</text></svg>`;
+    return `data:image/svg+xml,${encodeURIComponent(svg)}`;
+}
+function renderSize(width, height, pixels) {
+    const aspect = width / Math.max(height, 1);
+    const rawWidth = Math.sqrt(pixels * aspect);
+    const rawHeight = rawWidth / aspect;
+    const scale = Math.min(1, 960 / rawWidth, 960 / rawHeight);
+    return [Math.max(1, Math.round(rawWidth * scale)), Math.max(1, Math.round(rawHeight * scale))];
+}
+function renderTarget() {
+    return new THREE.WebGLRenderTarget(384, 216, {
+        magFilter: THREE.NearestFilter, minFilter: THREE.NearestFilter, depthBuffer: true,
+    });
+}
+const vertexShader = `varying vec2 vUv;
+void main() { vUv = uv; gl_Position = vec4(position.xy, 0.0, 1.0); }`;
+const fragmentShader = `uniform sampler2D sceneTex;
+uniform float ps1;
+varying vec2 vUv;
+float dither(vec2 p) {
+  vec2 c = mod(floor(p), 4.0);
+  if (c.y < 1.0) return c.x < 1.0 ? -4.0 : c.x < 2.0 ? 0.0 : c.x < 3.0 ? -3.0 : 1.0;
+  if (c.y < 2.0) return c.x < 1.0 ? 2.0 : c.x < 2.0 ? -2.0 : c.x < 3.0 ? 3.0 : -1.0;
+  if (c.y < 3.0) return c.x < 1.0 ? -3.0 : c.x < 2.0 ? 1.0 : c.x < 3.0 ? -4.0 : 0.0;
+  return c.x < 1.0 ? 3.0 : c.x < 2.0 ? -1.0 : c.x < 3.0 ? 2.0 : -2.0;
+}
+void main() {
+  vec3 color = texture2D(sceneTex, vUv).rgb;
+  color = mix(12.92 * color, 1.055 * pow(max(color, vec3(0.0)), vec3(1.0 / 2.4)) - 0.055,
+    step(vec3(0.0031308), color));
+  if (ps1 > 0.5) color = floor(clamp(color * 255.0 + dither(gl_FragCoord.xy), 0.0, 255.0) / 8.0) / 31.0;
+  gl_FragColor = vec4(color, 1.0);
+}`;
+function makeCompositeMaterial() {
+    return new THREE.ShaderMaterial({
+        uniforms: { sceneTex: { value: null }, ps1: { value: 1 } },
+        vertexShader, fragmentShader, depthTest: false, depthWrite: false,
+    });
+}
+function interpolate(a, b, amount) {
+    return new THREE.Vector3(...a).lerp(new THREE.Vector3(...b), amount);
+}
+function cameraAmount(mode, seconds, speed) {
+    if (mode === "fixed" || mode === "still")
+        return 0;
+    if (mode === "ambient")
+        return 0.5 - 0.5 * Math.cos(seconds * speed * Math.PI / 20);
+    const frame = ((seconds * speed) % 8 + 8) % 8;
+    const u = frame / 8;
+    return u * u * (3 - 2 * u);
+}
+class Background {
+    canvas = document.createElement("canvas");
+    host;
+    wrapper = document.createElement("div");
+    poster = document.createElement("img");
+    camera = new THREE.PerspectiveCamera(50, 16 / 9, 0.1, 300);
+    compositeScene = new THREE.Scene();
+    compositeCamera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+    compositeMaterial = makeCompositeMaterial();
+    reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
+    resizeObserver;
+    intersectionObserver;
+    kit;
+    definition;
+    renderer;
+    target;
+    mode;
+    quality;
+    autoLow = false;
+    shot;
+    speed;
+    originalPosition;
+    changedPosition = false;
+    visible = true;
+    contextLost = false;
+    frameId = 0;
+    lastFrame = 0;
+    elapsed = 0;
+    slowFrames = 0;
+    currentState = "paused";
+    get state() { return this.currentState; }
+    constructor(options) {
+        if (!options.scene || typeof options.scene.build !== "function")
+            throw new Error("A valid scene is required");
+        this.definition = options.scene;
+        this.mode = options.motion ?? "ambient";
+        this.quality = options.quality ?? "auto";
+        if (!isMotion(this.mode))
+            throw new Error(`Unknown motion mode: ${this.mode}`);
+        if (!isQuality(this.quality))
+            throw new Error(`Unknown quality mode: ${this.quality}`);
+        this.shot = options.camera ?? "survey";
+        if (!options.scene.cameras[this.shot])
+            throw new Error(`Unknown camera: ${this.shot}`);
+        this.speed = options.speed ?? 1;
+        if (!Number.isFinite(this.speed) || this.speed <= 0)
+            throw new Error("Background speed must be positive");
+        this.host = resolveElement(options.element);
+        this.originalPosition = this.host.style.position;
+        if (this.host !== document.body && getComputedStyle(this.host).position === "static") {
+            this.host.style.position = "relative";
+            this.changedPosition = true;
+        }
+        this.wrapper.style.cssText = this.host === document.body
+            ? "position:fixed;inset:0;z-index:-1;overflow:hidden;pointer-events:none;"
+            : "position:absolute;inset:0;z-index:0;overflow:hidden;pointer-events:none;";
+        this.wrapper.setAttribute("aria-hidden", "true");
+        this.canvas.style.cssText = "display:block;width:100%;height:100%;image-rendering:pixelated;pointer-events:none;";
+        this.canvas.setAttribute("aria-hidden", "true");
+        this.poster.style.cssText = "position:absolute;inset:0;width:100%;height:100%;object-fit:cover;display:none;pointer-events:none;";
+        this.poster.alt = "";
+        this.poster.src = posterFor(options.scene);
+        this.wrapper.append(this.canvas, this.poster);
+        this.host.prepend(this.wrapper);
+        this.kit = this.makeKit();
+        try {
+            this.renderer = new THREE.WebGLRenderer({ canvas: this.canvas, antialias: false, powerPreference: "low-power" });
+            this.renderer.setPixelRatio(1);
+            this.renderer.outputColorSpace = THREE.SRGBColorSpace;
+            this.renderer.toneMapping = THREE.NoToneMapping;
+            this.target = renderTarget();
+            this.compositeMaterial.uniforms.sceneTex.value = this.target.texture;
+            this.compositeScene.add(new THREE.Mesh(new THREE.PlaneGeometry(2, 2), this.compositeMaterial));
+        }
+        catch (error) {
+            this.showFallback(error);
+        }
+        if (this.renderer) {
+            try {
+                options.scene.build(this.kit);
+            }
+            catch (error) {
+                this.kit.dispose();
+                this.target?.dispose();
+                this.compositeMaterial.dispose();
+                this.renderer.dispose();
+                this.wrapper.remove();
+                if (this.changedPosition)
+                    this.host.style.position = this.originalPosition;
+                throw error;
+            }
+        }
+        this.resizeObserver = new ResizeObserver(() => this.resize());
+        this.resizeObserver.observe(this.host);
+        if (typeof IntersectionObserver !== "undefined") {
+            this.intersectionObserver = new IntersectionObserver((entries) => {
+                this.visible = entries[0]?.isIntersecting ?? false;
+                this.schedule();
+            });
+            this.intersectionObserver.observe(this.host);
+        }
+        this.reducedMotion.addEventListener("change", this.onVisibility);
+        document.addEventListener("visibilitychange", this.onVisibility);
+        this.canvas.addEventListener("webglcontextlost", this.onContextLost);
+        this.canvas.addEventListener("webglcontextrestored", this.onContextRestored);
+        this.resize();
+        this.schedule();
+    }
+    makeKit() {
+        const kit = new Kit(this.definition, () => {
+            if (this.kit === kit && this.currentState === "paused" && this.visible && !document.hidden)
+                this.draw();
+        }, (error) => {
+            if (this.kit === kit && this.currentState !== "disposed")
+                this.showFallback(error);
+        });
+        return kit;
+    }
+    showFallback(error) {
+        this.currentState = "fallback";
+        this.poster.style.display = "block";
+        const detail = error instanceof Error ? error : new Error(String(error));
+        this.host.dispatchEvent(new CustomEvent("ps1-background-error", {
+            detail, bubbles: true, composed: true,
+        }));
+        console.error("PS1 Backgrounds could not render this scene:", detail);
+    }
+    onVisibility = () => { this.schedule(); };
+    onContextLost = (event) => {
+        event.preventDefault();
+        this.contextLost = true;
+        this.kit.dispose();
+        this.target?.dispose();
+        this.target = undefined;
+        for (const child of [...this.compositeScene.children]) {
+            if (child instanceof THREE.Mesh)
+                child.geometry.dispose();
+            this.compositeScene.remove(child);
+        }
+        this.compositeMaterial.dispose();
+        this.compositeMaterial = makeCompositeMaterial();
+        this.showFallback(new Error("WebGL context lost"));
+        this.schedule();
+    };
+    onContextRestored = () => {
+        this.contextLost = false;
+        const kit = this.makeKit();
+        try {
+            this.definition.build(kit);
+        }
+        catch (error) {
+            kit.dispose();
+            this.showFallback(error);
+            return;
+        }
+        this.kit = kit;
+        this.target = renderTarget();
+        this.compositeMaterial.uniforms.sceneTex.value = this.target.texture;
+        this.compositeScene.add(new THREE.Mesh(new THREE.PlaneGeometry(2, 2), this.compositeMaterial));
+        this.poster.style.display = "none";
+        this.currentState = "paused";
+        this.resize();
+        this.schedule();
+        this.host.dispatchEvent(new CustomEvent("ps1-background-restored", {
+            bubbles: true, composed: true,
+        }));
+    };
+    resize() {
+        if (!this.renderer || !this.target || this.currentState === "disposed")
+            return;
+        const width = this.host === document.body ? window.innerWidth : this.host.clientWidth;
+        const height = this.host === document.body ? window.innerHeight : this.host.clientHeight;
+        if (width < 1 || height < 1)
+            return;
+        const authored = this.kit.definition.presentation?.internal_size;
+        const authoredPixels = authored ? authored[0] * authored[1] : 384 * 216;
+        const maxPixels = this.quality === "low" || (this.quality === "auto" && this.autoLow)
+            ? 320 * 180
+            : this.quality === "high" ? authoredPixels : Math.min(authoredPixels, 640 * 360);
+        const [renderWidth, renderHeight] = renderSize(width, height, maxPixels);
+        this.renderer.setSize(renderWidth, renderHeight, false);
+        this.target.setSize(renderWidth, renderHeight);
+        this.camera.aspect = renderWidth / renderHeight;
+        this.camera.updateProjectionMatrix();
+        if (this.mode === "still" || this.reducedMotion.matches)
+            this.draw();
+    }
+    updateCamera(path, amount) {
+        const eased = amount * amount * (3 - 2 * amount);
+        if (path.projection === "orthogonal") {
+            const height = path.size ?? 30;
+            const width = height * this.camera.aspect;
+            if (!(this.compositionCamera instanceof THREE.OrthographicCamera)) {
+                this.compositionCamera = new THREE.OrthographicCamera(-width / 2, width / 2, height / 2, -height / 2, 0.1, 300);
+            }
+            const active = this.compositionCamera;
+            active.left = -width / 2;
+            active.right = width / 2;
+            active.top = height / 2;
+            active.bottom = -height / 2;
+            active.position.copy(interpolate(path.from, path.to, eased));
+            active.lookAt(interpolate(path.target_from, path.target_to, eased));
+            active.updateProjectionMatrix();
+        }
+        else {
+            this.compositionCamera = this.camera;
+            this.camera.position.copy(interpolate(path.from, path.to, eased));
+            this.camera.lookAt(interpolate(path.target_from, path.target_to, eased));
+            this.camera.fov = path.fov ?? 50;
+            this.camera.updateProjectionMatrix();
+        }
+    }
+    compositionCamera = this.camera;
+    draw() {
+        if (!this.renderer || !this.target || this.contextLost || this.currentState === "disposed")
+            return;
+        const mode = this.reducedMotion.matches ? "still" : this.mode;
+        const seconds = mode === "still" ? 0 : this.elapsed;
+        const amount = cameraAmount(mode, seconds, this.speed);
+        this.updateCamera(this.kit.definition.cameras[this.shot], amount);
+        this.kit.setTime(seconds);
+        this.compositeMaterial.uniforms.ps1.value = this.kit.definition.presentation?.composite === "clean" ? 0 : 1;
+        try {
+            this.renderer.setRenderTarget(this.target);
+            this.renderer.render(this.kit.scene, this.compositionCamera);
+            this.renderer.setRenderTarget(null);
+            this.renderer.render(this.compositeScene, this.compositeCamera);
+        }
+        catch (error) {
+            this.showFallback(error);
+        }
+    }
+    tick = (now) => {
+        this.frameId = 0;
+        if (!this.canRun()) {
+            this.schedule();
+            return;
+        }
+        const previous = this.lastFrame;
+        const delta = previous ? Math.min(100, now - previous) : 0;
+        const cap = this.quality === "low" || this.autoLow ? 30 : 60;
+        if (previous && delta < 1000 / cap - 1) {
+            this.frameId = requestAnimationFrame(this.tick);
+            return;
+        }
+        this.lastFrame = now;
+        this.elapsed += delta / 1000;
+        if (this.quality === "auto" && !this.autoLow && delta > 45) {
+            this.slowFrames++;
+            if (this.slowFrames >= 20) {
+                this.autoLow = true;
+                this.resize();
+            }
+        }
+        else if (delta < 35) {
+            this.slowFrames = 0;
+        }
+        this.draw();
+        this.frameId = requestAnimationFrame(this.tick);
+    };
+    canRun() {
+        return Boolean(this.renderer && !this.contextLost && this.visible && !document.hidden &&
+            !this.reducedMotion.matches && this.mode !== "still" && this.currentState !== "disposed" &&
+            this.currentState !== "fallback");
+    }
+    schedule() {
+        if (this.frameId) {
+            cancelAnimationFrame(this.frameId);
+            this.frameId = 0;
+        }
+        if (this.currentState === "disposed" || this.currentState === "fallback")
+            return;
+        if (this.canRun()) {
+            this.currentState = "running";
+            this.lastFrame = 0;
+            this.frameId = requestAnimationFrame(this.tick);
+        }
+        else {
+            this.currentState = "paused";
+            if (this.renderer && !this.contextLost && this.visible && !document.hidden)
+                this.draw();
+        }
+    }
+    setMotion(mode) {
+        if (this.currentState === "disposed")
+            throw new Error("Background is disposed");
+        if (!isMotion(mode))
+            throw new Error(`Unknown motion mode: ${mode}`);
+        this.mode = mode;
+        this.schedule();
+    }
+    setQuality(mode) {
+        if (this.currentState === "disposed")
+            throw new Error("Background is disposed");
+        if (!isQuality(mode))
+            throw new Error(`Unknown quality mode: ${mode}`);
+        this.quality = mode;
+        this.autoLow = false;
+        this.resize();
+        this.schedule();
+    }
+    dispose() {
+        if (this.currentState === "disposed")
+            return;
+        this.currentState = "disposed";
+        if (activeHosts.get(this.host) === this)
+            activeHosts.delete(this.host);
+        if (this.frameId)
+            cancelAnimationFrame(this.frameId);
+        this.resizeObserver.disconnect();
+        this.intersectionObserver?.disconnect();
+        this.reducedMotion.removeEventListener("change", this.onVisibility);
+        document.removeEventListener("visibilitychange", this.onVisibility);
+        this.canvas.removeEventListener("webglcontextlost", this.onContextLost);
+        this.canvas.removeEventListener("webglcontextrestored", this.onContextRestored);
+        this.kit.dispose();
+        this.target?.dispose();
+        for (const child of this.compositeScene.children) {
+            if (child instanceof THREE.Mesh)
+                child.geometry.dispose();
+        }
+        this.compositeMaterial.dispose();
+        this.renderer?.dispose();
+        this.wrapper.remove();
+        if (this.changedPosition)
+            this.host.style.position = this.originalPosition;
+    }
+}
+export function createBackground(options) {
+    const host = resolveElement(options.element);
+    if (activeHosts.has(host))
+        throw new Error("Background element already has an active scene");
+    const background = new Background({ ...options, element: host });
+    activeHosts.set(host, background);
+    return background;
+}

package/dist/scene.d.ts

@@ -0,0 +1,137 @@
+export type Vec2 = readonly [number, number];
+export type Vec3 = readonly [number, number, number];
+export type Quat = readonly [number, number, number, number];
+export type Role = "body" | "accent" | "stone" | "metal" | "light" | "water";
+export interface ScenePalette extends Record<Role, string> {
+    sky: string;
+    fog: string;
+}
+export interface CameraPath {
+    from: Vec3;
+    to: Vec3;
+    target_from: Vec3;
+    target_to: Vec3;
+    fov?: number;
+    projection?: "perspective" | "orthogonal";
+    size?: number;
+}
+export interface PresentationSpec {
+    internal_size?: Vec2;
+    composite?: "ps1" | "clean";
+    surface?: "legacy" | "painted";
+    snap_vertices?: boolean;
+    affine_uv?: boolean;
+}
+export interface TransformRecord {
+    position: Vec3;
+    quaternion: Quat;
+    scale: Vec3;
+}
+export interface MotionRecord {
+    times: number[];
+    positions: Vec3[];
+    quaternions: Quat[];
+    scales: Vec3[];
+    visible: boolean[];
+}
+export interface MaterialRecord {
+    role?: Role;
+    kind: "legacy" | "painted" | "card" | "cutout";
+    color?: string;
+    opacity?: number;
+    texture?: string;
+    blob?: boolean;
+}
+export type PrimitiveKind = "box" | "cylinder" | "sphere" | "torus" | "quad";
+export interface PrimitiveRecord {
+    kind: PrimitiveKind;
+    args: (number | number[])[];
+    transform: TransformRecord;
+    visible?: boolean;
+    material: MaterialRecord;
+    motion?: MotionRecord;
+}
+export interface MeshRecord {
+    kind?: "mesh";
+    positions: number[];
+    normals?: number[];
+    uvs?: number[];
+    colors?: number[];
+    indices?: number[];
+    transform: TransformRecord;
+    visible?: boolean;
+    material: MaterialRecord;
+    motion?: MotionRecord;
+}
+export interface SceneNode {
+    readonly id: number;
+}
+export interface SceneKit {
+    box(options: {
+        position: Vec3;
+        size: Vec3;
+        material: Role;
+        rotation?: Vec3;
+    }): SceneNode;
+    cylinder(options: {
+        position: Vec3;
+        radius: number;
+        height: number;
+        material: Role;
+        segments?: number;
+        topRadius?: number;
+    }): SceneNode;
+    sphere(options: {
+        position: Vec3;
+        radius: number;
+        material: Role;
+        rings?: number;
+        segments?: number;
+    }): SceneNode;
+    torus(options: {
+        position: Vec3;
+        inner: number;
+        outer: number;
+        material: Role;
+        rotation?: Vec3;
+    }): SceneNode;
+    beam(options: {
+        from: Vec3;
+        to: Vec3;
+        width: number;
+        material: Role;
+    }): SceneNode;
+    island(options: {
+        position: Vec3;
+        radius: number;
+        height?: number;
+        depth?: number;
+        phase?: Vec2;
+    }): SceneNode;
+    ribbonArch(options: {
+        position: Vec3;
+        radius: number;
+        width: number;
+        material: Role;
+    }): SceneNode[];
+    rotate(node: SceneNode, options: {
+        axis: Vec3;
+        speed: number;
+    }): void;
+    addPrimitive(record: PrimitiveRecord): SceneNode;
+    addMesh(record: MeshRecord): SceneNode;
+}
+export interface SceneDefinition {
+    id: string;
+    title: string;
+    palette: ScenePalette;
+    fog: Vec2;
+    cameras: {
+        survey: CameraPath;
+        detail: CameraPath;
+    };
+    presentation?: PresentationSpec;
+    poster?: string;
+    build(kit: SceneKit): void;
+}
+export declare function defineScene<T extends SceneDefinition>(definition: T): T;

package/dist/scene.js

@@ -0,0 +1,10 @@
+export function defineScene(definition) {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(definition.id)) {
+        throw new Error(`Invalid scene id: ${definition.id}`);
+    }
+    for (const shot of ["survey", "detail"]) {
+        if (!definition.cameras[shot])
+            throw new Error(`Scene ${definition.id} has no ${shot} camera`);
+    }
+    return definition;
+}

package/dist/scenes/generated/atlas-of-little-worlds.d.ts

@@ -0,0 +1,48 @@
+declare const _default: {
+    title: string;
+    palette: {
+        accent: string;
+        body: string;
+        fog: string;
+        light: string;
+        metal: string;
+        sky: string;
+        stone: string;
+        water: string;
+    };
+    fog: [number, number];
+    cameras: {
+        detail: {
+            fov: number;
+            from: [number, number, number];
+            target_from: [number, number, number];
+            target_to: [number, number, number];
+            to: [number, number, number];
+        };
+        survey: {
+            fov: number;
+            from: [number, number, number];
+            projection: "orthogonal";
+            size: number;
+            target_from: [number, number, number];
+            target_to: [number, number, number];
+            to: [number, number, number];
+        };
+    };
+    id: string;
+    poster: string;
+    seed: number;
+    presentation: {
+        composite: "clean";
+        internal_size: [number, number];
+        surface: "painted";
+    };
+    overlay: {
+        accent: string;
+        style: string;
+        subtitle: string;
+        title: string;
+    };
+    build(kit: import("../../scene.js").SceneKit): void;
+};
+export default _default;