@uppercut-labs/ps1-backgrounds 0.1.0

package/dist/kit.js

@@ -0,0 +1,383 @@
+import * as THREE from "three";
+const vector = (point) => new THREE.Vector3(...point);
+const legacyVertexShader = `
+varying vec2 vUv;
+varying vec3 vLight;
+varying float vFog;
+varying float vCap;
+uniform vec2 fogRange;
+void main() {
+  vec4 world = modelMatrix * vec4(position, 1.0);
+  vec4 view = viewMatrix * world;
+  vec3 normalWorld = normalize(mat3(modelMatrix) * normal);
+  float moon = abs(dot(normalWorld, normalize(vec3(0.45, 0.8, 0.35))));
+  vLight = vec3(0.48, 0.54, 0.62) + vec3(0.72, 0.71, 0.66) * moon;
+  vUv = uv;
+  vFog = clamp((-view.z - fogRange.x) / max(fogRange.y - fogRange.x, 0.001), 0.0, 1.0);
+#ifdef USE_CAP
+  vCap = color.r;
+#else
+  vCap = 0.0;
+#endif
+  gl_Position = projectionMatrix * view;
+}`;
+const legacyFragmentShader = `
+varying vec2 vUv;
+varying vec3 vLight;
+varying float vFog;
+varying float vCap;
+uniform sampler2D pattern;
+uniform vec3 baseColor;
+uniform vec3 capColor;
+uniform vec3 fogColor;
+uniform float emission;
+void main() {
+  vec3 base = texture2D(pattern, vUv).rgb * baseColor;
+  vec3 color = base * (vLight + emission) + capColor * vCap * 1.1;
+  gl_FragColor = vec4(mix(color, fogColor, vFog), 1.0);
+}`;
+function numbers(value, count, name) {
+    if (!Array.isArray(value) || value.length !== count || value.some((n) => !Number.isFinite(n))) {
+        throw new Error(`${name} must contain ${count} finite numbers`);
+    }
+    return value;
+}
+function number(value, name) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        throw new Error(`${name} must be a finite number`);
+    return value;
+}
+function roleMaterial(role) {
+    return { role, kind: "legacy" };
+}
+function transform(position, rotation = [0, 0, 0]) {
+    const q = new THREE.Quaternion().setFromEuler(new THREE.Euler(...rotation));
+    return { position, quaternion: [q.x, q.y, q.z, q.w], scale: [1, 1, 1] };
+}
+export class Kit {
+    definition;
+    onTextureReady;
+    onTextureError;
+    scene = new THREE.Scene();
+    nodes = [];
+    geometries = new Set();
+    materials = new Map();
+    textures = new Set();
+    rolePattern;
+    animations = [];
+    disposed = false;
+    constructor(definition, onTextureReady, onTextureError) {
+        this.definition = definition;
+        this.onTextureReady = onTextureReady;
+        this.onTextureError = onTextureError;
+        this.scene.background = new THREE.Color(definition.palette.sky);
+        this.scene.fog = new THREE.Fog(definition.palette.fog, definition.fog[0], definition.fog[1]);
+        this.scene.add(new THREE.AmbientLight(0xc3d8ef, 1.15));
+        const sun = new THREE.DirectionalLight(0xffedca, 1.9);
+        sun.position.set(24, 60, 18);
+        this.scene.add(sun);
+    }
+    material(spec, vertexColors, hasUv) {
+        const color = spec.color ?? (spec.kind === "cutout" && spec.texture
+            ? "#ffffff" : this.definition.palette[spec.role ?? "body"]);
+        if (!color)
+            throw new Error(`Unknown material role: ${spec.role ?? "body"}`);
+        const opacity = spec.opacity ?? 1;
+        const key = JSON.stringify([spec.kind, color, opacity, spec.texture, spec.role, vertexColors, hasUv]);
+        const cached = this.materials.get(key);
+        if (cached)
+            return cached;
+        if (spec.kind === "legacy") {
+            const material = new THREE.ShaderMaterial({
+                vertexShader: legacyVertexShader,
+                fragmentShader: legacyFragmentShader,
+                uniforms: {
+                    pattern: { value: this.roleTexture() },
+                    baseColor: { value: new THREE.Color(color) },
+                    capColor: { value: new THREE.Color(this.definition.palette.accent) },
+                    fogColor: { value: new THREE.Color(this.definition.palette.fog) },
+                    fogRange: { value: new THREE.Vector2(...this.definition.fog) },
+                    emission: { value: spec.role === "accent" || spec.role === "light" ? 0.65 : 0 },
+                },
+                defines: vertexColors ? { USE_CAP: 1 } : {},
+                side: THREE.DoubleSide,
+                vertexColors,
+            });
+            this.materials.set(key, material);
+            return material;
+        }
+        const transparent = opacity < 1 || spec.kind === "card";
+        const options = {
+            color: vertexColors && spec.kind !== "painted" ? 0xffffff : color,
+            side: THREE.DoubleSide,
+            transparent,
+            opacity,
+            depthWrite: !transparent,
+            alphaTest: spec.kind === "cutout" ? 0.5 : 0,
+            vertexColors,
+        };
+        if (spec.kind === "painted") {
+            if (spec.role === "light" || spec.role === "accent") {
+                options.emissive = vertexColors ? 0x666666 : color;
+                options.emissiveIntensity = spec.role === "light" ? 0.42 : 0.24;
+            }
+            if (hasUv && !vertexColors && !spec.texture)
+                options.map = this.roleTexture();
+        }
+        if (spec.texture && hasUv) {
+            const texture = new THREE.TextureLoader().load(spec.texture, () => this.onTextureReady?.(), undefined, (error) => this.onTextureError?.(error));
+            texture.colorSpace = THREE.SRGBColorSpace;
+            texture.magFilter = THREE.NearestFilter;
+            texture.minFilter = THREE.NearestFilter;
+            this.textures.add(texture);
+            options.map = texture;
+        }
+        const material = spec.kind === "card" || spec.kind === "cutout"
+            ? new THREE.MeshBasicMaterial(options)
+            : new THREE.MeshLambertMaterial({ ...options, flatShading: true });
+        this.materials.set(key, material);
+        return material;
+    }
+    roleTexture() {
+        if (this.rolePattern)
+            return this.rolePattern;
+        const pixels = new Uint8Array(64 * 64 * 4);
+        for (let y = 0; y < 64; y++)
+            for (let x = 0; x < 64; x++) {
+                const shade = y % 16 < 2 ? 255 : (Math.floor(x / 8) + Math.floor(y / 8)) % 2 ? 245 : 214;
+                const offset = (y * 64 + x) * 4;
+                pixels[offset] = pixels[offset + 1] = pixels[offset + 2] = shade;
+                pixels[offset + 3] = 255;
+            }
+        const texture = new THREE.DataTexture(pixels, 64, 64);
+        texture.colorSpace = THREE.SRGBColorSpace;
+        texture.magFilter = THREE.NearestFilter;
+        texture.minFilter = THREE.NearestFilter;
+        texture.wrapS = texture.wrapT = THREE.RepeatWrapping;
+        texture.needsUpdate = true;
+        this.textures.add(texture);
+        this.rolePattern = texture;
+        return texture;
+    }
+    put(geometry, record, vertexColors = false) {
+        const hasUv = geometry.hasAttribute("uv");
+        const mesh = new THREE.Mesh(geometry, this.material(record.material, vertexColors, hasUv));
+        const pose = record.transform;
+        mesh.position.set(...pose.position);
+        mesh.quaternion.set(...pose.quaternion);
+        mesh.scale.set(...pose.scale);
+        mesh.visible = record.visible ?? true;
+        this.scene.add(mesh);
+        this.geometries.add(geometry);
+        const handle = { id: this.nodes.length };
+        this.nodes.push(mesh);
+        if (record.motion)
+            this.animations.push({ mesh, samples: record.motion });
+        return handle;
+    }
+    addPrimitive(record) {
+        const args = record.args;
+        let geometry;
+        switch (record.kind) {
+            case "box": {
+                const size = numbers(args[0], 3, "box size");
+                geometry = new THREE.BoxGeometry(size[0], size[1], size[2]);
+                break;
+            }
+            case "cylinder": {
+                const bottom = number(args[0], "bottom radius");
+                const top = number(args[1], "top radius");
+                const height = number(args[2], "cylinder height");
+                const segments = number(args[3], "cylinder segments");
+                geometry = new THREE.CylinderGeometry(top, bottom, height, segments, 1);
+                break;
+            }
+            case "sphere": {
+                const radius = number(args[0], "sphere radius");
+                const rings = number(args[1], "sphere rings");
+                const segments = number(args[2], "sphere segments");
+                geometry = new THREE.SphereGeometry(radius, segments, rings);
+                break;
+            }
+            case "torus": {
+                const inner = number(args[0], "torus inner radius");
+                const outer = number(args[1], "torus outer radius");
+                const rings = number(args[2], "torus rings");
+                const segments = number(args[3], "torus segments");
+                geometry = new THREE.TorusGeometry((inner + outer) / 2, (outer - inner) / 2, rings, segments);
+                break;
+            }
+            case "quad": {
+                const size = numbers(args[0], 2, "quad size");
+                geometry = new THREE.PlaneGeometry(size[0], size[1]);
+                break;
+            }
+            default:
+                throw new Error(`Unknown primitive kind: ${String(record.kind)}`);
+        }
+        return this.put(geometry, record);
+    }
+    addMesh(record) {
+        if (record.positions.length < 9 || record.positions.length % 3 !== 0) {
+            throw new Error("Mesh positions must contain at least one triangle");
+        }
+        if (record.normals?.length && record.normals.length !== record.positions.length) {
+            throw new Error("Mesh normals must match positions");
+        }
+        if (record.uvs?.length && record.uvs.length !== record.positions.length / 3 * 2) {
+            throw new Error("Mesh UVs must match positions");
+        }
+        if (record.colors?.length && record.colors.length !== record.positions.length / 3 * 4) {
+            throw new Error("Mesh colors must have four channels per vertex");
+        }
+        if (record.indices && (record.indices.length % 3 !== 0 || record.indices.some((index) => index < 0 || index >= record.positions.length / 3))) {
+            throw new Error("Mesh indices must reference triangles within the vertex array");
+        }
+        const geometry = new THREE.BufferGeometry();
+        geometry.setAttribute("position", new THREE.Float32BufferAttribute(record.positions, 3));
+        if (record.indices?.length)
+            geometry.setIndex(record.indices);
+        if (record.normals?.length === record.positions.length) {
+            geometry.setAttribute("normal", new THREE.Float32BufferAttribute(record.normals, 3));
+        }
+        else {
+            geometry.computeVertexNormals();
+        }
+        if (record.uvs?.length === record.positions.length / 3 * 2) {
+            geometry.setAttribute("uv", new THREE.Float32BufferAttribute(record.uvs, 2));
+        }
+        const vertexColors = record.colors?.length === record.positions.length / 3 * 4;
+        if (vertexColors && record.colors) {
+            geometry.setAttribute("color", new THREE.Float32BufferAttribute(record.colors, 4));
+        }
+        return this.put(geometry, record, vertexColors);
+    }
+    box({ position, size, material, rotation }) {
+        return this.addPrimitive({ kind: "box", args: [[...size]], transform: transform(position, rotation), material: roleMaterial(material) });
+    }
+    cylinder({ position, radius, height, material, segments = 8, topRadius = radius }) {
+        return this.addPrimitive({ kind: "cylinder", args: [radius, topRadius, height, segments], transform: transform(position), material: roleMaterial(material) });
+    }
+    sphere({ position, radius, material, rings = 4, segments = 8 }) {
+        return this.addPrimitive({ kind: "sphere", args: [radius, rings, segments], transform: transform(position), material: roleMaterial(material) });
+    }
+    torus({ position, inner, outer, material, rotation }) {
+        return this.addPrimitive({ kind: "torus", args: [inner, outer, 4, 16], transform: transform(position, rotation), material: roleMaterial(material) });
+    }
+    beam({ from, to, width, material }) {
+        const start = vector(from);
+        const end = vector(to);
+        const length = start.distanceTo(end);
+        if (length < 0.001)
+            throw new Error("Zero-length beam");
+        const center = start.clone().add(end).multiplyScalar(0.5);
+        const quaternion = new THREE.Quaternion().setFromUnitVectors(new THREE.Vector3(0, 1, 0), end.sub(start).normalize());
+        return this.addPrimitive({
+            kind: "box", args: [[width, length, width]],
+            transform: { position: [center.x, center.y, center.z], quaternion: [quaternion.x, quaternion.y, quaternion.z, quaternion.w], scale: [1, 1, 1] },
+            material: roleMaterial(material),
+        });
+    }
+    island({ position, radius, height = 1, depth = 1, phase = [0, 0] }) {
+        const edge = [];
+        const top = (x, z, ratio) => (1.5 * (1 - ratio * ratio) + 0.45 * Math.sin(x * 0.52 + phase[0]) * Math.cos(z * 0.47 + phase[1])) * height;
+        for (let i = 0; i < 24; i++) {
+            const angle = i * Math.PI / 12;
+            const r = radius * (1 + 0.07 * Math.sin(3 * angle + phase[0]) + 0.045 * Math.sin(5 * angle + phase[1]));
+            const x = Math.cos(angle) * r;
+            const z = Math.sin(angle) * r;
+            edge.push([x, top(x, z, 1), z]);
+        }
+        const positions = [];
+        const uvs = [];
+        const triangle = (a, b, c) => {
+            for (const p of [a, b, c]) {
+                positions.push(...p);
+                uvs.push(p[0] / 8, p[2] / 8);
+            }
+        };
+        for (let i = 0; i < edge.length; i++) {
+            const a = edge[i];
+            const b = edge[(i + 1) % edge.length];
+            const midA = [a[0] * 0.46, top(a[0] * 0.46, a[2] * 0.46, 0.46), a[2] * 0.46];
+            const midB = [b[0] * 0.46, top(b[0] * 0.46, b[2] * 0.46, 0.46), b[2] * 0.46];
+            triangle([0, 1.25 * height, 0], midA, midB);
+            triangle(midA, a, b);
+            triangle(midA, b, midB);
+            const bottomA = [a[0] * 0.18, -radius * depth * 0.72, a[2] * 0.18];
+            const bottomB = [b[0] * 0.18, -radius * depth * 0.72, b[2] * 0.18];
+            triangle(a, bottomA, b);
+            triangle(b, bottomA, bottomB);
+        }
+        return this.addMesh({ positions, uvs, transform: transform(position), material: roleMaterial("body") });
+    }
+    ribbonArch({ position, radius, width, material }) {
+        const pieces = [];
+        for (let i = 0; i < 12; i++) {
+            const a = Math.PI * i / 12;
+            const b = Math.PI * (i + 1) / 12;
+            pieces.push(this.beam({
+                from: [position[0] + Math.cos(a) * radius, position[1] + Math.sin(a) * radius, position[2]],
+                to: [position[0] + Math.cos(b) * radius, position[1] + Math.sin(b) * radius, position[2]],
+                width, material,
+            }));
+        }
+        return pieces;
+    }
+    rotate(node, { axis, speed }) {
+        const mesh = this.nodes[node.id];
+        if (!mesh)
+            throw new Error("Scene node belongs to a different or disposed kit");
+        this.animations.push({ mesh, axis: vector(axis).normalize(), speed, base: mesh.quaternion.clone() });
+    }
+    setTime(seconds) {
+        const sampleTime = 8 - Math.abs((seconds % 16 + 16) % 16 - 8);
+        for (const animation of this.animations) {
+            if (animation.samples) {
+                const samples = animation.samples;
+                if (samples.times.length === 0)
+                    continue;
+                let right = samples.times.findIndex((time) => time >= sampleTime);
+                if (right < 0)
+                    right = samples.times.length - 1;
+                const left = Math.max(0, right - 1);
+                const span = samples.times[right] - samples.times[left];
+                const blend = span > 0 ? (sampleTime - samples.times[left]) / span : 0;
+                const a = samples.positions[left];
+                const b = samples.positions[right];
+                if (a && b)
+                    animation.mesh.position.copy(vector(a).lerp(vector(b), blend));
+                const qa = samples.quaternions[left];
+                const qb = samples.quaternions[right];
+                if (qa && qb)
+                    animation.mesh.quaternion.copy(new THREE.Quaternion(...qa).slerp(new THREE.Quaternion(...qb), blend));
+                const sa = samples.scales[left];
+                const sb = samples.scales[right];
+                if (sa && sb)
+                    animation.mesh.scale.copy(vector(sa).lerp(vector(sb), blend));
+                animation.mesh.visible = samples.visible[left] ?? true;
+            }
+            else if (animation.axis && animation.base && animation.speed !== undefined) {
+                animation.mesh.quaternion.copy(animation.base).premultiply(new THREE.Quaternion().setFromAxisAngle(animation.axis, seconds * animation.speed));
+            }
+        }
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.scene.remove(...this.nodes);
+        for (const geometry of this.geometries)
+            geometry.dispose();
+        for (const material of this.materials.values())
+            material.dispose();
+        for (const texture of this.textures)
+            texture.dispose();
+        this.geometries.clear();
+        this.materials.clear();
+        this.textures.clear();
+        this.rolePattern = undefined;
+        this.nodes.length = 0;
+        this.animations.length = 0;
+    }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,20 @@
+import type { SceneDefinition } from "./scene.js";
+export type MotionMode = "ambient" | "fixed" | "cinematic" | "still";
+export type QualityMode = "auto" | "high" | "low";
+export type BackgroundState = "running" | "paused" | "fallback" | "disposed";
+export interface BackgroundOptions {
+    element?: HTMLElement | string;
+    scene: SceneDefinition;
+    motion?: MotionMode;
+    quality?: QualityMode;
+    camera?: "survey" | "detail";
+    speed?: number;
+}
+export interface BackgroundHandle {
+    readonly state: BackgroundState;
+    readonly canvas: HTMLCanvasElement;
+    setMotion(mode: MotionMode): void;
+    setQuality(mode: QualityMode): void;
+    dispose(): void;
+}
+export declare function createBackground(options: BackgroundOptions): BackgroundHandle;