spi3der 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/APP.md +40 -0
- package/Dockerfile +4 -0
- package/MCP.md +149 -0
- package/PLAYER.md +136 -0
- package/README.md +35 -2
- package/api/mcp.mjs +31 -0
- package/api/store.mjs +158 -0
- package/bin/spi3der.mjs +20 -0
- package/emulator.html +17 -0
- package/engine/8fa668821759/bevel.js +265 -0
- package/engine/8fa668821759/camera.js +76 -0
- package/engine/8fa668821759/character.js +1019 -0
- package/engine/8fa668821759/check.js +83 -0
- package/engine/8fa668821759/csg.js +342 -0
- package/engine/8fa668821759/edit.js +48 -0
- package/engine/8fa668821759/galaxy.js +265 -0
- package/engine/8fa668821759/gl.js +798 -0
- package/engine/8fa668821759/gpu.js +1356 -0
- package/engine/8fa668821759/index.js +48 -0
- package/engine/8fa668821759/instances.js +41 -0
- package/engine/8fa668821759/joints.js +355 -0
- package/engine/8fa668821759/kernel-bytes.js +2 -0
- package/engine/8fa668821759/kernel.js +82 -0
- package/engine/8fa668821759/lathe.js +87 -0
- package/engine/8fa668821759/material.js +19 -0
- package/engine/8fa668821759/mesh.js +131 -0
- package/engine/8fa668821759/order.js +125 -0
- package/engine/8fa668821759/pick.js +85 -0
- package/engine/8fa668821759/place.js +17 -0
- package/engine/8fa668821759/planet.js +376 -0
- package/engine/8fa668821759/rig.js +417 -0
- package/engine/8fa668821759/saw.js +121 -0
- package/engine/8fa668821759/sky.js +428 -0
- package/engine/8fa668821759/svg.js +239 -0
- package/engine/8fa668821759/text.js +231 -0
- package/engine/8fa668821759/triangulate.js +72 -0
- package/engine/8fa668821759/types.js +2 -0
- package/engine/8fa668821759/vec.js +22 -0
- package/engine/8fa668821759/version.js +7 -0
- package/engine/8fa668821759/vrtsh.js +354 -0
- package/engine/8fa668821759/wire.js +346 -0
- package/favicon.svg +15 -0
- package/help.md +289 -0
- package/icons/apple-touch-icon.png +0 -0
- package/icons/favicon-32.png +0 -0
- package/icons/icon-192.png +0 -0
- package/icons/icon-512.png +0 -0
- package/icons/icon-maskable-512.png +0 -0
- package/icons/icon-maskable.svg +13 -0
- package/icons/icon.svg +15 -0
- package/index.html +13730 -0
- package/manifest.webmanifest +37 -0
- package/mcp/engine/bevel.js +265 -0
- package/mcp/engine/camera.js +76 -0
- package/mcp/engine/character.js +1019 -0
- package/mcp/engine/check.js +83 -0
- package/mcp/engine/csg.js +342 -0
- package/mcp/engine/edit.js +48 -0
- package/mcp/engine/galaxy.js +265 -0
- package/mcp/engine/gl.js +798 -0
- package/mcp/engine/gpu.js +1356 -0
- package/mcp/engine/index.js +48 -0
- package/mcp/engine/instances.js +41 -0
- package/mcp/engine/joints.js +355 -0
- package/mcp/engine/kernel-bytes.js +2 -0
- package/mcp/engine/kernel.js +82 -0
- package/mcp/engine/lathe.js +87 -0
- package/mcp/engine/material.js +19 -0
- package/mcp/engine/mesh.js +131 -0
- package/mcp/engine/order.js +125 -0
- package/mcp/engine/pick.js +85 -0
- package/mcp/engine/place.js +17 -0
- package/mcp/engine/planet.js +376 -0
- package/mcp/engine/rig.js +417 -0
- package/mcp/engine/saw.js +121 -0
- package/mcp/engine/sky.js +428 -0
- package/mcp/engine/svg.js +239 -0
- package/mcp/engine/text.js +231 -0
- package/mcp/engine/triangulate.js +72 -0
- package/mcp/engine/types.js +2 -0
- package/mcp/engine/vec.js +22 -0
- package/mcp/engine/version.js +7 -0
- package/mcp/engine/vrtsh.js +354 -0
- package/mcp/engine/wire.js +346 -0
- package/mcp/http.js +292 -0
- package/mcp/live.js +95 -0
- package/mcp/package.json +10 -0
- package/mcp/scene.js +1027 -0
- package/mcp/serve.js +87 -0
- package/mcp/server.js +97 -0
- package/media/face-of-spider.png +0 -0
- package/media/spider-paint-2015.png +0 -0
- package/media/spider-web.png +0 -0
- package/models/deepsky-lark.scene.json +1 -0
- package/models/deepsky.scene.json +1 -0
- package/models/globe.scene.json +1 -0
- package/models/lark-4.scene.json +1 -0
- package/models/lark.game.json +14 -0
- package/models/spider-build-v2.md +215 -0
- package/models/spider-build-v2.mjs +355 -0
- package/models/spider-build-v2.schema.json +1001 -0
- package/nginx.conf +12 -0
- package/package.json +45 -4
- package/player.html +274 -0
- package/sky.html +133 -0
- package/sky.md +285 -0
- package/src/demo.js +92 -0
- package/src/emulator/devices.js +22 -0
- package/src/emulator/xr.js +362 -0
- package/src/math.js +77 -0
- package/sw.js +37 -0
- package/xr-compare.html +332 -0
- package/xr-test.html +248 -0
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"format": "3draft-game",
|
|
3
|
+
"version": 1,
|
|
4
|
+
"title": "Lark in the Deep Sky",
|
|
5
|
+
"about": "The LARK-4 lander as the starship, in a copy of the Deep Sky universe (deepsky-lark). In VR you sit in the left pilot seat: the left hand's ship function flies it with both hands, the floating dashboard has Space, Esc, Tab, 0, [ and ].",
|
|
6
|
+
"universe": { "scene": "deepsky-lark" },
|
|
7
|
+
"ship": {
|
|
8
|
+
"scene": "lark-4",
|
|
9
|
+
"helm": { "eye": [0.92, 2.8, 1.0], "yaw": 3.141592653589793, "pitch": 0.1 },
|
|
10
|
+
"walk": { "eyeHeight": 1.7, "speed": 1.5, "run": 3, "radius": 0.25, "step": 0.35 }
|
|
11
|
+
},
|
|
12
|
+
"start": { "mode": "ship" },
|
|
13
|
+
"keys": { "c": "helm" }
|
|
14
|
+
}
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
# Spider Build v2
|
|
2
|
+
|
|
3
|
+
Spider Build is a UTF-8 JSON recording with the recommended extension `.build.json`.
|
|
4
|
+
It saves the complete construction history, independent camera motion, and independent
|
|
5
|
+
text/audio narration in one portable document. All included content uses English and metres.
|
|
6
|
+
|
|
7
|
+
- [JSON Schema](spider-build-v2.schema.json) (Draft 2020-12)
|
|
8
|
+
- [Small working example](spider-build-example.build.json)
|
|
9
|
+
- [LARK–4C recording](lark-4.build.json)
|
|
10
|
+
- [Player](lark-4-tutorial.html)
|
|
11
|
+
|
|
12
|
+
## Document layout
|
|
13
|
+
|
|
14
|
+
```text
|
|
15
|
+
format: "spider-build-tutorial"
|
|
16
|
+
version: 2
|
|
17
|
+
metadata Title, identifier, language, units, creation/completion dates
|
|
18
|
+
timeline timeUnit: "ms", durationMs
|
|
19
|
+
assets.meshes Shared, exact mesh snapshots keyed by asset ID
|
|
20
|
+
assets.audio Audio URI and MIME type keyed by asset ID
|
|
21
|
+
scene Initial objects and material palette
|
|
22
|
+
chapters Named timeline ranges for navigation
|
|
23
|
+
tracks.construction Timestamped commands and authoritative resulting changes
|
|
24
|
+
tracks.camera Initial pose, keyframes and named inspection presets
|
|
25
|
+
tracks.narration Timestamped text and optional audio cues
|
|
26
|
+
presentation Optional cutaway masks and named object inspection views
|
|
27
|
+
result Optional summary of the finished model
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Every required track may be empty. Camera and narration tracks may be edited, removed
|
|
31
|
+
or disabled without changing construction. They reference global time, never construction
|
|
32
|
+
step IDs or chapter IDs. Chapters contain navigation titles and ranges only; descriptive
|
|
33
|
+
chapter narration belongs in `tracks.narration`. All camera coordinates, including inspection
|
|
34
|
+
presets, belong in `tracks.camera`; presentation views reference presets by name.
|
|
35
|
+
|
|
36
|
+
## Construction
|
|
37
|
+
|
|
38
|
+
```json
|
|
39
|
+
{
|
|
40
|
+
"id": "build-000001",
|
|
41
|
+
"timeMs": 1000,
|
|
42
|
+
"command": {
|
|
43
|
+
"tool": "add_box",
|
|
44
|
+
"args": {"name": "example/block", "min": [-0.5, 0, -0.5], "max": [0.5, 1, 0.5]}
|
|
45
|
+
},
|
|
46
|
+
"changes": [{"type": "put", "object": {"name": "example/block", "meshRef": "block-mesh"}}],
|
|
47
|
+
"provenance": {"source": "spider-paint MCP", "executedAt": "2026-11-15T12:00:00Z"}
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`command` preserves the actual tool name and arguments for inspection, provenance and
|
|
52
|
+
future tool-aware players. **Replay applies `changes`; it does not execute commands.**
|
|
53
|
+
This preserves results across engine versions and does not depend on a viewport, random
|
|
54
|
+
seed or the availability of the original tool. Any operation is supported when its resulting
|
|
55
|
+
object changes are captured, including transforms, booleans and replacement meshes.
|
|
56
|
+
|
|
57
|
+
`put` creates or replaces a complete object, while `remove` deletes an existing object
|
|
58
|
+
by name. A multi-object operation stores multiple changes in order; a step is applied atomically.
|
|
59
|
+
Start from `scene.objects`, apply all steps with `timeMs <= playhead`, and preserve array
|
|
60
|
+
order when timestamps match. Replacement retains object order; removal followed by a new
|
|
61
|
+
put appends the object. Seeking backwards rebuilds from the initial scene, so deletions
|
|
62
|
+
and replacements are fully reversible. UI stepping treats equal-time steps as one group.
|
|
63
|
+
|
|
64
|
+
Mesh assets contain exact `positions` and convex CCW `faces` with optional `color` and
|
|
65
|
+
`mat`. Faces reference `scene.palette` materials by name, including alpha and emission.
|
|
66
|
+
Coordinates are stored without rounding. Identical mesh snapshots share one asset;
|
|
67
|
+
objects refer to it using `meshRef`. Recorded raw mesh tool arguments remain intact.
|
|
68
|
+
This is snapshot sharing, not a claim that every similar component has identical geometry.
|
|
69
|
+
|
|
70
|
+
## Camera
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{
|
|
74
|
+
"initialPose": {"eye": [8, 6, 10], "yaw": -38.66, "pitch": 18.99},
|
|
75
|
+
"keyframes": [
|
|
76
|
+
{"id": "hold", "timeMs": 1000, "transition": "cut", "pose": {"eye": [8, 6, 10], "yaw": -38.66, "pitch": 18.99}},
|
|
77
|
+
{"id": "orbit", "timeMs": 5000, "transition": "smoothstep", "pose": {"eye": [-8, 6, 10], "yaw": 38.66, "pitch": 18.99}}
|
|
78
|
+
],
|
|
79
|
+
"presets": {}
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
The engine uses Y up. Eye positions are in metres; yaw/pitch are in degrees. Yaw 0
|
|
84
|
+
looks toward -Z, positive yaw turns toward +X, and positive pitch looks down.
|
|
85
|
+
Pitch is limited to -90…90. Forward is
|
|
86
|
+
`[sin(yaw)*cos(pitch), -sin(pitch), -cos(yaw)*cos(pitch)]`.
|
|
87
|
+
|
|
88
|
+
Keyframes are strictly ordered by time. `transition` describes the approach **to that
|
|
89
|
+
keyframe** from the previous keyframe, or from the initial pose at time zero:
|
|
90
|
+
|
|
91
|
+
- `cut`: hold the previous pose until this timestamp, then switch immediately.
|
|
92
|
+
- `linear`: linearly interpolate eye and pitch; take the shortest yaw rotation.
|
|
93
|
+
- `smoothstep`: the same path with easing `t*t*(3-2*t)`.
|
|
94
|
+
|
|
95
|
+
The last pose holds to the end. A frame at time zero replaces the initial pose immediately.
|
|
96
|
+
Insert a duplicate pose at the intended movement start to create a stationary hold.
|
|
97
|
+
Native Stories additionally supports optional `roll` and `fov` values in degrees;
|
|
98
|
+
the original debug-bridge tutorial player uses eye/yaw/pitch only. Splines are outside
|
|
99
|
+
v2. A player must reject unsupported format versions.
|
|
100
|
+
|
|
101
|
+
## Narration
|
|
102
|
+
|
|
103
|
+
```json
|
|
104
|
+
{
|
|
105
|
+
"id": "intro",
|
|
106
|
+
"startMs": 500,
|
|
107
|
+
"endMs": 6500,
|
|
108
|
+
"channel": "voiceover",
|
|
109
|
+
"language": "en",
|
|
110
|
+
"text": "Build the floor before adding the cabin frame.",
|
|
111
|
+
"audio": {"assetId": "intro-voice", "offsetMs": 0, "volume": 1}
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Cue intervals include their start and exclude their end. Use `chapter` for descriptive
|
|
116
|
+
chapter text, `operation` for action captions, and `voiceover` for independent narration.
|
|
117
|
+
Each cue contains text, audio, or both. Cues can overlap and need not align with construction.
|
|
118
|
+
They are sorted by start time; ties retain serialized order. The player joins active text
|
|
119
|
+
per channel and can play overlapping audio. Language uses tags such as `en` or `en-GB`;
|
|
120
|
+
the supplied tutorials use `en`.
|
|
121
|
+
|
|
122
|
+
Audio assets have `{ "uri": "voice/intro.ogg", "mimeType": "audio/ogg" }`. URIs are
|
|
123
|
+
relative to the build document, HTTP(S), or `data:audio/...`. For a single-file recording,
|
|
124
|
+
embed audio as a data URI; external files must travel with the recording. `offsetMs` starts
|
|
125
|
+
inside the source clip. Playback speed applies to every track; pause, seeking and mute
|
|
126
|
+
resynchronize the audio. The player has independent Narration and Voiceover switches.
|
|
127
|
+
Audio still requires a browser-supported codec and permission to play. The migrated LARK
|
|
128
|
+
recording contains text narration; no voice recording has been fabricated.
|
|
129
|
+
|
|
130
|
+
## Timeline and validation
|
|
131
|
+
|
|
132
|
+
Time is elapsed playback time in milliseconds, independent of wall-clock `executedAt`.
|
|
133
|
+
`durationMs` includes any final hold and must cover all steps, frames, chapters and cues.
|
|
134
|
+
Construction steps and cue starts must be nondecreasing; camera timestamps must be unique.
|
|
135
|
+
IDs are unique within their own collection. Chapters cannot overlap. Material, mesh, audio
|
|
136
|
+
and camera-preset references must resolve. Negative/nonfinite times, out-of-range vertices,
|
|
137
|
+
removal of nonexistent objects and unsupported versions are errors.
|
|
138
|
+
|
|
139
|
+
Validate both the JSON Schema and semantic rules implemented by `validateBuildDocument`
|
|
140
|
+
in `spider-build-v2.mjs`. The schema checks structure; the runtime also checks references,
|
|
141
|
+
timeline bounds and object lifecycle. It does not prove that an arbitrary mesh is manifold
|
|
142
|
+
or that a recorded command would produce its captured result; use the engine geometry
|
|
143
|
+
validator and a comparison against the source scene for those checks.
|
|
144
|
+
|
|
145
|
+
```sh
|
|
146
|
+
node scripts/spider-build.mjs validate models/lark-4.build.json
|
|
147
|
+
node scripts/spider-build.mjs convert models/lark-4-tutorial.json models/lark-4.build.json
|
|
148
|
+
node --test scripts/spider-build.test.mjs
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Open `http://localhost:5173/models/lark-4-tutorial.html`. To load another recording, use
|
|
152
|
+
`?file=spider-build-example.build.json`. The player also accepts a v1 log and converts it
|
|
153
|
+
in memory. Native `.scene.json` files remain geometry snapshots and are unchanged.
|
|
154
|
+
|
|
155
|
+
## Native animation and Deep Sky environments
|
|
156
|
+
|
|
157
|
+
The native Stories player accepts optional `scene.environment` and `tracks.animation`
|
|
158
|
+
sections. Existing build-only files remain valid. An environment is an embedded native
|
|
159
|
+
`3draft-scene` with its prototype instances and optional point cloud; its materials belong
|
|
160
|
+
in the story's main `scene.palette`. This retains `bh-core` instances as native black holes,
|
|
161
|
+
so Spider draws its existing ray-traced accretion and lensing. Embed only the environment
|
|
162
|
+
subset needed for the scene.
|
|
163
|
+
|
|
164
|
+
`tracks.animation` contains `timesMs` (strictly increasing, beginning at zero), `channels`
|
|
165
|
+
and `bindings`. Each channel has an `id` and one `matrices` entry per sample time. Each
|
|
166
|
+
matrix contains 12 finite numbers: three row-major rows `[x, y, z, translation]` of an affine
|
|
167
|
+
transform. Adjacent captured matrices interpolate linearly; out-of-range times hold the
|
|
168
|
+
nearest pose. Capture rotations densely enough to preserve their shape during blending.
|
|
169
|
+
All channels share the animation clock, independently of construction, camera and
|
|
170
|
+
narration. The GPU supports at most 64 channels.
|
|
171
|
+
|
|
172
|
+
A channel may also have `emission`, an array of nonnegative finite brightness multipliers
|
|
173
|
+
with the same length as `timesMs`. It interpolates linearly on that clock and defaults to
|
|
174
|
+
1 when omitted. `animationAt(doc, timeMs, matrices, emission)` can fill a reusable 64-entry
|
|
175
|
+
emission array as well as the matrix array. The native WebGPU/WebGL2 player applies these
|
|
176
|
+
gains in the skin shader; emissive faces also become moving local lights when glow is on.
|
|
177
|
+
This animates brightness without rebuilding or uploading bind geometry every frame.
|
|
178
|
+
|
|
179
|
+
`scene.environment.view` saves `glow`, `light`, `studio` and other native view switches.
|
|
180
|
+
Its optional `material` object saves nonnegative global `ambient`, `diffuse`, `specular`
|
|
181
|
+
and `shininess` strengths, independently of the named surface materials in the palette.
|
|
182
|
+
|
|
183
|
+
A binding uses `{ "object": "wing", "channel": "port-wing" }` for a rigid part.
|
|
184
|
+
A skinned binding instead has `weights`: one array per vertex, containing one to four
|
|
185
|
+
`[channelId, weight]` pairs summing to one. Its vertex count must remain compatible across
|
|
186
|
+
construction replacements. Bindings reference the original meshes in the story assets.
|
|
187
|
+
The native player uploads these once and updates only the matrices. `sceneAt(doc, timeMs)`
|
|
188
|
+
creates editable geometry at a moment, triangulating flexible faces. Leaving Stories
|
|
189
|
+
retains this deformed geometry and the native environment.
|
|
190
|
+
|
|
191
|
+
Camera poses may additionally contain `roll` and `fov`, both in degrees. Lens values must
|
|
192
|
+
be between 5 and 150 degrees. They interpolate independently of motion; cuts still switch
|
|
193
|
+
immediately. See [LARK–4C / LAST LIGHT](lark-4c-accident.md) for a silent example using
|
|
194
|
+
these sections. Its complete recording is `lark-4c-accident.build.json`.
|
|
195
|
+
|
|
196
|
+
## Migration and authoring
|
|
197
|
+
|
|
198
|
+
The v1 adapter preserves every original command, resulting mesh, material and timestamp.
|
|
199
|
+
Legacy event durations and 1.5-second chapter pauses become explicit timeline time;
|
|
200
|
+
chapter cameras become cuts. It does not invent continuous camera paths that were never
|
|
201
|
+
recorded. For LARK recordings it preserves the old player's camera distance adjustment
|
|
202
|
+
and inspection views. Narration moves into its own cues. The original v1 file remains
|
|
203
|
+
available for existing authoring scripts and backward compatibility.
|
|
204
|
+
|
|
205
|
+
LARK's commit, finalize and English translation scripts automatically export v2 after
|
|
206
|
+
updating the legacy authoring journal. Changes made directly to the exported camera or
|
|
207
|
+
narration tracks should be saved as a separate edited recording before re-exporting: a
|
|
208
|
+
fresh export intentionally regenerates all tracks from the source journal. New generic
|
|
209
|
+
authoring tools should write v2 directly, capturing both command arguments and resulting
|
|
210
|
+
changes at each completed operation. Camera recording must write camera keyframes only;
|
|
211
|
+
narration editing must write narration cues only.
|
|
212
|
+
|
|
213
|
+
The format can preserve the complete history that was recorded. It cannot recover modeling
|
|
214
|
+
actions performed before recording began. Initial imported models can be embedded in
|
|
215
|
+
`scene.objects`, with geometry in `assets.meshes`; later edits are recorded as steps.
|
|
@@ -0,0 +1,355 @@
|
|
|
1
|
+
// (copied from 3Draft app/story.js by scripts/sync.mjs: change it there)
|
|
2
|
+
/** Spider Build v2 (story files, .build.json): dependency-free, shared by the browser and Node authoring tools.
|
|
3
|
+
* The viewer imports it (story mode); Spider Paint's sync copies it to models/spider-build-v2.mjs there. Its spec, schema
|
|
4
|
+
* and authoring tools live in Spider Paint (models/spider-build-v2.md). */
|
|
5
|
+
export const FORMAT = 'spider-build-tutorial';
|
|
6
|
+
export const VERSION = 2;
|
|
7
|
+
const copy = value => structuredClone(value);
|
|
8
|
+
const pose = (eye, target) => {
|
|
9
|
+
const d = target.map((v, i) => v - eye[i]);
|
|
10
|
+
return {eye, yaw: Math.atan2(d[0], -d[2]) * 180 / Math.PI,
|
|
11
|
+
pitch: -Math.atan2(d[1], Math.hypot(d[0], d[2])) * 180 / Math.PI};
|
|
12
|
+
};
|
|
13
|
+
|
|
14
|
+
/** Upgrade legacy logs without altering their recorded commands or geometry. */
|
|
15
|
+
export function migrateV1(old) {
|
|
16
|
+
if (old?.format !== FORMAT || old.version !== 1) throw Error('Expected a version 1 Spider build log.');
|
|
17
|
+
const meshes = {}, meshIds = new Map(), steps = [], cues = [], frames = [], chapters = [];
|
|
18
|
+
const isLark = /^LARK/i.test(old.shortTitle ?? old.title ?? '');
|
|
19
|
+
const intern = mesh => {
|
|
20
|
+
const key = JSON.stringify(mesh);
|
|
21
|
+
if (!meshIds.has(key)) {
|
|
22
|
+
const id = `mesh-${String(meshIds.size + 1).padStart(6, '0')}`;
|
|
23
|
+
meshIds.set(key, id); meshes[id] = copy(mesh);
|
|
24
|
+
}
|
|
25
|
+
return meshIds.get(key);
|
|
26
|
+
};
|
|
27
|
+
const chapterByStart = new Map(old.chapters.map(c => [c.start, c]));
|
|
28
|
+
let time = 0;
|
|
29
|
+
for (const [i, event] of old.events.entries()) {
|
|
30
|
+
const chapter = chapterByStart.get(i);
|
|
31
|
+
if (chapter) {
|
|
32
|
+
if (i) time += 1500;
|
|
33
|
+
chapters.push({id: `chapter-${chapter.id}`, title: chapter.title, startMs: time, endMs: 0});
|
|
34
|
+
cues.push({id: `chapter-text-${chapter.id}`, channel: 'chapter', language: old.language ?? 'en',
|
|
35
|
+
startMs: time, endMs: 0, text: chapter.text});
|
|
36
|
+
if (chapter.camera) {
|
|
37
|
+
const c = chapter.camera, target = c.target ?? [0, 2, 0];
|
|
38
|
+
// Preserve the original player's framing, including its distance adjustment.
|
|
39
|
+
frames.push({id: `camera-${chapter.id}`, timeMs: time, transition: 'cut',
|
|
40
|
+
pose: {eye: c.eye.map((v, k) => target[k] + (v - target[k]) * (isLark ? (chapter.id >= 15 ? 1.12 : 1.3) : 1)), yaw: c.yaw, pitch: c.pitch}});
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
time += event.duration ?? 650;
|
|
44
|
+
steps.push({id: `build-${String(i + 1).padStart(6, '0')}`, timeMs: time,
|
|
45
|
+
command: {tool: event.method, args: copy(event.args)},
|
|
46
|
+
changes: event.after ? [{type: 'put', object: {name: event.after.name, meshRef: intern(event.after.mesh)}}] :
|
|
47
|
+
event.method === 'remove' ? [{type: 'remove', name: event.name}] : [],
|
|
48
|
+
provenance: {source: event.source ?? 'spider-paint MCP', ...(event.executedAt ? {executedAt: event.executedAt} : {})}});
|
|
49
|
+
cues.push({id: `operation-text-${i + 1}`, channel: 'operation', language: old.language ?? 'en',
|
|
50
|
+
startMs: time, endMs: 0, text: event.label ?? event.method});
|
|
51
|
+
}
|
|
52
|
+
const durationMs = time + 1500;
|
|
53
|
+
for (let i = 0; i < chapters.length; i++) chapters[i].endMs = chapters[i + 1]?.startMs ?? durationMs;
|
|
54
|
+
for (const channel of ['chapter', 'operation']) {
|
|
55
|
+
const group = cues.filter(c => c.channel === channel);
|
|
56
|
+
group.forEach((cue, i) => {cue.endMs = group[i + 1]?.startMs ?? durationMs;});
|
|
57
|
+
}
|
|
58
|
+
const presets = {
|
|
59
|
+
cutaway: old.cutawayCamera ? {eye: copy(old.cutawayCamera.eye), yaw: old.cutawayCamera.yaw, pitch: old.cutawayCamera.pitch} : pose([-10.4, 10, 13], [0, 2, 0]),
|
|
60
|
+
hangar: pose([10, 13, -21], [0, 3.2, -10.2]),
|
|
61
|
+
quarters: pose([-8.5, 10.5, .5], [0, 2.7, -4.8])
|
|
62
|
+
};
|
|
63
|
+
const extended = isLark && old.chapters.find(c => c.id === 15);
|
|
64
|
+
const availableFromMs = extended ? chapters.find(c => c.id === 'chapter-15').startMs : durationMs;
|
|
65
|
+
const doc = {
|
|
66
|
+
$schema: './spider-build-v2.schema.json', format: FORMAT, version: VERSION,
|
|
67
|
+
metadata: {id: old.id ?? ((old.shortTitle ?? old.title ?? 'build').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'build'), title: old.title, shortTitle: old.shortTitle ?? old.title, language: old.language ?? 'en', units: old.units ?? 'metres',
|
|
68
|
+
...(old.createdAt ? {createdAt: old.createdAt} : {}), ...(old.finishedAt ? {finishedAt: old.finishedAt} : {})},
|
|
69
|
+
timeline: {timeUnit: 'ms', durationMs},
|
|
70
|
+
assets: {meshes, audio: {}}, scene: {palette: copy(old.palette ?? []), objects: []}, chapters,
|
|
71
|
+
tracks: {
|
|
72
|
+
construction: {steps},
|
|
73
|
+
camera: {initialPose: frames[0]?.pose ?? pose([8, 6, 10], [0, 2, 0]), keyframes: frames, presets},
|
|
74
|
+
narration: {cues: cues.sort((a, b) => a.startMs - b.startMs)}
|
|
75
|
+
},
|
|
76
|
+
presentation: {cutaway: {excludePrefixes: copy(old.cutawayPrefixes ?? []), cameraPreset: 'cutaway'}, views: extended ? [
|
|
77
|
+
{id: 'hangar', title: 'Hangar', cameraPreset: 'hangar', availableFromMs,
|
|
78
|
+
includePrefixes: ['hangar/', 'extension/structure/hangar-', 'extension/interior/hangar-floor', 'extension/shell/hangar-'],
|
|
79
|
+
excludePrefixes: ['hangar/ramp/', 'hangar/gate/leaf-']},
|
|
80
|
+
{id: 'quarters', title: 'Crew quarters', cameraPreset: 'quarters', availableFromMs,
|
|
81
|
+
includePrefixes: ['extension/interior/', 'interior/oxygen-', 'extension/shell/crew-'],
|
|
82
|
+
excludePrefixes: ['extension/interior/hangar-floor']}
|
|
83
|
+
] : []},
|
|
84
|
+
...(old.final ? {result: copy(old.final)} : {})
|
|
85
|
+
};
|
|
86
|
+
validateBuildDocument(doc);
|
|
87
|
+
return doc;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
export function normalizeBuildDocument(doc) {
|
|
91
|
+
if (doc?.version === 1) return migrateV1(doc);
|
|
92
|
+
validateBuildDocument(doc);
|
|
93
|
+
return doc;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/** Semantic checks supplement the published JSON Schema; throws a path-specific error. */
|
|
97
|
+
export function validateBuildDocument(doc) {
|
|
98
|
+
const fail = (path, message) => {throw Error(`${path}: ${message}`);};
|
|
99
|
+
const object = (v, path) => {if (!v || typeof v !== 'object' || Array.isArray(v)) fail(path, 'expected an object');};
|
|
100
|
+
const array = (v, path) => {if (!Array.isArray(v)) fail(path, 'expected an array');};
|
|
101
|
+
const string = (v, path) => {if (typeof v !== 'string' || !v.length) fail(path, 'expected a nonempty string');};
|
|
102
|
+
const finite = (v, path) => {if (typeof v !== 'number' || !Number.isFinite(v)) fail(path, 'expected a finite number');};
|
|
103
|
+
const keys = (v, allowed, path) => {object(v, path); for (const k of Object.keys(v)) if (!allowed.includes(k)) fail(`${path}.${k}`, 'unknown field');};
|
|
104
|
+
object(doc, '$');
|
|
105
|
+
keys(doc, ['$schema','format','version','metadata','timeline','assets','scene','chapters','tracks','presentation','result'], '$');
|
|
106
|
+
if (doc.format !== FORMAT || doc.version !== VERSION) fail('$', 'unsupported Spider build format/version');
|
|
107
|
+
if (doc.$schema !== undefined) string(doc.$schema, '$schema');
|
|
108
|
+
if (doc.result !== undefined) object(doc.result, 'result');
|
|
109
|
+
keys(doc.metadata, ['id','title','shortTitle','language','units','createdAt','finishedAt'], 'metadata');
|
|
110
|
+
for (const k of ['id','title','language','units']) string(doc.metadata[k], `metadata.${k}`);
|
|
111
|
+
if (doc.metadata.units !== 'metres') fail('metadata.units', 'v2 uses metres');
|
|
112
|
+
if (doc.metadata.shortTitle !== undefined) string(doc.metadata.shortTitle, 'metadata.shortTitle');
|
|
113
|
+
for (const k of ['createdAt','finishedAt']) if (doc.metadata[k] !== undefined && (typeof doc.metadata[k] !== 'string' || !Number.isFinite(Date.parse(doc.metadata[k])))) fail(`metadata.${k}`, 'expected an ISO date-time');
|
|
114
|
+
keys(doc.timeline, ['timeUnit','durationMs'], 'timeline');
|
|
115
|
+
if (doc.timeline.timeUnit !== 'ms') fail('timeline.timeUnit', 'expected ms');
|
|
116
|
+
const duration = doc.timeline.durationMs;
|
|
117
|
+
finite(duration, 'timeline.durationMs');
|
|
118
|
+
if (duration < 0) fail('timeline.durationMs', 'must be nonnegative');
|
|
119
|
+
const time = (v, path) => {finite(v, path); if (v < 0 || v > duration) fail(path, 'outside timeline');};
|
|
120
|
+
const vec = (v, path) => {array(v, path); if (v.length !== 3) fail(path, 'expected three coordinates'); v.forEach((x, i) => finite(x, `${path}[${i}]`));};
|
|
121
|
+
const camera = (v, path) => {
|
|
122
|
+
keys(v, ['eye','yaw','pitch','roll','fov'], path); vec(v.eye, `${path}.eye`); finite(v.yaw, `${path}.yaw`); finite(v.pitch, `${path}.pitch`);
|
|
123
|
+
if (v.pitch < -90 || v.pitch > 90) fail(path, 'pitch must be between -90 and 90');
|
|
124
|
+
if (v.roll !== undefined) finite(v.roll, `${path}.roll`);
|
|
125
|
+
if (v.fov !== undefined) {finite(v.fov, `${path}.fov`); if (v.fov < 5 || v.fov > 150) fail(path, 'fov must be between 5 and 150 degrees');}
|
|
126
|
+
};
|
|
127
|
+
const unique = (items, path) => {array(items, path); const ids = new Set(); for (const item of items) {object(item,path); string(item.id, `${path}.id`); if (ids.has(item.id)) fail(path, `duplicate id ${item.id}`); ids.add(item.id);}};
|
|
128
|
+
const ordered = (items, field, path) => {let previous = -1; for (const item of items) {time(item[field], `${path}.${field}`); if (item[field] < previous) fail(path, 'times must be nondecreasing'); previous = item[field];}};
|
|
129
|
+
keys(doc.assets, ['meshes','audio'], 'assets'); object(doc.assets.meshes, 'assets.meshes'); object(doc.assets.audio, 'assets.audio');
|
|
130
|
+
keys(doc.scene, ['palette','objects','environment'], 'scene'); array(doc.scene.palette, 'scene.palette'); array(doc.scene.objects, 'scene.objects');
|
|
131
|
+
const materials = new Set();
|
|
132
|
+
for (const material of doc.scene.palette) {
|
|
133
|
+
object(material, 'scene.palette'); string(material.name, 'scene.palette.name');
|
|
134
|
+
if (materials.has(material.name)) fail('scene.palette', `duplicate material ${material.name}`);
|
|
135
|
+
materials.add(material.name);
|
|
136
|
+
if (material.color !== undefined) string(material.color, 'scene.palette.color');
|
|
137
|
+
for (const k of ['metal','rough','emit','soft']) if (material[k] !== undefined) finite(material[k], `scene.palette.${k}`);
|
|
138
|
+
if (material.alpha !== undefined) {finite(material.alpha, 'scene.palette.alpha'); if (material.alpha < 0 || material.alpha > 1) fail('scene.palette.alpha', 'outside 0..1');}
|
|
139
|
+
}
|
|
140
|
+
for (const [id, mesh] of Object.entries(doc.assets.meshes)) {
|
|
141
|
+
const path = `assets.meshes.${id}`;
|
|
142
|
+
keys(mesh, ['positions','faces'], path); array(mesh.positions, `${path}.positions`); array(mesh.faces, `${path}.faces`);
|
|
143
|
+
mesh.positions.forEach((v, i) => vec(v, `${path}.positions[${i}]`));
|
|
144
|
+
for (const face of mesh.faces) {
|
|
145
|
+
keys(face, ['v','color','mat'], path); array(face.v, `${path}.faces.v`);
|
|
146
|
+
if (face.v.length < 3 || face.v.some(v => !Number.isInteger(v) || v < 0 || v >= mesh.positions.length)) fail(path, 'invalid face vertex indices');
|
|
147
|
+
if (face.color !== undefined) string(face.color, `${path}.faces.color`);
|
|
148
|
+
if (face.mat !== undefined && !materials.has(face.mat)) fail(path, `unknown material ${face.mat}`);
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
for (const [id, asset] of Object.entries(doc.assets.audio)) {
|
|
152
|
+
keys(asset, ['uri','mimeType'], `assets.audio.${id}`); string(asset.uri, `assets.audio.${id}.uri`); string(asset.mimeType, `assets.audio.${id}.mimeType`);
|
|
153
|
+
if (!/^(?:https?:|data:audio\/|[^:/?#]+(?:\/|$))/.test(asset.uri) || /^(?:javascript|file):/i.test(asset.uri)) fail(`assets.audio.${id}.uri`, 'expected relative, HTTP(S), or audio data URI');
|
|
154
|
+
}
|
|
155
|
+
const names = new Set();
|
|
156
|
+
const obj = (o, path) => {keys(o, ['name','meshRef'], path); string(o.name, `${path}.name`); string(o.meshRef, `${path}.meshRef`); if (!Object.hasOwn(doc.assets.meshes, o.meshRef)) fail(path, `unknown mesh ${o.meshRef}`);};
|
|
157
|
+
for (const o of doc.scene.objects) {obj(o, 'scene.objects'); if (names.has(o.name)) fail('scene.objects', `duplicate object ${o.name}`); names.add(o.name);}
|
|
158
|
+
keys(doc.tracks, ['construction','camera','narration','animation'], 'tracks');
|
|
159
|
+
keys(doc.tracks.construction, ['steps'], 'tracks.construction');
|
|
160
|
+
const steps = doc.tracks.construction.steps;
|
|
161
|
+
unique(steps, 'construction.steps'); ordered(steps, 'timeMs', 'construction.steps');
|
|
162
|
+
for (const s of steps) {
|
|
163
|
+
keys(s, ['id','timeMs','command','changes','provenance'], `construction.${s.id}`);
|
|
164
|
+
keys(s.command, ['tool','args'], `construction.${s.id}.command`); string(s.command.tool, 'command.tool'); object(s.command.args, 'command.args');
|
|
165
|
+
if (s.provenance !== undefined) {
|
|
166
|
+
keys(s.provenance,['source','executedAt'],'provenance'); string(s.provenance.source,'provenance.source');
|
|
167
|
+
if (s.provenance.executedAt !== undefined && (typeof s.provenance.executedAt !== 'string' || !Number.isFinite(Date.parse(s.provenance.executedAt)))) fail('provenance.executedAt', 'expected an ISO date-time');
|
|
168
|
+
}
|
|
169
|
+
array(s.changes, 'changes');
|
|
170
|
+
if (!s.changes.length) fail(s.id, 'must record at least one resulting change');
|
|
171
|
+
for (const c of s.changes) {
|
|
172
|
+
if (c.type === 'put') {keys(c, ['type','object'], s.id); obj(c.object, s.id); names.add(c.object.name);}
|
|
173
|
+
else if (c.type === 'remove') {keys(c, ['type','name'], s.id); string(c.name, s.id); if (!names.delete(c.name)) fail(s.id, `cannot remove missing object ${c.name}`);}
|
|
174
|
+
else fail(s.id, 'unknown change type');
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
if (doc.scene.environment !== undefined) {
|
|
178
|
+
const env = doc.scene.environment;
|
|
179
|
+
keys(env, ['format','version','name','prototypes','objects','cloud','view','vehicle'], 'scene.environment');
|
|
180
|
+
if (env.format !== '3draft-scene' || ![1,2].includes(env.version)) fail('scene.environment', 'expected a native 3Draft scene');
|
|
181
|
+
object(env.prototypes ?? {}, 'environment.prototypes'); array(env.objects, 'environment.objects');
|
|
182
|
+
const envNames = new Set(), allNames = new Set(doc.scene.objects.map(o=>o.name));
|
|
183
|
+
for(const s of steps)for(const c of s.changes)if(c.type==='put')allNames.add(c.object.name);
|
|
184
|
+
for (const o of env.objects) {
|
|
185
|
+
object(o, 'environment.objects'); string(o.name, 'environment.object.name');
|
|
186
|
+
if (envNames.has(o.name) || allNames.has(o.name)) fail('environment.objects', `duplicate object ${o.name}`); envNames.add(o.name);
|
|
187
|
+
if (o.proto) {
|
|
188
|
+
if (!Object.hasOwn(env.prototypes ?? {}, o.proto)) fail('environment.objects', `unknown prototype ${o.proto}`);
|
|
189
|
+
vec(o.at, 'environment.object.at');
|
|
190
|
+
if (typeof o.scale === 'number') {finite(o.scale, 'environment.object.scale'); if (o.scale <= 0) fail(o.name, 'scale must be positive');}
|
|
191
|
+
else {object(o.scale, 'environment.object.scale'); for (const s of Object.values(o.scale)) {finite(s,o.name); if(s<=0)fail(o.name,'scale must be positive');}}
|
|
192
|
+
for (const mat of Object.values(o.mats ?? {})) if (!materials.has(mat)) fail(o.name, `unknown material ${mat}`);
|
|
193
|
+
} else if (!o.mesh) fail(o.name, 'expected mesh or prototype');
|
|
194
|
+
}
|
|
195
|
+
for (const [id, proto] of Object.entries(env.prototypes ?? {})) {
|
|
196
|
+
array(proto.lods, `environment.prototypes.${id}.lods`); if (!proto.lods.length) fail(id, 'prototype needs a LOD');
|
|
197
|
+
for (const mesh of proto.lods) {
|
|
198
|
+
array(mesh.positions, id); array(mesh.faces, id); mesh.positions.forEach(p => vec(p,id));
|
|
199
|
+
for (const f of mesh.faces) if (!Array.isArray(f.v) || f.v.length < 3 || f.v.some(i => !Number.isInteger(i) || i < 0 || i >= mesh.positions.length)) fail(id, 'invalid prototype face');
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
if (env.cloud) {
|
|
203
|
+
const c=env.cloud; object(c,'environment.cloud'); finite(c.unit,'environment.cloud.unit');
|
|
204
|
+
if (c.unit <= 0 || !Number.isInteger(c.n) || c.n < 0) fail('environment.cloud','invalid point count or unit');
|
|
205
|
+
for (const [k,n] of [['p',c.n*3],['r',c.n],['c',c.n],['l',c.n]]) {
|
|
206
|
+
array(c[k],`environment.cloud.${k}`); if(c[k].length!==n)fail(k,'cloud array length mismatch'); c[k].forEach(v=>finite(v,k));
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
if (doc.tracks.animation !== undefined) {
|
|
211
|
+
const a=doc.tracks.animation;
|
|
212
|
+
keys(a,['timesMs','channels','bindings'],'tracks.animation'); array(a.timesMs,'animation.timesMs');
|
|
213
|
+
if (!a.timesMs.length || a.timesMs[0]!==0) fail('animation.timesMs','must start at time zero');
|
|
214
|
+
let previous=-1; for(const t of a.timesMs){time(t,'animation.timesMs');if(t<=previous)fail('animation.timesMs','must be strictly increasing');previous=t;}
|
|
215
|
+
unique(a.channels,'animation.channels'); if(a.channels.length>64)fail('animation.channels','GPU supports at most 64 channels');
|
|
216
|
+
for(const ch of a.channels){
|
|
217
|
+
keys(ch,['id','matrices','emission'],ch.id);array(ch.matrices,ch.id);if(ch.matrices.length!==a.timesMs.length)fail(ch.id,'matrix count must match timeline');
|
|
218
|
+
for(const m of ch.matrices){array(m,ch.id);if(m.length!==12)fail(ch.id,'expected a 3x4 affine matrix');m.forEach(v=>finite(v,ch.id));}
|
|
219
|
+
if(ch.emission!==undefined){array(ch.emission,ch.id);if(ch.emission.length!==a.timesMs.length)fail(ch.id,'emission count must match timeline');for(const e of ch.emission){finite(e,ch.id);if(e<0)fail(ch.id,'negative emission');}}
|
|
220
|
+
}
|
|
221
|
+
const channels=new Set(a.channels.map(c=>c.id)),known=new Map(doc.scene.objects.map(o=>[o.name,o]));
|
|
222
|
+
for(const s of steps)for(const c of s.changes)if(c.type==='put')known.set(c.object.name,c.object);
|
|
223
|
+
array(a.bindings,'animation.bindings');const bound=new Set();
|
|
224
|
+
for(const b of a.bindings){
|
|
225
|
+
keys(b,['object','channel','weights'],'animation.binding');string(b.object,'animation.binding.object');
|
|
226
|
+
if(!known.has(b.object)||bound.has(b.object))fail(b.object,'missing or duplicate animated object');bound.add(b.object);
|
|
227
|
+
if((b.channel!==undefined)===(b.weights!==undefined))fail(b.object,'use exactly one rigid channel or skin weights');
|
|
228
|
+
if(b.channel!==undefined){if(!channels.has(b.channel))fail(b.object,'unknown animation channel');}
|
|
229
|
+
else {
|
|
230
|
+
array(b.weights,b.object);const mesh=doc.assets.meshes[known.get(b.object).meshRef];
|
|
231
|
+
if(b.weights.length!==mesh.positions.length)fail(b.object,'weight count must match vertices');
|
|
232
|
+
for(const s of steps)for(const c of s.changes)if(c.type==='put'&&c.object.name===b.object&&doc.assets.meshes[c.object.meshRef].positions.length!==b.weights.length)fail(b.object,'skin topology changes during construction');
|
|
233
|
+
for(const w of b.weights){array(w,b.object);if(!w.length||w.length>4)fail(b.object,'expected one to four influences');let sum=0;
|
|
234
|
+
for(const pair of w){array(pair,b.object);if(pair.length!==2||!channels.has(pair[0]))fail(b.object,'unknown skin channel');finite(pair[1],b.object);if(pair[1]<0)fail(b.object,'negative skin weight');sum+=pair[1];}
|
|
235
|
+
if(Math.abs(sum-1)>.001)fail(b.object,'skin weights must sum to one');
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
const cam = doc.tracks.camera;
|
|
241
|
+
keys(cam, ['initialPose','keyframes','presets'], 'tracks.camera'); camera(cam.initialPose, 'camera.initialPose');
|
|
242
|
+
unique(cam.keyframes, 'camera.keyframes'); ordered(cam.keyframes, 'timeMs', 'camera.keyframes'); object(cam.presets, 'camera.presets');
|
|
243
|
+
let prev = -1;
|
|
244
|
+
for (const f of cam.keyframes) {
|
|
245
|
+
keys(f, ['id','timeMs','pose','transition'], f.id); camera(f.pose, f.id);
|
|
246
|
+
if (f.timeMs <= prev) fail(f.id, 'camera times must be strictly increasing'); prev = f.timeMs;
|
|
247
|
+
if (!['cut','linear','smoothstep'].includes(f.transition)) fail(f.id, 'unknown camera transition');
|
|
248
|
+
}
|
|
249
|
+
for (const [id, p] of Object.entries(cam.presets)) camera(p, `camera.presets.${id}`);
|
|
250
|
+
keys(doc.tracks.narration, ['cues'], 'tracks.narration');
|
|
251
|
+
const cues = doc.tracks.narration.cues;
|
|
252
|
+
unique(cues, 'narration.cues'); ordered(cues, 'startMs', 'narration.cues');
|
|
253
|
+
for (const c of cues) {
|
|
254
|
+
keys(c, ['id','startMs','endMs','channel','language','text','audio'], c.id);
|
|
255
|
+
time(c.endMs, `${c.id}.endMs`); if (c.endMs <= c.startMs) fail(c.id, 'cue end must follow start');
|
|
256
|
+
if (!['chapter','operation','voiceover'].includes(c.channel)) fail(c.id, 'unknown narration channel');
|
|
257
|
+
string(c.language, `${c.id}.language`);
|
|
258
|
+
if (c.text !== undefined) string(c.text, `${c.id}.text`);
|
|
259
|
+
if (!c.text && !c.audio) fail(c.id, 'expected text or audio');
|
|
260
|
+
if (c.audio) {
|
|
261
|
+
keys(c.audio, ['assetId','offsetMs','volume'], `${c.id}.audio`);
|
|
262
|
+
if (!Object.hasOwn(doc.assets.audio, c.audio.assetId)) fail(c.id, `unknown audio asset ${c.audio.assetId}`);
|
|
263
|
+
if (c.audio.offsetMs !== undefined) {finite(c.audio.offsetMs, c.id); if (c.audio.offsetMs < 0) fail(c.id, 'negative audio offset');}
|
|
264
|
+
if (c.audio.volume !== undefined) {finite(c.audio.volume, c.id); if (c.audio.volume < 0 || c.audio.volume > 1) fail(c.id, 'audio volume outside 0..1');}
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
unique(doc.chapters, 'chapters'); ordered(doc.chapters, 'startMs', 'chapters');
|
|
268
|
+
let chapterEnd = 0;
|
|
269
|
+
for (const c of doc.chapters) {
|
|
270
|
+
keys(c, ['id','title','startMs','endMs'], c.id); string(c.title, c.id); time(c.endMs, c.id);
|
|
271
|
+
if (c.startMs < chapterEnd || c.endMs <= c.startMs) fail(c.id, 'overlapping or empty chapter'); chapterEnd = c.endMs;
|
|
272
|
+
}
|
|
273
|
+
if (doc.presentation) {
|
|
274
|
+
keys(doc.presentation, ['cutaway','views'], 'presentation');
|
|
275
|
+
const preset = v => {if (!Object.hasOwn(cam.presets, v)) fail('presentation', `unknown camera preset ${v}`);};
|
|
276
|
+
const prefixes = (v, path) => {array(v,path); v.forEach(x => string(x,path));};
|
|
277
|
+
if (doc.presentation.cutaway) {const v=doc.presentation.cutaway; keys(v,['excludePrefixes','cameraPreset'],'presentation.cutaway'); preset(v.cameraPreset); prefixes(v.excludePrefixes,'cutaway.excludePrefixes');}
|
|
278
|
+
unique(doc.presentation.views ?? [], 'presentation.views');
|
|
279
|
+
for (const v of doc.presentation.views ?? []) {
|
|
280
|
+
keys(v, ['id','title','cameraPreset','availableFromMs','includePrefixes','excludePrefixes'], v.id);
|
|
281
|
+
string(v.title,v.id); preset(v.cameraPreset); time(v.availableFromMs,v.id);
|
|
282
|
+
prefixes(v.includePrefixes,`${v.id}.includePrefixes`); prefixes(v.excludePrefixes,`${v.id}.excludePrefixes`);
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
return doc;
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
/** Count all steps at or before the playhead; equal times use serialized array order. */
|
|
289
|
+
export function constructionIndexAtTime(doc, timeMs) {
|
|
290
|
+
const steps = doc.tracks.construction.steps;
|
|
291
|
+
let lo = 0, hi = steps.length;
|
|
292
|
+
while (lo < hi) {const mid = (lo + hi) >>> 1; if (steps[mid].timeMs <= timeMs) lo = mid + 1; else hi = mid;}
|
|
293
|
+
return lo;
|
|
294
|
+
}
|
|
295
|
+
export function constructionAt(doc, timeMs) {
|
|
296
|
+
const map = new Map(doc.scene.objects.map(o => [o.name, o]));
|
|
297
|
+
const end = constructionIndexAtTime(doc, timeMs);
|
|
298
|
+
for (let i = 0; i < end; i++) for (const c of doc.tracks.construction.steps[i].changes) {
|
|
299
|
+
if (c.type === 'put') map.set(c.object.name, c.object); else map.delete(c.name);
|
|
300
|
+
}
|
|
301
|
+
// Returned snapshots are independent: a viewer/editor cannot mutate saved assets.
|
|
302
|
+
return copy([...map.values()].map(o => ({name: o.name, mesh: doc.assets.meshes[o.meshRef]})));
|
|
303
|
+
}
|
|
304
|
+
export function cameraAt(doc, timeMs) {
|
|
305
|
+
let previous = {timeMs: 0, pose: doc.tracks.camera.initialPose};
|
|
306
|
+
for (const next of doc.tracks.camera.keyframes) {
|
|
307
|
+
if (next.timeMs <= timeMs) {previous = next; continue;}
|
|
308
|
+
if (next.transition === 'cut' || timeMs <= previous.timeMs) return copy(previous.pose);
|
|
309
|
+
let t = Math.max(0, Math.min(1, (timeMs - previous.timeMs) / (next.timeMs - previous.timeMs)));
|
|
310
|
+
if (next.transition === 'smoothstep') t = t * t * (3 - 2 * t);
|
|
311
|
+
const a = previous.pose, b = next.pose, yawDelta = ((b.yaw - a.yaw + 180) % 360 + 360) % 360 - 180;
|
|
312
|
+
return {eye: a.eye.map((v, i) => v + (b.eye[i] - v) * t), yaw: a.yaw + yawDelta * t, pitch: a.pitch + (b.pitch - a.pitch) * t,
|
|
313
|
+
...((a.roll!==undefined||b.roll!==undefined)?{roll:(a.roll??0)+((b.roll??0)-(a.roll??0))*t}:{}),
|
|
314
|
+
...((a.fov!==undefined||b.fov!==undefined)?{fov:(a.fov??b.fov)+((b.fov??a.fov)-(a.fov??b.fov))*t}:{})};
|
|
315
|
+
}
|
|
316
|
+
return copy(previous.pose);
|
|
317
|
+
}
|
|
318
|
+
export function narrationAt(doc, timeMs) {
|
|
319
|
+
return doc.tracks.narration.cues.filter(c => c.startMs <= timeMs && timeMs < c.endMs);
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
/** GPU-ready affine channels. Adjacent captured poses blend at the shared animation clock. */
|
|
323
|
+
export function animationAt(doc,timeMs,out,emission) {
|
|
324
|
+
const a=doc.tracks.animation;if(!a)return null;
|
|
325
|
+
out??=new Float32Array(64*12);
|
|
326
|
+
let lo=0,hi=a.timesMs.length;
|
|
327
|
+
while(lo<hi){const m=(lo+hi)>>>1;if(a.timesMs[m]<=timeMs)lo=m+1;else hi=m;}
|
|
328
|
+
const i=Math.max(0,lo-1),j=Math.min(i+1,a.timesMs.length-1);
|
|
329
|
+
const t=i===j?0:Math.max(0,Math.min(1,(timeMs-a.timesMs[i])/(a.timesMs[j]-a.timesMs[i])));
|
|
330
|
+
a.channels.forEach((c,k)=>{for(let n=0;n<12;n++)out[k*12+n]=c.matrices[i][n]+(c.matrices[j][n]-c.matrices[i][n])*t;});
|
|
331
|
+
if(emission){emission.fill(1);a.channels.forEach((c,k)=>{if(c.emission)emission[k]=c.emission[i]+(c.emission[j]-c.emission[i])*t;});}
|
|
332
|
+
return out;
|
|
333
|
+
}
|
|
334
|
+
/** Bind geometry and weights are uploaded once. Only `bones` changes during playback. */
|
|
335
|
+
export function animationSkin(doc,objects) {
|
|
336
|
+
const a=doc.tracks.animation;if(!a)return null;
|
|
337
|
+
const channels=new Map(a.channels.map((c,i)=>[c.id,i])),bindings=new Map(a.bindings.map(b=>[b.object,b]));
|
|
338
|
+
const meshes=[],weights=[],names=new Set();
|
|
339
|
+
for(const o of objects){const b=bindings.get(o.name);if(!b)continue;names.add(o.name);meshes.push(o.mesh);
|
|
340
|
+
weights.push(b.channel!==undefined?o.mesh.positions.map(()=>[[channels.get(b.channel),1]]):b.weights.map(w=>w.map(([id,v])=>[channels.get(id),v])));
|
|
341
|
+
}
|
|
342
|
+
return {meshes,weights,names,bones:new Float32Array(64*12),emission:new Float32Array(64).fill(1)};
|
|
343
|
+
}
|
|
344
|
+
/** CPU projection for editable snapshots, leaving story mode, and non-GPU rendering. */
|
|
345
|
+
export function sceneAt(doc,timeMs) {
|
|
346
|
+
const objects=constructionAt(doc,timeMs),skin=animationSkin(doc,objects);
|
|
347
|
+
if(!skin)return objects;
|
|
348
|
+
animationAt(doc,timeMs,skin.bones);let m=0;
|
|
349
|
+
const flexible=new Set(doc.tracks.animation.bindings.filter(b=>b.weights).map(b=>b.object));
|
|
350
|
+
for(const o of objects){if(!skin.names.has(o.name))continue;const weights=skin.weights[m++];
|
|
351
|
+
o.mesh.positions=o.mesh.positions.map((p,i)=>{const q=[0,0,0];for(const [j,w] of weights[i])for(let r=0;r<3;r++)q[r]+=w*(skin.bones[j*12+r*4]*p[0]+skin.bones[j*12+r*4+1]*p[1]+skin.bones[j*12+r*4+2]*p[2]+skin.bones[j*12+r*4+3]);return q;});
|
|
352
|
+
if(flexible.has(o.name))o.mesh.faces=o.mesh.faces.flatMap(f=>f.v.slice(1,-1).map((v,i)=>({...f,v:[f.v[0],v,f.v[i+2]]})));
|
|
353
|
+
}
|
|
354
|
+
return objects;
|
|
355
|
+
}
|