@wildshard/sdk 0.3.0 → 0.3.2

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.
Files changed (61) hide show
  1. package/GUIDE.md +10 -2
  2. package/docs/api/EXPORT-TIERS.md +7 -4
  3. package/lint/export-tiers.json +3 -0
  4. package/lint/host-callbacks.mjs +1 -1
  5. package/package.json +9 -5
  6. package/scripts/bake/template-skins.mjs +6 -3
  7. package/scripts/bake/template-warden.mjs +25 -0
  8. package/scripts/export-ci21-guests.mjs +89 -0
  9. package/scripts/scratch-sweep.mjs +3 -1
  10. package/src/cli/hero/hero.ts +45 -2
  11. package/src/sharddev/as/prelude.ts +67 -0
  12. package/src/sharddev/authorLint.ts +45 -0
  13. package/src/sharddev/bake/compileScript.ts +6 -0
  14. package/src/sharddev/bake/terrain.ts +11 -2
  15. package/src/sharddev/checkProject.ts +7 -18
  16. package/src/sharddev/engineMusic.ts +23 -0
  17. package/src/sharddev/materials.ts +7 -3
  18. package/src/sharddev/project.ts +5 -0
  19. package/src/sharddev/refusals.ts +1 -1
  20. package/src/sharddev/scene/author.ts +116 -11
  21. package/src/sharddev/scene/canvas.ts +2 -3
  22. package/src/sharddev/scene/description.ts +55 -2
  23. package/src/sharddev/scene/lower.ts +144 -29
  24. package/src/sharddev/scene/shard.ts +5 -2
  25. package/src/sharddev/scene/shardfile.ts +385 -72
  26. package/src/sharddev/watch/page.ts +116 -29
  27. package/src/sharddev/watch/pageEntry.ts +38 -2
  28. package/src/sharddev/watch/parity-baseline.json +22 -0
  29. package/src/sharddev/watch/parity.mjs +168 -0
  30. package/src/sharddev/watch/proof.mjs +129 -22
  31. package/src/sharddev/watch/protocol.ts +66 -8
  32. package/src/sharddev/watch/watch.ts +215 -51
  33. package/src/shards/_template/assets/3058c100bc477fd6fe8268f33b53756b8a2556e7e41c58b2216c703ca7b042c6 +1 -0
  34. package/src/shards/_template/assets/8a0440f392737a31cf0926a3c7dc011c320144972882945a5462c893e817d94a +0 -0
  35. package/src/shards/_template/behaviour/door.as +16 -26
  36. package/src/shards/_template/card/landscape.jpg +0 -0
  37. package/src/shards/_template/card/portrait.jpg +0 -0
  38. package/src/shards/_template/card/thumb.jpg +0 -0
  39. package/src/shards/_template/data/clientScripts.json +43 -43
  40. package/src/shards/_template/data/creatures.json +2 -2
  41. package/src/shards/_template/data/look.json +141 -13
  42. package/src/shards/_template/data/rows.json +20 -2
  43. package/src/shards/_template/data/skins.json +32 -0
  44. package/src/shards/_template/data/water.json +18 -0
  45. package/src/shards/_template/generators/product.ts +5 -1
  46. package/src/shards/_template/generators/warden.ts +273 -0
  47. package/src/shards/_template/generators/world.ts +52 -21
  48. package/src/shards/_template/hero.json +6 -6
  49. package/src/shards/authoring-slice/generators/shard.ts +9 -1
  50. package/src/shards/authoring-slice/generators/sky.ts +64 -0
  51. package/src/shards/authoring-slice/generators/template-sky.ts +27 -0
  52. package/src/shards/authoring-slice/generators/textures.ts +59 -0
  53. package/src/shards/authoring-slice/generators/world.ts +108 -5
  54. package/src/shards/mossgate/generators/shard.ts +6 -0
  55. package/src/shards/mossgate/generators/sky.ts +64 -0
  56. package/src/shards/mossgate/generators/textures.ts +249 -0
  57. package/src/shards/mossgate/generators/world.ts +998 -0
  58. package/src/shards/mossgate/shard.config.ts +7 -0
  59. package/scripts/shard-output-report.d.mts +0 -9
  60. package/scripts/shard-output-report.mjs +0 -85
  61. package/scripts/shard-platform-cli.mjs +0 -93
@@ -1,28 +1,41 @@
1
- import { BufferAttribute, BufferGeometry, Float32BufferAttribute, Matrix3, Matrix4, MeshStandardMaterial, Quaternion, Vector3 } from 'three';
1
+ import { Box3, BufferAttribute, BufferGeometry, Color, Float32BufferAttribute, Matrix3, Matrix4, MeshStandardMaterial, Quaternion, Vector3 } from 'three';
2
+ import type { PoolSurface } from '@wildshard/format/pool-surface';
2
3
  import { parseShardfile, type Shardfile } from '@wildshard/format/shardSchema';
3
4
  import { emptyShardfile } from '../author';
4
5
  import { parseGlb, parseKtx2 } from '../assets';
5
6
  import { hashImmutableBytes } from '../immutable';
6
7
  import type { GeneratedProject, ProjectGenerationContext } from '../projectGeneration';
7
8
  import { staticGlb, type GlbPrimitive } from '../bake/glb';
8
- import { bakeTerrain } from '../bake/terrain';
9
+ import { bakeTerrain, groundLattice } from '../bake/terrain';
10
+ import { encodeTerrainTile } from '@wildshard/format/terrainTileBytes';
9
11
  import { bakeRawColourPixels } from '../bake/rawTexture';
10
- import type { Rgb, SceneCollider, SceneDraw, SceneGeometry, SceneLight, SceneMaterial, ScenePart, ShardScene } from './description';
12
+ import type { Rgb, SceneCollider, SceneDraw, SceneGeometry, SceneLight, SceneMaterial, SceneMotion, ScenePart, ShardScene } from './description';
13
+ import { SceneRefusalError } from './lower';
14
+ import { hashOf } from './hash';
11
15
 
12
16
  /**
13
17
  * AUTHORING-PARITY AP2, AP3, AP4: the shardfile back end. It reads only the scene description and writes the sections an
14
18
  * author types by hand today:
15
19
  *
16
- * - **static parts** (AP2): every `Mesh` and `InstancedMesh`, merged per material per 62.5 m tile (instances expanded, their
17
- * colours in the vertex colours, the map's repeat and offset in the uvs), one named GLB material per scene material, a
18
- * generated `look.materials` entry and `props.materials` binding for each, painted textures as RGBA8 KTX2 slots;
20
+ * - **static parts** (AP2): every `Mesh`, merged per material per 62.5 m tile (the map's repeat and offset in the uvs), one
21
+ * named GLB material per scene material, a generated `look.materials` entry and `props.materials` binding for each,
22
+ * painted textures as RGBA8 KTX2 slots; an `InstancedMesh` with no motion stays instanced (SHARD-SOURCE AP15): its
23
+ * geometry once per tile, its copies as `EXT_mesh_gpu_instancing` rows in the tile of their seat (a swaying or carded
24
+ * one is still expanded: the engine's sway reads the mesh's own frame);
19
25
  * - **light and look** (AP3): `PointLight`s to `look.light.lamps` (the 16 brightest), the brightest `DirectionalLight` to
20
26
  * the sun key, a `HemisphereLight` to the ambient key, `scene.fog`, `world.post`;
21
27
  * - **ground, colliders, water** (AP4): `world.ground(heightAt)` to the terrain bake, `solid(mesh)` to collider boxes, each
22
28
  * `Water` to a `water[]` pool row whose outline is its own geometry's.
29
+ * - **panels** (AP16): a `world.part(name, build, { panel })` is one library GLB of its own (`props.panels`, every entry
30
+ * merged whole) and one collider bound to it, so a `targets.panels` row hides both by state (a gate that opens).
31
+ *
32
+ * - **cards** (AP11): every `Sprite` and every point of a `Points` cloud as a camera-facing quad (its seat in `position`, its
33
+ * corner in the `_CORNER` channel), merged per material and motion per tile: one draw a tile, an emissive `card` entry;
34
+ * - **declared motion** (AP12): a light's `flicker` to its lamp row, a card's `pulse` / `drift` / `rise` to its entry's
35
+ * `motion`, a mesh's `sway` to its entry's `sway` plus a `_SWAY` channel (metres, growing with the square of the height
36
+ * over the mesh's own bounds), a mesh's `uvScroll` to its entry's `uvScroll`.
23
37
  *
24
38
  * Phone tile caps are reported, not enforced (J338: this shard may use up to 50 MB): AP9 turns them into a per-part table.
25
- * Sprites have no shardfile lowering until AP11 and are reported, never silently dropped.
26
39
  */
27
40
 
28
41
  export interface ShardfileOptions {
@@ -31,26 +44,45 @@ export interface ShardfileOptions {
31
44
  }
32
45
 
33
46
  const TILE = 62.5, HALF = 250;
47
+ /** AP15: how far an instanced copy may hang past the cell's edge (format `props.overhang`, at most 1 m). */
48
+ const OVERHANG = 1;
34
49
  const glbName = (material: SceneMaterial, taken: Map<string, string>): string => {
35
50
  const wanted = material.name.replaceAll(/[^\w.-]/gu, '-').slice(0, 96) || material.key;
36
51
  const owner = taken.get(wanted);
37
52
  const name = owner === undefined || owner === material.key ? wanted : `${wanted}-${material.key}`;
38
53
  taken.set(name, material.key); return name;
39
54
  };
40
- const lookId = (material: SceneMaterial): string => `scene.${material.key}`;
55
+ const lookId = (key: string): string => `scene.${key}`;
56
+ /** A point's card width per metre of `PointsMaterial.size` (three's size attenuation at the cleanrooms' 72° view: tan 36°). */
57
+ const POINT_CARD = 0.7265;
58
+ /** One merge's material: the scene material, the motion its draws declare, and whether it is a card. */
59
+ interface Entry { readonly material: SceneMaterial; readonly motion: SceneMotion | null; readonly card: boolean }
60
+ const entryKey = (material: string, motion: SceneMotion | null, card = false): string =>
61
+ motion === null && !card ? material : `${material}${card ? '.card' : ''}${motion === null ? '' : `.${hashOf((h) => h.json(motion))}`}`;
41
62
  const luminance = ([r, g, b]: Rgb): number => 0.2126 * r + 0.7152 * g + 0.0722 * b;
42
63
  const clamp01 = (value: number): number => Math.min(1, Math.max(0, value));
43
64
  const round = (value: number, digits = 4): number => { const k = 10 ** digits; const out = Math.round(value * k) / k; return out === 0 ? 0 : out; };
44
65
  const rgb01 = (colour: Rgb): [number, number, number] => [round(clamp01(colour[0])), round(clamp01(colour[1])), round(clamp01(colour[2]))];
66
+ /** A linear channel as sRGB (three's `LinearToSRGB`). */
67
+ const toSrgb = (c: number): number => (c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055);
68
+ /**
69
+ * ss4d: a linear colour (every scene colour, as three.js holds it) as the format's sRGB material colour (`look.materials`
70
+ * `colour`, `emissive` and a detail layer's moss are sRGB: what an artist picks; engine `families/pbr.ts` reads them with
71
+ * `SRGBColorSpace`). Lamps, fog, sky keys, pool tints and the environment ground stay linear, as the format says.
72
+ */
73
+ const srgb01 = (colour: Rgb): [number, number, number] => [round(clamp01(toSrgb(clamp01(colour[0])))), round(clamp01(toSrgb(clamp01(colour[1])))), round(clamp01(toSrgb(clamp01(colour[2]))))];
74
+ /** ss4d: the ground's PBR material id (the terrain family; the format's default `toon` drew a lit scene's ground flat). */
75
+ export const GROUND_MATERIAL = 'scene.ground';
45
76
 
46
77
  /** One tile's growing merge for one material: world-space vertices and an index (a copy inside one tile keeps its
47
78
  * own index; a triangle cut at a tile seam adds its clipped corners). */
48
- interface Merge { position: number[]; normal: number[]; uv: number[]; colour: number[]; index: number[] }
79
+ interface Merge { position: number[]; normal: number[]; uv: number[]; colour: number[]; index: number[]; sway: number[]; corner: number[] }
80
+ const emptyMerge = (): Merge => ({ position: [], normal: [], uv: [], colour: [], index: [], sway: [], corner: [] });
49
81
 
50
82
  /** The tiles a world box touches, by L0 address. */
51
83
  const tileOf = (value: number): number => Math.min(7, Math.max(0, Math.floor((value + HALF) / TILE)));
52
84
 
53
- interface Vertex { p: Vector3; n: Vector3; u: number; v: number; c: Vector3 }
85
+ interface Vertex { p: Vector3; n: Vector3; u: number; v: number; c: Vector3; s: number }
54
86
  function clipToTile(triangle: readonly Vertex[], x: number, z: number): Vertex[] {
55
87
  const x0 = -HALF + x * TILE, z0 = -HALF + z * TILE;
56
88
  let polygon = [...triangle];
@@ -60,14 +92,14 @@ function clipToTile(triangle: readonly Vertex[], x: number, z: number): Vertex[]
60
92
  const a = input[i], b = input[(i + 1) % input.length]; if (a === undefined || b === undefined) continue;
61
93
  const da = (a.p[axis] - limit) * direction, db = (b.p[axis] - limit) * direction;
62
94
  if (da >= 0) polygon.push(a);
63
- if ((da < 0) !== (db < 0)) { const t = da / (da - db); polygon.push({ p: a.p.clone().lerp(b.p, t), n: a.n.clone().lerp(b.n, t).normalize(), u: a.u + (b.u - a.u) * t, v: a.v + (b.v - a.v) * t, c: a.c.clone().lerp(b.c, t) }); }
95
+ if ((da < 0) !== (db < 0)) { const t = da / (da - db); polygon.push({ p: a.p.clone().lerp(b.p, t), n: a.n.clone().lerp(b.n, t).normalize(), u: a.u + (b.u - a.u) * t, v: a.v + (b.v - a.v) * t, c: a.c.clone().lerp(b.c, t), s: a.s + (b.s - a.s) * t }); }
64
96
  }
65
97
  }
66
98
  return polygon;
67
99
  }
68
100
 
69
- /** Expand every draw of one material into per-tile world triangles. */
70
- function mergeDraws(draws: readonly SceneDraw[], scene: ShardScene, tiles: Map<string, Map<string, Merge>>): void {
101
+ /** Expand every draw of one entry into per-tile world triangles. */
102
+ function mergeDraws(key: string, draws: readonly SceneDraw[], scene: ShardScene, tiles: Map<string, Map<string, Merge>>): void {
71
103
  const p = new Vector3(), n = new Vector3(), world = new Matrix4(), local = new Matrix4(), normalMatrix = new Matrix3();
72
104
  for (const draw of draws) {
73
105
  const geometry = scene.geometries[draw.geometry], material = scene.materials[draw.material];
@@ -78,27 +110,81 @@ function mergeDraws(draws: readonly SceneDraw[], scene: ShardScene, tiles: Map<s
78
110
  normalMatrix.getNormalMatrix(world);
79
111
  const flip = world.determinant() < 0;
80
112
  const tint = draw.instances?.colours ? new Vector3(draw.instances.colours[copy * 3] ?? 1, draw.instances.colours[copy * 3 + 1] ?? 1, draw.instances.colours[copy * 3 + 2] ?? 1) : new Vector3(1, 1, 1);
81
- appendCopy(geometry, material, world, normalMatrix, flip, tint, draw.material, tiles, p, n);
113
+ appendCopy(geometry, material, world, normalMatrix, flip, tint, key, tiles, p, n, draw.motion?.kind === 'sway' ? draw.motion.amount : 0);
82
114
  }
83
115
  }
84
116
  }
85
117
 
86
- function appendCopy(geometry: SceneGeometry, material: SceneMaterial, world: Matrix4, normalMatrix: Matrix3, flip: boolean, tint: Vector3, key: string, tiles: Map<string, Map<string, Merge>>, p: Vector3, n: Vector3): void {
118
+ /** AP15: one instanced draw's copies in one tile: its base geometry (local, uvs and vertex colours as the merge writes
119
+ * them) once, each copy's world matrix and its colour. */
120
+ interface InstancedGroup { key: string; geometry: BufferGeometry; matrices: Matrix4[]; colours: Color[] | null; castShadow: boolean; box: Box3 }
121
+ /** The fewest copies a draw needs to stay instanced (below it the merge is as small). */
122
+ const INSTANCE_MIN = 2, INSTANCE_CAP = 10_000;
123
+
124
+ /** A copy the engine's loader can place: translation, rotation and a positive scale, no shear (the loader reads instance
125
+ * TRS rows; an exact `_MATRIX` row loads as the identity there). */
126
+ function isTrs(matrix: Matrix4): boolean {
127
+ const position = new Vector3(), rotation = new Quaternion(), scale = new Vector3();
128
+ matrix.decompose(position, rotation, scale);
129
+ const composed = new Matrix4().compose(position, rotation, scale);
130
+ return scale.x > 0 && scale.y > 0 && scale.z > 0 && matrix.elements.every((n, i) => Number.isFinite(n) && Math.abs(n - (composed.elements[i] ?? Infinity)) <= 1e-6);
131
+ }
132
+
133
+ /** AP15: an `InstancedMesh` with no motion as per-tile instance groups, or null when a copy is mirrored or sheared (the
134
+ * merge takes it). Instance colours over 1 are folded into the base colours (glTF instance colours are 0 to 1). */
135
+ function instanceGroups(key: string, draw: SceneDraw, scene: ShardScene): Map<string, InstancedGroup> | null {
136
+ const geometry = scene.geometries[draw.geometry], material = scene.materials[draw.material], instances = draw.instances;
137
+ if (geometry === undefined || material === undefined || instances === null) return null;
138
+ const base = new Matrix4().fromArray(draw.matrix), worlds: Matrix4[] = [];
139
+ for (let copy = 0; copy < instances.count; copy++) {
140
+ const world = base.clone().multiply(new Matrix4().fromArray(instances.matrices, copy * 16));
141
+ if (!(world.determinant() > 0) || !isTrs(world)) return null;
142
+ worlds.push(world);
143
+ }
144
+ const tints = instances.colours; let peak = 1; if (tints !== null) for (const tint of tints) peak = Math.max(peak, tint);
145
+ const count = geometry.position.length / 3, uv = new Float32Array(count * 2), colour = new Float32Array(count * 3);
146
+ for (let at = 0; at < count; at++) {
147
+ uv[at * 2] = (geometry.uv?.[at * 2] ?? 0) * material.repeat[0] + material.offset[0];
148
+ uv[at * 2 + 1] = (geometry.uv?.[at * 2 + 1] ?? 0) * material.repeat[1] + material.offset[1];
149
+ for (let c = 0; c < 3; c++) colour[at * 3 + c] = (material.vertexColours && geometry.colour !== null ? geometry.colour[at * 3 + c] ?? 1 : 1) * peak;
150
+ }
151
+ const shape = new BufferGeometry().setAttribute('position', new Float32BufferAttribute(geometry.position, 3)).setAttribute('normal', new Float32BufferAttribute(geometry.normal, 3))
152
+ .setAttribute('uv', new Float32BufferAttribute(uv, 2)).setAttribute('color', new BufferAttribute(colour, 3));
153
+ if (geometry.index !== null) shape.setIndex([...geometry.index]);
154
+ shape.computeBoundingBox();
155
+ const local = shape.boundingBox ?? new Box3(), groups = new Map<string, InstancedGroup>();
156
+ worlds.forEach((world, copy) => {
157
+ const tile = `${tileOf(world.elements[12] ?? 0)}/${tileOf(world.elements[14] ?? 0)}`;
158
+ let group = groups.get(tile);
159
+ if (group === undefined) { group = { key, geometry: shape, matrices: [], colours: tints === null ? null : [], castShadow: draw.castShadow, box: new Box3() }; groups.set(tile, group); }
160
+ group.matrices.push(world);
161
+ if (tints !== null) group.colours?.push(new Color((tints[copy * 3] ?? 1) / peak, (tints[copy * 3 + 1] ?? 1) / peak, (tints[copy * 3 + 2] ?? 1) / peak));
162
+ group.box.union(local.clone().applyMatrix4(world));
163
+ });
164
+ return groups;
165
+ }
166
+
167
+ function appendCopy(geometry: SceneGeometry, material: SceneMaterial, world: Matrix4, normalMatrix: Matrix3, flip: boolean, tint: Vector3, key: string, tiles: Map<string, Map<string, Merge>>, p: Vector3, n: Vector3, sway = 0): void {
87
168
  const count = geometry.index?.length ?? geometry.position.length / 3;
169
+ // AP12: sway grows with the square of the height over the geometry's own bounds (0 at its root)
170
+ let low = Infinity, high = -Infinity;
171
+ if (sway > 0) for (let i = 1; i < geometry.position.length; i += 3) { const y = geometry.position[i] ?? 0; low = Math.min(low, y); high = Math.max(high, y); }
172
+ const swayAt = (at: number): number => (sway > 0 && high > low ? sway * (((geometry.position[at * 3 + 1] ?? low) - low) / (high - low)) ** 2 : 0);
88
173
  const vertex = (at: number): Vertex => ({ // world-space corner
89
174
  p: p.fromArray(geometry.position, at * 3).applyMatrix4(world).clone(),
90
175
  n: n.fromArray(geometry.normal, at * 3).applyMatrix3(normalMatrix).normalize().clone(),
91
176
  u: (geometry.uv?.[at * 2] ?? 0) * material.repeat[0] + material.offset[0], v: (geometry.uv?.[at * 2 + 1] ?? 0) * material.repeat[1] + material.offset[1],
92
177
  c: (material.vertexColours && geometry.colour !== null ? new Vector3().fromArray(geometry.colour, at * 3) : new Vector3(1, 1, 1)).multiply(tint),
178
+ s: swayAt(at),
93
179
  });
94
180
  const mergeOf = (tile: string): Merge => {
95
181
  const merges = tiles.get(tile) ?? new Map<string, Merge>(); tiles.set(tile, merges);
96
- const merge = merges.get(key) ?? { position: [], normal: [], uv: [], colour: [], index: [] }; merges.set(key, merge);
182
+ const merge = merges.get(key) ?? emptyMerge(); merges.set(key, merge);
97
183
  return merge;
98
184
  };
99
185
  const push = (merge: Merge, corner: Vertex): number => {
100
186
  merge.position.push(corner.p.x, corner.p.y, corner.p.z); merge.normal.push(corner.n.x, corner.n.y, corner.n.z);
101
- merge.uv.push(corner.u, corner.v); merge.colour.push(corner.c.x, corner.c.y, corner.c.z);
187
+ merge.uv.push(corner.u, corner.v); merge.colour.push(corner.c.x, corner.c.y, corner.c.z); merge.sway.push(corner.s);
102
188
  return merge.position.length / 3 - 1;
103
189
  };
104
190
  const vertexCount = geometry.position.length / 3, corners = Array.from({ length: vertexCount }, (_, at) => vertex(at));
@@ -126,18 +212,71 @@ function appendCopy(geometry: SceneGeometry, material: SceneMaterial, world: Mat
126
212
  }
127
213
  }
128
214
 
215
+ /** AP11: one camera-facing quad per card, into its seat's tile: `position` the seat, `_CORNER` the view-space offset. */
216
+ function appendCard(key: string, seat: readonly [number, number, number], size: readonly [number, number], centre: readonly [number, number], tiles: Map<string, Map<string, Merge>>): void {
217
+ const tile = `${tileOf(seat[0])}/${tileOf(seat[2])}`, merges = tiles.get(tile) ?? new Map<string, Merge>(); tiles.set(tile, merges);
218
+ const merge = merges.get(key) ?? emptyMerge(); merges.set(key, merge);
219
+ const base = merge.position.length / 3;
220
+ for (const [u, v] of [[0, 0], [1, 0], [1, 1], [0, 1]] as const) {
221
+ merge.position.push(seat[0], seat[1], seat[2]); merge.normal.push(0, 0, 1); merge.uv.push(u, v); merge.colour.push(1, 1, 1); merge.sway.push(0);
222
+ merge.corner.push((u - centre[0]) * size[0], (v - centre[1]) * size[1]);
223
+ }
224
+ merge.index.push(base, base + 1, base + 2, base, base + 2, base + 3);
225
+ }
226
+
129
227
  /** A merge cut into primitives of at most 200,000 vertices, each with its own compact vertex list. */
228
+ /** One entry's merge as GLB primitives: a card's corners and a swaying surface's amplitude ride their own channels (AP11, AP12). */
229
+ function primitivesOf(merge: Merge, entry: Entry, name: string, castShadow: boolean): GlbPrimitive[] {
230
+ const swaying = entry.motion?.kind === 'sway';
231
+ return chunks(merge).map((chunk) => {
232
+ const geometry = new BufferGeometry().setAttribute('position', new Float32BufferAttribute(chunk.position, 3)).setAttribute('normal', new Float32BufferAttribute(chunk.normal, 3))
233
+ .setAttribute('uv', new Float32BufferAttribute(chunk.uv, 2)).setAttribute('color', new BufferAttribute(new Float32Array(chunk.colour), 3)).setIndex(chunk.index);
234
+ if (entry.card) geometry.setAttribute('corner', new Float32BufferAttribute(chunk.corner, 2));
235
+ if (swaying) geometry.setAttribute('sway', new Float32BufferAttribute(chunk.sway, 1));
236
+ const material = new MeshStandardMaterial({ color: 0xffffff, vertexColors: true }); material.name = name;
237
+ const primitive: GlbPrimitive = { geometry, material, castShadow: entry.card ? false : castShadow };
238
+ if (entry.card) primitive.customAttributes = { _CORNER: 'corner' }; else if (swaying) primitive.customAttributes = { _SWAY: 'sway' };
239
+ return primitive;
240
+ });
241
+ }
242
+
243
+ /** A primitive's GLB bytes, near enough to batch by: 44 a vertex (position, normal, uv, colour, one more channel), 4 an index, 76 an instance. */
244
+ function glbBytes(primitive: GlbPrimitive): number {
245
+ return primitive.geometry.getAttribute('position').count * 44 + (primitive.geometry.getIndex()?.count ?? 0) * 4 + (primitive.instances?.length ?? 0) * 76;
246
+ }
247
+
248
+ /** `from`'s vertices and triangles added to `into` (AP16's panels: one merge a material across tiles). */
249
+ function appendMerge(into: Merge, from: Merge): void {
250
+ const base = into.position.length / 3;
251
+ // element by element: a spread of a large merge overflows the call stack
252
+ for (const channel of ['position', 'normal', 'uv', 'colour', 'sway', 'corner'] as const) for (const value of from[channel]) into[channel].push(value);
253
+ for (const at of from.index) into.index.push(at + base);
254
+ }
255
+
256
+ /** AP16: what the library roots cost with their dependencies (format asset admission's `budgets.library` check). */
257
+ function libraryCost(files: Shardfile['files'], roots: readonly string[]): { resident: number; compressed: number } {
258
+ const byHash = new Map(files.map((f) => [f.hash, f])), seen = new Set<string>(), pending = [...roots];
259
+ let resident = 0, compressed = 0;
260
+ while (pending.length > 0) {
261
+ const hash = pending.pop(); if (hash === undefined || seen.has(hash)) continue;
262
+ seen.add(hash); const file = byHash.get(hash); if (file === undefined) continue;
263
+ resident += file.decoded + file.gpu; compressed += file.compressed; pending.push(...file.dependencies);
264
+ }
265
+ return { resident, compressed };
266
+ }
267
+
130
268
  function chunks(merge: Merge, limit = 200_000): Merge[] {
131
269
  if (merge.position.length / 3 <= limit) return [merge];
132
270
  const out: Merge[] = []; let current: Merge | null = null, remap = new Map<number, number>();
133
271
  for (let i = 0; i < merge.index.length; i += 3) {
134
- if (current === null || current.position.length / 3 + 3 > limit) { current = { position: [], normal: [], uv: [], colour: [], index: [] }; out.push(current); remap = new Map(); }
272
+ if (current === null || current.position.length / 3 + 3 > limit) { current = emptyMerge(); out.push(current); remap = new Map(); }
135
273
  for (let k = 0; k < 3; k++) {
136
274
  const from = merge.index[i + k] ?? 0; let to = remap.get(from);
137
275
  if (to === undefined) {
138
276
  to = current.position.length / 3; remap.set(from, to);
139
277
  current.position.push(...merge.position.slice(from * 3, from * 3 + 3)); current.normal.push(...merge.normal.slice(from * 3, from * 3 + 3));
140
278
  current.uv.push(...merge.uv.slice(from * 2, from * 2 + 2)); current.colour.push(...merge.colour.slice(from * 3, from * 3 + 3));
279
+ current.sway.push(merge.sway[from] ?? 0); current.corner.push(...merge.corner.slice(from * 2, from * 2 + 2));
141
280
  }
142
281
  current.index.push(to);
143
282
  }
@@ -164,20 +303,35 @@ function boxRow(collider: SceneCollider): { kind: 'box'; x: number; y: number; z
164
303
  }
165
304
 
166
305
  /** Point lights as the look's lamp rows (`look.light.lamps`): what a baked shard and a watched part (the dev hook) both draw. */
167
- export function lampRows(lights: readonly SceneLight[]): { at: [number, number, number]; colour: [number, number, number]; intensity: number; distance: number }[] {
168
- return lights.filter((l) => l.kind === 'point').map((l) => ({ at: l.position.map((v) => round(v, 3)) as [number, number, number], colour: rgb01(l.colour), intensity: round(Math.min(100, l.intensity), 3), distance: round(Math.min(50, Math.max(0.1, l.distance === 0 ? 50 : l.distance)), 3) }));
306
+ export function lampRows(lights: readonly SceneLight[]): { at: [number, number, number]; colour: [number, number, number]; intensity: number; distance: number; decay?: number; flicker?: { rate: number; amount: number } }[] {
307
+ type LampRow = ReturnType<typeof lampRows>[number];
308
+ const rows: LampRow[] = [];
309
+ for (const l of lights) {
310
+ if (l.kind !== 'point') continue;
311
+ const row: LampRow = { at: [round(l.position[0], 3), round(l.position[1], 3), round(l.position[2], 3)], colour: rgb01(l.colour), intensity: round(Math.min(100, l.intensity), 3),
312
+ distance: round(Math.min(50, Math.max(0.1, l.distance === 0 ? 50 : l.distance)), 3) };
313
+ if (l.decay !== 2) row.decay = round(clamp01(l.decay / 2) * 2, 3);
314
+ // AP12: the light's declared flicker, played by the engine's lamps (format `lamps[].flicker`)
315
+ if (l.motion?.kind === 'flicker') row.flicker = { rate: round(Math.min(30, l.motion.rate), 3), amount: round(clamp01(l.motion.amount), 3) };
316
+ rows.push(row);
317
+ }
318
+ return rows;
169
319
  }
170
320
 
171
321
  /** A part's `Water` surfaces as the shardfile's water rows (AP4): the outline is the Water's own geometry. */
172
- export function waterRows(part: ScenePart): { id: string; kind: 'pool'; level: number; shape: { kind: 'polygon'; points: [number, number][] } }[] {
322
+ export function waterRows(part: ScenePart): { id: string; kind: 'pool'; level: number; shape: { kind: 'polygon'; points: [number, number][] }; surface: PoolSurface }[] {
173
323
  return part.water.map((w, i) => ({
174
324
  id: `scene.${part.name}.water${i === 0 ? '' : `-${i}`}`, kind: 'pool', level: round(w.level, 3),
175
325
  shape: { kind: 'polygon', points: w.outline.map(([px, pz]) => [round(px, 3), round(pz, 3)]) },
176
- // shard-format 0.4.10 has no water surface fields; tint and planar reflection ride TEMPLATES-CLEANROOM M4.6's format
326
+ // AP14: the Water's own reflection and deep tint (format pool-surface, TEMPLATES-CLEANROOM M4.6): the cleanroom pond's
327
+ // Fresnel 0.35 + 0.65 (1 - v.y)^3 and its 1024 mirror; a planar mirror shows the painted sky, a phone's sky reflection too
328
+ surface: { reflect: w.reflect, tint: rgb01(w.tint), fresnel: [0.35, 3], ripple: { scale: 3, amplitude: 0.0022, speed: 1 }, resolution: 1024 },
177
329
  }));
178
330
  }
179
331
 
180
- /** The look a scene declares (AP3), over the format's day-key model fixed at one time of day. */
332
+ /** The look a scene declares (AP3), over the format's day-key model fixed at one time of day. The engine sets its
333
+ * hemisphere light's intensity to the ambient key's (engine `dataLook.ts`), so the key is the HemisphereLight's own
334
+ * number (ss4d: it was x pi, a ground three times brighter than its cleanroom's). */
181
335
  export function sceneLook(scene: ShardScene, lights: readonly SceneLight[], materials: Record<string, unknown>): Shardfile['look'] {
182
336
  const directional = lights.filter((l) => l.kind === 'directional').sort((a, b) => b.intensity - a.intensity);
183
337
  const sun = directional[0], hemisphere = lights.find((l) => l.kind === 'hemisphere'), ambient = lights.find((l) => l.kind === 'ambient');
@@ -186,47 +340,92 @@ export function sceneLook(scene: ShardScene, lights: readonly SceneLight[], mate
186
340
  const toSun = sun === undefined ? new Vector3(0.3, 1, 0.4) : new Vector3(...sun.position).sub(new Vector3(...sun.target ?? [0, 0, 0]));
187
341
  toSun.normalize();
188
342
  const elevation = Math.asin(clamp01(toSun.y)) * 180 / Math.PI, azimuth = Math.atan2(toSun.x, -toSun.z) * 180 / Math.PI;
189
- const fog = scene.look.fog, post = scene.look.post;
343
+ const fog = scene.look.fog, post = scene.look.post, sky = scene.look.sky ?? null;
190
344
  const skyColour: Rgb = hemisphere?.colour ?? ambient?.colour ?? [0.5, 0.5, 0.6], groundColour: Rgb = hemisphere?.groundColour ?? skyColour;
191
345
  const fogColour: Rgb = fog?.colour ?? scene.look.background ?? skyColour;
192
346
  return {
193
347
  families: ['pbr', 'emissive'], materials: materials as Shardfile['look']['materials'],
348
+ ...(post?.passes === undefined || post.passes.length === 0 ? {} : { post: post.passes.map((graph) => ({ graph })) }),
349
+ // AP14: the painted sky on the dome; the engine filters its environment from the same dome
350
+ ...(sky === null ? {} : { sky: { graph: sky.graph } }),
194
351
  grade: { exposure: round(Math.log2(post?.exposure ?? 1), 3), saturation: 1, contrast: 1, lut: null,
195
- ...(post?.bloom === null || post?.bloom === undefined ? {} : { bloom: { intensity: round(Math.min(4, post.bloom.strength * 1.5), 3), threshold: round(post.bloom.threshold, 3) } }),
196
- ...(post?.tone === 'neutral' ? { tone: 'neutral' } : {}) },
352
+ ...(post?.bloom === null || post?.bloom === undefined ? {} : { bloom: { intensity: round(Math.min(4, post.bloom.strength * 1.5), 3), threshold: round(post.bloom.threshold, 3), radius: round(clamp01(post.bloom.radius), 3) } }),
353
+ ...(post?.tone === 'neutral' || post?.tone === 'aces' ? { tone: post.tone } : {}) },
197
354
  clock: 'engine', day: { minutes: 12, start: 0.5, maxElevation: round(Math.max(5, elevation), 2), azimuth: round(azimuth, 2) }, dayOverride: 0.5,
198
355
  keys: [{ time: 0, sky: { zenith: rgb01(skyColour), horizon: rgb01(fogColour) },
199
356
  fog: fog?.kind === 'linear' ? { colour: rgb01(fog.colour), density: 0, near: fog.near, far: fog.far } : { colour: rgb01(fogColour), density: round(fog?.kind === 'exp2' ? fog.density : 0, 5) },
200
357
  sun: { colour: rgb01(sun?.colour ?? [1, 1, 1]), intensity: round(sun?.intensity ?? 0, 3) },
201
- ambient: { sky: rgb01(skyColour), ground: rgb01(groundColour), intensity: round((hemisphere?.intensity ?? ambient?.intensity ?? 0.5) * Math.PI, 3) } }],
202
- light: lamps.length === 0 ? {} : { lamps: lampRows(lamps) },
358
+ ambient: { sky: rgb01(skyColour), ground: rgb01(groundColour), intensity: round(hemisphere?.intensity ?? ambient?.intensity ?? 0.5, 3) } }],
359
+ light: { ...(lamps.length === 0 ? {} : { lamps: lampRows(lamps) }),
360
+ ...(sky?.environment === null || sky === null ? {} : { environment: { intensity: round(Math.min(4, sky.environment.intensity), 3), ground: rgb01(sky.environment.ground) } }) },
203
361
  } as Shardfile['look'];
204
362
  }
205
363
 
206
- /** A look.materials entry for one scene material (AP2): pbr for lit surfaces, emissive for glowing or unlit ones. */
207
- function materialEntry(material: SceneMaterial): Record<string, unknown> {
208
- const glow = luminance(material.emissive) * material.emissiveIntensity;
209
- if (material.kind === 'basic' || glow > 0.5) {
210
- const colour = material.kind === 'basic' ? material.colour : material.emissive;
211
- return { family: 'emissive', colour: rgb01(colour), intensity: round(Math.min(10, material.kind === 'basic' ? 1 : material.emissiveIntensity), 3), vertexColours: true, ...(material.side === 'double' ? { doubleSided: true } : {}) };
364
+ /** A linear HDR colour as an sRGB tint (0..1) and the gain that restores it. */
365
+ function tintAndGain(colour: Rgb): { tint: [number, number, number]; gain: number } {
366
+ const peak = Math.max(colour[0], colour[1], colour[2], 1e-6);
367
+ return { tint: srgb01([colour[0] / peak, colour[1] / peak, colour[2] / peak]), gain: peak };
368
+ }
369
+
370
+ /** A card's motion as the format's (AP12): only a card's kinds reach here. */
371
+ function cardMotion(motion: SceneMotion | null): Record<string, unknown> {
372
+ if (motion === null) return {};
373
+ if (motion.kind === 'pulse') return { motion: { kind: 'pulse', rate: round(Math.min(30, motion.rate), 3), amount: round(clamp01(motion.amount), 3) } };
374
+ if (motion.kind === 'drift') return { motion: { kind: 'drift', rate: round(Math.min(30, motion.rate), 3), radius: round(Math.min(10, motion.radius), 3) } };
375
+ if (motion.kind === 'rise') return { motion: { kind: 'rise', rate: round(Math.min(30, motion.rate), 3), height: round(Math.min(50, motion.height), 3), spread: round(Math.min(10, motion.spread), 3) } };
376
+ return {};
377
+ }
378
+
379
+ /**
380
+ * A look.materials entry for one scene material (AP2, AP10 to AP12): pbr for lit surfaces (with their own glow, alpha,
381
+ * decal offset, sway and uv scroll), emissive for unlit ones, an emissive card for a sprite or a point.
382
+ */
383
+ function materialEntry({ material, motion, card }: Entry): Record<string, unknown> {
384
+ const doubleSided = material.side === 'double' ? { doubleSided: true } : {};
385
+ if (material.entry !== null) return { ...material.entry };
386
+ if (card) {
387
+ const { tint, gain } = tintAndGain(material.colour);
388
+ return { family: 'emissive', card: true, colour: tint, intensity: round(Math.min(64, gain * material.opacity), 3), blend: material.blending === 'additive' ? 'additive' : 'alpha',
389
+ fog: material.fog ? 1 : 0, ...cardMotion(motion) };
390
+ }
391
+ if (material.kind === 'basic') {
392
+ const { tint, gain } = tintAndGain(material.colour);
393
+ return { family: 'emissive', colour: tint, intensity: round(Math.min(64, gain * (material.blending === 'additive' ? material.opacity : 1)), 3), vertexColours: true, ...doubleSided,
394
+ ...(material.blending === 'additive' ? { blend: 'additive' } : material.transparent ? { blend: 'alpha' } : {}), ...(material.fog ? {} : { fog: 0 }) };
212
395
  }
213
- // AP10 adds sorted transparency; until then a transparent surface is cut at a low alpha, as a decal mostly is
214
- const cutoff = material.alphaTest > 0 ? material.alphaTest : material.transparent && material.map !== null ? 0.3 : 0;
215
- return { family: 'pbr', colour: rgb01(material.colour), roughness: round(clamp01(material.roughness), 3), metalness: round(clamp01(material.metalness), 3), vertexColours: true,
216
- ...(material.side === 'double' ? { doubleSided: true } : {}), ...(cutoff > 0 ? { alphaCutoff: round(cutoff, 3) } : {}) };
396
+ const glow = luminance(material.emissive) * material.emissiveIntensity, emissive = glow > 0 ? tintAndGain(material.emissive) : null;
397
+ const alpha = material.transparent && material.blending === 'normal';
398
+ return { family: 'pbr', colour: srgb01(material.colour), roughness: round(clamp01(material.roughness), 3), metalness: round(clamp01(material.metalness), 3), vertexColours: true, ...doubleSided,
399
+ ...(material.alphaTest > 0 ? { alphaCutoff: round(clamp01(material.alphaTest), 3) } : {}),
400
+ // M4.3: a lit surface's own glow (lamp glass, candles) stays lit by the sun and lamps
401
+ ...(emissive === null ? {} : { emissive: emissive.tint, emissiveIntensity: round(Math.min(64, emissive.gain * material.emissiveIntensity), 3) }),
402
+ // AP10: a see-through surface sorts after the opaque world; a polygon offset pulls a decal off its wall
403
+ ...(alpha ? { blend: 'alpha', ...(material.opacity < 1 ? { opacity: round(clamp01(material.opacity), 3) } : {}) } : {}),
404
+ ...(material.polygonOffset === 0 ? {} : { depthOffset: round(Math.min(16, Math.max(-16, material.polygonOffset)), 3) }),
405
+ // AP12: wind sway (its amplitude rides the _SWAY channel) and a scrolling map
406
+ ...(motion?.kind === 'sway' ? { sway: { rate: round(Math.min(8, motion.rate), 3), direction: [round(Math.max(-1, Math.min(1, motion.direction[0])), 3), round(Math.max(-1, Math.min(1, motion.direction[1])), 3)] } } : {}),
407
+ ...(motion?.kind === 'uvScroll' ? { uvScroll: [round(Math.max(-10, Math.min(10, motion.u)), 4), round(Math.max(-10, Math.min(10, motion.v)), 4)] } : {}) };
408
+ }
409
+
410
+ /** ss4d: the ground's PBR entry: its vertex colours (`colourAt`, linear) times the material's colour, lit as the cleanroom's
411
+ * ground mesh is; a flat cell is a plain rough surface. */
412
+ export function groundEntry(scene: Pick<ShardScene, 'ground'>): Record<string, unknown> {
413
+ const surface = scene.ground?.surface ?? { colour: [1, 1, 1] as Rgb, roughness: 1, metalness: 0, detail: null };
414
+ return { family: 'pbr', colour: srgb01(surface.colour), roughness: round(clamp01(surface.roughness), 3), metalness: round(clamp01(surface.metalness), 3), vertexColours: true,
415
+ ...(surface.detail === null ? {} : { detail: surface.detail }) };
217
416
  }
218
417
 
219
418
  /** What the shardfile back end did not write, for the build log (never silent). */
220
- export interface ShardfileReport { readonly sprites: number; readonly lampsDropped: number; readonly tiles: readonly { tile: string; triangles: number; draws: number; bytes: number }[] }
419
+ export interface ShardfileReport { readonly cards: number; readonly lampsDropped: number; readonly tiles: readonly { tile: string; triangles: number; draws: number; bytes: number }[] }
221
420
 
222
421
  /** The shardfile back end: the description in, a generated project out. Runs at compile time. */
223
422
  export function compileShardfile(scene: ShardScene, ctx: ProjectGenerationContext, options: ShardfileOptions = {}): Promise<GeneratedProject> {
224
423
  const { shard, assets, report } = sceneShardfile(scene, options);
225
424
  for (const [hash, bytes] of assets) if (ctx.asset(bytes) !== hash) throw new Error('scene: an asset hash differs from the product store');
226
- if (report.sprites > 0) console.info(`scene: ${report.sprites} sprites are drawn by watch only until AP11 (billboards)`);
227
425
  if (report.lampsDropped > 0) console.info(`scene: ${report.lampsDropped} point lights past the 16 brightest are not in the shardfile (AP28)`);
228
- const over = report.tiles.filter((t) => t.triangles > 40_000 || t.draws > 8);
229
- if (over.length > 0) console.info(`scene: ${over.length} tiles are over the phone tile caps (J338; AP9 turns this into a per-part table): ${over.map((t) => `${t.tile} ${t.triangles} tris ${t.draws} draws`).join(', ')}`);
426
+ // AP8: draws are a view's budget now (the engine draws a material once across tiles; format VIEW_DRAWS), not a tile's
427
+ const over = report.tiles.filter((t) => t.triangles > 40_000);
428
+ if (over.length > 0) console.info(`scene: ${over.length} tiles are over the phone tile triangle cap (J338; AP9 turns this into a per-part table): ${over.map((t) => `${t.tile} ${t.triangles} tris ${t.draws} draws`).join(', ')}`);
230
429
  return Promise.resolve({ shard, output: {} });
231
430
  }
232
431
 
@@ -241,52 +440,100 @@ export function sceneShardfile(scene: ShardScene, options: ShardfileOptions = {}
241
440
  };
242
441
  // ground (AP4): the declared height field, or a flat cell
243
442
  const ground = scene.ground;
244
- const terrain = bakeTerrain({ heightAt: ground?.heightAt ?? (() => 0), colourAt: (x, z) => ground?.colourAt?.(x, z) ?? [0.3, 0.36, 0.2] });
443
+ const terrain = bakeTerrain({ ...groundSource(scene), family: GROUND_MATERIAL });
245
444
  for (const [hash, bytes] of terrain.assets) assets.set(hash, bytes);
246
445
  files.push(...terrain.files);
247
446
 
248
447
  // textures (AP2): RGBA8 KTX2, one file per painted raster
249
448
  const textureFiles = new Map<string, Shardfile['files'][number]>();
250
- // only the textures a drawn material samples: a sprite's (AP11) would be an orphan file
251
- const sampled = new Set(scene.parts.flatMap((part) => part.draws.map((d) => scene.materials[d.material]?.map)).filter((key) => typeof key === 'string'));
449
+ // only the textures a drawn material or a card samples
450
+ const sampled = new Set(scene.parts.flatMap((part) => [...part.draws.map((d) => d.material), ...part.sprites.map((c) => c.material), ...part.points.map((c) => c.material)].map((key) => scene.materials[key]?.map)).filter((key) => typeof key === 'string'));
252
451
  for (const texture of Object.values(scene.textures).filter((t) => sampled.has(t.key))) {
253
452
  const bytes = bakeRawColourPixels({ width: texture.width, height: texture.height, pixels: new Uint8ClampedArray(texture.rgba) }, { colourSpace: texture.colourSpace });
254
453
  textureFiles.set(texture.key, store(bytes, 'ktx2'));
255
454
  }
256
- // static parts (AP2): merged per material per tile
257
- const draws = scene.parts.flatMap((part) => part.draws), byMaterial = new Map<string, SceneDraw[]>();
258
- for (const draw of draws) { const list = byMaterial.get(draw.material) ?? []; list.push(draw); byMaterial.set(draw.material, list); }
455
+ // static parts (AP2): merged per entry (a material and the motion its draws declare) per tile
456
+ const draws = scene.parts.filter((part) => part.panel === undefined).flatMap((part) => part.draws), byEntry = new Map<string, SceneDraw[]>(), entries = new Map<string, Entry>();
457
+ const entryOf = (material: string, motion: SceneMotion | null, card = false): string | null => {
458
+ const found = scene.materials[material]; if (found === undefined) return null;
459
+ const key = entryKey(material, motion, card); if (!entries.has(key)) entries.set(key, { material: found, motion, card }); return key;
460
+ };
461
+ const instanced = new Map<string, InstancedGroup[]>();
462
+ for (const draw of draws) {
463
+ const key = entryOf(draw.material, draw.motion); if (key === null) continue;
464
+ // AP15: a still InstancedMesh stays instanced, its copies in the tiles of their seats
465
+ const groups = draw.motion === null && (draw.instances?.count ?? 0) >= INSTANCE_MIN ? instanceGroups(key, draw, scene) : null;
466
+ if (groups !== null) { for (const [tile, group] of groups) { const list = instanced.get(tile) ?? []; list.push(group); instanced.set(tile, list); } continue; }
467
+ const list = byEntry.get(key) ?? []; list.push(draw); byEntry.set(key, list);
468
+ }
259
469
  const tiles = new Map<string, Map<string, Merge>>();
260
- for (const list of byMaterial.values()) mergeDraws(list, scene, tiles);
261
- const names = new Map<string, string>(), used = [...byMaterial.keys()].flatMap((key) => { const m = scene.materials[key]; return m === undefined ? [] : [m]; });
262
- const glbNames = new Map(used.map((m) => [m.key, glbName(m, names)]));
263
- const casts = new Map<string, boolean>(); for (const draw of draws) casts.set(draw.material, (casts.get(draw.material) ?? false) || draw.castShadow);
470
+ for (const [key, list] of byEntry) mergeDraws(key, list, scene, tiles);
471
+ // cards (AP11): every sprite and every point a camera-facing quad in its seat's tile
472
+ let cards = 0;
473
+ for (const part of scene.parts) {
474
+ for (const sprite of part.sprites) { const key = entryOf(sprite.material, sprite.motion, true); if (key === null) continue; appendCard(key, sprite.position, sprite.scale, sprite.center, tiles); cards++; }
475
+ for (const cloud of part.points) {
476
+ const key = entryOf(cloud.material, cloud.motion, true), size = (scene.materials[cloud.material]?.pointSize ?? 0) * POINT_CARD; if (key === null) continue;
477
+ for (let i = 0; i < cloud.positions.length; i += 3) { appendCard(key, [cloud.positions[i] ?? 0, cloud.positions[i + 1] ?? 0, cloud.positions[i + 2] ?? 0], [size, size], [0.5, 0.5], tiles); cards++; }
478
+ }
479
+ }
480
+ // AP16: each panel part's entries, merged whole (the tile split only cuts its triangles; the panel is one GLB)
481
+ const panelParts = scene.parts.filter((part) => part.panel !== undefined).map((part) => {
482
+ const merges = new Map<string, Map<string, Merge>>(), shadows = new Map<string, boolean>(), byKey = new Map<string, SceneDraw[]>();
483
+ for (const draw of part.draws) {
484
+ const key = entryOf(draw.material, draw.motion); if (key === null) continue;
485
+ const list = byKey.get(key) ?? []; list.push(draw); byKey.set(key, list); shadows.set(key, (shadows.get(key) ?? false) || draw.castShadow);
486
+ }
487
+ for (const [key, list] of byKey) mergeDraws(key, list, scene, merges);
488
+ return { id: part.panel ?? part.name, merges, shadows };
489
+ });
490
+ const names = new Map<string, string>(), glbNames = new Map([...entries].map(([key, entry]) => [key, glbName({ ...entry.material, key, name: entry.card || entry.motion !== null ? `${entry.material.name}-${key.slice(entry.material.key.length + 1)}` : entry.material.name }, names)]));
491
+ const casts = new Map<string, boolean>(); for (const draw of draws) { const key = entryKey(draw.material, draw.motion); casts.set(key, (casts.get(key) ?? false) || draw.castShadow); }
264
492
  const lookMaterials: Record<string, unknown> = {}, propMaterials: Record<string, unknown> = {};
265
- for (const material of used) {
266
- const name = glbNames.get(material.key) ?? material.key, file = material.map === null ? undefined : textureFiles.get(material.map);
267
- lookMaterials[lookId(material)] = materialEntry(material);
268
- propMaterials[name] = { id: lookId(material), ...(file === undefined ? {} : { colour: { file: file.hash, wrapS: 10497, wrapT: 10497, minFilter: 9987, magFilter: 9729, anisotropy: 4 } }) };
493
+ for (const [key, entry] of entries) {
494
+ const name = glbNames.get(key) ?? key, file = entry.material.map === null ? undefined : textureFiles.get(entry.material.map);
495
+ lookMaterials[lookId(key)] = materialEntry(entry);
496
+ propMaterials[name] = { id: lookId(key), ...(file === undefined ? {} : { colour: { file: file.hash, wrapS: 10497, wrapT: 10497, minFilter: 9987, magFilter: 9729, anisotropy: 4 } }) };
269
497
  }
498
+ lookMaterials[GROUND_MATERIAL] = groundEntry(scene);
270
499
  const shardTiles = terrain.tiles.map((t) => ({ ...t, files: [...t.files], bounds: { min: [...t.bounds.min] as [number, number, number], max: [...t.bounds.max] as [number, number, number] } }));
271
500
  const propTiles: { lod: 0; x: number; z: number; file: string }[] = [], tileReport: { tile: string; triangles: number; draws: number; bytes: number }[] = [];
272
- for (const [address, merges] of [...tiles].sort(([a], [b]) => a.localeCompare(b))) {
501
+ const addresses = [...new Set([...tiles.keys(), ...instanced.keys()])].sort((a, b) => a.localeCompare(b));
502
+ for (const address of addresses) {
503
+ const merges = tiles.get(address) ?? new Map<string, Merge>();
273
504
  const [x = 0, z = 0] = address.split('/').map(Number);
274
- const primitives: GlbPrimitive[] = [], dependencies = new Set<string>();
505
+ const primitives: GlbPrimitive[] = [], dependencies = new Set<string>(), drawn = new Box3();
275
506
  for (const [key, merge] of [...merges].sort(([p], [q]) => p.localeCompare(q))) {
276
- const material = scene.materials[key]; if (material === undefined || merge.position.length === 0) continue;
277
- for (const chunk of chunks(merge)) {
278
- const geometry = new BufferGeometry().setAttribute('position', new Float32BufferAttribute(chunk.position, 3)).setAttribute('normal', new Float32BufferAttribute(chunk.normal, 3))
279
- .setAttribute('uv', new Float32BufferAttribute(chunk.uv, 2)).setAttribute('color', new BufferAttribute(new Float32Array(chunk.colour), 3)).setIndex(chunk.index);
280
- const glbMaterial = new MeshStandardMaterial({ color: 0xffffff, vertexColors: true }); glbMaterial.name = glbNames.get(key) ?? key;
281
- primitives.push({ geometry, material: glbMaterial, castShadow: casts.get(key) ?? true });
507
+ const entry = entries.get(key), material = entry?.material; if (entry === undefined || material === undefined || merge.position.length === 0) continue;
508
+ for (const primitive of primitivesOf(merge, entry, glbNames.get(key) ?? key, casts.get(key) ?? true)) {
509
+ primitives.push(primitive);
510
+ // a card draws past its seats by its corners and its rise: the tile's drawn box holds that reach
511
+ const corner = primitive.geometry.getAttribute('corner');
512
+ if (entry.card && corner !== undefined) {
513
+ const geometry = primitive.geometry; geometry.computeBoundingBox(); let reach = 0; for (const c of corner.array) reach = Math.max(reach, Math.abs(c));
514
+ const motion = entry.motion; if (motion?.kind === 'rise') reach += motion.height + motion.spread; else if (motion?.kind === 'drift') reach += motion.radius;
515
+ if (geometry.boundingBox !== null) drawn.union(geometry.boundingBox.clone().expandByScalar(reach));
516
+ }
517
+ }
518
+ const file = material.map === null ? undefined : textureFiles.get(material.map); if (file !== undefined) dependencies.add(file.hash);
519
+ }
520
+ for (const primitive of primitives) { primitive.geometry.computeBoundingBox(); if (primitive.geometry.boundingBox !== null) drawn.union(primitive.geometry.boundingBox); }
521
+ // AP15: the tile's instance groups, at most INSTANCE_CAP copies a node
522
+ for (const group of instanced.get(address) ?? []) {
523
+ const entry = entries.get(group.key), material = entry?.material; if (entry === undefined || material === undefined) continue;
524
+ const glbMaterial = new MeshStandardMaterial({ color: 0xffffff, vertexColors: true }); glbMaterial.name = glbNames.get(group.key) ?? group.key;
525
+ for (let from = 0; from < group.matrices.length; from += INSTANCE_CAP) {
526
+ const colours = group.colours?.slice(from, from + INSTANCE_CAP);
527
+ primitives.push({ geometry: group.geometry, material: glbMaterial, castShadow: group.castShadow, instances: group.matrices.slice(from, from + INSTANCE_CAP), ...(colours === undefined ? {} : { instanceColours: colours }) });
282
528
  }
529
+ drawn.union(group.box);
283
530
  const file = material.map === null ? undefined : textureFiles.get(material.map); if (file !== undefined) dependencies.add(file.hash);
284
531
  }
285
532
  if (primitives.length === 0) continue;
286
533
  // a GLB holds at most 25 MB (shard-format glbCost): batch the primitives into as many files as the tile needs
287
534
  const batches: GlbPrimitive[][] = []; let batch: GlbPrimitive[] = [], bytes = 0;
288
535
  for (const primitive of primitives) {
289
- const size = primitive.geometry.getAttribute('position').count * 44 + (primitive.geometry.getIndex()?.count ?? 0) * 4;
536
+ const size = glbBytes(primitive);
290
537
  if (batch.length > 0 && bytes + size > 18_000_000) { batches.push(batch); batch = []; bytes = 0; }
291
538
  batch.push(primitive); bytes += size;
292
539
  }
@@ -301,12 +548,41 @@ export function sceneShardfile(scene: ShardScene, options: ShardfileOptions = {}
301
548
  const sum = (pick: (f: Shardfile['files'][number]) => number): number => rows.reduce((n, f) => n + pick(f), 0) + textures.reduce((n, f) => n + pick(f), 0);
302
549
  tile.compressed += sum((f) => f.compressed); tile.decoded += sum((f) => f.decoded); tile.gpu += sum((f) => f.gpu);
303
550
  tile.triangles += rows.reduce((n, f) => n + f.triangles, 0); tile.draws += rows.reduce((n, f) => n + f.draws, 0);
304
- for (const primitive of primitives) { primitive.geometry.computeBoundingBox(); const box = primitive.geometry.boundingBox; if (box === null) continue; tile.bounds.min[1] = Math.min(tile.bounds.min[1], box.min.y); tile.bounds.max[1] = Math.max(tile.bounds.max[1], box.max.y); }
551
+ if (!drawn.isEmpty()) {
552
+ tile.bounds.min[1] = Math.min(tile.bounds.min[1], drawn.min.y); tile.bounds.max[1] = Math.max(tile.bounds.max[1], drawn.max.y);
553
+ // AP15: an instanced copy is whole in its seat's tile, so it may hang over the tile's edge: its draw bounds say so
554
+ if (drawn.min.x < tile.bounds.min[0] || drawn.min.z < tile.bounds.min[2] || drawn.max.x > tile.bounds.max[0] || drawn.max.z > tile.bounds.max[2]) {
555
+ const low = (v: number): number => Math.max(-HALF - OVERHANG, Math.floor(v * 1000) / 1000), high = (v: number): number => Math.min(HALF + OVERHANG, Math.ceil(v * 1000) / 1000);
556
+ tile.drawBounds = { min: [low(Math.min(tile.bounds.min[0], drawn.min.x)), tile.bounds.min[1], low(Math.min(tile.bounds.min[2], drawn.min.z))],
557
+ max: [high(Math.max(tile.bounds.max[0], drawn.max.x)), tile.bounds.max[1], high(Math.max(tile.bounds.max[2], drawn.max.z))] };
558
+ }
559
+ }
305
560
  const row = { triangles: rows.reduce((n, f) => n + f.triangles, 0), draws: rows.reduce((n, f) => n + f.draws, 0), compressed: rows.reduce((n, f) => n + f.compressed, 0) };
306
561
  tileReport.push({ tile: `0/${x}/${z}`, triangles: row.triangles, draws: row.draws, bytes: row.compressed });
307
562
  }
308
- // colliders (AP4)
309
- const colliders = scene.parts.filter((part) => part.colliders.length > 0).map((part) => ({ id: `scene.${part.name}`, panel: null, initialActive: true, shapes: part.colliders.map(boxRow) }));
563
+ // panels (AP16): one library GLB each, its texture slots as dependencies
564
+ const panels = panelParts.map(({ id, merges, shadows }) => {
565
+ const primitives: GlbPrimitive[] = [], dependencies = new Set<string>();
566
+ // the panel is one GLB: a material's triangles in every tile it crosses are one merge again, so one draw, not one a tile
567
+ const byKey = new Map<string, Merge>();
568
+ for (const [, tile] of [...merges].sort(([a], [b]) => a.localeCompare(b))) {
569
+ for (const [key, merge] of [...tile].sort(([a], [b]) => a.localeCompare(b))) { const whole = byKey.get(key); if (whole === undefined) byKey.set(key, merge); else appendMerge(whole, merge); }
570
+ }
571
+ for (const [key, merge] of [...byKey].sort(([a], [b]) => a.localeCompare(b))) {
572
+ const entry = entries.get(key); if (entry === undefined || merge.position.length === 0) continue;
573
+ primitives.push(...primitivesOf(merge, entry, glbNames.get(key) ?? key, shadows.get(key) ?? true));
574
+ const file = entry.material.map === null ? undefined : textureFiles.get(entry.material.map); if (file !== undefined) dependencies.add(file.hash);
575
+ }
576
+ if (primitives.length === 0) throw new SceneRefusalError(id, 'a panel part draws nothing', 'Give the panel part a visible mesh, or drop its panel option');
577
+ // a panel is one library file (format props `panels[].file`), and a GLB holds at most 25 MB: the tiles' 18 MB batch is
578
+ // not open to it, so a panel past that is refused here, by name, not at admission
579
+ const size = primitives.reduce((n, primitive) => n + glbBytes(primitive), 0);
580
+ if (size > 18_000_000) throw new SceneRefusalError(id, `a panel part's mesh is ${(size / 1e6).toFixed(1)} MB, over the 18 MB a panel GLB holds`, 'Split it into smaller panel parts, or drop detail from its meshes');
581
+ return { id, file: store(staticGlb(primitives, `scene.panel.${id}`), 'glb', [...dependencies].sort()).hash, visible: true };
582
+ });
583
+ const library = panels.map((panel) => panel.file);
584
+ // colliders (AP4); a panel part's solids are its panel's one collider (AP16)
585
+ const colliders = scene.parts.filter((part) => part.colliders.length > 0).map((part) => ({ id: part.panel ?? `scene.${part.name}`, panel: part.panel ?? null, initialActive: true, shapes: part.colliders.map(boxRow) }));
310
586
  // water (AP4)
311
587
  const water = scene.parts.flatMap(waterRows);
312
588
  const lights = scene.parts.flatMap((part) => part.lights);
@@ -314,15 +590,52 @@ export function sceneShardfile(scene: ShardScene, options: ShardfileOptions = {}
314
590
  const [sx, sy, sz] = scene.spawn.position;
315
591
  const spawnY = Math.max(sy, (ground?.heightAt(sx, sz) ?? 0) + 1);
316
592
  const product = {
317
- ...base, budgets: { ...base.budgets, sim: { resident: 16_000_000, compressed: 1_000_000 } }, serverBudget: { ...base.serverBudget, tickMicros: 5_000, memory: 16_000_000 },
593
+ ...base, budgets: { ...base.budgets, library: libraryCost(files, library), sim: { resident: 16_000_000, compressed: 1_000_000 } }, serverBudget: { ...base.serverBudget, tickMicros: 5_000, memory: 16_000_000 },
318
594
  look: sceneLook(scene, lights, lookMaterials), spawn: { x: round(sx, 3), y: round(spawnY, 3), z: round(sz, 3), yaw: round(scene.spawn.yaw, 4) },
319
595
  terrain: { ...terrain.terrain, shadow: { cast: true, receive: true }, follow: 5 }, tiles: shardTiles, files: files.sort((a, b) => a.hash.localeCompare(b.hash)), edge: terrain.edge,
320
- critical: [...terrain.critical], far: null,
321
- props: { version: 1, family: 'pbr', tiles: propTiles, panels: [], models: [], far: null, textures: [], colliders, ...(Object.keys(propMaterials).length === 0 ? {} : { materials: propMaterials }) },
596
+ critical: [...terrain.critical], far: null, library: [...base.library, ...library],
597
+ props: { version: 1, family: 'pbr', overhang: OVERHANG, tiles: propTiles, panels, models: [], far: null, textures: [], colliders, ...(Object.keys(propMaterials).length === 0 ? {} : { materials: propMaterials }) },
322
598
  ...(water.length === 0 ? {} : { water }),
323
599
  };
324
600
  // oxlint-disable-next-line unicorn/prefer-structured-clone -- JSON wire normalization (signed zero), as product.ts does
325
601
  let shard = parseShardfile(JSON.parse(JSON.stringify(product)));
326
602
  if (options.extend !== undefined) shard = options.extend(shard);
327
- return { shard, assets, report: { sprites: scene.parts.reduce((n, p) => n + p.sprites.length, 0), lampsDropped: Math.max(0, lights.filter((l) => l.kind === 'point').length - 16), tiles: tileReport } };
603
+ return { shard, assets, report: { cards, lampsDropped: Math.max(0, lights.filter((l) => l.kind === 'point').length - 16), tiles: tileReport } };
604
+ }
605
+
606
+ /**
607
+ * SHARD-SOURCE AP19: the shardfile sections a watched page restarts its simulation for (engine's dev hook v4,
608
+ * `DEV_GAMEPLAY_SECTIONS` in engine `src/shared/game/devGameplay.ts`: keep the two lists the same).
609
+ */
610
+ // `questNpcs` and `clientScripts` are the page's alone (the hook rebuilds only the quest views): a change there is a new shell.
611
+ export const GAMEPLAY_SECTIONS = ['quests', 'questHost', 'encounters', 'directors', 'creatures', 'crowds', 'hooks', 'ledger', 'sim'] as const;
612
+
613
+ /**
614
+ * AP19: what `options.extend` adds to a scene shard, split for `wildshard watch`: the gameplay sections (a soft restart takes
615
+ * them live) and the rest (a change there needs a new shell). Cheap: `extend` runs over an empty shardfile of the scene's
616
+ * identity, never the baked one, so it must not read the scene's rows (none of today's do).
617
+ */
618
+ export function sceneGameplay(identity: ShardScene['identity'], options: ShardfileOptions = {}): { gameplay: Record<string, unknown>; rest: Record<string, unknown> } {
619
+ const base = parseShardfile(emptyShardfile({ slug: identity.slug, name: identity.name, author: identity.author ?? 'Wildshard', revision: identity.revision ?? 1, seed: identity.seed ?? 1 }));
620
+ // the base as it was, before an `extend` that edits its input in place can change it
621
+ const before = structuredClone(base) as unknown as Record<string, unknown>;
622
+ const shard = options.extend === undefined ? base : options.extend(base) as unknown as Record<string, unknown>;
623
+ const gameplay: Record<string, unknown> = {}, rest: Record<string, unknown> = {};
624
+ for (const key of new Set([...Object.keys(before), ...Object.keys(shard)])) {
625
+ const value = (shard as Record<string, unknown>)[key];
626
+ if ((GAMEPLAY_SECTIONS as readonly string[]).includes(key)) { if (value !== undefined) gameplay[key] = value; }
627
+ else if (JSON.stringify(value) !== JSON.stringify(before[key])) rest[key] = value ?? null;
628
+ }
629
+ return { gameplay, rest };
630
+ }
631
+
632
+ /** The scene's ground as the terrain bake reads it: the declared height field, or a flat cell. */
633
+ function groundSource(scene: ShardScene): Parameters<typeof bakeTerrain>[0] {
634
+ const ground = scene.ground;
635
+ return { heightAt: ground?.heightAt ?? (() => 0), colourAt: (x, z) => ground?.colourAt?.(x, z) ?? [0.3, 0.36, 0.2] };
636
+ }
637
+
638
+ /** AP18: the scene's whole ground as one terrain tile's wire bytes (heights and colours), what a watched page's hook swaps in. */
639
+ export function sceneGroundBytes(scene: ShardScene): Uint8Array {
640
+ return encodeTerrainTile(groundLattice(groundSource(scene)));
328
641
  }