diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 632ff04..6ef1e4c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -62,3 +62,8 @@ jobs: cargo clippy --release --target wasm32-unknown-unknown -p viewer --lib --no-default-features -- -D warnings cargo build --release --target wasm32-unknown-unknown -p viewer --lib cargo clippy --release --target wasm32-unknown-unknown -p viewer --lib -- -D warnings + cargo build --release --target wasm32-unknown-unknown -p viewer --lib --no-default-features --features editor + cargo clippy --release --target wasm32-unknown-unknown -p viewer --lib --no-default-features --features editor -- -D warnings + - name: Test the editor's page + if: steps.affected.outputs.web == 'true' + run: node apps/viewer/web/editor/test.mjs diff --git a/apps/bake/src/scene_file.rs b/apps/bake/src/scene_file.rs index bae0647..aaac19f 100644 --- a/apps/bake/src/scene_file.rs +++ b/apps/bake/src/scene_file.rs @@ -1175,14 +1175,21 @@ pub(crate) fn build_commands( scene.collide[instance as usize] = *how; } } - for (range, owner) in ranges + let placements = &models[model]; + let placed = placements + .whole + .iter() + .chain(placements.parts.iter().map(|(_, at)| at)); + for ((range, owner), placement) in ranges .iter() .zip(collide.whole_owners.iter().chain(&collide.part_owners)) + .zip(placed) { if let Some(id) = owner { scene.sources.push(Source { id: id.clone(), instances: range.clone(), + placement: *placement, }); } } @@ -1210,6 +1217,7 @@ pub(crate) fn build_commands( scene.sources.push(Source { id: CIRCUIT_SOURCE.to_owned(), instances: first..scene.instances.len() as u32, + placement: Mat4::IDENTITY, }); } scene.ground = Some(built.ground); @@ -1242,6 +1250,7 @@ pub(crate) fn build_commands( scene.sources.push(Source { id: TERRAIN_SOURCE.to_owned(), instances: first..scene.instances.len() as u32, + placement: Mat4::IDENTITY, }); } } diff --git a/apps/viewer/Cargo.toml b/apps/viewer/Cargo.toml index 801ed3b..77c6abb 100644 --- a/apps/viewer/Cargo.toml +++ b/apps/viewer/Cargo.toml @@ -20,6 +20,9 @@ required-features = ["gameplay"] [features] default = ["gameplay"] gameplay = ["dep:solstice-game"] +# The editor's page (docs/editor.md): picking, moving instances and the map of what made them. +# Only `editor.html` loads a build with it. +editor = [] [dependencies] solstice-asset.workspace = true diff --git a/apps/viewer/src/web.rs b/apps/viewer/src/web.rs index 4cc8ad1..d0217b8 100644 --- a/apps/viewer/src/web.rs +++ b/apps/viewer/src/web.rs @@ -67,6 +67,9 @@ pub struct WebViewer { /// What scripts logged, and errors, for the page to take. #[cfg(feature = "gameplay")] messages: Vec, + /// Which entity of the scene's project made which instances, for the editor. + #[cfg(feature = "editor")] + sources: Vec, } /// How far around the camera a scene read in parts loads what isn't in view, in metres. @@ -209,6 +212,8 @@ impl WebViewer { play: None, #[cfg(feature = "gameplay")] messages: Vec::new(), + #[cfg(feature = "editor")] + sources: scene.sources, }) } @@ -917,3 +922,121 @@ pub fn read_header(bytes: &[u8]) -> Result, JsValue> { header.manifest_bytes as f64, ]) } + +/// What the editor's page needs (`docs/editor.md`): the map of which entity made which +/// instances, moving and hiding instances, the camera's matrices, and picking. +#[cfg(feature = "editor")] +#[wasm_bindgen] +impl WebViewer { + /// The ids of the entities the scene's map names, one to a line, in its order. Empty for a + /// scene not baked from a project. + pub fn source_ids(&self) -> String { + let ids: Vec<&str> = self.sources.iter().map(|s| s.id.as_str()).collect(); + ids.join("\n") + } + + /// Each mapped entity's instances, as its first and one past its last, in the map's order. + pub fn source_ranges(&self) -> Vec { + self.sources + .iter() + .flat_map(|s| [s.instances.start, s.instances.end]) + .collect() + } + + /// Each mapped entity's placement as the bake made it, 16 numbers by column, in the map's + /// order. + pub fn source_placements(&self) -> Vec { + self.sources + .iter() + .flat_map(|s| s.placement.to_cols_array()) + .collect() + } + + pub fn instance_count(&self) -> u32 { + self.renderer.instance_count() + } + + /// Where an instance is drawn, 16 numbers by column; empty if there is no such instance. + pub fn instance_transform(&self, instance: u32) -> Vec { + self.renderer + .instance_transform(instance) + .map(|m| m.to_cols_array().to_vec()) + .unwrap_or_default() + } + + /// An instance's bounding sphere in the world: centre x, y, z and radius; empty if none. + pub fn instance_bounds(&self, instance: u32) -> Vec { + self.renderer + .instance_bounds(instance) + .map(|(c, r)| vec![c.x, c.y, c.z, r]) + .unwrap_or_default() + } + + /// Puts an instance at `world` (16 numbers by column) from the next frame. `jump` puts it + /// there with no motion between, as an undo should; otherwise it moves there, as a drag does. + /// False if there is no such instance or the matrix can't be inverted. + pub fn set_instance_transform(&mut self, instance: u32, world: &[f32], jump: bool) -> bool { + let Ok(columns) = <[f32; 16]>::try_from(world) else { + return false; + }; + let world = glam::Mat4::from_cols_array(&columns); + if !world.is_finite() || world.determinant().abs() < 1e-12 { + return false; + } + if jump { + self.renderer.place_instance(instance, world) + } else { + self.renderer.move_instance(instance, world) + } + } + + /// Makes an instance movable while it is dragged, and static again after, so the cached + /// shadows and GI are redrawn once at the end rather than every frame of the drag. + pub fn set_instance_movable(&mut self, instance: u32, movable: bool) -> bool { + self.renderer.set_instance_movable(instance, movable) + } + + pub fn set_instance_hidden(&mut self, instance: u32, hidden: bool) -> bool { + self.renderer.set_instance_hidden(instance, hidden) + } + + /// The camera's view and projection, 16 numbers by column each, for the page to draw the + /// gizmo over the scene and turn the mouse into rays. The projection has reversed depth and + /// no far plane. + pub fn view_projection(&self) -> Vec { + let camera = &self.camera.camera; + let aspect = self.config.width as f32 / self.config.height.max(1) as f32; + let mut out = camera.view().to_cols_array().to_vec(); + out.extend(camera.projection(aspect).to_cols_array()); + out + } + + /// How fast the camera flies, in metres a second (Shift goes five times faster). + pub fn set_camera_speed(&mut self, metres_per_second: f32) { + if metres_per_second.is_finite() && metres_per_second > 0.0 { + self.camera.speed = metres_per_second; + } + } + + pub fn camera_speed(&self) -> f32 { + self.camera.speed + } + + /// Asks what is under a point of the canvas, as fractions of its width and height from the + /// top left. `take_pick` gives the answer a frame or two later. + pub fn request_pick(&mut self, x: f32, y: f32) { + self.renderer.request_pick(x, y); + } + + /// The last pick's answer, once: the instance (or -1 for the sky) and its reversed depth. + /// Empty while it isn't ready. + pub fn take_pick(&mut self) -> Vec { + match self.renderer.take_pick() { + None => Vec::new(), + Some(picked) => vec![ + picked.instance.map_or(-1.0, f64::from), + f64::from(picked.depth), + ], + } + } +} diff --git a/apps/viewer/web/editor.html b/apps/viewer/web/editor.html new file mode 100644 index 0000000..5c630ef --- /dev/null +++ b/apps/viewer/web/editor.html @@ -0,0 +1,146 @@ + + + + + +Solstice Editor + + + + +
+ Solstice Editor +
+ + + +
+
+ + + +
+
+ + +
+ + +
+ + View scene +
+ +
+ + +
Click select · W E R move/rotate/scale · F frame · Right-drag + WASD fly · Alt-drag orbit · Middle-drag pan · Wheel zoom
+ +
Starting…
+
+ +
+
Nothing selected
+ + + diff --git a/apps/viewer/web/editor/commands.js b/apps/viewer/web/editor/commands.js new file mode 100644 index 0000000..968db6a --- /dev/null +++ b/apps/viewer/web/editor/commands.js @@ -0,0 +1,171 @@ +// The editor's one list of commands (docs/editor.md, "The command API for agents"). The panels, +// the keyboard, the gizmo and agents all act through it, so each can do what the others can, and +// every change is undone the same way. +// +// A command is `{ description, args, run(args, context) }`. `args` is a small schema: each +// argument's type, whether it is needed, and what it means, which `help` reports. A command +// that changes the scene returns a step for the history: `{ label, undo(), redo() }`, with the +// change already made. + +export class CommandError extends Error { + constructor(code, message) { + super(message); + this.code = code; + } +} + +/// Checks a call's arguments against a command's schema, and gives them back tidied. +function check(name, schema, args) { + if (args === null || typeof args !== "object" || Array.isArray(args)) { + throw new CommandError("bad_arguments", `${name} takes an object of arguments`); + } + for (const key of Object.keys(args)) { + if (!(key in schema)) { + throw new CommandError("bad_arguments", + `${name} has no argument \`${key}\`; it takes ${Object.keys(schema).join(", ") || "none"}`); + } + } + const out = {}; + for (const [key, spec] of Object.entries(schema)) { + const value = args[key]; + if (value === undefined) { + if (spec.required) throw new CommandError("bad_arguments", `${name} needs \`${key}\``); + continue; + } + const fail = () => { + throw new CommandError("bad_arguments", `${name}: \`${key}\` should be ${spec.type}`); + }; + switch (spec.type) { + case "number": if (typeof value !== "number" || !Number.isFinite(value)) fail(); break; + case "string": if (typeof value !== "string") fail(); break; + case "boolean": if (typeof value !== "boolean") fail(); break; + case "vec3": + if (!Array.isArray(value) || value.length !== 3 + || !value.every((v) => typeof v === "number" && Number.isFinite(v))) fail(); + break; + case "string[]": + if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) fail(); + break; + default: break; + } + out[key] = value; + } + return out; +} + +/// What `help` reports of an argument schema: JSON Schema, which agents and WebMCP read. +function jsonSchema(schema) { + const types = { + number: { type: "number" }, + string: { type: "string" }, + boolean: { type: "boolean" }, + vec3: { type: "array", items: { type: "number" }, minItems: 3, maxItems: 3 }, + "string[]": { type: "array", items: { type: "string" } }, + }; + return { + type: "object", + properties: Object.fromEntries(Object.entries(schema).map(([key, spec]) => + [key, { ...types[spec.type], description: spec.description }])), + required: Object.entries(schema).filter(([, spec]) => spec.required).map(([key]) => key), + additionalProperties: false, + }; +} + +/// Undo and redo, step by step, each step saying who took it. +export class History { + #done = []; + #undone = []; + /// Called after every change to the history. + onChange = () => {}; + static LIMIT = 500; + + push(step) { + this.#done.push(step); + if (this.#done.length > History.LIMIT) this.#done.shift(); + this.#undone = []; + this.onChange(); + } + + undo() { + const step = this.#done.pop(); + if (!step) return null; + step.undo(); + this.#undone.push(step); + this.onChange(); + return step; + } + + redo() { + const step = this.#undone.pop(); + if (!step) return null; + step.redo(); + this.#done.push(step); + this.onChange(); + return step; + } + + /// What can be undone, oldest first, and what can be redone, next first. + list() { + const describe = (step) => ({ label: step.label, by: step.by }); + return { done: this.#done.map(describe), undone: [...this.#undone].reverse().map(describe) }; + } +} + +export class Commands { + #commands = new Map(); + history = new History(); + /// Called after each command that ran, with its name, its arguments and who called it. + onRun = () => {}; + + constructor(context) { + this.context = context; + } + + define(name, command) { + this.#commands.set(name, command); + } + + /// Runs a command. `by` is who asked: "user" from the page, "agent" from the API. Gives back + /// `{ ok: true, result }` or `{ ok: false, error: { code, message } }`, never throwing, so a + /// caller always has something to read. + async call(name, args = {}, by = "user") { + try { + const command = this.#commands.get(name); + if (!command) { + throw new CommandError("unknown_command", + `no command \`${name}\`; solstice.help() lists them`); + } + const checked = check(name, command.args ?? {}, args ?? {}); + const outcome = await command.run(checked, this.context, by); + const { step, result } = outcome && "step" in outcome ? outcome : { step: null, result: outcome }; + if (step) this.history.push({ ...step, by }); + this.onRun(name, checked, by); + return { ok: true, result: result ?? null }; + } catch (error) { + if (!(error instanceof CommandError)) console.error(error); + return { + ok: false, + error: { + code: error.code ?? "failed", + message: error.message ?? String(error), + }, + }; + } + } + + /// Every command, or one, with its description, its arguments as JSON Schema, and an example. + help(name) { + const describe = (n, c) => ({ + name: n, + description: c.description, + changes: Boolean(c.changes), + arguments: jsonSchema(c.args ?? {}), + example: c.example ?? null, + }); + if (name !== undefined) { + const command = this.#commands.get(name); + return command ? describe(name, command) : null; + } + return [...this.#commands].map(([n, c]) => describe(n, c)); + } +} diff --git a/apps/viewer/web/editor/gizmo.js b/apps/viewer/web/editor/gizmo.js new file mode 100644 index 0000000..1032b20 --- /dev/null +++ b/apps/viewer/web/editor/gizmo.js @@ -0,0 +1,290 @@ +// The transform gizmo: move, rotate and scale handles drawn over the viewport, as Unreal's and +// Unity's are, a constant size on screen. It is drawn on a 2D canvas over the scene, and turns a +// drag on a handle into a new transform; the editor makes that a command. + +import { + add, closestAlongLine, cross, dot, eulerFromColumns, length, multiply, normalize, + projectToScreen, rayPlane, rotateColumns, rotationColumns, scale, sub, tidy, tidyAngles, +} from "./math.js"; + +const COLOURS = ["#e5484d", "#46a758", "#3e63dd"]; +const HOVER = "#ffd60a"; +/// How tall the gizmo stands on screen, in CSS pixels. +const SIZE_PX = 130; +const PICK_PX = 9; +const RING_SEGMENTS = 64; + +export class Gizmo { + /// "move", "rotate" or "scale". + mode = "move"; + /// "world" or "local": which way the handles point. + space = "world"; + snap = { on: true, move: 0.5, angle: 15, scale: 0.1 }; + /// The handle under the mouse, or being dragged. + hover = null; + + /// The handles' frame for `transform`, given the camera: where its centre is, which way its + /// axes point, and how long they are in metres so they look `SIZE_PX` tall. + #frame(transform, camera) { + const origin = transform.position; + const axes = this.space === "local" && this.mode !== "scale" + ? rotationColumns(transform.rotation) + : [[1, 0, 0], [0, 1, 0], [0, 0, 1]]; + const distance = Math.max(0.01, dot(sub(origin, camera.position), camera.forward)); + const size = distance * camera.tanHalfFov * 2 * SIZE_PX / camera.cssHeight; + return { origin, axes, size }; + } + + /// Handles as screen shapes: each `{ handle, kind, points, colour }`. + #shapes(transform, camera) { + const { origin, axes, size } = this.#frame(transform, camera); + const toScreen = (p) => projectToScreen(camera.viewProjection, p, camera.cssWidth, camera.cssHeight); + const shapes = []; + if (this.mode === "rotate") { + axes.forEach((axis, k) => { + const u = axes[(k + 1) % 3]; + const v = axes[(k + 2) % 3]; + const points = []; + for (let i = 0; i <= RING_SEGMENTS; i++) { + const a = (i / RING_SEGMENTS) * Math.PI * 2; + const p = add(origin, add(scale(u, Math.cos(a) * size), scale(v, Math.sin(a) * size))); + points.push({ ...toScreen(p), facing: dot(sub(p, origin), camera.forward) < 0 }); + } + shapes.push({ handle: { kind: "ring", axis: k }, kind: "ring", points, colour: COLOURS[k] }); + }); + return shapes; + } + axes.forEach((axis, k) => { + const tip = add(origin, scale(axis, size)); + shapes.push({ + handle: { kind: this.mode === "move" ? "axis" : "scale", axis: k }, + kind: this.mode === "move" ? "arrow" : "stick", + points: [toScreen(origin), toScreen(tip)], + colour: COLOURS[k], + }); + }); + if (this.mode === "move") { + // A square in each plane, between the two axes it holds. + axes.forEach((_, k) => { + const u = axes[(k + 1) % 3]; + const v = axes[(k + 2) % 3]; + const corner = (a, b) => toScreen(add(origin, add(scale(u, a * size), scale(v, b * size)))); + shapes.push({ + handle: { kind: "plane", axis: k }, + kind: "quad", + points: [corner(0.25, 0.25), corner(0.45, 0.25), corner(0.45, 0.45), corner(0.25, 0.45)], + colour: COLOURS[k], + }); + }); + } + shapes.push({ + handle: { kind: this.mode === "move" ? "free" : "uniform", axis: -1 }, + kind: "centre", + points: [toScreen(origin)], + colour: "#f2f2f2", + }); + return shapes; + } + + draw(context, transform, camera) { + context.save(); + context.lineCap = "round"; + for (const shape of this.#shapes(transform, camera)) { + const hot = this.hover && this.hover.kind === shape.handle.kind && this.hover.axis === shape.handle.axis; + const colour = hot ? HOVER : shape.colour; + context.strokeStyle = colour; + context.fillStyle = colour; + const [a, b] = shape.points; + if (shape.points.some((p) => !p.front)) continue; + if (shape.kind === "ring") { + // The back half of a ring is fainter, as both editors draw it. + for (let i = 1; i < shape.points.length; i++) { + const p = shape.points[i - 1]; + const q = shape.points[i]; + context.globalAlpha = p.facing ? 1 : 0.35; + context.lineWidth = hot ? 4 : 2.5; + context.beginPath(); + context.moveTo(p.x, p.y); + context.lineTo(q.x, q.y); + context.stroke(); + } + context.globalAlpha = 1; + } else if (shape.kind === "arrow" || shape.kind === "stick") { + context.lineWidth = hot ? 4 : 2.5; + context.beginPath(); + context.moveTo(a.x, a.y); + context.lineTo(b.x, b.y); + context.stroke(); + const dx = b.x - a.x; + const dy = b.y - a.y; + const l = Math.hypot(dx, dy) || 1; + const [ux, uy] = [dx / l, dy / l]; + context.beginPath(); + if (shape.kind === "arrow") { + context.moveTo(b.x + ux * 12, b.y + uy * 12); + context.lineTo(b.x - uy * 5, b.y + ux * 5); + context.lineTo(b.x + uy * 5, b.y - ux * 5); + } else { + context.rect(b.x - 5, b.y - 5, 10, 10); + } + context.fill(); + } else if (shape.kind === "quad") { + context.globalAlpha = hot ? 0.75 : 0.4; + context.beginPath(); + shape.points.forEach((p, i) => (i ? context.lineTo(p.x, p.y) : context.moveTo(p.x, p.y))); + context.closePath(); + context.fill(); + context.globalAlpha = 1; + } else if (shape.kind === "centre") { + context.beginPath(); + context.arc(a.x, a.y, hot ? 6 : 4.5, 0, Math.PI * 2); + context.fill(); + } + } + context.restore(); + } + + /// The handle under a point of the canvas, in CSS pixels, or null. + hit(transform, camera, x, y) { + let best = null; + let bestDistance = PICK_PX; + const consider = (handle, distance) => { + if (distance < bestDistance) { + bestDistance = distance; + best = handle; + } + }; + for (const shape of this.#shapes(transform, camera)) { + if (shape.points.some((p) => !p.front)) continue; + if (shape.kind === "centre") { + consider(shape.handle, Math.hypot(shape.points[0].x - x, shape.points[0].y - y) - 3); + } else if (shape.kind === "quad") { + if (insidePolygon(shape.points, x, y)) consider(shape.handle, 1); + } else { + for (let i = 1; i < shape.points.length; i++) { + // A ring is picked by its front half first, where the eye goes. + const penalty = shape.points[i].facing === false ? 2 : 0; + consider(shape.handle, segmentDistance(shape.points[i - 1], shape.points[i], x, y) + penalty); + } + } + } + return best; + } + + /// Starts dragging `handle` on an entity whose transform is `start`, from a mouse ray. Gives + /// back a function from each later ray (whether to snap, and the mouse) to the change so far: + /// `{ transform, change }`, where `transform` is the dragged entity's and `change` is the same + /// change for any other selected with it: `{ move: [x, y, z] }`, `{ axis, angle }` (radians + /// about a world axis) or `{ ratio }`. + drag(handle, start, camera, ray0, mouse0) { + const { origin, axes } = this.#frame(start, camera); + const columns0 = rotationColumns(start.rotation); + const snap = (on) => on && this.snap.on; + if (handle.kind === "axis") { + const axis = axes[handle.axis]; + const t0 = closestAlongLine(origin, axis, ray0); + return (ray, snapping) => { + const t = closestAlongLine(origin, axis, ray); + if (t === null || t0 === null) return { transform: start, change: { move: [0, 0, 0] } }; + const position = this.#snapMove(add(start.position, scale(axis, t - t0)), start.position, axis, snap(snapping)); + return { transform: { ...start, position }, change: { move: sub(position, start.position) } }; + }; + } + if (handle.kind === "plane" || handle.kind === "free") { + // The free handle moves across the screen's own plane. + const normal = handle.kind === "plane" ? axes[handle.axis] : camera.forward; + const p0 = rayPlane(ray0, origin, normal); + return (ray, snapping) => { + const p = rayPlane(ray, origin, normal); + if (!p || !p0) return { transform: start, change: { move: [0, 0, 0] } }; + const position = this.#snapMove(add(start.position, sub(p, p0)), start.position, null, snap(snapping)); + return { transform: { ...start, position }, change: { move: sub(position, start.position) } }; + }; + } + if (handle.kind === "ring") { + const axis = axes[handle.axis]; + const p0 = rayPlane(ray0, origin, axis) ?? add(origin, axes[(handle.axis + 1) % 3]); + const v0 = normalize(sub(p0, origin)); + return (ray, snapping) => { + const p = rayPlane(ray, origin, axis); + if (!p) return { transform: start, change: { axis, angle: 0 } }; + const v = normalize(sub(p, origin)); + let angle = Math.atan2(dot(cross(v0, v), axis), dot(v0, v)); + if (snap(snapping)) { + const step = this.snap.angle * Math.PI / 180; + angle = Math.round(angle / step) * step; + } + const rotation = tidyAngles(eulerFromColumns(rotateColumns(columns0, axis, angle))); + return { transform: { ...start, rotation }, change: { axis, angle } }; + }; + } + // Scale, by any handle: by how much farther from the centre on screen the mouse is. + const centre = projectToScreen(camera.viewProjection, origin, camera.cssWidth, camera.cssHeight); + const d0 = Math.max(4, Math.hypot(mouse0.x - centre.x, mouse0.y - centre.y)); + return (ray, snapping, mouse) => { + const ratio = Math.hypot(mouse.x - centre.x, mouse.y - centre.y) / d0; + let s = Math.max(0.01, start.scale * ratio); + s = snap(snapping) ? Math.max(this.snap.scale, tidy(s, this.snap.scale)) : tidy(s, 0.001); + return { transform: { ...start, scale: s }, change: { ratio: s / start.scale } }; + }; + } + + /// Snaps a moved position to the grid: along `axis` only, if given, as moving along one axis + /// shouldn't shift the others. + #snapMove(position, from, axis, on) { + if (!on) return position.map((v) => tidy(v, 0.001)); + const step = this.snap.move; + const isWorldAxis = axis && axis.filter((v) => Math.abs(v) > 1e-6).length === 1; + return position.map((v, k) => { + if (axis && isWorldAxis && Math.abs(axis[k]) < 1e-6) return from[k]; + if (axis && !isWorldAxis) { + // Along a turned axis, the distance moved snaps, not the coordinates. + const moved = dot(sub(position, from), axis); + return tidy(from[k] + axis[k] * Math.round(moved / step) * step, 0.001); + } + return tidy(Math.round(v / step) * step, 0.001); + }); + } +} + +function segmentDistance(a, b, x, y) { + const dx = b.x - a.x; + const dy = b.y - a.y; + const l2 = dx * dx + dy * dy; + const t = l2 ? Math.max(0, Math.min(1, ((x - a.x) * dx + (y - a.y) * dy) / l2)) : 0; + return Math.hypot(a.x + dx * t - x, a.y + dy * t - y); +} + +function insidePolygon(points, x, y) { + let inside = false; + for (let i = 0, j = points.length - 1; i < points.length; j = i++) { + const [a, b] = [points[i], points[j]]; + if ((a.y > y) !== (b.y > y) && x < ((b.x - a.x) * (y - a.y)) / (b.y - a.y) + a.x) inside = !inside; + } + return inside; +} + +/// The camera as the gizmo needs it, from the viewer's matrices and the canvas's CSS size. +export function cameraFrom(viewer, cssWidth, cssHeight) { + const both = Array.from(viewer.view_projection()); + const view = both.slice(0, 16); + const projection = both.slice(16); + const at = Array.from(viewer.camera()); + const [yaw, pitch] = [at[3], at[4]]; + const forward = [-Math.sin(yaw) * Math.cos(pitch), Math.sin(pitch), -Math.cos(yaw) * Math.cos(pitch)]; + return { + view, + projection, + viewProjection: multiply(projection, view), + position: at.slice(0, 3), + yaw, + pitch, + forward, + // projection[5] is 1 / tan(fov_y / 2). + tanHalfFov: 1 / projection[5], + cssWidth, + cssHeight, + }; +} + +export { length }; diff --git a/apps/viewer/web/editor/main.js b/apps/viewer/web/editor/main.js new file mode 100644 index 0000000..00c8bcb --- /dev/null +++ b/apps/viewer/web/editor/main.js @@ -0,0 +1,1150 @@ +// The editor's page (docs/editor.md): opens a scene and its project, and lets people, and agents +// through `window.solstice`, select, move, turn and scale what is in it, with undo. + +import { openScene, requestAdapter } from "../loader.js"; +import { Commands, CommandError } from "./commands.js"; +import { Gizmo, cameraFrom } from "./gizmo.js"; +import { + add, dot, multiply, normalize, projectToScreen, rayThrough, rotateColumns, rotationColumns, + eulerFromColumns, scale as scaleVector, sub, tidy, tidyAngles, +} from "./math.js"; +import { Details, Outliner } from "./panels.js"; +import { Project, kindOf } from "./project.js"; + +const params = new URLSearchParams(location.search); +const el = (id) => document.getElementById(id); +const canvas = el("view"); +const overlay = el("overlay-canvas"); +const context = overlay.getContext("2d"); + +const sceneName = params.get("scene") ?? "cove"; +if (!/^[\w-]+$/.test(sceneName)) throw new Error("invalid scene name"); +const sceneBase = params.get("scenes") ?? "assets/"; +const API_VERSION = 1; + +// ---- The output log, which agents read through `log.read`. +const log = { + entries: [], + next: 1, + add(level, text) { + const entry = { seq: this.next++, time: Math.round(performance.now()), level, text }; + this.entries.push(entry); + if (this.entries.length > 1000) this.entries.shift(); + const line = document.createElement("div"); + line.className = `log-${level}`; + line.textContent = text; + el("log").append(line); + while (el("log").childElementCount > 200) el("log").firstChild.remove(); + el("log").scrollTop = el("log").scrollHeight; + if (level === "error") console.error(text); + }, +}; + +function fail(text) { + el("loading").hidden = false; + el("loading-text").textContent = text; + el("loading-text").className = "error"; + log.add("error", text); +} + +async function main() { + if (!navigator.gpu || !(await requestAdapter())) { + fail("This browser has no WebGPU adapter for this GPU. Try a recent Chrome or Edge."); + return; + } + const wasm = await import("../editor-wasm/solstice_viewer.js"); + await wasm.default(); + el("loading-text").textContent = "Loading scene…"; + const resize = () => { + const ratio = Math.min(window.devicePixelRatio || 1, 2); + const box = canvas.getBoundingClientRect(); + return [Math.max(1, Math.round(box.width * ratio)), Math.max(1, Math.round(box.height * ratio)), ratio]; + }; + [canvas.width, canvas.height] = resize(); + const { viewer, streamer, file } = await openScene(wasm, canvas, { + url: `${sceneBase}${sceneName}.solstice`, + geometryBudget: (Number(params.get("geometry-mb")) || 128) * 1048576, + textureBudget: (Number(params.get("texture-mb")) || 64) * 1048576, + onStage: (text) => { el("loading-text").textContent = text; }, + onDownload: (received) => { + if (received !== null) el("loading-text").textContent = `Downloading scene: ${(received / 1e6).toFixed(0)} MB`; + }, + }); + + // The project: the scene file beside the baked scene, if there is one. + let sceneJson = null; + const projectUrl = params.get("project") ?? `${sceneBase}${sceneName}.scene`; + try { + const response = await fetch(projectUrl); + if (response.ok) sceneJson = await response.text(); + } catch { /* none */ } + const project = new Project(sceneJson ? JSON.parse(sceneJson) : null, viewer); + if (!project.saveable) { + log.add("warn", `No project at ${projectUrl}: each instance is listed alone, and can be moved but not saved.`); + } else if (viewer.source_ids() === "") { + log.add("warn", "This scene was baked without the map of its entities (bake it with --project): nothing can be picked or moved."); + } + editor.start(viewer, streamer, file, project, sceneJson, resize); +} + +/// Everything the editor holds, and the commands that change it. +const editor = { + viewer: null, + project: null, + selection: new Set(), + hidden: new Set(), + gizmo: new Gizmo(), + commands: null, + frames: 0, + fps: 0, + frameMs: 0, + /// Picks waiting for the GPU's answer. + picks: [], + /// Calls waiting for frames: `{ frames, resolve }`. + waits: [], + dirty: false, + + call(name, args) { + return this.commands.call(name, args, "user"); + }, + + /// Where entities were before a drag or a scrub began showing changes, by id: the change is + /// made a step in the history from there when it ends. + previews: new Map(), + + /// Shows a transform while a field is scrubbed or a handle dragged, without a step in the + /// history. + preview(id, transform) { + if (!this.previews.has(id)) this.previews.set(id, this.project.snapshot(id)); + this.project.setTransform(id, nextTransform(this, id, transform), false); + this.renderOverlay(); + }, + + /// Puts back what previews moved, as they were. + endPreviews() { + for (const [id, snapshot] of this.previews) this.project.restore(id, snapshot, true); + this.previews.clear(); + }, + + start(viewer, streamer, file, project, sceneJson, resize) { + this.viewer = viewer; + this.streamer = streamer; + this.file = file; + this.project = project; + this.savedJson = sceneJson; + this.resize = resize; + this.commands = new Commands(this); + defineCommands(this.commands, this); + this.commands.history.onChange = () => { + this.dirty = true; + this.refresh(); + scheduleAutosave(this); + el("undo").disabled = this.commands.history.list().done.length === 0; + el("redo").disabled = this.commands.history.list().undone.length === 0; + }; + this.outliner = new Outliner(el("outliner"), this); + this.details = new Details(el("details"), this); + this.refresh(); + bindInput(this); + bindToolbar(this); + exposeApi(this); + offerDraft(this); + el("loading").hidden = true; + log.add("info", `Opened ${sceneName}: ${project.entities.size} entities, ${viewer.instance_count()} instances.`); + requestAnimationFrame((now) => this.tick(now, now)); + }, + + refresh() { + this.outliner.render(); + this.details.render(); + el("selected").textContent = this.selection.size + ? [...this.selection].map((id) => this.project.entities.get(id)?.name).join(", ") + : "Nothing selected"; + el("save").disabled = !this.project.saveable; + document.title = `${this.dirty ? "• " : ""}${sceneName} — Solstice Editor`; + }, + + tick(now, previous) { + const delta = Math.min((now - previous) / 1000, 0.1); + this.streamer.pump(); + const fly = this.input.flying ? this.input.axes() : [0, 0, 0]; + this.viewer.frame(delta, fly[0], fly[1], fly[2], this.input.lookYaw, this.input.lookPitch, this.input.fast()); + this.input.lookYaw = 0; + this.input.lookPitch = 0; + this.frames += 1; + this.frameMs = this.frameMs * 0.9 + (now - previous) * 0.1; + this.fps = this.frameMs > 0 ? 1000 / this.frameMs : 0; + if (this.frames % 15 === 0) { + el("fps").textContent = `${this.fps.toFixed(0)} fps · ${this.frameMs.toFixed(1)} ms`; + const errors = this.viewer.gpu_error_count(); + if (errors !== this.gpuErrors) { + if (this.gpuErrors !== undefined) log.add("error", `GPU errors: ${errors}`); + this.gpuErrors = errors; + } + } + const pick = this.viewer.take_pick(); + if (pick.length) { + // An answer to a pick given up on (its tab was hidden) belongs to nobody waiting now. + if (this.pickStale) this.pickStale = false; + else if (this.picks.length) { + const { resolve, fx, fy } = this.picks.shift(); + resolve(pickResult(this, pick, fx, fy)); + } + if (this.picks.length) this.viewer.request_pick(this.picks[0].fx, this.picks[0].fy); + } + this.waits = this.waits.filter((w) => { + w.frames -= 1; + if (w.frames > 0) return true; + w.resolve(); + return false; + }); + this.renderOverlay(); + requestAnimationFrame((next) => this.tick(next, now)); + }, + + camera() { + return cameraFrom(this.viewer, overlay.clientWidth, overlay.clientHeight); + }, + + /// The selected entity the gizmo sits on: the last selected that has a transform. + primary() { + return [...this.selection].reverse().find((id) => this.project.shownTransform(id)) ?? null; + }, + + renderOverlay() { + const ratio = window.devicePixelRatio || 1; + const [w, h] = [overlay.clientWidth, overlay.clientHeight]; + if (overlay.width !== Math.round(w * ratio) || overlay.height !== Math.round(h * ratio)) { + overlay.width = Math.round(w * ratio); + overlay.height = Math.round(h * ratio); + } + context.setTransform(ratio, 0, 0, ratio, 0, 0); + context.clearRect(0, 0, w, h); + const camera = this.camera(); + // Things with nowhere to be drawn, such as lights and blockers, show as markers. + for (const marker of this.markers(camera)) { + context.fillStyle = this.selection.has(marker.id) ? "#ff9f1a" : "rgba(235, 235, 235, 0.8)"; + context.beginPath(); + context.arc(marker.x, marker.y, 5, 0, Math.PI * 2); + context.fill(); + } + for (const id of this.selection) { + const bounds = this.project.bounds(id); + if (!bounds) continue; + const centre = projectToScreen(camera.viewProjection, bounds.centre, w, h); + if (!centre.front) continue; + const distance = Math.max(0.01, dot(sub(bounds.centre, camera.position), camera.forward)); + const radius = (bounds.radius / (distance * camera.tanHalfFov)) * (h / 2); + context.strokeStyle = "#ff9f1a"; + context.lineWidth = 1.5; + context.setLineDash([6, 4]); + context.beginPath(); + context.arc(centre.x, centre.y, Math.min(radius, Math.max(w, h)), 0, Math.PI * 2); + context.stroke(); + context.setLineDash([]); + } + const primary = this.primary(); + if (primary) this.gizmo.draw(context, this.project.shownTransform(primary), camera); + }, + + /// Where entities that draw nothing are on screen. + markers(camera) { + const out = []; + for (const [id, entity] of this.project.entities) { + if (!entity.transform || this.project.drawn(id) || this.hidden.has(id)) continue; + const p = projectToScreen(camera.viewProjection, this.project.shownTransform(id).position, + camera.cssWidth, camera.cssHeight); + if (p.front) out.push({ id, x: p.x, y: p.y }); + } + return out; + }, + + /// Asks the GPU what is under a point of the viewport, as fractions of its size. + pick(fx, fy) { + return withinTime(new Promise((resolve) => { + this.picks.push({ fx, fy, resolve }); + if (this.picks.length === 1 && !this.pickStale) this.viewer.request_pick(fx, fy); + }), () => { + this.picks = []; + this.pickStale = true; + }); + }, + + /// Resolves after `frames` frames. Frames stop while the tab is hidden, so it gives up after + /// a while rather than leave an agent waiting for ever. + waitFrames(frames) { + const wait = { frames }; + return withinTime(new Promise((resolve) => { + wait.resolve = resolve; + this.waits.push(wait); + }), () => { this.waits = this.waits.filter((w) => w !== wait); }, 2000 + frames * 100); + }, +}; + +/// Gives up on what needs frames drawn when none come, as in a hidden tab, with an error that +/// says so; `cancel` forgets the wait. +function withinTime(promise, cancel, ms = 5000) { + let timer; + const timeout = new Promise((_, reject) => { + timer = setTimeout(() => { + cancel(); + reject(new CommandError("not_drawing", + "the viewport drew no frames in time: is its tab hidden or in the background? Bring it to the front")); + }, ms); + }); + return Promise.race([promise, timeout]).finally(() => clearTimeout(timer)); +} + +/// What a pick found: the entity, the instance and the point hit, from the GPU's answer. +function pickResult(editor, [instance, depth], fx, fy) { + if (instance < 0) return { id: null, instance: null, point: null }; + const camera = editor.camera(); + const ray = rayThrough(camera.view, camera.projection, fx, fy); + // Reversed depth with no far plane: depth = near / distance along the view. + const near = camera.projection[14]; + const along = near / depth; + const point = add(ray.origin, scaleVector(ray.direction, along / Math.max(1e-6, dot(ray.direction, camera.forward)))); + return { + id: editor.project.entityAt(instance), + instance, + point: point.map((v) => tidy(v, 0.001)), + }; +} + +// ---- Changing transforms, as one step for any number of entities. + +/// Applies new transforms (by id) and gives back the step that undoes them. What any preview +/// showed is put back first, so the step goes from where things really were. +function transformStep(editor, changes, label) { + const before = new Map(); + for (const id of changes.keys()) { + before.set(id, editor.previews.get(id) ?? editor.project.snapshot(id)); + } + editor.endPreviews(); + for (const [id, transform] of changes) editor.project.setTransform(id, transform, true); + const after = new Map([...changes.keys()].map((id) => [id, editor.project.snapshot(id)])); + const apply = (map) => { + for (const [id, snapshot] of map) editor.project.restore(id, snapshot, true); + editor.refresh(); + }; + return { label, undo: () => apply(before), redo: () => apply(after) }; +} + +/// An entity's shown transform made into the project's, given a new one from the editor: a +/// model seated on the ground keeps its seat until its height is changed. +function nextTransform(editor, id, shown) { + // Compared with where it was before any preview began. + const original = editor.previews.get(id) ?? editor.project.snapshot(id); + const was = editor.project.shownFrom(original); + // Only what changed is tidied; what didn't keeps its value exactly as the file had it. + const keep = (value, before, step) => (Math.abs(value - before) < 1e-9 ? before : tidy(value, step)); + const rotation = shown.rotation ?? [0, 0, 0]; + const turned = rotation.some((v, k) => Math.abs(v - was.rotation[k]) > 1e-9); + const out = { + position: shown.position.map((v, k) => keep(v, was.position[k], 0.0001)), + rotation: turned ? tidyAngles(rotation) : was.rotation, + scale: keep(shown.scale ?? 1, was.scale, 0.0001), + }; + if (!(out.scale >= 0.0001) || !Number.isFinite(out.scale)) { + throw new CommandError("bad_arguments", "scale must be at least 0.0001"); + } + if (!out.position.every((v) => Number.isFinite(v) && Math.abs(v) < 1e7)) { + throw new CommandError("bad_arguments", "positions must be within 10 000 km of the origin"); + } + // A model seated on the ground stays seated until it is moved; then it keeps the height it + // was shown at, as both editors' models do, and the project says that height. + const ground = original.transform.ground; + const moved = out.position.some((v, k) => v !== was.position[k]); + if (ground !== undefined && !moved) out.ground = ground; + return out; +} + +/// The same change a gizmo drag made to its entity, made to another selected with it. +function applyChange(shown, change) { + if (change.move) return { ...shown, position: add(shown.position, change.move) }; + if (change.axis) { + const rotation = tidyAngles(eulerFromColumns(rotateColumns(rotationColumns(shown.rotation), change.axis, change.angle))); + return { ...shown, rotation }; + } + return { ...shown, scale: shown.scale * change.ratio }; +} + +// ---- Commands: what the panels, the keyboard and agents can do. + +function needEntity(editor, id) { + const entity = editor.project.entities.get(id); + if (!entity) throw new CommandError("unknown_id", `no entity \`${id}\`; scene.objects lists them`); + return entity; +} + +function needTransform(editor, id) { + needEntity(editor, id); + const shown = editor.project.shownTransform(id); + if (!shown) throw new CommandError("no_transform", `\`${id}\` is a folder or has no place to move`); + return shown; +} + +function describe(editor, id) { + const entity = editor.project.entities.get(id); + const shown = editor.project.shownTransform(id); + return { + id, + name: entity.name, + kind: kindOf(entity), + parent: editor.project.parents.get(id) ?? null, + ...(shown ? { + position: shown.position.map((v) => tidy(v, 0.0001)), + rotation: shown.rotation, + scale: shown.scale, + } : {}), + ...(entity.transform?.ground !== undefined ? { on_ground: entity.transform.ground } : {}), + hidden: editor.hidden.has(id), + selected: editor.selection.has(id), + instances: editor.project.instancesOf(id).length, + }; +} + +function setSelection(editor, ids) { + editor.selection = new Set(ids); + for (const id of ids) editor.outliner.reveal(id); + editor.refresh(); + if (ids.length) editor.outliner.scrollTo(ids[ids.length - 1]); +} + +function setHidden(editor, id, hidden) { + const ids = [id, ...descendants(editor, id)]; + for (const each of ids) { + if (hidden) editor.hidden.add(each); else editor.hidden.delete(each); + for (const instance of editor.project.instancesOf(each)) editor.viewer.set_instance_hidden(instance, hidden); + } +} + +function descendants(editor, id) { + const out = []; + const visit = (entity) => (entity.children ?? []).forEach((c) => { out.push(c.id); visit(c); }); + visit(editor.project.entities.get(id)); + return out; +} + +function frameCamera(editor, ids) { + const list = ids.length ? ids : [...editor.selection]; + const spheres = list.map((id) => editor.project.bounds(id)).filter(Boolean); + if (!spheres.length) throw new CommandError("nothing_to_frame", "nothing selected to frame"); + const centre = [0, 1, 2].map((k) => spheres.reduce((s, b) => s + b.centre[k], 0) / spheres.length); + const radius = Math.max(0.5, ...spheres.map((b) => Math.hypot(...sub(b.centre, centre)) + b.radius)); + const camera = editor.camera(); + const distance = radius / Math.sin(Math.atan(camera.tanHalfFov)) * 1.1; + const position = sub(centre, scaleVector(camera.forward, distance)); + editor.viewer.set_camera(...position, camera.yaw, camera.pitch); + editor.input.pivot = centre; + return { position: position.map((v) => tidy(v, 0.001)), looking_at: centre.map((v) => tidy(v, 0.001)) }; +} + +function defineCommands(commands, editor) { + const id = { type: "string", required: true, description: "The entity's id, as scene.objects gives it." }; + commands.define("scene.info", { + description: "The scene's name, how many entities and instances it has, whether it can be saved, and the API's version.", + run: () => ({ + scene: sceneName, + api_version: API_VERSION, + entities: editor.project.entities.size, + instances: editor.viewer.instance_count(), + saveable: editor.project.saveable, + unsaved_changes: editor.dirty, + selection: [...editor.selection], + }), + }); + commands.define("scene.objects", { + description: "The scene's entities, parents before children: id, name, kind, parent, position, rotation (degrees), scale, and how many instances draw it. Paged.", + args: { + filter: { type: "string", description: "Only those whose name or id holds this text (any case)." }, + kind: { type: "string", description: "Only this kind: mesh, actor, light, blocker, wood, clear, path, yard, pond or folder." }, + offset: { type: "number", description: "Skip this many (default 0)." }, + limit: { type: "number", description: "At most this many (default 100, at most 1000)." }, + }, + example: { filter: "statue" }, + run: ({ filter, kind, offset = 0, limit = 100 }) => { + const query = filter?.toLowerCase(); + const all = [...editor.project.entities.keys()].filter((each) => { + const entity = editor.project.entities.get(each); + return (!query || entity.name.toLowerCase().includes(query) || each.toLowerCase().includes(query)) + && (!kind || kindOf(entity) === kind); + }); + const page = all.slice(Math.max(0, offset), Math.max(0, offset) + Math.min(1000, Math.max(1, limit))); + return { total: all.length, objects: page.map((each) => describe(editor, each)) }; + }, + }); + commands.define("object.get", { + description: "One entity: everything scene.objects gives, its note, and its components as the project holds them.", + args: { id }, + run: ({ id: which }) => { + const entity = needEntity(editor, which); + const { children, ...rest } = entity; + return { ...describe(editor, which), note: entity.note ?? "", entity: rest, children: (children ?? []).map((c) => c.id) }; + }, + }); + commands.define("object.set", { + description: "Sets an entity's fields: position, rotation (degrees about X, Y, Z), scale, name, note, or hidden (in the editor only).", + changes: true, + args: { + id, + position: { type: "vec3", description: "Where it is, in metres." }, + rotation: { type: "vec3", description: "Degrees about X, Y and Z: yaw about Y, then pitch, then roll." }, + scale: { type: "number", description: "Uniform scale, above 0." }, + name: { type: "string", description: "Its name in the outliner." }, + note: { type: "string", description: "What it is for." }, + hidden: { type: "boolean", description: "Hidden in the editor's viewport. Not saved." }, + }, + example: { id: "a91fXq2b", position: [-7, 0, 2] }, + run: (args) => { + const entity = needEntity(editor, args.id); + if (args.scale !== undefined && !(args.scale > 0)) throw new CommandError("bad_arguments", "scale must be above 0"); + const steps = []; + if (args.position || args.rotation || args.scale !== undefined) { + const shown = needTransform(editor, args.id); + const next = nextTransform(editor, args.id, { + position: args.position ?? shown.position, + rotation: args.rotation ?? shown.rotation, + scale: args.scale ?? shown.scale, + }); + steps.push(transformStep(editor, new Map([[args.id, next]]), "Transform")); + } + for (const field of ["name", "note"]) { + if (args[field] === undefined) continue; + const before = entity[field]; + const set = (value) => { + if (value === "" && field === "note") delete entity.note; else entity[field] = value; + editor.refresh(); + }; + set(args[field]); + steps.push({ label: `Rename`, undo: () => set(before ?? ""), redo: () => set(args[field]) }); + } + if (args.hidden !== undefined) { + setHidden(editor, args.id, args.hidden); + editor.refresh(); + } + const result = describe(editor, args.id); + if (!steps.length) return result; + const label = steps.length === 1 ? `${steps[0].label} ${entity.name}` : `Edit ${entity.name}`; + return { + result, + step: { label, undo: () => [...steps].reverse().forEach((s) => s.undo()), redo: () => steps.forEach((s) => s.redo()) }, + }; + }, + }); + const transformCommand = (name, description, args, example, make) => commands.define(name, { + description, changes: true, example, + args: { ids: { type: "string[]", description: "The entities to change; the selection if left out." }, ...args }, + run: (call) => { + const ids = call.ids ?? [...editor.selection]; + if (!ids.length) throw new CommandError("nothing_selected", `${name} needs ids, or something selected`); + const changes = new Map(); + for (const each of ids) changes.set(each, nextTransform(editor, each, make(needTransform(editor, each), call))); + const step = transformStep(editor, changes, `${name.split(".")[1][0].toUpperCase()}${name.split(".")[1].slice(1)} ${ids.length === 1 ? editor.project.entities.get(ids[0]).name : `${ids.length} things`}`); + return { result: ids.map((each) => describe(editor, each)), step }; + }, + }); + transformCommand("object.move", "Moves entities by an offset, or to a position, in metres.", { + by: { type: "vec3", description: "How far to move, in metres along X, Y and Z." }, + to: { type: "vec3", description: "Where to put them." }, + }, { ids: ["a91fXq2b"], by: [0, 0, 2] }, (shown, { by, to }) => { + if (!by === !to) throw new CommandError("bad_arguments", "object.move takes `by` or `to`"); + return { ...shown, position: to ?? add(shown.position, by) }; + }); + transformCommand("object.rotate", "Turns entities: `by` degrees about the world's X, Y and Z axes (applied in that order), or `to` a rotation.", { + by: { type: "vec3", description: "Degrees to turn about the world's X, then Y, then Z axis." }, + to: { type: "vec3", description: "The rotation to set: degrees about X, Y and Z, as object.set takes it." }, + }, { by: [0, 90, 0] }, (shown, { by, to }) => { + if (!by === !to) throw new CommandError("bad_arguments", "object.rotate takes `by` or `to`"); + if (to) return { ...shown, rotation: to }; + let columns = rotationColumns(shown.rotation); + [[1, 0, 0], [0, 1, 0], [0, 0, 1]].forEach((axis, k) => { + if (by[k]) columns = rotateColumns(columns, axis, by[k] * Math.PI / 180); + }); + return { ...shown, rotation: eulerFromColumns(columns) }; + }); + transformCommand("object.scale", "Scales entities evenly: `by` a factor, or `to` a scale.", { + by: { type: "number", description: "A factor, above 0." }, + to: { type: "number", description: "The scale to set, above 0." }, + }, { by: 1.5 }, (shown, { by, to }) => { + const value = to ?? (by === undefined ? undefined : shown.scale * by); + if (by !== undefined && to !== undefined) throw new CommandError("bad_arguments", "object.scale takes `by` or `to`"); + if (!(value > 0)) throw new CommandError("bad_arguments", "object.scale needs `by` or `to`, above 0"); + return { ...shown, scale: value }; + }); + commands.define("selection.get", { + description: "What is selected, as scene.objects describes it.", + run: () => [...editor.selection].map((each) => describe(editor, each)), + }); + commands.define("selection.set", { + description: "Selects entities by id (an empty list clears the selection), as clicking them does.", + args: { ids: { type: "string[]", required: true, description: "The entities to select." } }, + example: { ids: ["a91fXq2b"] }, + run: ({ ids }) => { + ids.forEach((each) => needEntity(editor, each)); + setSelection(editor, ids); + return [...editor.selection]; + }, + }); + commands.define("camera.get", { + description: "The viewport's camera: position, yaw and pitch (radians; yaw 0 looks along -Z), field of view (degrees) and fly speed (m/s).", + run: () => { + const camera = editor.camera(); + return { + position: camera.position.map((v) => tidy(v, 0.001)), + yaw: tidy(camera.yaw, 0.0001), + pitch: tidy(camera.pitch, 0.0001), + fov_y: tidy(2 * Math.atan(camera.tanHalfFov) * 180 / Math.PI, 0.01), + speed: editor.viewer.camera_speed(), + }; + }, + }); + commands.define("camera.set", { + description: "Moves the viewport's camera: a position, a yaw and pitch (radians), or a point to look at.", + args: { + position: { type: "vec3", description: "Where the camera is." }, + yaw: { type: "number", description: "Radians about Y; 0 looks along -Z." }, + pitch: { type: "number", description: "Radians above the horizon." }, + look_at: { type: "vec3", description: "A point to face, instead of yaw and pitch." }, + speed: { type: "number", description: "Fly speed, metres a second." }, + }, + example: { position: [40, 6, 20], look_at: [0, 2, 0] }, + run: ({ position, yaw, pitch, look_at: lookAt, speed }) => { + const camera = editor.camera(); + const at = position ?? camera.position; + let [y, p] = [yaw ?? camera.yaw, pitch ?? camera.pitch]; + if (lookAt) { + const d = normalize(sub(lookAt, at)); + y = Math.atan2(-d[0], -d[2]); + p = Math.asin(Math.max(-1, Math.min(1, d[1]))); + } + editor.viewer.set_camera(...at, y, Math.max(-1.5, Math.min(1.5, p))); + if (speed !== undefined) editor.viewer.set_camera_speed(speed); + return commands.call("camera.get").then((r) => r.result); + }, + }); + commands.define("camera.frame", { + description: "Moves the camera to see entities whole (the selection if no ids), as F does.", + args: { ids: { type: "string[]", description: "The entities to frame; the selection if left out." } }, + run: ({ ids = [] }) => { + ids.forEach((each) => needEntity(editor, each)); + return frameCamera(editor, ids); + }, + }); + commands.define("pick", { + description: "What is under a point of the viewport, given as fractions of its width and height from the top left: the entity (null for the land or sky), the instance and the point hit. Selects nothing.", + args: { + x: { type: "number", required: true, description: "0 at the left edge, 1 at the right." }, + y: { type: "number", required: true, description: "0 at the top, 1 at the bottom." }, + }, + example: { x: 0.5, y: 0.5 }, + run: ({ x, y }) => editor.pick(Math.min(1, Math.max(0, x)), Math.min(1, Math.max(0, y))), + }); + commands.define("history.undo", { + description: "Undoes the last change, by anyone.", + run: () => editor.commands.history.undo()?.label ?? null, + }); + commands.define("history.redo", { + description: "Redoes the last change undone.", + run: () => editor.commands.history.redo()?.label ?? null, + }); + commands.define("history.list", { + description: "The changes that can be undone (oldest first) and redone (next first), each with who made it: user or agent.", + run: () => editor.commands.history.list(), + }); + commands.define("env.set", { + description: "The time of day (hours, 0 to 24), the weather (by name, or `changing`), and the ponds (x0,z0,x1,z1,level; with ; between). Not saved yet.", + args: { + time: { type: "number", description: "Hours, 0 to 24." }, + weather: { type: "string", description: "changing, or a weather's name: env.weathers lists them." }, + ponds: { type: "string", description: "Ponds as x0,z0,x1,z1,level, with ; between them." }, + }, + example: { time: 18.5, weather: "fair" }, + run: ({ time, weather, ponds }) => { + if (time !== undefined) editor.viewer.set_time(((time % 24) + 24) % 24); + if (weather === "changing") editor.viewer.set_weather_changing(true, "fair"); + else if (weather !== undefined && !editor.viewer.set_weather(weather, 10)) { + throw new CommandError("bad_arguments", `no weather \`${weather}\`; env.weathers lists them`); + } + if (ponds !== undefined && !editor.viewer.set_ponds(ponds)) { + throw new CommandError("bad_arguments", "ponds couldn't be read: x0,z0,x1,z1,level with ; between"); + } + return { time: tidy(editor.viewer.time_of_day(), 0.01), weather: editor.viewer.weather_summary() }; + }, + }); + commands.define("env.weathers", { + description: "The names env.set takes for the weather.", + run: () => editor.viewer.constructor.weather_names().split(",").map((w) => w.trim()).filter(Boolean), + }); + commands.define("stats.frame", { + description: "How the viewport is drawing: frames a second, milliseconds a frame, triangles, clusters, instances, geometry pages, megabytes fetched, GPU errors and any fallbacks for this GPU.", + run: () => ({ + fps: tidy(editor.fps, 0.1), + frame_ms: tidy(editor.frameMs, 0.01), + frames: editor.frames, + triangles: editor.viewer.triangles(), + clusters: editor.viewer.clusters(), + instances: editor.viewer.instances(), + pages: `${editor.viewer.pages_installed()} of ${editor.viewer.pages_total()}`, + fetched_mb: tidy(editor.file.bytesFetched / 1e6, 0.1), + gpu_errors: editor.viewer.gpu_error_count(), + fallbacks: editor.viewer.fallbacks(), + }), + }); + commands.define("log.read", { + description: "The output log: the editor's messages, warnings and errors, each with a number; `since` gives only those after one.", + args: { + since: { type: "number", description: "Only entries numbered above this." }, + level: { type: "string", description: "Only info, warn or error." }, + }, + run: ({ since = 0, level }) => log.entries.filter((e) => e.seq > since && (!level || e.level === level)), + }); + commands.define("wait", { + description: "Resolves after some frames have been drawn, or once streaming has settled, so stats and screenshots show a finished frame.", + args: { + frames: { type: "number", description: "Frames to wait (default 2, at most 600)." }, + settled: { type: "boolean", description: "Wait until no geometry has arrived for half a second (at most 30 s)." }, + }, + run: async ({ frames = 2, settled = false }) => { + await editor.waitFrames(Math.min(600, Math.max(1, Math.round(frames)))); + if (settled) { + const until = performance.now() + 30000; + let last = -1; + while (performance.now() < until) { + const pages = editor.viewer.pages_installed(); + if (pages === last) break; + last = pages; + await new Promise((resolve) => setTimeout(resolve, 500)); + } + } + return { frames: editor.frames }; + }, + }); + commands.define("project.get", { + description: "The scene's project file as it would be saved, and whether it has changes not yet saved.", + run: () => ({ + saveable: editor.project.saveable, + unsaved_changes: editor.dirty, + file: `${sceneName}.scene`, + text: editor.project.saveable ? editor.project.toJson() : null, + }), + }); + commands.define("gizmo.set", { + description: "The gizmo: its mode (move, rotate, scale), its space (world, local), and snapping (on, and its steps).", + args: { + mode: { type: "string", description: "move, rotate or scale." }, + space: { type: "string", description: "world or local." }, + snap: { type: "boolean", description: "Whether drags snap." }, + move_step: { type: "number", description: "Metres a move snaps to." }, + angle_step: { type: "number", description: "Degrees a turn snaps to." }, + }, + run: ({ mode, space, snap, move_step: move, angle_step: angle }) => { + const gizmo = editor.gizmo; + if (mode !== undefined) { + if (!["move", "rotate", "scale"].includes(mode)) throw new CommandError("bad_arguments", "mode is move, rotate or scale"); + gizmo.mode = mode; + } + if (space !== undefined) { + if (!["world", "local"].includes(space)) throw new CommandError("bad_arguments", "space is world or local"); + gizmo.space = space; + } + if (snap !== undefined) gizmo.snap.on = snap; + if (move > 0) gizmo.snap.move = move; + if (angle > 0) gizmo.snap.angle = angle; + syncToolbar(editor); + return { mode: gizmo.mode, space: gizmo.space, snap: { ...gizmo.snap } }; + }, + }); +} + +// ---- Input: the viewport's mouse and keyboard. + +function bindInput(editor) { + const keys = new Set(); + const input = { + flying: false, + lookYaw: 0, + lookPitch: 0, + pivot: null, + axes: () => { + const axis = (plus, minus) => (keys.has(plus) ? 1 : 0) - (keys.has(minus) ? 1 : 0); + return [axis("KeyW", "KeyS"), axis("KeyD", "KeyA"), axis("KeyE", "KeyQ")]; + }, + fast: () => keys.has("ShiftLeft") || keys.has("ShiftRight"), + }; + editor.input = input; + const fraction = (e) => { + const box = overlay.getBoundingClientRect(); + return { x: e.clientX - box.left, y: e.clientY - box.top, fx: (e.clientX - box.left) / box.width, fy: (e.clientY - box.top) / box.height }; + }; + let drag = null; + + overlay.addEventListener("contextmenu", (e) => e.preventDefault()); + overlay.addEventListener("pointerdown", (e) => { + overlay.focus(); + const m = fraction(e); + const camera = editor.camera(); + overlay.setPointerCapture(e.pointerId); + if (e.button === 2) { + input.flying = true; + drag = { kind: "look", last: m }; + return; + } + if (e.button === 1 || (e.button === 0 && e.altKey)) { + const pivot = input.pivot ?? add(camera.position, scaleVector(camera.forward, 10)); + drag = { kind: e.button === 1 ? "pan" : "orbit", last: m, pivot }; + return; + } + if (e.button !== 0) return; + const primary = editor.primary(); + if (primary) { + const shown = editor.project.shownTransform(primary); + const handle = editor.gizmo.hit(shown, camera, m.x, m.y); + if (handle) { + const ray = rayThrough(camera.view, camera.projection, m.fx, m.fy); + const others = [...editor.selection].filter((id) => id !== primary && editor.project.shownTransform(id)); + const starts = new Map([primary, ...others].map((id) => [id, editor.project.shownTransform(id)])); + // Moved as motion while dragged, then static again, so cached shadows redraw once. + for (const id of starts.keys()) { + for (const instance of editor.project.instancesOf(id)) editor.viewer.set_instance_movable(instance, true); + } + drag = { kind: "gizmo", handle, primary, starts, update: editor.gizmo.drag(handle, shown, camera, ray, m), last: null }; + editor.gizmo.hover = handle; + return; + } + } + drag = { kind: "click", start: m, additive: e.ctrlKey || e.metaKey || e.shiftKey }; + }); + overlay.addEventListener("pointermove", (e) => { + const m = fraction(e); + if (!drag) { + const primary = editor.primary(); + editor.gizmo.hover = primary + ? editor.gizmo.hit(editor.project.shownTransform(primary), editor.camera(), m.x, m.y) + : null; + overlay.style.cursor = editor.gizmo.hover ? "grab" : "default"; + return; + } + if (drag.kind === "look") { + input.lookYaw -= (m.x - drag.last.x) * 0.003; + input.lookPitch -= (m.y - drag.last.y) * 0.003; + drag.last = m; + } else if (drag.kind === "orbit" || drag.kind === "pan") { + const camera = editor.camera(); + const [dx, dy] = [m.x - drag.last.x, m.y - drag.last.y]; + drag.last = m; + if (drag.kind === "orbit") { + const distance = Math.hypot(...sub(camera.position, drag.pivot)); + const yaw = camera.yaw - dx * 0.006; + const pitch = Math.max(-1.5, Math.min(1.5, camera.pitch - dy * 0.006)); + const forward = [-Math.sin(yaw) * Math.cos(pitch), Math.sin(pitch), -Math.cos(yaw) * Math.cos(pitch)]; + editor.viewer.set_camera(...sub(drag.pivot, scaleVector(forward, distance)), yaw, pitch); + } else { + const distance = Math.max(1, dot(sub(drag.pivot, camera.position), camera.forward)); + const perPixel = (distance * camera.tanHalfFov * 2) / camera.cssHeight; + const right = [Math.cos(camera.yaw), 0, -Math.sin(camera.yaw)]; + const up = normalize(subCross(right, camera.forward)); + const move = add(scaleVector(right, -dx * perPixel), scaleVector(up, dy * perPixel)); + editor.viewer.set_camera(...add(camera.position, move), camera.yaw, camera.pitch); + drag.pivot = add(drag.pivot, move); + input.pivot = drag.pivot; + } + } else if (drag.kind === "gizmo") { + const camera = editor.camera(); + const ray = rayThrough(camera.view, camera.projection, m.fx, m.fy); + // Ctrl inverts snapping while held, as in both editors. + const { change } = drag.update(ray, !(e.ctrlKey || e.metaKey), m); + drag.last = change; + for (const [id, start] of drag.starts) editor.preview(id, applyChange(start, change)); + } + }); + const finish = async (e) => { + const was = drag; + drag = null; + input.flying = false; + if (!was) return; + if (was.kind === "gizmo") { + const changes = new Map(); + if (was.last) { + for (const [id, start] of was.starts) changes.set(id, nextTransform(editor, id, applyChange(start, was.last))); + } + const unchanged = [...changes].every(([id, t]) => + JSON.stringify(t) === JSON.stringify(nextTransform(editor, id, was.starts.get(id)))); + if (changes.size && !unchanged) { + const label = `${editor.gizmo.mode[0].toUpperCase()}${editor.gizmo.mode.slice(1)} ${changes.size === 1 ? editor.project.entities.get(was.primary).name : `${changes.size} things`}`; + editor.commands.history.push({ ...transformStep(editor, changes, label), by: "user" }); + } else { + editor.endPreviews(); + } + for (const id of was.starts.keys()) { + for (const instance of editor.project.instancesOf(id)) editor.viewer.set_instance_movable(instance, false); + } + return; + } + if (was.kind === "click" && e) { + const m = fraction(e); + if (Math.hypot(m.x - was.start.x, m.y - was.start.y) > 4) return; + // Markers first: lights and the like, which draw nothing to pick. + const marker = editor.markers(editor.camera()).find((k) => Math.hypot(k.x - m.x, k.y - m.y) < 8); + const found = marker ? { id: marker.id } : await editor.pick(m.fx, m.fy); + const ids = found.id + ? (was.additive + ? (editor.selection.has(found.id) ? [...editor.selection].filter((x) => x !== found.id) : [...editor.selection, found.id]) + : [found.id]) + : (was.additive ? [...editor.selection] : []); + editor.call("selection.set", { ids }); + if (found.id) input.pivot = editor.project.bounds(found.id)?.centre ?? null; + } + }; + overlay.addEventListener("pointerup", finish); + overlay.addEventListener("pointercancel", () => finish(null)); + overlay.addEventListener("wheel", (e) => { + e.preventDefault(); + if (input.flying) { + // As in Unreal: the wheel while looking sets how fast the camera flies. + const speed = editor.viewer.camera_speed() * (e.deltaY < 0 ? 1.25 : 0.8); + editor.viewer.set_camera_speed(Math.max(0.5, Math.min(500, speed))); + el("hint").textContent = `Fly speed ${editor.viewer.camera_speed().toFixed(1)} m/s`; + return; + } + const camera = editor.camera(); + const distance = input.pivot ? Math.max(1, Math.hypot(...sub(input.pivot, camera.position))) : 10; + const step = Math.sign(-e.deltaY) * Math.max(0.25, distance * 0.12); + editor.viewer.set_camera(...add(camera.position, scaleVector(camera.forward, step)), camera.yaw, camera.pitch); + }, { passive: false }); + + const typing = (e) => /^(INPUT|SELECT|TEXTAREA)$/.test(e.target.tagName); + addEventListener("keydown", (e) => { + if (typing(e)) return; + keys.add(e.code); + if (input.flying) return; + const ctrl = e.ctrlKey || e.metaKey; + // Nothing is undone under a drag: its previews stand on what is there now. + if (ctrl && drag && /^Key[ZY]$/.test(e.code)) { + e.preventDefault(); + } else if (ctrl && e.code === "KeyZ") { + e.preventDefault(); + editor.call(e.shiftKey ? "history.redo" : "history.undo"); + } else if (ctrl && e.code === "KeyY") { + e.preventDefault(); + editor.call("history.redo"); + } else if (ctrl && e.code === "KeyS") { + e.preventDefault(); + save(editor); + } else if (!ctrl && e.code === "KeyW") editor.call("gizmo.set", { mode: "move" }); + else if (!ctrl && e.code === "KeyE") editor.call("gizmo.set", { mode: "rotate" }); + else if (!ctrl && e.code === "KeyR") editor.call("gizmo.set", { mode: "scale" }); + else if (e.code === "Space" && !ctrl) { + e.preventDefault(); + const modes = ["move", "rotate", "scale"]; + editor.call("gizmo.set", { mode: modes[(modes.indexOf(editor.gizmo.mode) + 1) % 3] }); + } else if (e.code === "KeyF" && !ctrl) editor.call("camera.frame", {}); + else if (e.code === "Escape") editor.call("selection.set", { ids: [] }); + }); + addEventListener("keyup", (e) => keys.delete(e.code)); + addEventListener("blur", () => keys.clear()); + + new ResizeObserver(() => { + const [width, height] = editor.resize(); + if (width !== canvas.width || height !== canvas.height) { + [canvas.width, canvas.height] = [width, height]; + editor.viewer.resize(width, height); + } + }).observe(canvas); +} + +/// The camera's up: right × forward, for panning. +function subCross(right, forward) { + return [ + right[1] * forward[2] - right[2] * forward[1], + right[2] * forward[0] - right[0] * forward[2], + right[0] * forward[1] - right[1] * forward[0], + ]; +} + +// ---- The toolbar. + +function syncToolbar(editor) { + for (const mode of ["move", "rotate", "scale"]) { + el(`mode-${mode}`).setAttribute("aria-pressed", String(editor.gizmo.mode === mode)); + } + el("space").textContent = editor.gizmo.space === "world" ? "World" : "Local"; + el("snap").setAttribute("aria-pressed", String(editor.gizmo.snap.on)); + el("snap-move").value = String(editor.gizmo.snap.move); + el("snap-angle").value = String(editor.gizmo.snap.angle); +} + +function bindToolbar(editor) { + el("undo").addEventListener("click", () => editor.call("history.undo")); + el("redo").addEventListener("click", () => editor.call("history.redo")); + el("save").addEventListener("click", () => save(editor)); + for (const mode of ["move", "rotate", "scale"]) { + el(`mode-${mode}`).addEventListener("click", () => editor.call("gizmo.set", { mode })); + } + el("space").addEventListener("click", () => + editor.call("gizmo.set", { space: editor.gizmo.space === "world" ? "local" : "world" })); + el("snap").addEventListener("click", () => editor.call("gizmo.set", { snap: !editor.gizmo.snap.on })); + el("snap-move").addEventListener("change", (e) => editor.call("gizmo.set", { move_step: Number(e.target.value) })); + el("snap-angle").addEventListener("change", (e) => editor.call("gizmo.set", { angle_step: Number(e.target.value) })); + el("frame").addEventListener("click", () => editor.call("camera.frame", {})); + el("view-scene").href = `./?scene=${encodeURIComponent(sceneName)}`; + el("undo").disabled = true; + el("redo").disabled = true; + syncToolbar(editor); +} + +// ---- Saving: to the browser as you go, and to a file when asked. + +const DRAFT = `${sceneName}.scene`; + +async function draftDirectory() { + const root = await navigator.storage?.getDirectory?.(); + return root ? root.getDirectoryHandle("drafts", { create: true }) : null; +} + +let autosaveTimer = null; +function scheduleAutosave(editor) { + if (!editor.project.saveable) return; + clearTimeout(autosaveTimer); + autosaveTimer = setTimeout(async () => { + try { + const folder = await draftDirectory(); + if (!folder) return; + const writable = await (await folder.getFileHandle(DRAFT, { create: true })).createWritable(); + await writable.write(editor.project.toJson()); + await writable.close(); + el("hint").textContent = "Draft kept in this browser"; + } catch (error) { + log.add("warn", `Couldn't keep a draft in this browser: ${error.message ?? error}`); + } + }, 800); +} + +/// Offers to bring back a draft left from an earlier visit, if it differs from the scene served. +async function offerDraft(editor) { + if (!editor.project.saveable) return; + try { + const folder = await draftDirectory(); + const text = await (await (await folder?.getFileHandle(DRAFT))?.getFile())?.text(); + if (!text || text === editor.project.toJson()) return; + const draft = JSON.parse(text); + el("draft").hidden = false; + el("draft-restore").onclick = () => { + el("draft").hidden = true; + const changes = new Map(); + const texts = []; + const visit = (list) => list.forEach((entity) => { + const now = editor.project.entities.get(entity.id); + if (!now) return; + if (entity.transform && now.transform + && JSON.stringify(entity.transform) !== JSON.stringify(now.transform)) { + changes.set(entity.id, entity.transform); + } + for (const field of ["name", "note"]) { + if ((entity[field] ?? "") !== (now[field] ?? "")) texts.push([now, field, now[field], entity[field]]); + } + visit(entity.children ?? []); + }); + visit(draft.entities ?? []); + const setText = (entity, field, value) => { + if (value === undefined || (field === "note" && value === "")) delete entity[field]; + else entity[field] = value; + }; + texts.forEach(([entity, field, , after]) => setText(entity, field, after)); + const moved = changes.size ? transformStep(editor, changes, "") : null; + if (moved || texts.length) { + editor.commands.history.push({ + label: `Restore draft (${changes.size + texts.length} changes)`, + by: "user", + undo: () => { + moved?.undo(); + texts.forEach(([entity, field, before]) => setText(entity, field, before)); + editor.refresh(); + }, + redo: () => { + moved?.redo(); + texts.forEach(([entity, field, , after]) => setText(entity, field, after)); + editor.refresh(); + }, + }); + } + log.add("info", `Restored the draft: ${changes.size} moved, ${texts.length} renamed or noted.`); + }; + el("draft-discard").onclick = async () => { + el("draft").hidden = true; + await folder.removeEntry(DRAFT).catch(() => {}); + }; + } catch { /* no draft */ } +} + +let fileHandle = null; +async function save(editor) { + if (!editor.project.saveable) return; + const text = editor.project.toJson(); + try { + if (window.showSaveFilePicker) { + fileHandle ??= await window.showSaveFilePicker({ + suggestedName: `${sceneName}.scene`, + types: [{ description: "Solstice scene", accept: { "application/json": [".scene"] } }], + }); + const writable = await fileHandle.createWritable(); + await writable.write(text); + await writable.close(); + } else { + const link = Object.assign(document.createElement("a"), { + href: URL.createObjectURL(new Blob([text], { type: "application/json" })), + download: `${sceneName}.scene`, + }); + link.click(); + URL.revokeObjectURL(link.href); + } + editor.dirty = false; + editor.refresh(); + log.add("info", `Saved ${sceneName}.scene`); + } catch (error) { + if (error.name !== "AbortError") log.add("error", `Couldn't save: ${error.message ?? error}`); + } +} + +// ---- The API for agents. + +function exposeApi(editor) { + const api = { + version: API_VERSION, + /// Runs a command: `await solstice.call("object.move", { id, by: [0, 0, 2] })`. + call: (name, args) => editor.commands.call(name, args, "agent"), + /// Every command with its arguments as JSON Schema, or one by name. + help: (name) => editor.commands.help(name), + /// The commands' names. + list: () => editor.commands.help().map((c) => c.name), + }; + Object.defineProperty(window, "solstice", { value: Object.freeze(api), configurable: true }); + log.add("info", "Agents: window.solstice.help() lists the editor's commands."); + registerWebMcp(editor); +} + +/// Where the browser offers WebMCP (https://github.com/webmachinelearning/webmcp), each command +/// is a tool an agent sees by name, with the same description and arguments. Tool names can't +/// hold dots, so `object.move` is `object_move`. +function registerWebMcp(editor) { + const context = navigator.modelContext; + if (!context) return; + const tools = editor.commands.help().map((command) => ({ + name: command.name.replace(/\./g, "_"), + description: command.description, + inputSchema: command.arguments, + async execute(args) { + const outcome = await editor.commands.call(command.name, args ?? {}, "agent"); + return { content: [{ type: "text", text: JSON.stringify(outcome) }], isError: !outcome.ok }; + }, + })); + try { + if (typeof context.provideContext === "function") context.provideContext({ tools }); + else for (const tool of tools) context.registerTool(tool); + log.add("info", `WebMCP: the editor's ${tools.length} commands are tools.`); + } catch (error) { + log.add("warn", `WebMCP is here but refused the editor's tools: ${error.message ?? error}`); + } +} + +main().catch((error) => fail(`The editor couldn't start: ${error.message ?? error}`)); diff --git a/apps/viewer/web/editor/math.js b/apps/viewer/web/editor/math.js new file mode 100644 index 0000000..de5ca02 --- /dev/null +++ b/apps/viewer/web/editor/math.js @@ -0,0 +1,198 @@ +// Small vector and matrix helpers for the editor. Matrices are 16 numbers by column, as glam and +// WGSL keep them, so they pass to and from the viewer unchanged. + +export const DEG = Math.PI / 180; + +export const add = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]]; +export const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]]; +export const scale = (a, s) => [a[0] * s, a[1] * s, a[2] * s]; +export const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2]; +export const cross = (a, b) => [ + a[1] * b[2] - a[2] * b[1], + a[2] * b[0] - a[0] * b[2], + a[0] * b[1] - a[1] * b[0], +]; +export const length = (a) => Math.hypot(a[0], a[1], a[2]); +export const normalize = (a) => { + const l = length(a) || 1; + return [a[0] / l, a[1] / l, a[2] / l]; +}; + +export function multiply(a, b) { + const out = new Array(16); + for (let c = 0; c < 4; c++) { + for (let r = 0; r < 4; r++) { + out[c * 4 + r] = a[r] * b[c * 4] + a[4 + r] * b[c * 4 + 1] + a[8 + r] * b[c * 4 + 2] + + a[12 + r] * b[c * 4 + 3]; + } + } + return out; +} + +export function invert(m) { + const [a00, a01, a02, a03, a10, a11, a12, a13, a20, a21, a22, a23, a30, a31, a32, a33] = m; + const b00 = a00 * a11 - a01 * a10; + const b01 = a00 * a12 - a02 * a10; + const b02 = a00 * a13 - a03 * a10; + const b03 = a01 * a12 - a02 * a11; + const b04 = a01 * a13 - a03 * a11; + const b05 = a02 * a13 - a03 * a12; + const b06 = a20 * a31 - a21 * a30; + const b07 = a20 * a32 - a22 * a30; + const b08 = a20 * a33 - a23 * a30; + const b09 = a21 * a32 - a22 * a31; + const b10 = a21 * a33 - a23 * a31; + const b11 = a22 * a33 - a23 * a32; + const det = b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06; + if (!det) return null; + const d = 1 / det; + return [ + (a11 * b11 - a12 * b10 + a13 * b09) * d, + (a02 * b10 - a01 * b11 - a03 * b09) * d, + (a31 * b05 - a32 * b04 + a33 * b03) * d, + (a22 * b04 - a21 * b05 - a23 * b03) * d, + (a12 * b08 - a10 * b11 - a13 * b07) * d, + (a00 * b11 - a02 * b08 + a03 * b07) * d, + (a32 * b02 - a30 * b05 - a33 * b01) * d, + (a20 * b05 - a22 * b02 + a23 * b01) * d, + (a10 * b10 - a11 * b08 + a13 * b06) * d, + (a01 * b08 - a00 * b10 - a03 * b06) * d, + (a30 * b04 - a31 * b02 + a33 * b00) * d, + (a21 * b02 - a20 * b04 - a23 * b00) * d, + (a11 * b07 - a10 * b09 - a12 * b06) * d, + (a00 * b09 - a01 * b07 + a02 * b06) * d, + (a31 * b01 - a30 * b03 - a32 * b00) * d, + (a20 * b03 - a21 * b01 + a22 * b00) * d, + ]; +} + +export const transformPoint = (m, p) => { + const w = m[3] * p[0] + m[7] * p[1] + m[11] * p[2] + m[15]; + return [ + (m[0] * p[0] + m[4] * p[1] + m[8] * p[2] + m[12]) / w, + (m[1] * p[0] + m[5] * p[1] + m[9] * p[2] + m[13]) / w, + (m[2] * p[0] + m[6] * p[1] + m[10] * p[2] + m[14]) / w, + ]; +}; + +/// A rotation's 3x3 as columns, from degrees about X, Y and Z applied as the bake applies them: +/// yaw about Y, then pitch about the turned X, then roll about the turned Z (R = Ry Rx Rz). +export function rotationColumns([x, y, z]) { + const [sx, cx] = [Math.sin(x * DEG), Math.cos(x * DEG)]; + const [sy, cy] = [Math.sin(y * DEG), Math.cos(y * DEG)]; + const [sz, cz] = [Math.sin(z * DEG), Math.cos(z * DEG)]; + // Rows of Ry * Rx * Rz. + const m00 = cy * cz + sy * sx * sz; + const m01 = -cy * sz + sy * sx * cz; + const m02 = sy * cx; + const m10 = cx * sz; + const m11 = cx * cz; + const m12 = -sx; + const m20 = -sy * cz + cy * sx * sz; + const m21 = sy * sz + cy * sx * cz; + const m22 = cy * cx; + return [[m00, m10, m20], [m01, m11, m21], [m02, m12, m22]]; +} + +/// Degrees about X, Y and Z (as `rotationColumns` takes them) of a rotation given as columns. +export function eulerFromColumns(columns) { + const [[m00, m10, m20], [m01, m11, m21], [m02, m12, m22]] = columns; + const x = Math.asin(Math.max(-1, Math.min(1, -m12))); + let y; + let z; + if (Math.abs(m12) < 0.99999) { + y = Math.atan2(m02, m22); + z = Math.atan2(m10, m11); + } else { + // Looking straight up or down: yaw and roll turn about the same axis, so roll takes none. + y = Math.atan2(-m20, m00); + z = 0; + } + return [x / DEG, y / DEG, z / DEG]; +} + +/// The matrix of a project transform: `{ position, rotation, scale }`. +export function transformMatrix({ position, rotation = [0, 0, 0], scale: s = 1 }) { + const [c0, c1, c2] = rotationColumns(rotation); + return [ + c0[0] * s, c0[1] * s, c0[2] * s, 0, + c1[0] * s, c1[1] * s, c1[2] * s, 0, + c2[0] * s, c2[1] * s, c2[2] * s, 0, + position[0], position[1], position[2], 1, + ]; +} + +/// Rotates columns about a unit axis by `angle` radians: the axis-angle matrix times them. +export function rotateColumns(columns, axis, angle) { + const [x, y, z] = axis; + const c = Math.cos(angle); + const s = Math.sin(angle); + const t = 1 - c; + const r = [ + [t * x * x + c, t * x * y + s * z, t * x * z - s * y], + [t * x * y - s * z, t * y * y + c, t * y * z + s * x], + [t * x * z + s * y, t * y * z - s * x, t * z * z + c], + ]; + return columns.map((v) => [ + r[0][0] * v[0] + r[1][0] * v[1] + r[2][0] * v[2], + r[0][1] * v[0] + r[1][1] * v[1] + r[2][1] * v[2], + r[0][2] * v[0] + r[1][2] * v[1] + r[2][2] * v[2], + ]); +} + +/// Rounds a number for the project file, so edits leave tidy numbers: `step` apart, and no -0. +export function tidy(value, step) { + const rounded = Math.round(value / step) * step; + // Clears the binary noise a multiple of a step like 0.001 carries. + const out = Number(rounded.toFixed(Math.max(0, Math.ceil(-Math.log10(step)) + 1))); + return Object.is(out, -0) ? 0 : out; +} + +/// Turns a rotation's degrees into the range (-180, 180], tidied. +export function tidyAngles(angles) { + return angles.map((a) => { + let d = ((a % 360) + 360) % 360; + if (d > 180) d -= 360; + return tidy(d, 0.001); + }); +} + +/// A ray from the camera through a point of the canvas, given as fractions of its size. +export function rayThrough(view, projection, fx, fy) { + const inverse = invert(multiply(projection, view)); + const ndcX = fx * 2 - 1; + const ndcY = 1 - fy * 2; + // Reversed depth: 1 is the near plane, and smaller is farther. + const near = transformPoint(inverse, [ndcX, ndcY, 1]); + const far = transformPoint(inverse, [ndcX, ndcY, 0.001]); + return { origin: near, direction: normalize(sub(far, near)) }; +} + +/// Where a point of the world lands on the canvas, in pixels, and whether it is in front. +export function projectToScreen(viewProjection, point, width, height) { + const m = viewProjection; + const x = m[0] * point[0] + m[4] * point[1] + m[8] * point[2] + m[12]; + const y = m[1] * point[0] + m[5] * point[1] + m[9] * point[2] + m[13]; + const w = m[3] * point[0] + m[7] * point[1] + m[11] * point[2] + m[15]; + return { x: (x / w * 0.5 + 0.5) * width, y: (0.5 - y / w * 0.5) * height, front: w > 1e-4 }; +} + +/// The nearest point on a line (through `origin`, along unit `axis`) to a ray: how far along the +/// line it is, or null where the two are nearly parallel. +export function closestAlongLine(origin, axis, ray) { + const w = sub(origin, ray.origin); + const b = dot(axis, ray.direction); + const d = dot(axis, w); + const e = dot(ray.direction, w); + const denominator = 1 - b * b; + if (denominator < 1e-6) return null; + return (b * e - d) / denominator; +} + +/// Where a ray meets a plane through `point` with unit `normal`, or null if it doesn't. +export function rayPlane(ray, point, normal) { + const denominator = dot(ray.direction, normal); + if (Math.abs(denominator) < 1e-6) return null; + const t = dot(sub(point, ray.origin), normal) / denominator; + return t < 0 ? null : add(ray.origin, scale(ray.direction, t)); +} diff --git a/apps/viewer/web/editor/panels.js b/apps/viewer/web/editor/panels.js new file mode 100644 index 0000000..ddb6106 --- /dev/null +++ b/apps/viewer/web/editor/panels.js @@ -0,0 +1,242 @@ +// The outliner (the scene's entities as a tree) and the details panel (the selected entity's +// fields), as plain DOM. Both only show the editor's state and send commands; neither changes +// anything itself. + +import { kindOf } from "./project.js"; + +const ICONS = { + folder: "▤", mesh: "◆", actor: "●", light: "✦", blocker: "▭", wood: "♣", clear: "○", + path: "┅", yard: "▦", pond: "≈", +}; + +const make = (tag, props = {}, children = []) => { + const node = Object.assign(document.createElement(tag), props); + for (const child of children) node.append(child); + return node; +}; + +export class Outliner { + #root; + #search; + #rows = new Map(); + #collapsed = new Set(); + + /// `editor` gives `project`, `selection`, `call(name, args)` and `hidden` (a set of ids). + constructor(element, editor) { + this.editor = editor; + this.#search = make("input", { + type: "search", placeholder: "Search", className: "search", ariaLabel: "Search the outliner", + }); + this.#search.addEventListener("input", () => this.render()); + this.#root = make("div", { className: "tree", role: "tree" }); + element.append(this.#search, this.#root); + } + + /// Opens the folders holding `id`, so it can be seen. + reveal(id) { + for (const parent of this.editor.project.ancestors(id)) this.#collapsed.delete(parent); + } + + render() { + const { project, selection } = this.editor; + const query = this.#search.value.trim().toLowerCase(); + const matches = (entity) => !query || entity.name.toLowerCase().includes(query) + || entity.id.toLowerCase().includes(query) + || (entity.children ?? []).some(matches); + this.#root.replaceChildren(); + this.#rows.clear(); + const fragment = document.createDocumentFragment(); + const visit = (list, depth) => { + for (const entity of list) { + if (!matches(entity)) continue; + const kind = kindOf(entity); + const open = query || !this.#collapsed.has(entity.id); + const hasChildren = (entity.children ?? []).length > 0; + const row = make("div", { + className: `row${selection.has(entity.id) ? " selected" : ""}`, + role: "treeitem", + ariaSelected: String(selection.has(entity.id)), + title: entity.note || entity.name, + }); + row.dataset.id = entity.id; + row.style.paddingLeft = `${6 + depth * 14}px`; + const twisty = make("span", { + className: "twisty", + textContent: hasChildren ? (open ? "▾" : "▸") : "", + }); + twisty.addEventListener("click", (e) => { + e.stopPropagation(); + if (this.#collapsed.has(entity.id)) this.#collapsed.delete(entity.id); + else this.#collapsed.add(entity.id); + this.render(); + }); + const icon = make("span", { className: `icon ${kind}`, textContent: ICONS[kind] ?? "·" }); + const label = make("span", { className: "label", textContent: entity.name }); + const hidden = this.editor.hidden.has(entity.id); + const eye = make("button", { + className: `eye${hidden ? " off" : ""}`, + textContent: hidden ? "◌" : "◉", + title: hidden ? "Show" : "Hide", + ariaLabel: `${hidden ? "Show" : "Hide"} ${entity.name}`, + }); + eye.addEventListener("click", (e) => { + e.stopPropagation(); + this.editor.call("object.set", { id: entity.id, hidden: !hidden }); + }); + row.append(twisty, icon, label, eye); + row.addEventListener("click", (e) => { + const ids = e.ctrlKey || e.metaKey + ? (selection.has(entity.id) + ? [...selection].filter((id) => id !== entity.id) + : [...selection, entity.id]) + : [entity.id]; + this.editor.call("selection.set", { ids }); + }); + row.addEventListener("dblclick", () => this.editor.call("camera.frame", { ids: [entity.id] })); + fragment.append(row); + this.#rows.set(entity.id, row); + if (hasChildren && open) visit(entity.children, depth + 1); + } + }; + visit(project.scene.entities, 0); + this.#root.append(fragment); + } + + scrollTo(id) { + this.#rows.get(id)?.scrollIntoView({ block: "nearest" }); + } +} + +/// A number field whose label drags to change it, as both editors' are. +function numberField(label, value, step, onChange, onScrub) { + const input = make("input", { type: "number", value: String(value), step: String(step) }); + input.addEventListener("change", () => { + const v = Number(input.value); + if (Number.isFinite(v)) onChange(v); + }); + input.addEventListener("keydown", (e) => { + if (e.key === "Enter") input.blur(); + e.stopPropagation(); + }); + const name = make("span", { className: `axis ${label.toLowerCase()}`, textContent: label }); + name.addEventListener("pointerdown", (e) => { + const start = Number(input.value); + const x0 = e.clientX; + name.setPointerCapture(e.pointerId); + let last = start; + const move = (m) => { + const fine = m.shiftKey ? 0.1 : 1; + last = Number((start + Math.round((m.clientX - x0) * fine) * step).toFixed(6)); + input.value = String(last); + onScrub(last); + }; + const up = () => { + name.removeEventListener("pointermove", move); + name.removeEventListener("pointerup", up); + if (last !== start) onChange(last, start); + }; + name.addEventListener("pointermove", move); + name.addEventListener("pointerup", up); + }); + return make("label", { className: "number" }, [name, input]); +} + +export class Details { + #element; + + constructor(element, editor) { + this.#element = element; + this.editor = editor; + } + + render() { + const { project, selection } = this.editor; + const ids = [...selection]; + this.#element.replaceChildren(); + if (ids.length === 0) { + this.#element.append(make("p", { className: "empty", textContent: "Select something to see its details." })); + return; + } + if (ids.length > 1) { + this.#element.append(make("p", { className: "empty", textContent: `${ids.length} selected` })); + return; + } + const id = ids[0]; + const entity = project.entities.get(id); + if (!entity) return; + const section = (title, rows) => make("details", { open: true }, [make("summary", { textContent: title }), ...rows]); + const row = (label, value) => make("div", { className: "field" }, [ + make("span", { className: "name", textContent: label }), value, + ]); + const text = (value, onChange, readOnly = false) => { + const input = make("input", { type: "text", value: value ?? "", readOnly }); + input.addEventListener("change", () => onChange(input.value)); + input.addEventListener("keydown", (e) => { + if (e.key === "Enter") input.blur(); + e.stopPropagation(); + }); + return input; + }; + const general = [ + row("Name", text(entity.name, (name) => this.editor.call("object.set", { id, name }))), + row("Id", text(entity.id, () => {}, true)), + row("Kind", make("span", { textContent: kindOf(entity) })), + ]; + if (entity.note !== undefined || project.saveable) { + const note = make("textarea", { value: entity.note ?? "", rows: 2 }); + note.addEventListener("change", () => this.editor.call("object.set", { id, note: note.value })); + note.addEventListener("keydown", (e) => e.stopPropagation()); + general.push(row("Note", note)); + } + this.#element.append(section("General", general)); + + const shown = project.shownTransform(id); + if (shown) { + const vector = (label, key, step) => { + const fields = [0, 1, 2].map((k) => numberField("XYZ"[k], shown[key][k], step, + (value) => { + const next = [...shown[key]]; + next[k] = value; + this.editor.call("object.set", { id, [key]: next }); + }, + (value) => { + const next = [...shown[key]]; + next[k] = value; + this.editor.preview(id, { ...shown, [key]: next }); + })); + return row(label, make("div", { className: "vector" }, fields)); + }; + const rows = [ + vector("Location", "position", 0.01), + vector("Rotation", "rotation", 0.1), + row("Scale", numberField("S", shown.scale, 0.01, + (scale) => this.editor.call("object.set", { id, scale }), + (scale) => this.editor.preview(id, { ...shown, scale }))), + ]; + if (shown.ground !== undefined) { + rows.push(row("On ground", make("span", { + className: "hint", + textContent: `${shown.ground} sunk; moving it keeps its height instead`, + }))); + } + this.#element.append(section("Transform", rows)); + } + + const kind = kindOf(entity); + if (kind !== "folder") { + const component = entity[kind]; + const rows = Object.entries(component).map(([key, value]) => row(key, + make("span", { + className: "value", + textContent: typeof value === "object" ? JSON.stringify(value) : String(value), + }))); + this.#element.append(section(kind[0].toUpperCase() + kind.slice(1), rows)); + } + const drawn = project.instancesOf(id); + if (drawn.length) { + this.#element.append(section("Drawn by", [row("Instances", make("span", { + textContent: drawn.length === 1 ? `#${drawn[0]}` : `#${drawn[0]} to #${drawn[drawn.length - 1]}`, + }))])); + } + } +} diff --git a/apps/viewer/web/editor/project.js b/apps/viewer/web/editor/project.js new file mode 100644 index 0000000..a974e2f --- /dev/null +++ b/apps/viewer/web/editor/project.js @@ -0,0 +1,320 @@ +// The editor's document: a project's scene (docs/editor.md, `crates/solstice-project`), and how +// each of its entities is drawn by the viewer's instances, from the scene file's map of which +// entity made which. + +import { invert, multiply, transformMatrix } from "./math.js"; + +/// Each kind of thing an entity can be, as the project's components name them. +export const KINDS = ["mesh", "actor", "light", "blocker", "wood", "clear", "path", "yard", "pond"]; + +/// What an entity is, for its icon and label: one of `KINDS`, or "folder". +export const kindOf = (entity) => KINDS.find((kind) => entity[kind]) ?? "folder"; + +/// Ids the map gives to what the land makes, which no entity has. +const LAND_IDS = new Set(["terrain", "circuit"]); + +export class Project { + /// The scene as read, edited in place. + scene; + /// Every entity by id. + entities = new Map(); + /// Each entity's parent's id, or null at the top. + parents = new Map(); + /// Each mapped entity's instances, and each instance's place relative to the entity. + #drawn = new Map(); + /// Mapped ranges sorted by their first instance, for finding what an instance belongs to. + #ranges = []; + /// Instances of the land, which select nothing. + #land = []; + + /// `scene` is the parsed `.scene` file, or null for a scene with no project: then each + /// instance is an entity of its own, which can be moved but not saved. + constructor(scene, viewer) { + this.viewer = viewer; + this.scene = scene ?? { format: 1, entities: syntheticEntities(viewer) }; + this.saveable = Boolean(scene); + const visit = (list, parent) => { + for (const entity of list) { + this.entities.set(entity.id, entity); + this.parents.set(entity.id, parent); + visit(entity.children ?? [], entity.id); + } + }; + visit(this.scene.entities ?? (this.scene.entities = []), null); + if (scene) this.#mapFromScene(); + else this.#mapOneToOne(); + } + + #mapFromScene() { + const ids = this.viewer.source_ids().split("\n").filter(Boolean); + const ranges = this.viewer.source_ranges(); + const placements = this.viewer.source_placements(); + ids.forEach((id, k) => { + const [first, end] = [ranges[k * 2], ranges[k * 2 + 1]]; + if (LAND_IDS.has(id)) { + this.#land.push([first, end]); + return; + } + const entity = this.entities.get(id); + if (!entity?.transform) return; + const placement = Array.from(placements.slice(k * 16, k * 16 + 16)); + // A model seated on the ground was placed at a height the bake worked out, which the + // project leaves out: the editor shows it, and saves it once the model is moved. + if (entity.transform.ground !== undefined) { + this.bakedHeights.set(id, placement[13]); + } + this.#attach(id, first, end); + }); + } + + #mapOneToOne() { + for (const entity of this.scene.entities) { + this.#attach(entity.id, entity.instance, entity.instance + 1); + } + } + + /// Heights the bake seated models at, by id. + bakedHeights = new Map(); + + #attach(id, first, end) { + const base = invert(this.matrixOf(id)); + if (!base) return; + const instances = []; + for (let instance = first; instance < end; instance++) { + const world = Array.from(this.viewer.instance_transform(instance)); + if (world.length === 16) instances.push({ instance, local: multiply(base, world) }); + } + this.#drawn.set(id, instances); + this.#ranges.push([first, end, id]); + this.#ranges.sort((a, b) => a[0] - b[0]); + } + + /// The world matrix of an entity's transform as drawn, with any seated height filled in. + matrixOf(id) { + const transform = this.entities.get(id)?.transform; + if (!transform) return null; + const position = [...transform.position]; + if (transform.ground !== undefined && this.bakedHeights.has(id)) { + position[1] = this.bakedHeights.get(id); + } + return transformMatrix({ ...transform, position }); + } + + /// The transform the editor shows and edits: the project's, with any seated height filled in. + shownTransform(id) { + const transform = this.entities.get(id)?.transform; + if (!transform) return null; + const shown = structuredClone(transform); + if (shown.ground !== undefined && this.bakedHeights.has(id)) { + shown.position[1] = this.bakedHeights.get(id); + } + shown.rotation ??= [0, 0, 0]; + shown.scale ??= 1; + return shown; + } + + /// Sets an entity's transform and moves what draws it. `jump` places it without motion, as + /// undo and typed values should; a drag moves it as motion. + setTransform(id, transform, jump = true) { + const entity = this.entities.get(id); + if (!entity) return false; + entity.transform = canonicalTransform(transform); + if (entity.transform.ground === undefined) this.bakedHeights.delete(id); + this.#place(id, jump); + return true; + } + + /// All that says where an entity is, to put back exactly with `restore`. + snapshot(id) { + return { + transform: structuredClone(this.entities.get(id)?.transform), + baked: this.bakedHeights.get(id), + }; + } + + restore(id, snapshot, jump = true) { + const entity = this.entities.get(id); + if (!entity) return; + entity.transform = structuredClone(snapshot.transform); + if (snapshot.baked === undefined) this.bakedHeights.delete(id); + else this.bakedHeights.set(id, snapshot.baked); + this.#place(id, jump); + } + + /// The transform a snapshot shows, as `shownTransform` gives it. + shownFrom(snapshot) { + const shown = structuredClone(snapshot.transform); + if (shown.ground !== undefined && snapshot.baked !== undefined) shown.position[1] = snapshot.baked; + shown.rotation ??= [0, 0, 0]; + shown.scale ??= 1; + return shown; + } + + #place(id, jump) { + const world = this.matrixOf(id); + for (const { instance, local } of this.#drawn.get(id) ?? []) { + this.viewer.set_instance_transform(instance, multiply(world, local), jump); + } + } + + /// Instances that draw an entity. + instancesOf(id) { + return (this.#drawn.get(id) ?? []).map((d) => d.instance); + } + + /// Whether an entity and all it holds can be seen in the viewport (as `instancesOf` does). + drawn(id) { + return this.#drawn.has(id); + } + + /// The entity that drew an instance, or null for the land, or anything unmapped. + entityAt(instance) { + let lo = 0; + let hi = this.#ranges.length - 1; + while (lo <= hi) { + const mid = (lo + hi) >> 1; + const [first, end, id] = this.#ranges[mid]; + if (instance < first) hi = mid - 1; + else if (instance >= end) lo = mid + 1; + else return id; + } + return null; + } + + /// A sphere around everything an entity draws, or its position if it draws nothing. + bounds(id) { + const instances = this.instancesOf(id); + const spheres = instances.map((i) => Array.from(this.viewer.instance_bounds(i))) + .filter((s) => s.length === 4); + if (spheres.length === 0) { + const shown = this.shownTransform(id); + return shown ? { centre: shown.position, radius: 1 } : null; + } + const centre = [0, 1, 2].map((k) => spheres.reduce((sum, s) => sum + s[k], 0) / spheres.length); + const radius = Math.max(...spheres.map((s) => + Math.hypot(s[0] - centre[0], s[1] - centre[1], s[2] - centre[2]) + s[3])); + return { centre, radius }; + } + + /// The ids of an entity's line of parents, nearest first. + ancestors(id) { + const out = []; + for (let p = this.parents.get(id); p; p = this.parents.get(p)) out.push(p); + return out; + } + + /// The scene as its file holds it. + toJson() { + return writeScene(this.scene); + } +} + +/// For a scene with no project, one entity per instance, named by its number. +function syntheticEntities(viewer) { + const count = viewer.instance_count(); + const entities = []; + for (let instance = 0; instance < count; instance++) { + const world = Array.from(viewer.instance_transform(instance)); + if (world.length !== 16) continue; + entities.push({ + id: `instance-${instance}`, + name: `Instance ${instance}`, + instance, + transform: { position: [world[12], world[13], world[14]] }, + }); + } + return entities; +} + +/// A transform with defaults left out, as the project's files hold it, and its fields in order. +function canonicalTransform({ position, rotation, scale, ground }) { + const out = { position: position.map(Number) }; + if (rotation && rotation.some((a) => a !== 0)) out.rotation = rotation.map(Number); + if (scale !== undefined && scale !== 1) out.scale = Number(scale); + if (ground !== undefined) out.ground = Number(ground); + return out; +} + +// The order the Rust crate writes each kind of object's fields in, so that the editor's file is +// the one the bake would write: saving without an edit changes nothing. +const TRANSFORM = ["position", "rotation", "scale", "ground"]; +const ENTITY_ORDER = { + keys: ["id", "name", "note", "transform", ...KINDS, "children"], + nested: { + transform: { keys: TRANSFORM }, + mesh: { keys: ["asset", "part", "collide", "skinned"] }, + actor: { keys: ["asset", "properties"], nested: { properties: { keys: null } } }, + light: { keys: ["range", "intensity"] }, + blocker: { keys: ["size"] }, + wood: { keys: ["radius", "spacing"] }, + clear: { keys: ["radius"] }, + path: { keys: ["from", "to", "width"] }, + yard: { keys: ["from", "to"] }, + pond: { keys: ["min", "max", "level", "water"] }, + }, +}; +ENTITY_ORDER.nested.children = { list: ENTITY_ORDER }; +const SCENE_ORDER = { + keys: ["format", "note", "texture_size", "camera", "terrain", "land", "meadow", "water", "sea", + "game", "entities"], + nested: { + camera: { keys: ["position", "yaw_radians", "pitch_radians"] }, + terrain: { keys: ["size", "cells", "height", "shore_x"] }, + land: { keys: ["sand", "dirt"] }, + water: { keys: ["level", "color"] }, + sea: { keys: ["level", "ocean"] }, + game: { keys: ["input", "track", "circuit"] }, + entities: { list: ENTITY_ORDER }, + }, +}; + +/// A number as Rust writes an f32 or an integer: integral floats keep a `.0`. +function number(value, integer) { + if (integer || !Number.isFinite(value)) return String(value); + // The shortest text that reads back as the same f32, as serde_json writes it. + const f = Math.fround(value); + let text = String(f); + for (let digits = 1; digits <= 9; digits++) { + const candidate = f.toPrecision(digits); + if (Math.fround(Number(candidate)) === f) { + text = String(Number(candidate)); + break; + } + } + // Very small or large numbers are written with exponents, which serde_json and JavaScript + // place a little differently; the editor's own numbers are tidied well clear of them. + if (/e/.test(text)) return text.replace("+", ""); + return text.includes(".") ? text : `${text}.0`; +} + +// Fields held as whole numbers. +const INTEGERS = new Set(["format", "texture_size", "cells"]); + +/// Writes a value as the project's files are written: two-space indents, fields in `order`, +/// lists of numbers on one line, and other lists one item to a line. +export function writeJson(value, order, indent = "", key = "") { + const inner = `${indent} `; + if (Array.isArray(value)) { + if (value.length === 0) return "[]"; + if (value.every((v) => typeof v === "number")) { + return `[${value.map((v) => number(v, false)).join(", ")}]`; + } + const items = value.map((v) => inner + writeJson(v, order?.list ?? order, inner)); + return `[\n${items.join(",\n")}\n${indent}]`; + } + if (value && typeof value === "object") { + const keys = order?.keys + ? [...order.keys.filter((k) => k in value), ...Object.keys(value).filter((k) => !order.keys.includes(k))] + : Object.keys(value); + const fields = keys.filter((k) => value[k] !== undefined && !(Array.isArray(value[k]) + && value[k].length === 0 && (k === "children" || k === "entities"))); + if (fields.length === 0) return "{}"; + const lines = fields.map((k) => + `${inner}${JSON.stringify(k)}: ${writeJson(value[k], order?.nested?.[k], inner, k)}`); + return `{\n${lines.join(",\n")}\n${indent}}`; + } + if (typeof value === "number") return number(value, INTEGERS.has(key)); + return JSON.stringify(value); +} + +export const writeScene = (scene) => `${writeJson(scene, SCENE_ORDER)}\n`; diff --git a/apps/viewer/web/editor/test.mjs b/apps/viewer/web/editor/test.mjs new file mode 100644 index 0000000..f5142af --- /dev/null +++ b/apps/viewer/web/editor/test.mjs @@ -0,0 +1,132 @@ +// Tests of the editor's own code that need no browser: the project file writer, the rotation +// maths and the gizmo's drags. Run with `node apps/viewer/web/editor/test.mjs`; CI runs it. + +import { readFileSync } from "node:fs"; +import { Commands } from "./commands.js"; +import { Gizmo } from "./gizmo.js"; +import * as m from "./math.js"; +import { writeScene } from "./project.js"; + +let failures = 0; +function check(what, ok, detail) { + console.log(`${ok ? "ok " : "FAIL"} ${what}${ok ? "" : `: ${JSON.stringify(detail)}`}`); + if (!ok) failures += 1; +} + +// ---- The file writer writes what the Rust crate writes, so saving changes nothing. +{ + const fixture = readFileSync(new URL("../../../../crates/solstice-project/tests/fixture.scene", import.meta.url), "utf8") + .replace(/\r\n/g, "\n"); + const written = writeScene(JSON.parse(fixture)); + const at = [...written].findIndex((c, i) => c !== fixture[i]); + check("a scene written by the editor is the file the bake wrote", written === fixture, + at < 0 ? "lengths differ" : { at, editor: written.slice(at - 40, at + 40), bake: fixture.slice(at - 40, at + 40) }); + const edited = JSON.parse(fixture); + edited.entities[1].children[2].transform.position = [-7.25, 0, 1e-7]; + check("numbers are written as f32s are, with .0 on whole ones", + writeScene(edited).includes('"position": [-7.25, 0.0, 1e-7]')); +} + +// ---- Rotations: degrees about X, Y and Z, applied as the bake applies them. +{ + let worst = 0; + for (let k = 0; k < 2000; k++) { + const a = [Math.random() * 170 - 85, Math.random() * 360 - 180, Math.random() * 360 - 180]; + const b = m.eulerFromColumns(m.rotationColumns(a)); + worst = Math.max(worst, ...a.map((v, i) => Math.abs(v - b[i]))); + } + check("angles survive a trip through a matrix", worst < 1e-9, worst); + check("a turn about Y alone stays about Y alone", + JSON.stringify(m.tidyAngles(m.eulerFromColumns(m.rotationColumns([0, 137.5, 0])))) === "[0,137.5,0]"); + // glam's Quat::from_euler(EulerRot::YXZ, y, x, z) is Ry Rx Rz: X turned 90 about Y points along -Z. + const [x] = m.rotationColumns([0, 90, 0]); + check("yaw turns X towards -Z, as glam's does", Math.abs(x[2] + 1) < 1e-12, x); + const matrix = m.transformMatrix({ position: [1, 2, 3], rotation: [10, 20, 30], scale: 2 }); + const identity = m.multiply(m.invert(matrix), matrix); + check("a matrix times its inverse is the identity", + identity.every((v, i) => Math.abs(v - (i % 5 === 0 ? 1 : 0)) < 1e-9)); +} + +// ---- The gizmo, driven by rays as a mouse would drive it. +{ + // A camera at (0, 10, 10) looking at the origin, built as glam's look_to_rh and + // perspective_infinite_reverse_rh build the viewer's. + const position = [0, 10, 10]; + const forward = m.normalize(m.sub([0, 0, 0], position)); + const f = 1 / Math.tan((55 * Math.PI) / 360); + const side = m.normalize(m.cross(forward, [0, 1, 0])); + const up = m.cross(side, forward); + const view = [side[0], up[0], -forward[0], 0, side[1], up[1], -forward[1], 0, side[2], up[2], -forward[2], 0, + -m.dot(side, position), -m.dot(up, position), m.dot(forward, position), 1]; + const projection = [f / (16 / 9), 0, 0, 0, 0, f, 0, 0, 0, 0, 0, -1, 0, 0, 0.05, 0]; + const camera = { + view, projection, viewProjection: m.multiply(projection, view), position, forward, + yaw: Math.atan2(-forward[0], -forward[2]), pitch: Math.asin(forward[1]), + tanHalfFov: 1 / f, cssWidth: 1600, cssHeight: 900, + }; + const ray = (p) => m.rayThrough(view, projection, p.x / 1600, p.y / 900); + const screen = (p) => m.projectToScreen(camera.viewProjection, p, 1600, 900); + const start = { position: [0, 0, 0], rotation: [0, 90, 0], scale: 1 }; + const centre = screen([0, 0, 0]); + const gizmo = new Gizmo(); + // How long the handles are at this distance. + const size = 10 * Math.SQRT2 * camera.tanHalfFov * 2 * 130 / 900; + + const middle = screen([size / 2, 0, 0]); + const arrow = gizmo.hit(start, camera, middle.x, middle.y); + check("the X arrow is under its middle", arrow?.kind === "axis" && arrow.axis === 0, arrow); + // Grabbed at its middle, and dragged 2.3 m farther along. + const target = screen([size / 2 + 2.3, 0, 0]); + const moved = gizmo.drag(arrow, start, camera, ray(middle), middle)(ray(target), true, target); + check("moving along X snaps x to the grid and leaves y and z", + JSON.stringify(moved.transform.position) === "[2.5,0,0]", moved.transform); + const free = gizmo.drag(arrow, start, camera, ray(middle), middle)(ray(target), false, target); + check("and without snapping goes where the mouse does", Math.abs(free.transform.position[0] - 2.3) < 0.01, free.transform); + + gizmo.mode = "rotate"; + const h = size * Math.SQRT1_2; + const [from, to] = [screen([h, 0, h]), screen([h, 0, -h])]; + const ring = gizmo.hit(start, camera, from.x, from.y); + check("the Y ring is under a point of it", ring?.kind === "ring" && ring.axis === 1, ring); + const turned = gizmo.drag(ring, start, camera, ray(from), from)(ray(to), true, to); + check("a quarter turn round it adds 90 degrees of yaw", + JSON.stringify(turned.transform.rotation) === "[0,180,0]", turned.transform); + + gizmo.mode = "scale"; + const knob = screen([size, 0, 0]); + const handle = gizmo.hit(start, camera, knob.x, knob.y); + check("a scale handle is under its knob", handle?.kind === "scale", handle); + const far = { x: centre.x + (knob.x - centre.x) * 2, y: centre.y + (knob.y - centre.y) * 2 }; + check("dragging twice as far from the centre doubles the scale", + gizmo.drag(handle, start, camera, ray(knob), knob)(ray(far), true, far).transform.scale === 2); +} + +// ---- Commands check their arguments, never throw, and keep the history. +{ + const state = { value: 0 }; + const commands = new Commands(state); + commands.define("value.set", { + description: "Sets the value.", + args: { to: { type: "number", required: true, description: "The value." } }, + run: ({ to }, context) => { + const before = context.value; + context.value = to; + return { result: to, step: { label: "Set", undo: () => { context.value = before; }, redo: () => { context.value = to; } } }; + }, + }); + check("a call runs", (await commands.call("value.set", { to: 3 }, "agent")).result === 3 && state.value === 3); + const unknown = await commands.call("value.sett", {}); + check("an unknown command is an error, not a throw", unknown.ok === false && unknown.error.code === "unknown_command"); + const typo = await commands.call("value.set", { too: 3 }); + check("an unknown argument is named", typo.ok === false && /too/.test(typo.error.message), typo); + const wrong = await commands.call("value.set", { to: "3" }); + check("a wrong type is refused", wrong.ok === false && wrong.error.code === "bad_arguments"); + check("the history says who did what", JSON.stringify(commands.history.list().done) === '[{"label":"Set","by":"agent"}]'); + commands.history.undo(); + check("undo puts it back", state.value === 0); + const help = commands.help("value.set"); + check("help gives JSON Schema", help.arguments.required[0] === "to" && help.arguments.properties.to.type === "number"); +} + +console.log(failures ? `${failures} failed` : "all passed"); +process.exit(failures ? 1 : 0); diff --git a/apps/viewer/web/index.html b/apps/viewer/web/index.html index 31f7737..baed86e 100644 --- a/apps/viewer/web/index.html +++ b/apps/viewer/web/index.html @@ -252,13 +252,16 @@

// load the plain build, which is smaller and knows nothing of games. const playing = params.has("play"); const build = playing ? "./play/solstice_viewer.js" : "./pkg/solstice_viewer.js"; -const { default: init, WebViewer, header_bytes, read_header } = await import(build).catch((error) => { +const wasm = await import(build).catch((error) => { // Said on the page, not left at "Starting…": `fail` needs what is set up below. const message = document.getElementById("message"); message.textContent = `Could not load the viewer (${build}): ${error.message ?? error}`; message.className = "error"; throw error; }); +const { default: init } = wasm; +const { adapterReport, readWithRetries, inflateAtMost, requestAdapter, openScene } = + await import("./loader.js"); const sceneName = params.get("scene") ?? "cove"; if (!/^[\w-]+$/.test(sceneName)) throw new Error("invalid scene name"); @@ -291,58 +294,6 @@

el("message").className = "error"; } -/// The limits the renderer and its fallbacks turn on, as an adapter reports them. -const REPORTED_LIMITS = [ - "maxStorageBuffersPerShaderStage", "maxStorageBuffersInVertexStage", - "maxStorageBuffersInFragmentStage", "maxStorageTexturesPerShaderStage", - "maxStorageTexturesInFragmentStage", "maxSampledTexturesPerShaderStage", - "maxStorageBufferBindingSize", "maxBufferSize", "maxColorAttachments", - "maxComputeInvocationsPerWorkgroup", "maxComputeWorkgroupSizeX", - "maxComputeWorkgroupStorageSize", "maxInterStageShaderVariables", - "maxUniformBufferBindingSize", "maxTextureDimension2D", "maxTextureArrayLayers", -]; - -/// The browser's own adapter request, kept before `requestAdapter` may replace it, so that the -/// report says what the browser itself offers. -const browserRequestAdapter = globalThis.GPU?.prototype.requestAdapter; -let compatibilityShim = false; - -/// What the browser offers, adapter by adapter: for the page to show when the viewer can't -/// start, as a phone's console is out of reach. Each adapter is asked for afresh. -async function adapterReport() { - const lines = [ - `Page: ${location.href}`, - `Browser: ${navigator.userAgent}`, - `Secure context: ${isSecureContext}, WebGPU: ${Boolean(navigator.gpu)}` - + (compatibilityShim ? ", using a compatibility adapter as core" : ""), - ]; - const describe = async (label, options) => { - let adapter; - try { - adapter = await browserRequestAdapter.call(navigator.gpu, options); - } catch (error) { - lines.push(`${label}: request failed (${error.message ?? error})`); - return; - } - if (!adapter) { - lines.push(`${label}: none`); - return; - } - const info = adapter.info ?? {}; - const name = [info.vendor, info.architecture, info.device, info.description] - .filter(Boolean).join(" / "); - lines.push(`${label}: ${name || "unnamed"}${info.isFallbackAdapter ? " (software)" : ""}`); - lines.push(` features: ${[...adapter.features].sort().join(", ") || "none"}`); - lines.push(` limits: ${REPORTED_LIMITS.filter((key) => key in adapter.limits) - .map((key) => `${key} ${adapter.limits[key]}`).join(", ")}`); - }; - if (navigator.gpu) { - await describe("Core adapter", undefined); - await describe("Compatibility adapter", { featureLevel: "compatibility" }); - await describe("Software adapter", { forceFallbackAdapter: true }); - } - return lines.join("\n"); -} /// Fails with `text`, and under it what the browser offered, to read or copy. async function failWithReport(text) { @@ -356,287 +307,6 @@

.catch(() => { el("report-copy").textContent = "Copy failed: select the text"; }); } -/// Reads parts of a scene file by HTTP Range. If the server doesn't do ranges, the whole file -/// comes down once, and ranges are served from memory, so any static host works. -class SceneFile { - bytesFetched = 0; - #whole = null; - #etag = null; - #url; - - constructor(url) { - this.#url = url; - } - - async read(start, end, signal) { - if (this.#whole) return this.#whole.subarray(start, end); - const response = await fetch(this.#url, { headers: { Range: `bytes=${start}-${end - 1}` }, signal }); - if (!response.ok) { - throw new Error(`Could not load ${this.#url} (HTTP ${response.status}).`); - } - if (response.status === 200) { - this.#whole = await downloadWhole(response); - this.bytesFetched = this.#whole.length; - return this.#whole.subarray(start, end); - } - // A scene replaced while it's being read would mix two files, so start again from the top. - const etag = response.headers.get("etag"); - if (this.#etag && etag && etag !== this.#etag) { - location.reload(); - return new Promise(() => {}); - } - this.#etag = etag; - const bytes = new Uint8Array(await response.arrayBuffer()); - this.bytesFetched += bytes.length; - return bytes; - } -} - -/// Downloads a whole file with progress, for servers without Range support. -async function downloadWhole(response) { - const total = Number(response.headers.get("content-length")) || 0; - const reader = response.body.getReader(); - const chunks = []; - let received = 0; - el("progress").hidden = total === 0; - while (true) { - const { done, value } = await reader.read(); - if (done) break; - chunks.push(value); - received += value.length; - if (total) el("progress").value = received / total; - el("message").textContent = `Downloading scene: ${(received / 1e6).toFixed(0)} MB`; - } - const bytes = new Uint8Array(received); - let offset = 0; - for (const chunk of chunks) { - bytes.set(chunk, offset); - offset += chunk.length; - } - el("progress").hidden = true; - return bytes; -} - -async function inflate(bytes) { - const unpacked = new Blob([bytes]).stream().pipeThrough(new DecompressionStream("deflate-raw")); - return new Uint8Array(await new Response(unpacked).arrayBuffer()); -} - -/// Unpacks a block that should come to `limit` bytes, refusing to unpack more: a scene file comes -/// from outside. -async function inflateAtMost(bytes, limit) { - const unpacked = new Blob([bytes]).stream().pipeThrough(new DecompressionStream("deflate-raw")); - const reader = unpacked.getReader(); - const out = new Uint8Array(limit); - let filled = 0; - while (true) { - const { done, value } = await reader.read(); - if (done) break; - if (filled + value.length > limit) { - await reader.cancel(); - throw new Error("a part of the scene unpacks larger than it says"); - } - out.set(value, filled); - filled += value.length; - } - return out.subarray(0, filled); -} - -/// How long one try at reading part of a scene file may take, stalled or not. -const READ_TIMEOUT_MS = 60000; - -/// Reads part of a scene file, trying a few times before giving up. -async function readWithRetries(file, start, end) { - for (let attempt = 1; ; attempt++) { - try { - return await file.read(start, end, AbortSignal.timeout(READ_TIMEOUT_MS)); - } catch (error) { - if (attempt === 3) throw error; - await new Promise((resolve) => setTimeout(resolve, 500 * attempt)); - } - } -} - -/// Fetches what the viewer asks for, keeping the page responsive while it does. -/// Runs in workers: fetches one run of a scene file and unpacks its pages, off the main thread, -/// so that streaming doesn't cost the frame rate. -const FETCH_WORKER = ` -async function inflate(bytes) { - const unpacked = new Blob([bytes]).stream().pipeThrough(new DecompressionStream("deflate-raw")); - return new Uint8Array(await new Response(unpacked).arrayBuffer()); -} -// Many parts of a file in one response, one after another: scripts/serve.py. -async function many(url, spans) { - if (spans.length === 0) return new Uint8Array(0); - const ranges = spans.map(([start, end]) => start + "-" + (end - 1)).join(","); - const response = await fetch(url, { headers: { "X-Solstice-Ranges": ranges } }); - if (!response.headers.get("X-Solstice-Ranges")) { - throw new Error("this scene needs scripts/serve.py, which can send many parts at once"); - } - return new Uint8Array(await response.arrayBuffer()); -} -onmessage = async ({ data: { url, tablesUrl, ticket, run } }) => { - try { - const withRecords = run.filter((request) => request.clustersEnd > request.clustersStart); - const [stored, records] = await Promise.all([ - many(url, run.map((request) => [request.start, request.end])), - many(tablesUrl, withRecords.map((request) => [request.clustersStart, request.clustersEnd])), - ]); - let at = 0; - let recordsAt = 0; - const pages = await Promise.all(run.map(async (request) => { - const part = stored.subarray(at, at + request.end - request.start); - at += request.end - request.start; - let clusters = null; - if (request.clustersEnd > request.clustersStart) { - const length = request.clustersEnd - request.clustersStart; - clusters = records.slice(recordsAt, recordsAt + length); - recordsAt += length; - } - return { id: request.id, data: request.deflated ? await inflate(part) : part.slice(), clusters }; - })); - postMessage({ ticket, pages }, pages.flatMap((page) => - page.clusters ? [page.data.buffer, page.clusters.buffer] : [page.data.buffer])); - } catch (error) { - postMessage({ ticket, failed: run.map((request) => request.id), error: String(error) }); - } -}; -`; - -/// Fetches runs of pages in workers, each going to whichever has the least to do. -class WorkerFetcher { - #workers; - #busy; - #tickets = new Map(); - #next = 0; - #url; - #tablesUrl; - - constructor(url, tablesUrl, count, onPages, onFailed) { - this.#url = url; - this.#tablesUrl = new URL(tablesUrl, location.href).href; - const script = URL.createObjectURL(new Blob([FETCH_WORKER], { type: "text/javascript" })); - this.#busy = new Array(count).fill(0); - this.#workers = this.#busy.map((_, index) => { - const worker = new Worker(script); - worker.onmessage = ({ data }) => { - this.#busy[index]--; - this.#tickets.delete(data.ticket); - if (data.failed) { - console.warn(`Could not fetch part of the scene, and will retry: ${data.error}`); - onFailed(data.failed); - } else { - onPages(data.pages); - } - }; - return worker; - }); - } - - fetch(run) { - const index = this.#busy.indexOf(Math.min(...this.#busy)); - this.#busy[index]++; - const ticket = this.#next++; - this.#tickets.set(ticket, run); - this.#workers[index].postMessage({ - url: new URL(this.#url, location.href).href, tablesUrl: this.#tablesUrl, ticket, run, - }); - } -} - -class Streamer { - // Pages being fetched at once. ?fetching=N tries another number. - static MAX_FETCHING = Number(params.get("fetching")) || (params.has("split") ? 1024 : 16); - static WORKERS = Number(params.get("workers")) || Math.min(8, navigator.hardwareConcurrency || 4); - // Browsers run about six connections per host over HTTP/1.1, so requests for parts of the file - // that are close together share one, as long as what lies between them is small. - static MERGE_GAP_BYTES = 256 * 1024; - static MERGE_MAX_BYTES = 8 * 1048576; - static RETRY_MS = 1000; - // Pages asked for in one request, by the workers. Six requests at a time is all a browser sends. - static PAGES_PER_REQUEST = Number(params.get("batch")) || 64; - #viewer; - #file; - #workers = null; - - #tablesStart; - - constructor(viewer, file, tablesStart = 0) { - this.#viewer = viewer; - this.#file = file; - this.#tablesStart = tablesStart; - // Only for a scene read in parts, which is served with Range requests by something known. - if (params.has("split")) { - this.#workers = new WorkerFetcher( - sceneUrl, - `${sceneBase}${sceneName}.web`, - Streamer.WORKERS, - (pages) => { - for (const { id, data, clusters } of pages) { - if (clusters) this.#viewer.deliver_page(id, data, clusters); - else this.#viewer.deliver(id, data); - } - }, - (ids) => { for (const id of ids) setTimeout(() => this.#viewer.request_failed(id), Streamer.RETRY_MS); }, - ); - } - } - - /// Call once per frame. - pump() { - const flat = this.#viewer.stream_requests(Streamer.MAX_FETCHING); - const requests = []; - for (let i = 0; i < flat.length; i += 6) { - requests.push({ - id: flat[i], start: flat[i + 1], end: flat[i + 2], deflated: flat[i + 3] !== 0, - clustersStart: this.#tablesStart + flat[i + 4], clustersEnd: this.#tablesStart + flat[i + 5], - }); - } - requests.sort((a, b) => a.start - b.start); - if (this.#workers) { - for (let i = 0; i < requests.length; i += Streamer.PAGES_PER_REQUEST) { - this.#workers.fetch(requests.slice(i, i + Streamer.PAGES_PER_REQUEST)); - } - return; - } - let run = []; - for (const request of requests) { - const last = run[run.length - 1]; - if (last && (request.start - last.end > Streamer.MERGE_GAP_BYTES - || request.end - run[0].start > Streamer.MERGE_MAX_BYTES)) { - this.#fetchRun(run); - run = []; - } - run.push(request); - } - if (run.length > 0) this.#fetchRun(run); - } - - async #fetchRun(run) { - const start = run[0].start; - const end = run[run.length - 1].end; - let stored; - try { - stored = await this.#file.read(start, end); - } catch (error) { - console.warn(`Could not fetch part of the scene, and will retry: ${error.message ?? error}`); - for (const request of run) { - setTimeout(() => this.#viewer.request_failed(request.id), Streamer.RETRY_MS); - } - return; - } - for (const request of run) this.#unpack(request, stored.subarray(request.start - start, request.end - start)); - } - - async #unpack(request, stored) { - try { - this.#viewer.deliver(request.id, request.deflated ? await inflate(stored) : stored); - } catch (error) { - console.warn(`Could not unpack part of the scene, and will retry: ${error.message ?? error}`); - setTimeout(() => this.#viewer.request_failed(request.id), Streamer.RETRY_MS); - } - } -} const canvasSize = () => { const ratio = Math.min(window.devicePixelRatio || 1, 2); @@ -653,84 +323,6 @@

return String(n); } -/// Hands over tables too large for a browser's memory a part at a time, each going on to the GPU. -async function loadExternalTables(viewer, tables, start) { - const sizes = viewer.external_tables(); - if (sizes.length === 0) return; - const [clusterCount, pinnedBytes] = sizes; - const CHUNK = 64 * 1048576; - const RECORD = 48; - const pageSizes = viewer.pinned_sizes(); - const recordCounts = viewer.pinned_cluster_counts(); - let done = 0; - const report = () => { - el("progress").hidden = false; - el("progress").value = done / pinnedBytes; - el("message").textContent = - `Loading the scene's base: ${(done / 1e9).toFixed(1)} of ${(pinnedBytes / 1e9).toFixed(1)} GB`; - }; - // Lets the GPU process catch up, so uploads don't pile up in memory. - const breathe = () => new Promise((resolve) => setTimeout(resolve, 0)); - - // The table holds each page's records in turn, and pinned pages come first. - const pinnedRecords = recordCounts.reduce((sum, count) => sum + count, 0) * RECORD; - const records = await readWithRetries(tables, start, start + pinnedRecords); - const pinnedStart = start + clusterCount * RECORD; - let page = 0; - let at = 0; - let recordsAt = 0; - while (page < pageSizes.length) { - let end = at; - let last = page; - while (last < pageSizes.length && (end === at || end + pageSizes[last] - at <= CHUNK)) { - end += pageSizes[last]; - last++; - } - const bytes = await readWithRetries(tables, pinnedStart + at, pinnedStart + end); - let inside = 0; - for (; page < last; page++) { - const length = recordCounts[page] * RECORD; - viewer.install_pinned( - page, - bytes.subarray(inside, inside + pageSizes[page]), - records.subarray(recordsAt, recordsAt + length), - ); - inside += pageSizes[page]; - recordsAt += length; - } - done += end - at; - at = end; - report(); - await breathe(); - } - viewer.finish_external_tables(); - el("progress").hidden = true; -} - -/// The adapter the viewer will be given. Chrome offers some GPUs only to pages asking for -/// WebGPU's "compatibility" feature level, though they can do all of core WebGPU, as its own -/// software adapter on an Android emulator does; the viewer asks for core. If no core adapter -/// is offered, such an adapter is taken, and its devices asked for core. Anywhere a core -/// adapter is offered, nothing changes. -async function requestAdapter() { - const adapter = await navigator.gpu.requestAdapter(); - if (adapter) return adapter; - const CORE = "core-features-and-limits"; - const compatible = await navigator.gpu.requestAdapter({ featureLevel: "compatibility" }); - if (!compatible?.features.has(CORE)) return null; - const requestAdapter = GPU.prototype.requestAdapter; - GPU.prototype.requestAdapter = function (options = {}) { - return requestAdapter.call(this, { ...options, featureLevel: "compatibility" }); - }; - const requestDevice = GPUAdapter.prototype.requestDevice; - GPUAdapter.prototype.requestDevice = function (descriptor = {}) { - const requiredFeatures = [...(descriptor.requiredFeatures ?? []), CORE]; - return requestDevice.call(this, { ...descriptor, requiredFeatures }); - }; - console.info("using a GPU offered for WebGPU compatibility, which can do core WebGPU"); - compatibilityShim = true; - return compatible; -} async function main() { if (!navigator.gpu) { @@ -754,34 +346,36 @@

} await init(); el("message").textContent = "Loading scene…"; - const file = new SceneFile(sceneUrl); - // ?split reads the manifest from NAME.web, which leaves out the tables too large to hold in a - // browser's memory and carries them after the manifest. Pages still come from NAME.solstice. - const tables = params.has("split") ? new SceneFile(`${sceneBase}${sceneName}.web`) : file; - const [manifestOffset, manifestBytes] = read_header(await tables.read(0, header_bytes())); - const manifestEnd = manifestOffset + manifestBytes; - const manifest = await inflate(await tables.read(manifestOffset, manifestEnd)); - const [pagesOffset, pagesManifestBytes] = tables === file - ? [manifestOffset, manifestBytes] - : read_header(await file.read(0, header_bytes())); - el("message").textContent = "Preparing the GPU…"; - [canvas.width, canvas.height] = canvasSize(); - const viewer = await WebViewer.create( - canvas, - manifest, - pagesOffset + pagesManifestBytes, + const { viewer, streamer, file } = await openScene(wasm, canvas, { + url: sceneUrl, + // ?split reads the manifest from NAME.web, and pages from NAME.solstice. + tablesUrl: params.has("split") ? `${sceneBase}${sceneName}.web` : null, geometryBudget, textureBudget, - params.has("unpack-textures"), + unpackTextures: params.has("unpack-textures"), // ?limits=webgpu asks for no more than the WebGPU defaults, as many phones are given. - params.get("limits") === "webgpu", - ); - // A GPU given less than the renderer asks for has passes that do without. - const fallbacks = viewer.fallbacks(); - if (fallbacks) console.info(`fallbacks for this GPU's limits: ${fallbacks}`); - await loadExternalTables(viewer, tables, manifestEnd); - const streamer = new Streamer(viewer, file, manifestEnd); + defaultLimits: params.get("limits") === "webgpu", + // ?fetching=N, ?workers=N and ?batch=N try other numbers. + streaming: { + maxFetching: Number(params.get("fetching")) || 0, + workers: Number(params.get("workers")) || 0, + pagesPerRequest: Number(params.get("batch")) || 0, + }, + onStage: (text) => { el("message").textContent = text; }, + onDownload: (received, total) => { + el("progress").hidden = received === null || total === 0; + if (received === null) return; + if (total) el("progress").value = received / total; + el("message").textContent = `Downloading scene: ${(received / 1e6).toFixed(0)} MB`; + }, + onTablesProgress: (done, total) => { + el("progress").hidden = done >= total; + el("progress").value = done / total; + el("message").textContent = + `Loading the scene's base: ${(done / 1e9).toFixed(1)} of ${(total / 1e9).toFixed(1)} GB`; + }, + }); const camera = params.get("camera")?.split(",").map(Number); if (camera?.length === 5) viewer.set_camera(...camera); diff --git a/apps/viewer/web/loader.js b/apps/viewer/web/loader.js new file mode 100644 index 0000000..33059b2 --- /dev/null +++ b/apps/viewer/web/loader.js @@ -0,0 +1,455 @@ +// Loading a scene into the viewer, shared by the viewer's page and the editor's +// (docs/editor.md): reads a scene file by HTTP Range, hands the viewer the parts it asks for, and +// finds a GPU adapter to run it on. Nothing here touches the page. + +/// The limits the renderer and its fallbacks turn on, as an adapter reports them. +const REPORTED_LIMITS = [ + "maxStorageBuffersPerShaderStage", "maxStorageBuffersInVertexStage", + "maxStorageBuffersInFragmentStage", "maxStorageTexturesPerShaderStage", + "maxStorageTexturesInFragmentStage", "maxSampledTexturesPerShaderStage", + "maxStorageBufferBindingSize", "maxBufferSize", "maxColorAttachments", + "maxComputeInvocationsPerWorkgroup", "maxComputeWorkgroupSizeX", + "maxComputeWorkgroupStorageSize", "maxInterStageShaderVariables", + "maxUniformBufferBindingSize", "maxTextureDimension2D", "maxTextureArrayLayers", +]; + +/// The browser's own adapter request, kept before `requestAdapter` may replace it, so that the +/// report says what the browser itself offers. +const browserRequestAdapter = globalThis.GPU?.prototype.requestAdapter; +let compatibilityShim = false; + +/// What the browser offers, adapter by adapter: for the page to show when the viewer can't +/// start, as a phone's console is out of reach. Each adapter is asked for afresh. +export async function adapterReport() { + const lines = [ + `Page: ${location.href}`, + `Browser: ${navigator.userAgent}`, + `Secure context: ${isSecureContext}, WebGPU: ${Boolean(navigator.gpu)}` + + (compatibilityShim ? ", using a compatibility adapter as core" : ""), + ]; + const describe = async (label, options) => { + let adapter; + try { + adapter = await browserRequestAdapter.call(navigator.gpu, options); + } catch (error) { + lines.push(`${label}: request failed (${error.message ?? error})`); + return; + } + if (!adapter) { + lines.push(`${label}: none`); + return; + } + const info = adapter.info ?? {}; + const name = [info.vendor, info.architecture, info.device, info.description] + .filter(Boolean).join(" / "); + lines.push(`${label}: ${name || "unnamed"}${info.isFallbackAdapter ? " (software)" : ""}`); + lines.push(` features: ${[...adapter.features].sort().join(", ") || "none"}`); + lines.push(` limits: ${REPORTED_LIMITS.filter((key) => key in adapter.limits) + .map((key) => `${key} ${adapter.limits[key]}`).join(", ")}`); + }; + if (navigator.gpu) { + await describe("Core adapter", undefined); + await describe("Compatibility adapter", { featureLevel: "compatibility" }); + await describe("Software adapter", { forceFallbackAdapter: true }); + } + return lines.join("\n"); +} + +/// Reads parts of a scene file by HTTP Range. If the server doesn't do ranges, the whole file +/// comes down once, and ranges are served from memory, so any static host works. +export class SceneFile { + bytesFetched = 0; + #whole = null; + #etag = null; + #url; + #onDownload; + + /// `onDownload(received, total)` follows a whole-file download, for a server without ranges; + /// `total` is 0 if the server doesn't say, and `received` is null when it has finished. + constructor(url, onDownload = () => {}) { + this.#url = url; + this.#onDownload = onDownload; + } + + async read(start, end, signal) { + if (this.#whole) return this.#whole.subarray(start, end); + const response = await fetch(this.#url, { headers: { Range: `bytes=${start}-${end - 1}` }, signal }); + if (!response.ok) { + throw new Error(`Could not load ${this.#url} (HTTP ${response.status}).`); + } + if (response.status === 200) { + this.#whole = await downloadWhole(response, this.#onDownload); + this.bytesFetched = this.#whole.length; + return this.#whole.subarray(start, end); + } + // A scene replaced while it's being read would mix two files, so start again from the top. + const etag = response.headers.get("etag"); + if (this.#etag && etag && etag !== this.#etag) { + location.reload(); + return new Promise(() => {}); + } + this.#etag = etag; + const bytes = new Uint8Array(await response.arrayBuffer()); + this.bytesFetched += bytes.length; + return bytes; + } +} + +/// Downloads a whole file with progress, for servers without Range support. +async function downloadWhole(response, onDownload) { + const total = Number(response.headers.get("content-length")) || 0; + const reader = response.body.getReader(); + const chunks = []; + let received = 0; + while (true) { + const { done, value } = await reader.read(); + if (done) break; + chunks.push(value); + received += value.length; + onDownload(received, total); + } + const bytes = new Uint8Array(received); + let offset = 0; + for (const chunk of chunks) { + bytes.set(chunk, offset); + offset += chunk.length; + } + onDownload(null, total); + return bytes; +} + +export async function inflate(bytes) { + const unpacked = new Blob([bytes]).stream().pipeThrough(new DecompressionStream("deflate-raw")); + return new Uint8Array(await new Response(unpacked).arrayBuffer()); +} + +/// Unpacks a block that should come to `limit` bytes, refusing to unpack more: a scene file comes +/// from outside. +export async function inflateAtMost(bytes, limit) { + const unpacked = new Blob([bytes]).stream().pipeThrough(new DecompressionStream("deflate-raw")); + const reader = unpacked.getReader(); + const out = new Uint8Array(limit); + let filled = 0; + while (true) { + const { done, value } = await reader.read(); + if (done) break; + if (filled + value.length > limit) { + await reader.cancel(); + throw new Error("a part of the scene unpacks larger than it says"); + } + out.set(value, filled); + filled += value.length; + } + return out.subarray(0, filled); +} + +/// How long one try at reading part of a scene file may take, stalled or not. +const READ_TIMEOUT_MS = 60000; + +/// Reads part of a scene file, trying a few times before giving up. +export async function readWithRetries(file, start, end) { + for (let attempt = 1; ; attempt++) { + try { + return await file.read(start, end, AbortSignal.timeout(READ_TIMEOUT_MS)); + } catch (error) { + if (attempt === 3) throw error; + await new Promise((resolve) => setTimeout(resolve, 500 * attempt)); + } + } +} + +/// Runs in workers: fetches one run of a scene file and unpacks its pages, off the main thread, +/// so that streaming doesn't cost the frame rate. +const FETCH_WORKER = ` +async function inflate(bytes) { + const unpacked = new Blob([bytes]).stream().pipeThrough(new DecompressionStream("deflate-raw")); + return new Uint8Array(await new Response(unpacked).arrayBuffer()); +} +// Many parts of a file in one response, one after another: scripts/serve.py. +async function many(url, spans) { + if (spans.length === 0) return new Uint8Array(0); + const ranges = spans.map(([start, end]) => start + "-" + (end - 1)).join(","); + const response = await fetch(url, { headers: { "X-Solstice-Ranges": ranges } }); + if (!response.headers.get("X-Solstice-Ranges")) { + throw new Error("this scene needs scripts/serve.py, which can send many parts at once"); + } + return new Uint8Array(await response.arrayBuffer()); +} +onmessage = async ({ data: { url, tablesUrl, ticket, run } }) => { + try { + const withRecords = run.filter((request) => request.clustersEnd > request.clustersStart); + const [stored, records] = await Promise.all([ + many(url, run.map((request) => [request.start, request.end])), + many(tablesUrl, withRecords.map((request) => [request.clustersStart, request.clustersEnd])), + ]); + let at = 0; + let recordsAt = 0; + const pages = await Promise.all(run.map(async (request) => { + const part = stored.subarray(at, at + request.end - request.start); + at += request.end - request.start; + let clusters = null; + if (request.clustersEnd > request.clustersStart) { + const length = request.clustersEnd - request.clustersStart; + clusters = records.slice(recordsAt, recordsAt + length); + recordsAt += length; + } + return { id: request.id, data: request.deflated ? await inflate(part) : part.slice(), clusters }; + })); + postMessage({ ticket, pages }, pages.flatMap((page) => + page.clusters ? [page.data.buffer, page.clusters.buffer] : [page.data.buffer])); + } catch (error) { + postMessage({ ticket, failed: run.map((request) => request.id), error: String(error) }); + } +}; +`; + +/// Fetches runs of pages in workers, each going to whichever has the least to do. +class WorkerFetcher { + #workers; + #busy; + #tickets = new Map(); + #next = 0; + #url; + #tablesUrl; + + constructor(url, tablesUrl, count, onPages, onFailed) { + this.#url = url; + this.#tablesUrl = new URL(tablesUrl, location.href).href; + const script = URL.createObjectURL(new Blob([FETCH_WORKER], { type: "text/javascript" })); + this.#busy = new Array(count).fill(0); + this.#workers = this.#busy.map((_, index) => { + const worker = new Worker(script); + worker.onmessage = ({ data }) => { + this.#busy[index]--; + this.#tickets.delete(data.ticket); + if (data.failed) { + console.warn(`Could not fetch part of the scene, and will retry: ${data.error}`); + onFailed(data.failed); + } else { + onPages(data.pages); + } + }; + return worker; + }); + } + + fetch(run) { + const index = this.#busy.indexOf(Math.min(...this.#busy)); + this.#busy[index]++; + const ticket = this.#next++; + this.#tickets.set(ticket, run); + this.#workers[index].postMessage({ + url: new URL(this.#url, location.href).href, tablesUrl: this.#tablesUrl, ticket, run, + }); + } +} + +/// Fetches what the viewer asks for, keeping the page responsive while it does. +export class Streamer { + // Browsers run about six connections per host over HTTP/1.1, so requests for parts of the file + // that are close together share one, as long as what lies between them is small. + static MERGE_GAP_BYTES = 256 * 1024; + static MERGE_MAX_BYTES = 8 * 1048576; + static RETRY_MS = 1000; + #viewer; + #file; + #workers = null; + #tablesStart; + // Pages being fetched at once. + #maxFetching; + // Pages asked for in one request, by the workers. Six requests at a time is all a browser sends. + #pagesPerRequest; + + /// `split`, for a scene read in parts, names its scene file and its `.web` tables file, whose + /// pages `workers` workers fetch; it needs `scripts/serve.py`. + constructor(viewer, file, tablesStart = 0, { maxFetching, workers, pagesPerRequest, split = null } = {}) { + this.#viewer = viewer; + this.#file = file; + this.#tablesStart = tablesStart; + this.#maxFetching = maxFetching || (split ? 1024 : 16); + this.#pagesPerRequest = pagesPerRequest || 64; + // Only for a scene read in parts, which is served with Range requests by something known. + if (split) { + this.#workers = new WorkerFetcher( + split.url, + split.tablesUrl, + workers || Math.min(8, navigator.hardwareConcurrency || 4), + (pages) => { + for (const { id, data, clusters } of pages) { + if (clusters) this.#viewer.deliver_page(id, data, clusters); + else this.#viewer.deliver(id, data); + } + }, + (ids) => { for (const id of ids) setTimeout(() => this.#viewer.request_failed(id), Streamer.RETRY_MS); }, + ); + } + } + + /// Call once per frame. + pump() { + const flat = this.#viewer.stream_requests(this.#maxFetching); + const requests = []; + for (let i = 0; i < flat.length; i += 6) { + requests.push({ + id: flat[i], start: flat[i + 1], end: flat[i + 2], deflated: flat[i + 3] !== 0, + clustersStart: this.#tablesStart + flat[i + 4], clustersEnd: this.#tablesStart + flat[i + 5], + }); + } + requests.sort((a, b) => a.start - b.start); + if (this.#workers) { + for (let i = 0; i < requests.length; i += this.#pagesPerRequest) { + this.#workers.fetch(requests.slice(i, i + this.#pagesPerRequest)); + } + return; + } + let run = []; + for (const request of requests) { + const last = run[run.length - 1]; + if (last && (request.start - last.end > Streamer.MERGE_GAP_BYTES + || request.end - run[0].start > Streamer.MERGE_MAX_BYTES)) { + this.#fetchRun(run); + run = []; + } + run.push(request); + } + if (run.length > 0) this.#fetchRun(run); + } + + async #fetchRun(run) { + const start = run[0].start; + const end = run[run.length - 1].end; + let stored; + try { + stored = await this.#file.read(start, end); + } catch (error) { + console.warn(`Could not fetch part of the scene, and will retry: ${error.message ?? error}`); + for (const request of run) { + setTimeout(() => this.#viewer.request_failed(request.id), Streamer.RETRY_MS); + } + return; + } + for (const request of run) this.#unpack(request, stored.subarray(request.start - start, request.end - start)); + } + + async #unpack(request, stored) { + try { + this.#viewer.deliver(request.id, request.deflated ? await inflate(stored) : stored); + } catch (error) { + console.warn(`Could not unpack part of the scene, and will retry: ${error.message ?? error}`); + setTimeout(() => this.#viewer.request_failed(request.id), Streamer.RETRY_MS); + } + } +} + +/// Hands over tables too large for a browser's memory a part at a time, each going on to the GPU. +/// `onProgress(done, total)` follows it, in bytes. +export async function loadExternalTables(viewer, tables, start, onProgress = () => {}) { + const sizes = viewer.external_tables(); + if (sizes.length === 0) return; + const [clusterCount, pinnedBytes] = sizes; + const CHUNK = 64 * 1048576; + const RECORD = 48; + const pageSizes = viewer.pinned_sizes(); + const recordCounts = viewer.pinned_cluster_counts(); + let done = 0; + const report = () => onProgress(done, pinnedBytes); + // Lets the GPU process catch up, so uploads don't pile up in memory. + const breathe = () => new Promise((resolve) => setTimeout(resolve, 0)); + + // The table holds each page's records in turn, and pinned pages come first. + const pinnedRecords = recordCounts.reduce((sum, count) => sum + count, 0) * RECORD; + const records = await readWithRetries(tables, start, start + pinnedRecords); + const pinnedStart = start + clusterCount * RECORD; + let page = 0; + let at = 0; + let recordsAt = 0; + while (page < pageSizes.length) { + let end = at; + let last = page; + while (last < pageSizes.length && (end === at || end + pageSizes[last] - at <= CHUNK)) { + end += pageSizes[last]; + last++; + } + const bytes = await readWithRetries(tables, pinnedStart + at, pinnedStart + end); + let inside = 0; + for (; page < last; page++) { + const length = recordCounts[page] * RECORD; + viewer.install_pinned( + page, + bytes.subarray(inside, inside + pageSizes[page]), + records.subarray(recordsAt, recordsAt + length), + ); + inside += pageSizes[page]; + recordsAt += length; + } + done += end - at; + at = end; + report(); + await breathe(); + } + viewer.finish_external_tables(); +} + +/// The adapter the viewer will be given. Chrome offers some GPUs only to pages asking for +/// WebGPU's "compatibility" feature level, though they can do all of core WebGPU, as its own +/// software adapter on an Android emulator does; the viewer asks for core. If no core adapter +/// is offered, such an adapter is taken, and its devices asked for core. Anywhere a core +/// adapter is offered, nothing changes. +export async function requestAdapter() { + const adapter = await navigator.gpu.requestAdapter(); + if (adapter) return adapter; + const CORE = "core-features-and-limits"; + const compatible = await navigator.gpu.requestAdapter({ featureLevel: "compatibility" }); + if (!compatible?.features.has(CORE)) return null; + const requestAdapter = GPU.prototype.requestAdapter; + GPU.prototype.requestAdapter = function (options = {}) { + return requestAdapter.call(this, { ...options, featureLevel: "compatibility" }); + }; + const requestDevice = GPUAdapter.prototype.requestDevice; + GPUAdapter.prototype.requestDevice = function (descriptor = {}) { + const requiredFeatures = [...(descriptor.requiredFeatures ?? []), CORE]; + return requestDevice.call(this, { ...descriptor, requiredFeatures }); + }; + console.info("using a GPU offered for WebGPU compatibility, which can do core WebGPU"); + compatibilityShim = true; + return compatible; +} + +/// Opens a scene file: reads its header and manifest, makes a viewer on `canvas` from them, hands +/// over any tables that come separately, and gives back the viewer, a streamer to pump once a +/// frame, and the file. `wasm` is the viewer's module (`WebViewer`, `header_bytes`, +/// `read_header`). `options`: `url`; `tablesUrl` for a scene read in parts, whose manifest comes +/// from its `.web` file, which leaves out the tables too large for a browser's memory and +/// carries them after it (pages still come from `url`); `geometryBudget`, `textureBudget`, +/// `unpackTextures`, `defaultLimits` as `WebViewer.create` takes them; `streaming`, the +/// streamer's options; and `onDownload`, `onTablesProgress` and `onStage` to follow it. +export async function openScene(wasm, canvas, options) { + const { WebViewer, header_bytes, read_header } = wasm; + const file = new SceneFile(options.url, options.onDownload); + const tables = options.tablesUrl ? new SceneFile(options.tablesUrl, options.onDownload) : file; + const [manifestOffset, manifestBytes] = read_header(await tables.read(0, header_bytes())); + const manifestEnd = manifestOffset + manifestBytes; + const manifest = await inflate(await tables.read(manifestOffset, manifestEnd)); + const [pagesOffset, pagesManifestBytes] = tables === file + ? [manifestOffset, manifestBytes] + : read_header(await file.read(0, header_bytes())); + options.onStage?.("Preparing the GPU…"); + const viewer = await WebViewer.create( + canvas, + manifest, + pagesOffset + pagesManifestBytes, + options.geometryBudget, + options.textureBudget, + Boolean(options.unpackTextures), + Boolean(options.defaultLimits), + ); + // A GPU given less than the renderer asks for has passes that do without. + const fallbacks = viewer.fallbacks(); + if (fallbacks) console.info(`fallbacks for this GPU's limits: ${fallbacks}`); + await loadExternalTables(viewer, tables, manifestEnd, options.onTablesProgress); + const streamer = new Streamer(viewer, file, manifestEnd, { + ...options.streaming, + split: options.tablesUrl ? { url: options.url, tablesUrl: options.tablesUrl } : null, + }); + return { viewer, streamer, file }; +} diff --git a/crates/solstice-asset/src/file.rs b/crates/solstice-asset/src/file.rs index 4cc344c..b1e3634 100644 --- a/crates/solstice-asset/src/file.rs +++ b/crates/solstice-asset/src/file.rs @@ -38,8 +38,8 @@ const SEA_TAG: [u8; 4] = *b"SEA "; /// Still water: a count of ponds, five numbers for each, then the water's description as text. const POND_TAG: [u8; 4] = *b"POND"; /// The optional section saying which entity of an editor project made which instances: how many -/// [`Source`]s, then each one's first instance, its end, and its id's length and text. Written -/// only for scenes baked from a project. +/// [`Source`]s, then each one's first instance, its end, its placement (16 floats, by column), +/// and its id's length and text. Written only for scenes baked from a project. const SOURCE_TAG: [u8; 4] = *b"SRCE"; /// The optional section holding the scene's gameplay: how many [`GameFile`]s, then each one's /// name and text. Written only for scenes that have gameplay. @@ -726,13 +726,13 @@ fn encode_gameplay(files: &[GameFile]) -> Vec { fn encode_sources(sources: &[Source]) -> Vec { let mut bytes = (sources.len() as u32).to_le_bytes().to_vec(); for source in sources { - for number in [ - source.instances.start, - source.instances.end, - source.id.len() as u32, - ] { + for number in [source.instances.start, source.instances.end] { bytes.extend_from_slice(&number.to_le_bytes()); } + for value in source.placement.to_cols_array() { + bytes.extend_from_slice(&value.to_le_bytes()); + } + bytes.extend_from_slice(&(source.id.len() as u32).to_le_bytes()); bytes.extend_from_slice(source.id.as_bytes()); } bytes @@ -747,17 +747,22 @@ fn decode_sources(mut bytes: &[u8], instances: u32) -> Result, Decod Ok(u32::from_le_bytes(*word)) } let count = number(&mut bytes)? as usize; - // Each takes at least twelve bytes, so a count beyond that is a lie, not a large map. - if count > bytes.len() / 12 { + // Each takes at least 76 bytes, so a count beyond that is a lie, not a large map. + if count > bytes.len() / 76 { return Err(DecodeError::BadSources); } let mut sources = Vec::with_capacity(count); for _ in 0..count { - let (start, end, len) = ( - number(&mut bytes)?, - number(&mut bytes)?, - number(&mut bytes)?, - ); + let (start, end) = (number(&mut bytes)?, number(&mut bytes)?); + let mut columns = [0.0; 16]; + for value in &mut columns { + *value = f32::from_bits(number(&mut bytes)?); + } + let placement = Mat4::from_cols_array(&columns); + if !placement.is_finite() { + return Err(DecodeError::BadSources); + } + let len = number(&mut bytes)?; let (id, rest) = bytes .split_at_checked(len as usize) .ok_or(DecodeError::BadSources)?; @@ -768,6 +773,7 @@ fn decode_sources(mut bytes: &[u8], instances: u32) -> Result, Decod sources.push(Source { id: String::from_utf8(id.to_vec()).map_err(|_| DecodeError::BadSources)?, instances: start..end, + placement, }); } Ok(sources) @@ -1609,10 +1615,12 @@ mod tests { Source { id: "a91fXq2b".into(), instances: 0..1, + placement: Mat4::from_translation(Vec3::new(1.0, 2.0, 3.0)), }, Source { id: "terrain".into(), instances: 1..count, + placement: Mat4::IDENTITY, }, ]; loaded.scene.sources = sources.clone(); @@ -1636,6 +1644,7 @@ mod tests { let good = encode_sources(&[Source { id: "a91fXq2b".into(), instances: 0..2, + placement: Mat4::IDENTITY, }]); assert!(decode_sources(&good, 2).is_ok()); // Cut short anywhere. @@ -1651,11 +1660,18 @@ mod tests { huge[..4].copy_from_slice(&u32::MAX.to_le_bytes()); assert_eq!(decode_sources(&huge, 2), Err(DecodeError::BadSources)); let mut long = good.clone(); - long[12..16].copy_from_slice(&u32::MAX.to_le_bytes()); + long[76..80].copy_from_slice(&u32::MAX.to_le_bytes()); assert_eq!(decode_sources(&long, 2), Err(DecodeError::BadSources)); // An id that isn't text, and a range that runs backwards. let mut bad_text = good.clone(); - bad_text[16] = 0xff; + bad_text[80] = 0xff; + assert_eq!(decode_sources(&bad_text, 2), Err(DecodeError::BadSources)); + let mut not_a_number = good.clone(); + not_a_number[12..16].copy_from_slice(&f32::NAN.to_le_bytes()); + assert_eq!( + decode_sources(¬_a_number, 2), + Err(DecodeError::BadSources) + ); assert_eq!(decode_sources(&bad_text, 2), Err(DecodeError::BadSources)); let mut backwards = good; backwards[4..8].copy_from_slice(&2u32.to_le_bytes()); diff --git a/crates/solstice-asset/src/scene.rs b/crates/solstice-asset/src/scene.rs index da91df3..d52b62b 100644 --- a/crates/solstice-asset/src/scene.rs +++ b/crates/solstice-asset/src/scene.rs @@ -274,13 +274,18 @@ pub struct StillWater { } /// Which entity of an editor project made which instances (`docs/editor.md`), so the editor can -/// turn a click on an instance into the thing to select. -#[derive(Clone, Debug, Default, PartialEq, Eq)] +/// turn a click on an instance into the thing to select, and move what it made together. +#[derive(Clone, Debug, Default, PartialEq)] pub struct Source { /// The entity's id in its project, or `terrain` or `circuit` for all that the scene's land /// made. pub id: String, pub instances: std::ops::Range, + /// Where the bake placed the entity: each of its instances is this times the instance's + /// place in the model. It holds what the project doesn't say, such as the height a model + /// was seated at on the ground, or the turn and scale an actor's file gives its mesh. + /// Identity for the land. + pub placement: glam::Mat4, } /// One text file of a scene's gameplay: an actor file, a script, the input actions, or the list diff --git a/crates/solstice-project/tests/fixture.rs b/crates/solstice-project/tests/fixture.rs new file mode 100644 index 0000000..f7275b3 --- /dev/null +++ b/crates/solstice-project/tests/fixture.rs @@ -0,0 +1,18 @@ +//! The fixture holds a scene with every kind of thing in it, as this crate writes it. The editor's +//! own writer (`apps/viewer/web/editor/project.js`) is held to the same file by +//! `apps/viewer/web/editor/test.mjs`, so a scene saved by either is byte for byte the same. + +use solstice_project::Scene; + +#[test] +fn the_fixture_reads_and_writes_back_unchanged() { + let text = include_str!("fixture.scene").replace("\r\n", "\n"); + let scene = Scene::parse(&text).unwrap(); + assert_eq!(scene.to_json(), text); + let kinds: Vec<&str> = scene.walk().iter().flat_map(|e| e.kinds()).collect(); + for kind in [ + "mesh", "actor", "light", "blocker", "wood", "clear", "path", "yard", "pond", + ] { + assert!(kinds.contains(&kind), "the fixture has no {kind}"); + } +} diff --git a/crates/solstice-project/tests/fixture.scene b/crates/solstice-project/tests/fixture.scene new file mode 100644 index 0000000..cf9171e --- /dev/null +++ b/crates/solstice-project/tests/fixture.scene @@ -0,0 +1,185 @@ +{ + "format": 1, + "note": "Every kind of thing a scene holds, for the project writers' tests.", + "texture_size": 2048, + "camera": { + "position": [66.0, 1.5, -41.0], + "yaw_radians": 2.31, + "pitch_radians": 0.03 + }, + "terrain": { + "size": 900.0, + "cells": 1024, + "height": 0.3, + "shore_x": 52.0 + }, + "land": { + "sand": 10.0, + "dirt": 5.0 + }, + "meadow": 75.0, + "sea": { + "level": -0.6, + "ocean": "coastal" + }, + "entities": [ + { + "id": "gtrgPV4G", + "name": "Ground", + "note": "Ground. Sand, dirt and grass.", + "children": [ + { + "id": "w3osAlZU", + "name": "Yard", + "yard": { + "from": [-21.0, -21.0], + "to": [21.0, 21.0] + } + }, + { + "id": "bIVSr8y5", + "name": "Path", + "path": { + "from": [23.0, 0.0], + "to": [58.0, -6.0], + "width": 3.2 + } + }, + { + "id": "H7cjZQV9", + "name": "Clear", + "transform": { + "position": [0.0, 0.0, 0.0] + }, + "clear": { + "radius": 33.0 + } + }, + { + "id": "Dir5OS4z", + "name": "Wood", + "transform": { + "position": [-58.0, 0.0, -38.0] + }, + "wood": { + "radius": 20.0, + "spacing": 7.0 + } + }, + { + "id": "9gnxh49i", + "name": "Pond", + "pond": { + "min": [-10.0, -10.0], + "max": [-4.0, -2.0], + "level": 0.5, + "water": "coastal" + } + } + ] + }, + { + "id": "gwAazR8m", + "name": "The fort", + "children": [ + { + "id": "owy2xVBC", + "name": "tower_round", + "transform": { + "position": [22.0, 0.0, 22.0] + }, + "mesh": { + "asset": "kit/fort.gltf", + "part": "tower_round" + } + }, + { + "id": "57MfCxtw", + "name": "tower_round", + "transform": { + "position": [22.0, 0.0, -22.0], + "rotation": [0.0, 90.0, 0.0] + }, + "mesh": { + "asset": "kit/fort.gltf", + "part": "tower_round", + "collide": "hull" + } + }, + { + "id": "S2nu9H6y", + "name": "statue", + "transform": { + "position": [-7.0, 0.0, 0.0], + "rotation": [12.5, 90.0, -3.25], + "scale": 2.4 + }, + "mesh": { + "asset": "scans/statue.gltf" + } + }, + { + "id": "0uAbJ4nE", + "name": "boulder", + "note": "half buried", + "transform": { + "position": [31.0, 0.0, -24.0], + "rotation": [0.0, 40.0, 0.0], + "scale": 2.2, + "ground": 0.2 + }, + "mesh": { + "asset": "scans/boulder.gltf" + } + }, + { + "id": "2gzKrlyn", + "name": "keeper", + "transform": { + "position": [2.0, 0.0, 3.0] + }, + "mesh": { + "asset": "people/keeper.glb", + "skinned": true + } + }, + { + "id": "jOHO1AzT", + "name": "Blocker", + "transform": { + "position": [-1.1, 0.19, 17.3] + }, + "blocker": { + "size": [0.4, 0.38, 3.0] + } + }, + { + "id": "2HGOWrcu", + "name": "gate", + "transform": { + "position": [20.7, 0.0, 0.0], + "rotation": [0.0, 90.0, 0.0] + }, + "actor": { + "asset": "cove/gate.actor", + "properties": { + "locked": "true", + "speed": "2" + } + } + }, + { + "id": "iEd2cCCm", + "name": "Light", + "transform": { + "position": [0.0, 2.0, 0.0] + }, + "light": { + "range": 16.0, + "intensity": [40.0, 14.0, 3.0] + } + } + ] + } + ] +} diff --git a/crates/solstice-render/shaders/editor/pick.wgsl b/crates/solstice-render/shaders/editor/pick.wgsl new file mode 100644 index 0000000..693372c --- /dev/null +++ b/crates/solstice-render/shaders/editor/pick.wgsl @@ -0,0 +1,42 @@ +// What is under one pixel of the screen, for the editor to select: the instance there and its +// depth, read from the visibility buffer after the frame resolves. One thread, and only on a +// frame the editor asks. + +// As `VisibleCluster` in `common/scene.wgsl`: what each visibility id indexes. +struct VisibleCluster { + instance: u32, + cluster: u32, +} + +struct Params { + pixel: vec2u, + width: u32, + _pad: u32, +} + +struct Picked { + // 1 if something was there, else 0 (sky, or outside the screen). + found: u32, + instance: u32, + // Reversed depth, as the visibility buffer holds it. + depth: f32, + _pad: u32, +} + +@group(0) @binding(0) var params: Params; +@group(0) @binding(1) var vis_depth: array; +@group(0) @binding(2) var vis_id: array; +@group(0) @binding(3) var visible: array; +@group(0) @binding(4) var picked: Picked; + +@compute @workgroup_size(1) +fn main() { + let index = params.pixel.y * params.width + params.pixel.x; + let depth = bitcast(vis_depth[index]); + if depth <= 0.0 { + picked = Picked(0u, 0u, 0.0, 0u); + return; + } + let entry = visible[vis_id[index] >> 7u]; + picked = Picked(1u, entry.instance, depth, 0u); +} diff --git a/crates/solstice-render/src/lib.rs b/crates/solstice-render/src/lib.rs index a554a09..b8da7cb 100644 --- a/crates/solstice-render/src/lib.rs +++ b/crates/solstice-render/src/lib.rs @@ -29,6 +29,7 @@ pub mod lightning; pub mod motion; pub mod ocean; pub mod particles; +pub mod pick; pub mod post; pub mod profiler; pub mod rain; diff --git a/crates/solstice-render/src/pick.rs b/crates/solstice-render/src/pick.rs new file mode 100644 index 0000000..435cc01 --- /dev/null +++ b/crates/solstice-render/src/pick.rs @@ -0,0 +1,173 @@ +//! Picking for the editor (`docs/editor.md`): which instance is under a pixel, and how far +//! away, read from the visibility buffer once the frame resolves. +//! +//! Its pipeline is made on the first pick, and a frame without a pick records nothing, so a +//! scene that is only looked at pays nothing for it. + +use crate::gpu::{Gpu, LayoutBuilder}; +use crate::shaders; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::{Arc, Mutex}; + +/// What a pick found. +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct Picked { + /// The instance under the pixel, or `None` for the sky. + pub instance: Option, + /// Its reversed depth, as the visibility buffer holds it: `near / distance along the view`. + pub depth: f32, +} + +/// Bytes of the result: found, instance, depth, padding. +const RESULT_BYTES: u64 = 16; + +struct Pipeline { + layout: wgpu::BindGroupLayout, + pipeline: wgpu::ComputePipeline, + params: wgpu::Buffer, + result: wgpu::Buffer, + staging: wgpu::Buffer, +} + +/// Picks waiting to be recorded, recorded and waiting to be read, and read. +#[derive(Default)] +pub struct Picker { + pipeline: Option, + /// A point to pick on the next frame, as fractions of the screen from its top left. + wanted: Option<(f32, f32)>, + /// Whether a pick was recorded and copied out, and its staging buffer not yet mapped. + recorded: bool, + /// Set by the map callback when the staging buffer can be read. + mapped: Arc, + /// Whether a map is in flight, so another pick waits for it. + busy: Arc, + result: Arc>>, +} + +impl Picker { + /// Asks for what is under `point`, as fractions of the screen's width and height from its + /// top left, on the next frame. A later request before then replaces it. + pub fn request(&mut self, point: (f32, f32)) { + self.wanted = Some(point); + } + + /// The result of the last pick, once, when it has been read back. + pub fn take(&mut self) -> Option { + self.read(); + self.result.lock().ok()?.take() + } + + /// Records the pick asked for, if any, after the frame's visibility buffer resolves. + pub fn record( + &mut self, + gpu: &Gpu, + encoder: &mut wgpu::CommandEncoder, + vis_depth: &wgpu::Buffer, + vis_ids: &wgpu::Buffer, + visible: &wgpu::Buffer, + size: (u32, u32), + ) { + if self.busy.load(Ordering::Acquire) || self.recorded { + return; + } + let Some((x, y)) = self.wanted.take() else { + return; + }; + let pipeline = self.pipeline.get_or_insert_with(|| Pipeline::new(gpu)); + let pixel = |t: f32, size: u32| ((t.clamp(0.0, 1.0) * size as f32) as u32).min(size - 1); + let pixel = [pixel(x, size.0), pixel(y, size.1), size.0, 0]; + gpu.queue + .write_buffer(&pipeline.params, 0, bytemuck::cast_slice(&pixel)); + let group = gpu.bind_group( + "pick", + &pipeline.layout, + &[ + pipeline.params.as_entire_binding(), + vis_depth.as_entire_binding(), + vis_ids.as_entire_binding(), + visible.as_entire_binding(), + pipeline.result.as_entire_binding(), + ], + ); + { + let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor { + label: Some("pick"), + timestamp_writes: None, + }); + pass.set_pipeline(&pipeline.pipeline); + pass.set_bind_group(0, &group, &[]); + pass.dispatch_workgroups(1, 1, 1); + } + encoder.copy_buffer_to_buffer(&pipeline.result, 0, &pipeline.staging, 0, RESULT_BYTES); + self.recorded = true; + } + + /// Starts reading back a recorded pick, once its frame is submitted. + pub fn request_map(&mut self) { + let Some(pipeline) = &self.pipeline else { + return; + }; + if !std::mem::take(&mut self.recorded) { + return; + } + self.busy.store(true, Ordering::Release); + let (mapped, busy) = (self.mapped.clone(), self.busy.clone()); + pipeline + .staging + .slice(..) + .map_async(wgpu::MapMode::Read, move |result| match result { + Ok(()) => mapped.store(true, Ordering::Release), + Err(_) => busy.store(false, Ordering::Release), + }); + } + + fn read(&mut self) { + let Some(pipeline) = &self.pipeline else { + return; + }; + if !self.mapped.swap(false, Ordering::AcqRel) { + return; + } + let words: [u32; 4] = { + let view = pipeline + .staging + .slice(..) + .get_mapped_range() + .expect("a mapped buffer is readable"); + bytemuck::pod_read_unaligned(&view[..RESULT_BYTES as usize]) + }; + pipeline.staging.unmap(); + self.busy.store(false, Ordering::Release); + if let Ok(mut result) = self.result.lock() { + *result = Some(Picked { + instance: (words[0] != 0).then_some(words[1]), + depth: f32::from_bits(words[2]), + }); + } + } +} + +impl Pipeline { + fn new(gpu: &Gpu) -> Self { + let layout = LayoutBuilder::new() + .uniform() + .storage_read() + .storage_read() + .storage_read() + .storage_write() + .build(gpu, "pick"); + let module = shaders::module(&gpu.device, "editor/pick.wgsl"); + Self { + pipeline: gpu.compute_pipeline("pick", &module, "main", &[&layout]), + layout, + params: gpu.uniform_buffer("pick params", 16), + result: gpu.storage_buffer("pick result", RESULT_BYTES, wgpu::BufferUsages::COPY_SRC), + staging: gpu.device.create_buffer(&wgpu::BufferDescriptor { + label: Some("pick staging"), + size: RESULT_BYTES, + usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST, + mapped_at_creation: false, + }), + } + } +} diff --git a/crates/solstice-render/src/renderer.rs b/crates/solstice-render/src/renderer.rs index 2415de9..c212756 100644 --- a/crates/solstice-render/src/renderer.rs +++ b/crates/solstice-render/src/renderer.rs @@ -321,6 +321,8 @@ pub struct Renderer { view_slots: ViewSlots, cull: CullPipelines, main_work: CullWork, + /// The editor's picks; idle, and free, unless one is asked for. + picker: crate::pick::Picker, aux_work: CullWork, aux_cull_scene: wgpu::BindGroup, aux_raster: RasterBindings, @@ -616,6 +618,17 @@ impl Renderer { self.scene.skins.set(pose, bones, true) } + /// Asks what is under a point of the screen, as fractions of its width and height from the + /// top left, on the next frame. [`Self::take_pick`] gives the answer a frame or two later. + pub fn request_pick(&mut self, x: f32, y: f32) { + self.picker.request((x, y)); + } + + /// What the last pick found, once it has been read back. + pub fn take_pick(&mut self) -> Option { + self.picker.take() + } + /// An instance's bounding sphere in the world, as its centre and radius. pub fn instance_bounds(&self, instance: u32) -> Option<(Vec3, f32)> { self.scene.instance_table.world_sphere(instance) @@ -758,6 +771,7 @@ impl Renderer { view_slots, cull, main_work, + picker: Default::default(), aux_work, aux_cull_scene, aux_raster, @@ -1288,6 +1302,14 @@ impl Renderer { &self.rain.surface_group, render_size, ); + self.picker.record( + gpu, + &mut encoder, + &sized.visibility.depth, + &sized.visibility.ids, + &self.main_work.visible, + render_size, + ); // Lighting. mark(&self.profiler, &mut encoder, section::CLOUDS_ON_SCREEN); @@ -1459,6 +1481,7 @@ impl Renderer { self.particles.map_stats(); self.aux_work.map_stats(); self.streamer.map_requests(); + self.picker.request_map(); if let Some(profiler) = &mut self.profiler { profiler.request_map(); } diff --git a/crates/solstice-render/src/shaders.rs b/crates/solstice-render/src/shaders.rs index f238470..a103d75 100644 --- a/crates/solstice-render/src/shaders.rs +++ b/crates/solstice-render/src/shaders.rs @@ -124,6 +124,7 @@ pub const SOURCES: &[(&str, &str)] = shader_table![ "post/exposure.wgsl", "post/bloom.wgsl", "post/tonemap.wgsl", + "editor/pick.wgsl", ]; /// Entry-point files: the ones compiled into shader modules. Everything else exists @@ -131,6 +132,7 @@ pub const SOURCES: &[(&str, &str)] = shader_table![ #[cfg(test)] pub const ENTRY_POINTS: &[&str] = &[ "vg/cull.wgsl", + "editor/pick.wgsl", "wind/field.wgsl", "wind/sway_probe.wgsl", "rain/map.wgsl", diff --git a/crates/solstice-render/tests/gpu.rs b/crates/solstice-render/tests/gpu.rs index 3b0691c..7a9942f 100644 --- a/crates/solstice-render/tests/gpu.rs +++ b/crates/solstice-render/tests/gpu.rs @@ -6152,3 +6152,55 @@ fn indirect_light_leaves_no_trail_behind_what_moves() { "the ball left a trail in the indirect light: {trail:.1} on a floor of {floor:.1}" ); } + +/// The editor's pick finds the instance under a point of the screen, and nothing on the sky. +#[test] +fn a_pick_finds_the_instance_under_a_point() { + let Some(gpu) = request_gpu() else { return }; + let ball = build_virtual_mesh(&sphere(4), &BuildOptions::default()); + // Three balls in a row across the view: instance 0 left, 1 in the middle, 2 right. + let scene = SceneAsset { + meshes: vec![ball], + materials: vec![white_material()], + instances: [-3.0, 0.0, 3.0] + .iter() + .map(|&x| instance(0, Mat4::from_translation(Vec3::new(x, 0.0, 0.0)))) + .collect(), + ..Default::default() + }; + let camera = Camera { + position: Vec3::new(0.0, 0.0, 10.0), + ..Default::default() + }; + let size = 256; + let mut renderer = Renderer::new(&gpu, &paginate(&scene), FORMAT, Default::default()); + let target = test_target(&gpu, size); + let view = target.create_view(&Default::default()); + let mut pick = |x: f32, y: f32| { + renderer.request_pick(x, y); + for _ in 0..4 { + renderer.render(&gpu, &camera, &darkness(), &view, (size, size), 1.0 / 60.0); + gpu.device + .poll(wgpu::PollType::wait_indefinitely()) + .unwrap(); + if let Some(picked) = renderer.take_pick() { + return picked; + } + } + panic!("the pick at {x}, {y} never came back"); + }; + // A frame first, so the depth history exists. + pick(0.5, 0.5); + let middle = pick(0.5, 0.5); + assert_eq!(middle.instance, Some(1)); + // The ball's near face is 9 m away: reversed depth is near / distance. + let distance = camera.near / middle.depth; + assert!( + (distance - 9.0).abs() < 0.1, + "the middle ball is {distance} m away" + ); + // 3 m left of centre at 10 m, with a 55 degree view, is about 0.2 of the screen across. + assert_eq!(pick(0.21, 0.5).instance, Some(0)); + assert_eq!(pick(0.79, 0.5).instance, Some(2)); + assert_eq!(pick(0.5, 0.05).instance, None, "the sky above them"); +} diff --git a/docs/editor-api.md b/docs/editor-api.md new file mode 100644 index 0000000..6491170 --- /dev/null +++ b/docs/editor-api.md @@ -0,0 +1,293 @@ +# Editor API + +The editor's page (`editor.html`, design in `docs/editor.md`) exposes every command it has to +agents. The panels, the keyboard and the gizmo act through the same commands, so an agent can do +whatever a person can, and a person sees it happen and can undo it. + +## Calling it + +From an agent driving the page with a browser MCP, such as Claude in Chrome's `javascript_tool` +or the `evaluate` tool of Playwright's or Chrome DevTools' MCP servers: + +```js +await solstice.call("scene.objects", { filter: "statue" }) +// → { ok: true, result: { total: 1, objects: [{ id: "nohUSzZ9", name: "gothic_statue", ... }] } } +await solstice.call("object.move", { ids: ["nohUSzZ9"], by: [0, 0, 3] }) +await solstice.call("history.undo") +solstice.help() // every command, its arguments as JSON Schema, and an example +solstice.help("object.move") // one +solstice.list() // the names +solstice.version // 1, raised when a command changes +``` + +Every call returns `{ ok: true, result }` or `{ ok: false, error: { code, message } }`, and never +throws. Error codes are `unknown_command`, `bad_arguments` (a missing, misspelt or mistyped +argument, named in the message), `unknown_id`, `no_transform`, `nothing_selected`, +`nothing_to_frame`, `not_drawing` (a `pick` or `wait` while the tab is hidden, which draws no +frames: bring it to the front) and `failed`. + +Changes an agent makes are steps in the same history as a person's, marked `agent` in +`history.list`, and undone the same way. + +**WebMCP.** Where the browser offers `navigator.modelContext` +([WebMCP](https://github.com/webmachinelearning/webmcp)), the page also registers each command +as a tool with the same description and schema, its dots made underscores (`object_move`). + +**What it can reach.** Only the scene open in that tab: no network, no files beyond the scene's +own project, and nothing given to it runs as code. + +## Conventions + +- Positions are metres, in the world: +Y is up, the sea lies towards +X in Cove. +- Rotations are degrees about X, Y and Z, applied as the bake applies them: yaw about Y, then + pitch about the turned X, then roll about the turned Z. The camera's yaw and pitch are radians, + as the viewer's are; yaw 0 looks along -Z. +- Entities are named by their id, which never changes. Names are for people and may repeat. +- A model seated on the ground (`on_ground` in `scene.objects`) shows the height the bake gave + it. Moving it keeps that height, and drops its seat: the project then says the height. + +## A session + +```js +const { result: { objects: [statue] } } = await solstice.call("scene.objects", { filter: "gothic" }); +await solstice.call("selection.set", { ids: [statue.id] }); +await solstice.call("camera.frame", {}); +await solstice.call("object.move", { ids: [statue.id], by: [0, 0, 3] }); +await solstice.call("object.rotate", { ids: [statue.id], by: [0, 45, 0] }); +await solstice.call("wait", { settled: true }); +await solstice.call("stats.frame"); // fps, frame time, triangles, GPU errors... +await solstice.call("log.read", { level: "error" }); +await solstice.call("history.undo"); +``` + +## Commands + +### `scene.info` + +The scene's name, how many entities and instances it has, whether it can be saved, and the API's version. + +No arguments. + +### `scene.objects` + +The scene's entities, parents before children: id, name, kind, parent, position, rotation (degrees), scale, and how many instances draw it. Paged. + +| Argument | Type | Needed | Meaning | +|---|---|---|---| +| `filter` | string | | Only those whose name or id holds this text (any case). | +| `kind` | string | | Only this kind: mesh, actor, light, blocker, wood, clear, path, yard, pond or folder. | +| `offset` | number | | Skip this many (default 0). | +| `limit` | number | | At most this many (default 100, at most 1000). | + +```js +await solstice.call("scene.objects", {"filter":"statue"}) +``` + +### `object.get` + +One entity: everything scene.objects gives, its note, and its components as the project holds them. + +| Argument | Type | Needed | Meaning | +|---|---|---|---| +| `id` | string | yes | The entity's id, as scene.objects gives it. | + +### `object.set` + +Sets an entity's fields: position, rotation (degrees about X, Y, Z), scale, name, note, or hidden (in the editor only). One undo step. + +| Argument | Type | Needed | Meaning | +|---|---|---|---| +| `id` | string | yes | The entity's id, as scene.objects gives it. | +| `position` | [x, y, z] | | Where it is, in metres. | +| `rotation` | [x, y, z] | | Degrees about X, Y and Z: yaw about Y, then pitch, then roll. | +| `scale` | number | | Uniform scale, above 0. | +| `name` | string | | Its name in the outliner. | +| `note` | string | | What it is for. | +| `hidden` | boolean | | Hidden in the editor's viewport. Not saved. | + +```js +await solstice.call("object.set", {"id":"a91fXq2b","position":[-7,0,2]}) +``` + +### `object.move` + +Moves entities by an offset, or to a position, in metres. One undo step. + +| Argument | Type | Needed | Meaning | +|---|---|---|---| +| `ids` | string[] | | The entities to change; the selection if left out. | +| `by` | [x, y, z] | | How far to move, in metres along X, Y and Z. | +| `to` | [x, y, z] | | Where to put them. | + +```js +await solstice.call("object.move", {"ids":["a91fXq2b"],"by":[0,0,2]}) +``` + +### `object.rotate` + +Turns entities: `by` degrees about the world's X, Y and Z axes (applied in that order), or `to` a rotation. One undo step. + +| Argument | Type | Needed | Meaning | +|---|---|---|---| +| `ids` | string[] | | The entities to change; the selection if left out. | +| `by` | [x, y, z] | | Degrees to turn about the world's X, then Y, then Z axis. | +| `to` | [x, y, z] | | The rotation to set: degrees about X, Y and Z, as object.set takes it. | + +```js +await solstice.call("object.rotate", {"by":[0,90,0]}) +``` + +### `object.scale` + +Scales entities evenly: `by` a factor, or `to` a scale. One undo step. + +| Argument | Type | Needed | Meaning | +|---|---|---|---| +| `ids` | string[] | | The entities to change; the selection if left out. | +| `by` | number | | A factor, above 0. | +| `to` | number | | The scale to set, above 0. | + +```js +await solstice.call("object.scale", {"by":1.5}) +``` + +### `selection.get` + +What is selected, as scene.objects describes it. + +No arguments. + +### `selection.set` + +Selects entities by id (an empty list clears the selection), as clicking them does. + +| Argument | Type | Needed | Meaning | +|---|---|---|---| +| `ids` | string[] | yes | The entities to select. | + +```js +await solstice.call("selection.set", {"ids":["a91fXq2b"]}) +``` + +### `camera.get` + +The viewport's camera: position, yaw and pitch (radians; yaw 0 looks along -Z), field of view (degrees) and fly speed (m/s). + +No arguments. + +### `camera.set` + +Moves the viewport's camera: a position, a yaw and pitch (radians), or a point to look at. + +| Argument | Type | Needed | Meaning | +|---|---|---|---| +| `position` | [x, y, z] | | Where the camera is. | +| `yaw` | number | | Radians about Y; 0 looks along -Z. | +| `pitch` | number | | Radians above the horizon. | +| `look_at` | [x, y, z] | | A point to face, instead of yaw and pitch. | +| `speed` | number | | Fly speed, metres a second. | + +```js +await solstice.call("camera.set", {"position":[40,6,20],"look_at":[0,2,0]}) +``` + +### `camera.frame` + +Moves the camera to see entities whole (the selection if no ids), as F does. + +| Argument | Type | Needed | Meaning | +|---|---|---|---| +| `ids` | string[] | | The entities to frame; the selection if left out. | + +### `pick` + +What is under a point of the viewport, given as fractions of its width and height from the top left: the entity (null for the land or sky), the instance and the point hit. Selects nothing. + +| Argument | Type | Needed | Meaning | +|---|---|---|---| +| `x` | number | yes | 0 at the left edge, 1 at the right. | +| `y` | number | yes | 0 at the top, 1 at the bottom. | + +```js +await solstice.call("pick", {"x":0.5,"y":0.5}) +``` + +### `history.undo` + +Undoes the last change, by anyone. + +No arguments. + +### `history.redo` + +Redoes the last change undone. + +No arguments. + +### `history.list` + +The changes that can be undone (oldest first) and redone (next first), each with who made it: user or agent. + +No arguments. + +### `env.set` + +The time of day (hours, 0 to 24), the weather (by name, or `changing`), and the ponds (x0,z0,x1,z1,level; with ; between). Not saved yet. + +| Argument | Type | Needed | Meaning | +|---|---|---|---| +| `time` | number | | Hours, 0 to 24. | +| `weather` | string | | changing, or a weather's name: env.weathers lists them. | +| `ponds` | string | | Ponds as x0,z0,x1,z1,level, with ; between them. | + +```js +await solstice.call("env.set", {"time":18.5,"weather":"fair"}) +``` + +### `env.weathers` + +The names env.set takes for the weather. + +No arguments. + +### `stats.frame` + +How the viewport is drawing: frames a second, milliseconds a frame, triangles, clusters, instances, geometry pages, megabytes fetched, GPU errors and any fallbacks for this GPU. + +No arguments. + +### `log.read` + +The output log: the editor's messages, warnings and errors, each with a number; `since` gives only those after one. + +| Argument | Type | Needed | Meaning | +|---|---|---|---| +| `since` | number | | Only entries numbered above this. | +| `level` | string | | Only info, warn or error. | + +### `wait` + +Resolves after some frames have been drawn, or once streaming has settled, so stats and screenshots show a finished frame. + +| Argument | Type | Needed | Meaning | +|---|---|---|---| +| `frames` | number | | Frames to wait (default 2, at most 600). | +| `settled` | boolean | | Wait until no geometry has arrived for half a second (at most 30 s). | + +### `project.get` + +The scene's project file as it would be saved, and whether it has changes not yet saved. + +No arguments. + +### `gizmo.set` + +The gizmo: its mode (move, rotate, scale), its space (world, local), and snapping (on, and its steps). + +| Argument | Type | Needed | Meaning | +|---|---|---|---| +| `mode` | string | | move, rotate or scale. | +| `space` | string | | world or local. | +| `snap` | boolean | | Whether drags snap. | +| `move_step` | number | | Metres a move snaps to. | +| `angle_step` | number | | Degrees a turn snaps to. | diff --git a/docs/editor.md b/docs/editor.md index 05b595d..23e7b19 100644 --- a/docs/editor.md +++ b/docs/editor.md @@ -530,39 +530,56 @@ etc.) and no glue is needed at all. A standalone MCP server is not needed and no ## Phases -Each phase is one or more reviewable PRs, each demonstrated in Chrome on the 5080 and checked +The editor is for making scenes and games from nothing, as Unreal's and Unity's are: a blank +terrain to begin, then land, water, trees, models, lights, weather, actors and their scripts, +all made and changed in the browser. Editing the site's own scenes comes with it, not instead. +Every tool is a command as well, so an agent can build a scene as a person does: sculpt, +plant, place, script and play. + +Each phase is one or more reviewable PRs, each shown working in Chrome on the 5080 and checked on a phone. -1. **Project format and first slice** (this stage's goal), as three PRs: - 1. The project format (`solstice-project` crate: types, read, write, schema tests), - `bake --convert` and `bake --project`, with `SRCE` written; Cove converted, and baking its - project proven to give the same scene as its text. - 2. `editor.html` and the `editor` build: opens Cove's project and baked scene (the loader - moves out of `index.html` into a shared module both pages import); viewport with fly and - orbit camera, click to select, move/rotate/scale gizmo with snapping, outliner, details - panel with transform fields, undo and redo, `F` to frame, autosave to OPFS. - 3. The command API (bold rows) on `window.solstice` and WebMCP, and `docs/editor-api.md`. +1. **Project format and first slice.** + 1. The project format, `bake --convert` and `bake --project`, with `SRCE` (PR #76). + 2. `editor.html` and its build: open a scene and its project, a viewport with fly and orbit + cameras, GPU picking, move/rotate/scale gizmo with snapping, outliner, details, undo and + redo, frame, autosave in the browser, save to a file, and the command API on + `window.solstice` and WebMCP (`docs/editor-api.md`). **Milestone**: Claude, through Claude in Chrome, opens the editor on Cove, lists the - courtyard's entities, moves the statue, reads frame stats, undoes, and the user watches it - happen. -2. **A real workflow, and baking in the browser.** `solstice-bake` as a library in pieces with - the content-hash cache, run in a Web Worker; Bake in the editor writes the same file the PC - does (tested byte for byte). Duplicate and delete (renderer: room to add instances after - load), box select, multi-select editing, End to ground, content browser of the project's - meshes, weather/time/water panels, output log, `view.capture`, open a folder on disk, zip - in and out. Play-in-editor with colliders where things now stand. **Milestone**: rearrange - the Cove's courtyard, play through the gate, bake in the browser and load the result in the - viewer; open the same folder natively and `bake --project` gives the same file. -3. **Import.** glTF drop-in, baked in the worker; renderer appends meshes, materials and - textures; content browser thumbnails. **Milestone**: drop a Poly Haven scan on the page and - place it within ten seconds. -4. **Land.** Terrain sculpt and paint, paths and yards, foliage painting and generator shapes, - ponds and lights with handles. **Milestone**: build a small island scene from the template. -5. **Games.** Actors and scripts in the editor, Simulate, a script editor with errors in place, - the player start, input maps. **Milestone**: make the gate puzzle from scratch in the browser. -6. **Polish to the bar.** Orthographic views, layouts, the phone layout's gestures, the - shortcut sheet, and a pass against the table above. + courtyard's entities, moves the statue, reads frame stats and undoes, while you watch. +2. **A new scene from blank terrain.** File ▸ New makes a project from a template: terrain, + sea, sky and a camera. The bake runs in the browser: `solstice-bake` as a library, in a Web + Worker, for the terrain, its land bands, the sea and the meadow. The terrain's and the + land's settings are edited in the details panel and rebuilt as you change them. The project + is kept in the browser or in a folder on disk, and Bake writes the scene file the viewer + plays, the same file `bake --project` writes natively. Commands: `project.new`, `bake.run`, + `bake.status`, `terrain.set`, `env.set` saved with the scene. + **Milestone**: from an empty page, make an island with sand, grass and sea, save it, reopen + it, and open it in the viewer; an agent does the same through the API. +3. **Trees, water and weather.** Woods, meadows and clearings as shapes with handles, planted + and regrown in the worker, area by area; tree species and grass from the built-in ones and + from species files, edited in a panel; ponds with handles; the scene's weather and time of + day saved with it. Commands: `foliage.*`, `species.*`, `pond.*`. + **Milestone**: plant a wood with a clearing and a pond on the island. +4. **Placing things.** A content browser of the built-in models, the scans the site's scenes use, + and glTF files dropped on the page and baked in the worker; drag into the viewport onto the + ground; duplicate, delete, box select, End to the ground; lights with handles. The renderer + takes new meshes, materials, textures and instances after load. Commands: `asset.import`, + `object.place`, `object.duplicate`, `object.delete`, `light.*`. + **Milestone**: furnish the island with a few Poly Haven scans and a lamp-lit hut. +5. **Games and scripting.** Actors placed from `.actor` files and new ones made in the editor; + their properties in the details panel; a script panel for their Starlark with errors marked + where they are, reloaded as you type; input maps; a player start; Play and Simulate in the + viewport, with what was edited kept, and the scripts' messages in the output log. Commands: + `actor.*`, `script.read`, `script.write`, `play.start`, `play.stop`, `play.input`. + **Milestone**: make the gate puzzle from scratch on the island, and play it; an agent writes + and fixes a script by reading its errors. +6. **Sculpting and painting.** Terrain brushes (raise, lower, smooth, flatten, noise) and + painting sand, dirt and grass, rebuilt tile by tile; paths and yards with handles. + **Milestone**: carve a valley and a road through the island. +7. **Polish to the bar.** Orthographic views, docking layouts, the phone layout's gestures, the + shortcut sheet, selection outlines in the renderer, and a pass against the table above. ## Coordination diff --git a/scripts/build-web.sh b/scripts/build-web.sh index efe5931..85110a8 100644 --- a/scripts/build-web.sh +++ b/scripts/build-web.sh @@ -26,7 +26,13 @@ cargo build --release --target wasm32-unknown-unknown -p viewer --lib --no-defau "$bindgen" --target web --no-typescript --out-dir dist/pkg target/wasm32-unknown-unknown/release/solstice_viewer.wasm RUSTFLAGS="-C target-feature=+simd128" cargo build --release --target wasm32-unknown-unknown -p viewer --lib --target-dir target/web-play "$bindgen" --target web --no-typescript --out-dir dist/play target/web-play/wasm32-unknown-unknown/release/solstice_viewer.wasm -cp apps/viewer/web/index.html dist/ +# The editor (docs/editor.md): a third build, of the plain viewer with the editor's API, which +# only editor.html loads. Built after the plain one in the same folder, so only the viewer's own +# crate builds again. +cargo build --release --target wasm32-unknown-unknown -p viewer --lib --no-default-features --features editor +"$bindgen" --target web --no-typescript --out-dir dist/editor-wasm target/wasm32-unknown-unknown/release/solstice_viewer.wasm +cp apps/viewer/web/index.html apps/viewer/web/editor.html apps/viewer/web/loader.js dist/ +cp -r apps/viewer/web/editor dist/ # Scene files are already compressed where it helps, part by part, so that the page can fetch # any part alone. Hard links keep big scenes from taking disk space twice. for scene in assets/*.solstice; do @@ -34,6 +40,11 @@ for scene in assets/*.solstice; do [ -e "$scene" ] || continue ln -f "$scene" "dist/assets/$(basename "$scene")" 2>/dev/null || cp "$scene" "dist/assets/" done +# Each scene's project scene, for the editor to open beside its bake. +for project in assets/*.scene; do + [ -e "$project" ] || continue + cp "$project" dist/assets/ +done # Games kept as folders of text, to play on scenes baked without them (?game=NAME): each # folder in scenes/ with a scene.game of its own. for game in scenes/*/scene.game; do