@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
@@ -0,0 +1,23 @@
1
+ import { ENGINE_MUSIC_STYLE, engineMusicFiles, musicDir } from '@wildshard/engine/audio/bootAudio';
2
+ import { withAssetTables, type AssetTables } from '@wildshard/engine/boot/tables';
3
+ import { MUSIC_MANIFESTS, SFX_MANIFESTS } from '@wildshard/engine/game/boot/audio.generated';
4
+ import { PUBLIC_BYTES } from '@wildshard/engine/game/boot/bytes.generated';
5
+ import { ASSET_VERSIONS } from '@wildshard/engine/game/boot/versions.generated';
6
+ import { PACKS } from '@wildshard/engine/game/boot/packs.generated';
7
+ import type { AudioData } from '@wildshard/format/audio';
8
+
9
+ /** The engine's own boot tables, as the page installs them: which engine music ships, and each file's bytes. */
10
+ export const ENGINE_TABLES: AssetTables = { bytes: PUBLIC_BYTES, versions: ASSET_VERSIONS, music: MUSIC_MANIFESTS, sfx: SFX_MANIFESTS, packs: PACKS };
11
+
12
+ /** AUDIO AU18: the build log's line for the engine music a shard plays, derived from its `audio/audio` rows by name,
13
+ * in the engine cook's `engineMusicLine` format. Undefined when the shard has no audio section. Throws, naming each,
14
+ * when the rows name engine music this engine's style lacks. */
15
+ export function engineMusicLine(shard: string, section: unknown, tables: AssetTables = ENGINE_TABLES): string | undefined {
16
+ if (typeof section !== 'object' || section === null || !('audio' in section)) return undefined;
17
+ const data = section.audio as AudioData, dir = musicDir(ENGINE_MUSIC_STYLE);
18
+ let files: string[];
19
+ try { files = withAssetTables(tables, () => engineMusicFiles(data)); }
20
+ catch (error) { throw new Error(`${shard}: ${error instanceof Error ? error.message : String(error)}`, { cause: error }); }
21
+ const bytes = files.reduce((sum, url) => sum + (tables.bytes[url] ?? 0), 0);
22
+ return `${shard}: engine music: ${files.length} files, ${(bytes / 1e6).toFixed(2)} MB${files.length === 0 ? '' : ` (${files.map(url => url.slice(dir.length)).join(', ')})`}`;
23
+ }
@@ -150,7 +150,9 @@ readonly skyLightDirection: Node<"vec3">;
150
150
  /** Its linear colour multiplied by intensity; excludes shadowing and atmosphere fog colour. */
151
151
  readonly skyLightColour: Node<"vec3">;
152
152
  /** the scene colour at the pixel (a post input) */
153
- readonly sceneColour: Node<"vec4">; } = {
153
+ readonly sceneColour: Node<"vec4">;
154
+ /** the world direction through the pixel (a post input: sky detail; SHARD-SOURCE AP13) */
155
+ readonly viewRay: Node<"vec3">; } = {
154
156
  /** toward the light (the `sun` sub-graph only) */
155
157
  /** true for a front-facing fragment; vertex stages refuse this input */
156
158
  frontFacing: op('frontFacing', 'bool'),
@@ -198,6 +200,7 @@ readonly sceneColour: Node<"vec4">; } = {
198
200
  skyLightColour: op('skyLightColour', 'vec3'),
199
201
  /** the scene colour at the pixel (a post input) */
200
202
  sceneColour: op('sceneColour', 'vec4'),
203
+ viewRay: op('viewRay', 'vec3'),
201
204
  } as const;
202
205
 
203
206
  /** TSL built-ins that are graph inputs as they are (matched by identity; `uv()` by its attribute). */
@@ -264,7 +267,7 @@ function constLiteral(value: unknown): GraphLiteral | undefined {
264
267
  * const ir = graph({ flatShading: true, lighting: { sun: graphInputs.albedo.mul(graphInputs.sunColour).mul(cel).mul(1 / Math.PI) } });
265
268
  * ```
266
269
  */
267
- export function graph(spec: GraphSpec): GraphIr {
270
+ export function graph(spec: GraphSpec, host: { readonly budget?: GraphBudget } = {}): GraphIr {
268
271
  const nodes: Record<string, GraphNode> = {}, ids = new Map<Node, string>(), used = new Set<string>(), paramDefs: Record<string, GraphParam> = {};
269
272
  let counter = 0;
270
273
  const fresh = (): string => { let id = `n${counter++}`; while (used.has(id)) id = `n${counter++}`; return id; };
@@ -381,7 +384,8 @@ export function graph(spec: GraphSpec): GraphIr {
381
384
  ...(spec.doubleSided === undefined ? {} : { doubleSided: spec.doubleSided }), ...(spec.flipBackfaceNormals === undefined ? {} : { flipBackfaceNormals: spec.flipBackfaceNormals }), ...(spec.toonCaustics === undefined ? {} : { toonCaustics: spec.toonCaustics }), ...(spec.flatShading === undefined ? {} : { flatShading: spec.flatShading }),
382
385
  ...(Object.keys(paramDefs).length === 0 ? {} : { params: paramDefs }), nodes, stages,
383
386
  };
384
- const checked = validateGraph(structuredClone(ir), { trustedBudget: true });
387
+ // `host.budget`: the ceilings a host grants this kind of graph (a look's sky, AP14), checked here and never written in it
388
+ const checked = validateGraph(structuredClone(ir), { trustedBudget: true, ...(host.budget === undefined ? {} : { budget: host.budget }) });
385
389
  if (!checked.ok) throw new Error(`graph: ${checked.errors.join('; ')}`);
386
390
  return checked.graph;
387
391
  }
@@ -37,6 +37,7 @@ import { projectPlaceholders } from './bake/placeholders';
37
37
  import type { ScriptAdmissionRows } from '@wildshard/format/scriptContract';
38
38
  import { readCookInput, type CookInput } from './cookInput';
39
39
  import { audioEncodeLine, encodeMountAudio, readStereoMarks } from './audioEncode';
40
+ import { engineMusicLine } from './engineMusic';
40
41
  import { AUTHOR_BUDGETS, AUTHOR_BUDGETS_MODULE, authorManifest } from './authorManifest';
41
42
  import { discoveryDocument, discoveryUrl } from './discoveryDocument';
42
43
  import { outputScriptAdmissionRows, outputPlatformPayloads, clearOutputProduct, writeOutputProduct, type OutputProductOptions } from './outputProduct';
@@ -285,6 +286,10 @@ export async function buildProject(project: string, output?: string, options: {
285
286
  descriptor = writeOutputProduct(shard, assets, destination, { ...loaded.output, ...(runtime === undefined ? {} : { runtime }), ...(cook === undefined ? {} : { cook }) });
286
287
  assertNoRenamedAudioNames(destination, encoded?.renamed ?? new Map());
287
288
  phase('product-write');
289
+ // AUDIO AU18: name the engine music this shard plays, derived from its audio rows (a name the engine lacks refuses).
290
+ const audio = descriptor.sections.find(row => row.name === 'audio/audio');
291
+ const music = audio === undefined ? undefined : engineMusicLine(shard.identity.slug, JSON.parse(readFileSync(resolve(destination, audio.path), 'utf8')));
292
+ if (music !== undefined) console.info(music);
288
293
  if (runtime !== undefined) proveRuntimeData(destination, descriptor, loaded.mirrors);
289
294
  phase('runtime-proof');
290
295
  } catch (error) { clearOutputProduct(destination); throw error; }
@@ -200,7 +200,7 @@ export const REFUSAL_RULES: readonly RefusalRule[] = [
200
200
  fix: 'Read the reason: a format refusal means build again (`wildshard build`); a server refusal names what it wants.' },
201
201
  // lint, besides the rules below
202
202
  { id: 'lint-not-run', anchor: 'lint-not-run', steps: ['lint'], match: /^oxlint (?:did not run|exited|report has no)/u,
203
- fix: 'Reinstall @wildshard/sdk (`pnpm install`): the author lint ships with it.' },
203
+ fix: 'Reinstall (`pnpm install`): the author lint runs the repo\'s oxlint, or the one that ships with @wildshard/sdk.' },
204
204
  { id: 'lint-refused', anchor: 'lint-refused', steps: ['lint'],
205
205
  fix: 'Fix what the message names at the file and line shown.' },
206
206
  ];
@@ -1,5 +1,8 @@
1
1
  import { DataTexture, LinearFilter, LinearMipmapLinearFilter, Mesh, MeshStandardMaterial, RepeatWrapping, SRGBColorSpace, ShapeGeometry, LinearSRGBColorSpace, type ColorRepresentation, type Group, type Object3D, type Scene, type Shape } from 'three';
2
- import type { Rgb, ScenePost } from './description';
2
+ import { positionLocal } from 'three/tsl';
3
+ import type { DetailLayer } from '@wildshard/format/detail-layer';
4
+ import type { GraphValue } from '../materials';
5
+ import type { Rgb, SceneMotion, ScenePost } from './description';
3
6
 
4
7
  /**
5
8
  * AUTHORING-PARITY AP1: what an author's scene module calls besides three.js itself. Everything here runs at compile time
@@ -7,18 +10,42 @@ import type { Rgb, ScenePost } from './description';
7
10
  */
8
11
 
9
12
  /** The world a `defineShard` build function receives. `scene` is a plain three.js `Scene`: add to it as in a cleanroom. */
13
+ /** AP16: what a part is besides its content. */
14
+ export interface PartOptions {
15
+ /** a panel id (`brasscap.gate`): the part's meshes are one hideable GLB and its solids one collider, both of this id */
16
+ readonly panel?: string;
17
+ }
18
+
10
19
  export interface ShardWorld {
11
20
  readonly scene: Scene;
12
- /** A named piece of the world, the unit `watch` swaps. Objects added to `scene` outside a part belong to part `scene`. */
13
- part: (name: string, build: (part: Group) => void) => Group;
14
- /** The ground: its height everywhere in the 500 m cell, and optionally its colour (linear RGB). */
15
- ground: (heightAt: (x: number, z: number) => number, options?: { colourAt?: (x: number, z: number) => Rgb }) => void;
21
+ /**
22
+ * A named piece of the world, the unit `watch` swaps. Objects added to `scene` outside a part belong to part `scene`.
23
+ * `options.panel` makes the part a panel (SHARD-SOURCE AP16): its meshes ship as one GLB the shard's `targets.panels`
24
+ * rows show and hide by state (a gate that opens, a rifle taken off a rack), and its solids as one collider of that id.
25
+ */
26
+ part: (name: string, build: (part: Group) => void, options?: PartOptions) => Group;
27
+ /**
28
+ * The ground: its height everywhere in the 500 m cell, and optionally its colour (linear RGB). `material` is the
29
+ * cleanroom ground mesh's `MeshStandardMaterial` (its colour, roughness and metalness; the vertex colours are
30
+ * `colourAt`); a map on it does not reach the shard (the terrain has no uvs): say its grain with `detail`, the PBR
31
+ * family's procedural layer (format `detail-layer`), drawn from world position.
32
+ */
33
+ ground: (heightAt: (x: number, z: number) => number, options?: { colourAt?: (x: number, z: number) => Rgb; material?: MeshStandardMaterial; detail?: DetailLayer }) => void;
34
+ /**
35
+ * AP14: the sky, a TSL colour (linear) along {@link skyRay}, drawn on the engine's dome in place of its gradient: the
36
+ * cleanroom's sky dome `ShaderMaterial`, written in TSL. `environment` lights PBR surfaces from that same sky (three's
37
+ * `scene.environment` from a PMREM of the dome, at `intensity`, over a `ground` colour), so ponds and metal reflect it.
38
+ */
39
+ sky: (colour: GraphValue, options?: { environment?: { intensity: number; ground: Rgb } }) => void;
16
40
  /** The cleanroom's composer, as numbers. */
17
41
  post: (settings: Partial<Omit<ScenePost, 'bloom'>> & { bloom?: ScenePost['bloom'] }) => void;
18
42
  /** Where a player enters. */
19
43
  spawn: (x: number, y: number, z: number, yaw?: number) => void;
20
44
  }
21
45
 
46
+ /** AP14: the view ray through a sky pixel (unit, world axes, y up): the dome is centred on the camera. */
47
+ export const skyRay: ReturnType<typeof positionLocal.normalize> = positionLocal.normalize();
48
+
22
49
  /** Painted pixels by texture source: `clone()` shares the source, so a clone with its own `repeat` still lowers. */
23
50
  /** as a canvas `ImageData` stores a value: clamped to 0..255 and rounded */
24
51
  export const byte = (value: number): number => Math.min(255, Math.max(0, Math.round(value)));
@@ -32,12 +59,58 @@ export const paintedPixels = (source: object): { width: number; height: number;
32
59
  */
33
60
  export function paint(width: number, height: number, fn: (u: number, v: number, x: number, y: number) => readonly number[], options: { colourSpace?: 'srgb' | 'linear' } = {}): DataTexture {
34
61
  checkSize(width, height);
35
- const top = new Uint8Array(width * height * 4);
36
- for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
37
- const [r = 0, g = 0, b = 0, a = 255] = fn(x / width, y / height, x, y), i = (y * width + x) * 4;
38
- top[i] = byte(r); top[i + 1] = byte(g); top[i + 2] = byte(b); top[i + 3] = byte(a);
62
+ return memoPainted('paint', width, height, fn, options, () => {
63
+ const top = new Uint8Array(width * height * 4);
64
+ for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
65
+ const [r = 0, g = 0, b = 0, a = 255] = fn(x / width, y / height, x, y), i = (y * width + x) * 4;
66
+ top[i] = byte(r); top[i + 1] = byte(g); top[i + 2] = byte(b); top[i + 3] = byte(a);
67
+ }
68
+ return top;
69
+ });
70
+ }
71
+
72
+ /**
73
+ * SHARD-SOURCE AP17: `wildshard watch`'s paint memo. A watched revision reruns the author's whole build, and painting is most
74
+ * of it (the authoring slice: ~200 of ~250 ms). While `withPaintMemo` runs a build in `guess` mode, a `paint` or
75
+ * `paintCanvas` call whose painter source, size and colour space match the n-th such call of the last revision takes that
76
+ * call's pixels without painting. It is a guess: a painter's closure can change while its source text does not. So watch
77
+ * pushes the guess, then runs the build again in `truth` mode (every call paints) and pushes the difference, if any.
78
+ */
79
+ export class PaintMemo {
80
+ private last = new Map<string, Uint8Array>();
81
+ private now = new Map<string, Uint8Array>();
82
+ private readonly seen = new Map<string, number>();
83
+ mode: 'guess' | 'truth' = 'guess';
84
+ hits = 0;
85
+ misses = 0;
86
+ /** Start a build: what the last one painted (or guessed) is what this one may take. */
87
+ begin(mode: 'guess' | 'truth'): void {
88
+ if (this.now.size > 0) this.last = this.now;
89
+ this.now = new Map(); this.seen.clear(); this.mode = mode; this.hits = 0; this.misses = 0;
39
90
  }
40
- return paintedTexture(width, height, top, options);
91
+ /** One call's pixels (rows bottom first, as the texture holds them): the last revision's, or `paint()`'s. */
92
+ pixels(kind: string, width: number, height: number, source: string, colourSpace: string, draw: () => Uint8Array): Uint8Array {
93
+ const base = `${kind}|${width}x${height}|${colourSpace}|${source}`, nth = this.seen.get(base) ?? 0;
94
+ this.seen.set(base, nth + 1);
95
+ const key = `${base}#${nth}`, kept = this.mode === 'guess' ? this.last.get(key) : undefined;
96
+ if (kept !== undefined) this.hits++; else this.misses++;
97
+ const rgba = kept ?? draw();
98
+ this.now.set(key, rgba);
99
+ return rgba;
100
+ }
101
+ }
102
+ let memo: PaintMemo | null = null;
103
+ /** Run `build` with `next` as the paint memo (null: none, every call paints). */
104
+ export function withPaintMemo<T>(next: PaintMemo | null, build: () => T): T {
105
+ const before = memo; memo = next;
106
+ try { return build(); } finally { memo = before; }
107
+ }
108
+ /** A painter's texture through the memo, when one is set (rows top first in, as a canvas holds them). */
109
+ export function memoPainted(kind: string, width: number, height: number, painter: object, options: { colourSpace?: 'srgb' | 'linear' }, top: () => Uint8Array): DataTexture {
110
+ if (memo === null) return paintedTexture(width, height, top(), options);
111
+ // eslint-disable-next-line @typescript-eslint/no-base-to-string -- a painter is a function: its source text is the key
112
+ const rgba = memo.pixels(kind, width, height, String(painter), options.colourSpace ?? 'srgb', () => flipRows(width, height, top()));
113
+ return textureOf(width, height, rgba, options);
41
114
  }
42
115
 
43
116
  /** A texture size from 1 to 4096 a side, or a refusal. */
@@ -47,9 +120,17 @@ export function checkSize(width: number, height: number): void {
47
120
 
48
121
  /** RGBA8 rows top first (as a canvas holds them) as the texture a `CanvasTexture` of that canvas would be. */
49
122
  export function paintedTexture(width: number, height: number, top: Uint8Array, options: { colourSpace?: 'srgb' | 'linear' } = {}): DataTexture {
50
- // canvas row y (top = 0) is texture row height-1-y: a CanvasTexture flips Y on upload, a DataTexture does not
123
+ return textureOf(width, height, flipRows(width, height, top), options);
124
+ }
125
+
126
+ /** Canvas row y (top = 0) is texture row height-1-y: a CanvasTexture flips Y on upload, a DataTexture does not. */
127
+ function flipRows(width: number, height: number, top: Uint8Array): Uint8Array {
51
128
  const rgba = new Uint8Array(width * height * 4);
52
129
  for (let y = 0; y < height; y++) rgba.set(top.subarray(y * width * 4, (y + 1) * width * 4), (height - 1 - y) * width * 4);
130
+ return rgba;
131
+ }
132
+
133
+ function textureOf(width: number, height: number, rgba: Uint8Array, options: { colourSpace?: 'srgb' | 'linear' }): DataTexture {
53
134
  const texture = new DataTexture(rgba, width, height);
54
135
  texture.colorSpace = options.colourSpace === 'linear' ? LinearSRGBColorSpace : SRGBColorSpace;
55
136
  texture.wrapS = texture.wrapT = RepeatWrapping;
@@ -77,3 +158,27 @@ export class Water extends Mesh<ShapeGeometry, MeshStandardMaterial> {
77
158
  this.name = 'water';
78
159
  }
79
160
  }
161
+
162
+ const MOTION = new WeakMap<Object3D, SceneMotion>();
163
+ /**
164
+ * `animate(node, motion)`: declared motion (SHARD-SOURCE AP12), the cleanroom's `update(t)` said as data. The engine plays
165
+ * it per frame; no author code runs in a page. A motion on a group reaches every object under it in its part.
166
+ *
167
+ * - `flicker` on a `PointLight`: its intensity wavers (a lamp, a fire);
168
+ * - `pulse` on a `Sprite`: the card breathes (a flame tongue); `drift` / `rise` on a `Sprite` or `Points`: the card wanders
169
+ * round its seat (fireflies) or climbs and fades (sparks);
170
+ * - `sway` on a mesh: it bends in the wind from its root (foliage); `uvScroll` on a mesh: its map moves (water, cloud).
171
+ */
172
+ export function animate<T extends Object3D>(object: T, motion: SceneMotion): T { MOTION.set(object, motion); return object; }
173
+ /** The motion declared on `object` or its nearest animated ancestor under `root`. */
174
+ export function motionOf(object: Object3D, root: Object3D): SceneMotion | null {
175
+ for (let node: Object3D | null = object; node !== null; node = node.parent) { const m = MOTION.get(node); if (m !== undefined) return m; if (node === root) break; }
176
+ return null;
177
+ }
178
+ export const flicker = (o: { rate: number; amount: number }): SceneMotion => ({ kind: 'flicker', rate: o.rate, amount: o.amount });
179
+ export const pulse = (o: { rate: number; amount: number }): SceneMotion => ({ kind: 'pulse', rate: o.rate, amount: o.amount });
180
+ export const drift = (o: { rate: number; radius: number }): SceneMotion => ({ kind: 'drift', rate: o.rate, radius: o.radius });
181
+ export const rise = (o: { rate: number; height: number; spread?: number }): SceneMotion => ({ kind: 'rise', rate: o.rate, height: o.height, spread: o.spread ?? 0 });
182
+ /** `amount`: metres the top of the mesh moves; it grows with the square of the height over the mesh's own bounds. */
183
+ export const sway = (o: { rate: number; amount: number; direction?: readonly [number, number] }): SceneMotion => ({ kind: 'sway', rate: o.rate, amount: o.amount, direction: o.direction ?? [0.8, 0.6] });
184
+ export const uvScroll = (u: number, v: number): SceneMotion => ({ kind: 'uvScroll', u, v });
@@ -1,5 +1,5 @@
1
1
  import type { DataTexture } from 'three';
2
- import { byte, checkSize, paintedTexture } from './author';
2
+ import { byte, checkSize, memoPainted } from './author';
3
3
 
4
4
  /**
5
5
  * AUTHORING-PARITY AP1: `paintCanvas(w, h, draw)`, the part of the Canvas 2D API the cleanrooms paint with, in plain
@@ -208,6 +208,5 @@ export class PaintContext {
208
208
  /** `paintCanvas(w, h, (ctx) => ...)`: a cleanroom canvas painter, run at compile time, as a sampled texture. */
209
209
  export function paintCanvas(width: number, height: number, draw: (ctx: PaintContext) => void, options: { colourSpace?: 'srgb' | 'linear' } = {}): DataTexture {
210
210
  checkSize(width, height);
211
- const ctx = new PaintContext(width, height); draw(ctx);
212
- return paintedTexture(width, height, ctx.bytes(), options);
211
+ return memoPainted('canvas', width, height, draw, options, () => { const ctx = new PaintContext(width, height); draw(ctx); return ctx.bytes(); });
213
212
  }
@@ -1,3 +1,4 @@
1
+ import type { DetailLayer } from '@wildshard/format/detail-layer';
1
2
  /**
2
3
  * AUTHORING-PARITY AP1: the scene description. An author writes an ordinary three.js scene inside `defineShard`; the
3
4
  * walker (`lower.ts`) reads it once into this plain, serialisable shape, and both back ends read only this: the shardfile
@@ -8,6 +9,9 @@
8
9
  * Each part carries a content hash, so a re-run that changes one part changes only that part's hash.
9
10
  */
10
11
 
12
+ import type { GraphIr } from '@wildshard/format/materialGraph';
13
+ import type { MaterialEntry } from '@wildshard/format/materials';
14
+
11
15
  /** Linear RGB, each 0..n (an HDR emissive may exceed 1). */
12
16
  export type Rgb = readonly [number, number, number];
13
17
  export type Vec3 = readonly [number, number, number];
@@ -21,12 +25,21 @@ export interface SceneTexture {
21
25
  readonly colourSpace: 'srgb' | 'linear';
22
26
  }
23
27
 
24
- /** A lowered material: the fields of `MeshStandardMaterial` / `MeshBasicMaterial` / `SpriteMaterial` an M1 scene uses. */
28
+ /** A declared motion (`animate(node, ...)`, SHARD-SOURCE AP12): plain data the engine plays, never author code. */
29
+ export type SceneMotion =
30
+ | { readonly kind: 'flicker'; readonly rate: number; readonly amount: number }
31
+ | { readonly kind: 'pulse'; readonly rate: number; readonly amount: number }
32
+ | { readonly kind: 'drift'; readonly rate: number; readonly radius: number }
33
+ | { readonly kind: 'rise'; readonly rate: number; readonly height: number; readonly spread: number }
34
+ | { readonly kind: 'sway'; readonly rate: number; readonly amount: number; readonly direction: readonly [number, number] }
35
+ | { readonly kind: 'uvScroll'; readonly u: number; readonly v: number };
36
+
37
+ /** A lowered material: the fields of `MeshStandardMaterial` / `MeshBasicMaterial` / `SpriteMaterial` / `PointsMaterial`. */
25
38
  export interface SceneMaterial {
26
39
  readonly key: string;
27
40
  /** the author's `material.name`, or the key */
28
41
  readonly name: string;
29
- readonly kind: 'standard' | 'basic' | 'sprite';
42
+ readonly kind: 'standard' | 'basic' | 'sprite' | 'points';
30
43
  readonly colour: Rgb;
31
44
  readonly roughness: number;
32
45
  readonly metalness: number;
@@ -45,6 +58,12 @@ export interface SceneMaterial {
45
58
  readonly blending: 'normal' | 'additive';
46
59
  readonly depthWrite: boolean;
47
60
  readonly fog: boolean;
61
+ /** AP13: a TSL material's catalogue entry (`GraphMaterial`, `ToonMaterial`, `PainterlyMaterial`): written as it is */
62
+ readonly entry: MaterialEntry | null;
63
+ /** AP10: `polygonOffset` as its factor (0: none) */
64
+ readonly polygonOffset: number;
65
+ /** AP11: a `PointsMaterial`'s `size` (metres with size attenuation); 0 otherwise */
66
+ readonly pointSize: number;
48
67
  }
49
68
 
50
69
  /** One geometry in its own frame. `colour` is 3 floats per vertex when present. */
@@ -71,6 +90,8 @@ export interface SceneDraw {
71
90
  readonly instances: { readonly count: number; readonly matrices: Float32Array; readonly colours: Float32Array | null } | null;
72
91
  readonly castShadow: boolean;
73
92
  readonly receiveShadow: boolean;
93
+ /** AP12: `sway` or `uvScroll`, declared on the mesh or an ancestor in its part; null: still */
94
+ readonly motion: SceneMotion | null;
74
95
  }
75
96
 
76
97
  /** A `Sprite`: a camera-facing card at a world point. */
@@ -80,6 +101,17 @@ export interface SceneSprite {
80
101
  readonly position: Vec3;
81
102
  readonly scale: readonly [number, number];
82
103
  readonly center: readonly [number, number];
104
+ /** AP12: `pulse`, `drift` or `rise`; null: still */
105
+ readonly motion: SceneMotion | null;
106
+ }
107
+
108
+ /** AP11: a `Points` cloud: each point a camera-facing card `pointSize` across, its seat in world space. */
109
+ export interface ScenePoints {
110
+ readonly path: string;
111
+ readonly material: string;
112
+ /** world x, y, z per point */
113
+ readonly positions: Float32Array;
114
+ readonly motion: SceneMotion | null;
83
115
  }
84
116
 
85
117
  export interface SceneLight {
@@ -96,6 +128,8 @@ export interface SceneLight {
96
128
  /** directional only: where it points */
97
129
  readonly target: Vec3 | null;
98
130
  readonly castShadow: boolean;
131
+ /** AP12: a point light's `flicker`; null: steady */
132
+ readonly motion: SceneMotion | null;
99
133
  }
100
134
 
101
135
  /** A solid box, said once by `solid(mesh)`: the mesh's own bounds in its world frame. */
@@ -121,10 +155,13 @@ export interface SceneWater {
121
155
 
122
156
  export interface ScenePart {
123
157
  readonly name: string;
158
+ /** AP16: the panel id when the part is one (`world.part(name, build, { panel })`): one hideable GLB and one collider */
159
+ readonly panel?: string;
124
160
  /** content hash of everything below and of the materials, textures and geometries it uses */
125
161
  readonly hash: string;
126
162
  readonly draws: readonly SceneDraw[];
127
163
  readonly sprites: readonly SceneSprite[];
164
+ readonly points: readonly ScenePoints[];
128
165
  readonly lights: readonly SceneLight[];
129
166
  readonly colliders: readonly SceneCollider[];
130
167
  readonly water: readonly SceneWater[];
@@ -139,18 +176,34 @@ export interface ScenePost {
139
176
  readonly exposure: number;
140
177
  readonly bloom: { readonly strength: number; readonly radius: number; readonly threshold: number } | null;
141
178
  readonly vignette: number;
179
+ /** AP13: post passes compiled from TSL (`graph({ kind: 'post', ... })`), drawn in order after the grade */
180
+ readonly passes?: readonly GraphIr[];
181
+ }
182
+
183
+ /** AP14 `world.sky(...)`: the dome's painted sky (an unlit graph over the view ray) and the light it gives. */
184
+ export interface SceneSky {
185
+ readonly graph: GraphIr;
186
+ /** PBR surfaces lit from the sky (and a pond reflecting it): an intensity over a ground colour; null: none */
187
+ readonly environment: { readonly intensity: number; readonly ground: Rgb } | null;
142
188
  }
143
189
 
144
190
  export interface SceneLook {
191
+ /** AP14: null or absent: the format's two-colour dome */
192
+ readonly sky?: SceneSky | null;
145
193
  readonly fog: { readonly kind: 'exp2'; readonly colour: Rgb; readonly density: number } | { readonly kind: 'linear'; readonly colour: Rgb; readonly near: number; readonly far: number } | null;
146
194
  readonly background: Rgb | null;
147
195
  readonly post: ScenePost | null;
148
196
  }
149
197
 
198
+ /** ss4d: the ground's lit surface, from `world.ground`'s `material` and `detail`. */
199
+ export interface SceneGroundSurface { readonly colour: Rgb; readonly roughness: number; readonly metalness: number; readonly detail: DetailLayer | null }
200
+
150
201
  /** The ground the author declared with `world.ground(heightAt)`: closures stay at compile time, never on the wire. */
151
202
  export interface SceneGround {
152
203
  readonly heightAt: (x: number, z: number) => number;
153
204
  readonly colourAt: ((x: number, z: number) => Rgb) | null;
205
+ /** ss4d: the ground's lit surface (a PBR terrain material): colour (linear), roughness, metalness and its detail layer */
206
+ readonly surface: SceneGroundSurface;
154
207
  /** a hash of the height field sampled on a 2 m grid, so a re-run knows whether the ground changed */
155
208
  readonly hash: string;
156
209
  }