@wildshard/sdk 0.2.13 → 0.3.1

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 (88) hide show
  1. package/GUIDE.md +26 -13
  2. package/bin/wildshard.mjs +2 -1
  3. package/docs/api/EXPORT-TIERS.md +16 -4
  4. package/lint/export-tiers.json +12 -0
  5. package/lint/host-callbacks.mjs +1 -1
  6. package/package.json +22 -6
  7. package/scripts/bake/template-skins.mjs +6 -3
  8. package/scripts/bake/template-warden.mjs +25 -0
  9. package/scripts/build-shardfiles.mjs +7 -2
  10. package/scripts/export-ci21-guests.mjs +89 -0
  11. package/scripts/prepare-product.mjs +2 -2
  12. package/scripts/scratch-sweep.mjs +182 -0
  13. package/scripts/wildshard.mjs +1 -1
  14. package/skills/wildshard-mockup-to-model/SKILL.md +5 -3
  15. package/skills/wildshard-upgrade/SKILL.md +4 -4
  16. package/src/cli/help.ts +9 -5
  17. package/src/cli/upload/validate.ts +7 -5
  18. package/src/sharddev/as/prelude.ts +67 -0
  19. package/src/sharddev/assets.ts +1 -1
  20. package/src/sharddev/authorLint.ts +45 -0
  21. package/src/sharddev/bake/compactGlb.ts +1 -1
  22. package/src/sharddev/bake/compileScript.ts +6 -0
  23. package/src/sharddev/bake/glbCompression.ts +1 -1
  24. package/src/sharddev/bake/gltfSource.ts +1 -1
  25. package/src/sharddev/bake/placeholders.ts +1 -1
  26. package/src/sharddev/bake/terrain.ts +12 -3
  27. package/src/sharddev/blobBytes.ts +1 -1
  28. package/src/sharddev/blobs.ts +2 -2
  29. package/src/sharddev/checkProject.ts +7 -18
  30. package/src/sharddev/cli.ts +17 -4
  31. package/src/sharddev/engineMusic.ts +23 -0
  32. package/src/sharddev/formatJsonSchema.ts +1 -1
  33. package/src/sharddev/materialGraphFiles.ts +1 -1
  34. package/src/sharddev/materials.ts +7 -3
  35. package/src/sharddev/newProject.ts +18 -10
  36. package/src/sharddev/outputProduct.ts +2 -2
  37. package/src/sharddev/productOutput.ts +2 -2
  38. package/src/sharddev/project.ts +6 -1
  39. package/src/sharddev/projectMap.ts +1 -1
  40. package/src/sharddev/refusals.ts +5 -3
  41. package/src/sharddev/reportCard.ts +1 -1
  42. package/src/sharddev/scene/author.ts +184 -0
  43. package/src/sharddev/scene/canvas.ts +212 -0
  44. package/src/sharddev/scene/description.ts +223 -0
  45. package/src/sharddev/scene/hash.ts +23 -0
  46. package/src/sharddev/scene/lower.ts +341 -0
  47. package/src/sharddev/scene/shard.ts +41 -0
  48. package/src/sharddev/scene/shardfile.ts +621 -0
  49. package/src/sharddev/threeGate.mjs +14 -0
  50. package/src/sharddev/threePin.mjs +40 -0
  51. package/src/sharddev/watch/page.ts +284 -0
  52. package/src/sharddev/watch/pageEntry.ts +59 -0
  53. package/src/sharddev/watch/parity-baseline.json +22 -0
  54. package/src/sharddev/watch/parity.mjs +168 -0
  55. package/src/sharddev/watch/proof.mjs +199 -0
  56. package/src/sharddev/watch/protocol.ts +166 -0
  57. package/src/sharddev/watch/socket.ts +57 -0
  58. package/src/sharddev/watch/watch.ts +373 -0
  59. package/src/shards/_template/assets/3058c100bc477fd6fe8268f33b53756b8a2556e7e41c58b2216c703ca7b042c6 +1 -0
  60. package/src/shards/_template/assets/8a0440f392737a31cf0926a3c7dc011c320144972882945a5462c893e817d94a +0 -0
  61. package/src/shards/_template/behaviour/door.as +16 -26
  62. package/src/shards/_template/card/landscape.jpg +0 -0
  63. package/src/shards/_template/card/portrait.jpg +0 -0
  64. package/src/shards/_template/card/thumb.jpg +0 -0
  65. package/src/shards/_template/data/clientScripts.json +43 -43
  66. package/src/shards/_template/data/creatures.json +2 -2
  67. package/src/shards/_template/data/look.json +141 -13
  68. package/src/shards/_template/data/rows.json +20 -2
  69. package/src/shards/_template/data/skins.json +32 -0
  70. package/src/shards/_template/data/water.json +18 -0
  71. package/src/shards/_template/generators/product.ts +5 -1
  72. package/src/shards/_template/generators/warden.ts +273 -0
  73. package/src/shards/_template/generators/world.ts +52 -21
  74. package/src/shards/_template/hero.json +6 -6
  75. package/src/shards/authoring-slice/generators/shard.ts +14 -0
  76. package/src/shards/authoring-slice/generators/sky.ts +64 -0
  77. package/src/shards/authoring-slice/generators/template-sky.ts +27 -0
  78. package/src/shards/authoring-slice/generators/textures.ts +232 -0
  79. package/src/shards/authoring-slice/generators/world.ts +518 -0
  80. package/src/shards/authoring-slice/shard.config.ts +7 -0
  81. package/src/shards/mossgate/generators/shard.ts +6 -0
  82. package/src/shards/mossgate/generators/sky.ts +64 -0
  83. package/src/shards/mossgate/generators/textures.ts +249 -0
  84. package/src/shards/mossgate/generators/world.ts +998 -0
  85. package/src/shards/mossgate/shard.config.ts +7 -0
  86. package/scripts/shard-output-report.d.mts +0 -9
  87. package/scripts/shard-output-report.mjs +0 -85
  88. package/scripts/shard-platform-cli.mjs +0 -93
@@ -0,0 +1,212 @@
1
+ import type { DataTexture } from 'three';
2
+ import { byte, checkSize, memoPainted } from './author';
3
+
4
+ /**
5
+ * AUTHORING-PARITY AP1: `paintCanvas(w, h, draw)`, the part of the Canvas 2D API the cleanrooms paint with, in plain
6
+ * JavaScript at compile time. A cleanroom painter (`const [c, ctx] = canvas(w, h); ...; return new CanvasTexture(c)`)
7
+ * ports by swapping its first and last lines. Fills sample each pixel centre (no antialiasing; the mip chain softens);
8
+ * the nonzero rule, source-over and destination-out compositing, transforms, linear and radial gradients and a 5x7
9
+ * bitmap `fillText` are what the cleanroom textures use. Anything else throws, so a missing call is never silent.
10
+ */
11
+
12
+ type Colour = [number, number, number, number];
13
+ interface Gradient { readonly kind: 'linear' | 'radial'; readonly at: readonly number[]; readonly stops: [number, Colour][]; addColorStop: (offset: number, colour: string) => void }
14
+ type Style = string | Gradient;
15
+ type Matrix = [number, number, number, number, number, number];
16
+ interface State { transform: Matrix; fillStyle: Style; strokeStyle: Style; lineWidth: number; globalAlpha: number; globalCompositeOperation: 'source-over' | 'destination-out'; font: string; textAlign: 'left' | 'center' | 'right' | 'start'; textBaseline: 'alphabetic' | 'middle' | 'top' | 'bottom' }
17
+
18
+ function parseColour(text: string): Colour {
19
+ const s = text.trim().toLowerCase();
20
+ if (s.startsWith('#')) {
21
+ const hex = s.length === 4 ? Array.from(s.slice(1), (c) => c + c).join('') : s.slice(1, 7);
22
+ return [Number.parseInt(hex.slice(0, 2), 16), Number.parseInt(hex.slice(2, 4), 16), Number.parseInt(hex.slice(4, 6), 16), 1];
23
+ }
24
+ const match = /^rgba?\(([^)]*)\)$/u.exec(s);
25
+ if (match?.[1] !== undefined) { const [r = 0, g = 0, b = 0, a = 1] = match[1].split(',').map((part) => Number.parseFloat(part)); return [r, g, b, a]; }
26
+ if (s === 'transparent') return [0, 0, 0, 0];
27
+ if (s === 'white') return [255, 255, 255, 1];
28
+ if (s === 'black') return [0, 0, 0, 1];
29
+ throw new Error(`paintCanvas: colour ${text} is not #hex, rgb() or rgba()`);
30
+ }
31
+
32
+ /** 5x7 capitals, digits and `x`, one string of 7 rows per glyph. */
33
+ const GLYPHS: Readonly<Record<string, string>> = {
34
+ A: '01110100011000111111100011000110001', B: '11110100011000111110100011000111110', C: '01110100011000010000100001000101110',
35
+ D: '11110100011000110001100011000111110', E: '11111100001000011110100001000011111', F: '11111100001000011110100001000010000',
36
+ G: '01110100011000010111100011000101111', H: '10001100011000111111100011000110001', I: '01110001000010000100001000010001110',
37
+ J: '00111000100001000010000101001001100', K: '10001100101010011000101001001010001', L: '10000100001000010000100001000011111',
38
+ M: '10001110111010110101100011000110001', N: '10001110011010110011100011000110001', O: '01110100011000110001100011000101110',
39
+ P: '11110100011000111110100001000010000', Q: '01110100011000110001101011001001101', R: '11110100011000111110101001001010001',
40
+ S: '01111100001000001110000010000111110', T: '11111001000010000100001000010000100', U: '10001100011000110001100011000101110',
41
+ V: '10001100011000110001100010101000100', W: '10001100011000110101101011010101010', X: '10001100010101000100010101000110001',
42
+ Y: '10001100010101000100001000010000100', Z: '11111000010001000100010001000011111', x: '00000000001000101010001000101010001',
43
+ 0: '01110100011001110101110011000101110', 1: '00100011000010000100001000010001110', 2: '01110100010000100010001000100011111',
44
+ 3: '11111000100010000010000011000101110', 4: '00010001100101010010111110001000010', 5: '11111100001111000001000011000101110',
45
+ 6: '00110010001000011110100011000101110', 7: '11111000010001000100010000100001000', 8: '01110100011000101110100011000101110',
46
+ 9: '01110100011000101111000010001001100', '-': '00000000000000011111000000000000000', '.': '00000000000000000000000000110001100',
47
+ };
48
+
49
+ /** A canvas-like 2D context over an RGBA buffer (rows top first). */
50
+ export class PaintContext {
51
+ readonly width: number;
52
+ readonly height: number;
53
+ /** straight (non-premultiplied) RGBA, 0..255 colour, 0..1 alpha */
54
+ private readonly pixels: Float32Array;
55
+ private state: State = { transform: [1, 0, 0, 1, 0, 0], fillStyle: '#000', strokeStyle: '#000', lineWidth: 1, globalAlpha: 1, globalCompositeOperation: 'source-over', font: '10px monospace', textAlign: 'start', textBaseline: 'alphabetic' };
56
+ private readonly stack: State[] = [];
57
+ private path: [number, number][][] = [];
58
+ constructor(width: number, height: number) { this.width = width; this.height = height; this.pixels = new Float32Array(width * height * 4); }
59
+
60
+ get fillStyle(): Style { return this.state.fillStyle; } set fillStyle(value: Style) { this.state.fillStyle = value; }
61
+ get strokeStyle(): Style { return this.state.strokeStyle; } set strokeStyle(value: Style) { this.state.strokeStyle = value; }
62
+ get lineWidth(): number { return this.state.lineWidth; } set lineWidth(value: number) { this.state.lineWidth = value; }
63
+ get globalAlpha(): number { return this.state.globalAlpha; } set globalAlpha(value: number) { this.state.globalAlpha = value; }
64
+ get globalCompositeOperation(): string { return this.state.globalCompositeOperation; }
65
+ set globalCompositeOperation(value: string) { if (value !== 'source-over' && value !== 'destination-out') throw new Error(`paintCanvas: globalCompositeOperation ${value} is not supported`); this.state.globalCompositeOperation = value; }
66
+ get font(): string { return this.state.font; } set font(value: string) { this.state.font = value; }
67
+ get textAlign(): string { return this.state.textAlign; } set textAlign(value: string) { this.state.textAlign = value as State['textAlign']; }
68
+ get textBaseline(): string { return this.state.textBaseline; } set textBaseline(value: string) { this.state.textBaseline = value as State['textBaseline']; }
69
+
70
+ save(): void { this.stack.push({ ...this.state, transform: [...this.state.transform] }); }
71
+ restore(): void { const state = this.stack.pop(); if (state !== undefined) this.state = state; }
72
+ translate(x: number, y: number): void { this.multiply([1, 0, 0, 1, x, y]); }
73
+ rotate(angle: number): void { const c = Math.cos(angle), s = Math.sin(angle); this.multiply([c, s, -s, c, 0, 0]); }
74
+ scale(x: number, y: number): void { this.multiply([x, 0, 0, y, 0, 0]); }
75
+ private multiply([a2, b2, c2, d2, e2, f2]: Matrix): void {
76
+ const [a, b, c, d, e, f] = this.state.transform;
77
+ this.state.transform = [a * a2 + c * b2, b * a2 + d * b2, a * c2 + c * d2, b * c2 + d * d2, a * e2 + c * f2 + e, b * e2 + d * f2 + f];
78
+ }
79
+ private point(x: number, y: number): [number, number] { const [a, b, c, d, e, f] = this.state.transform; return [a * x + c * y + e, b * x + d * y + f]; }
80
+
81
+ beginPath(): void { this.path = []; }
82
+ moveTo(x: number, y: number): void { this.path.push([this.point(x, y)]); }
83
+ lineTo(x: number, y: number): void { const sub = this.path.at(-1); if (sub === undefined) this.moveTo(x, y); else sub.push(this.point(x, y)); }
84
+ closePath(): void { const sub = this.path.at(-1); const first = sub?.[0]; if (sub !== undefined && first !== undefined) { sub.push(first); this.path.push([first]); } }
85
+ private last(): [number, number] { const sub = this.path.at(-1), point = sub?.at(-1); if (point === undefined) throw new Error('paintCanvas: a curve needs a current point'); return this.inverse(point); }
86
+ private inverse([x, y]: [number, number]): [number, number] {
87
+ const [a, b, c, d, e, f] = this.state.transform, det = a * d - b * c;
88
+ return [(d * (x - e) - c * (y - f)) / det, (-b * (x - e) + a * (y - f)) / det];
89
+ }
90
+ quadraticCurveTo(cx: number, cy: number, x: number, y: number): void {
91
+ const [x0, y0] = this.last();
92
+ for (let i = 1; i <= 16; i++) { const t = i / 16, u = 1 - t; this.lineTo(u * u * x0 + 2 * u * t * cx + t * t * x, u * u * y0 + 2 * u * t * cy + t * t * y); }
93
+ }
94
+ bezierCurveTo(c1x: number, c1y: number, c2x: number, c2y: number, x: number, y: number): void {
95
+ const [x0, y0] = this.last();
96
+ for (let i = 1; i <= 20; i++) { const t = i / 20, u = 1 - t; this.lineTo(u * u * u * x0 + 3 * u * u * t * c1x + 3 * u * t * t * c2x + t * t * t * x, u * u * u * y0 + 3 * u * u * t * c1y + 3 * u * t * t * c2y + t * t * t * y); }
97
+ }
98
+ arc(x: number, y: number, r: number, a0: number, a1: number, ccw = false): void { this.ellipse(x, y, r, r, 0, a0, a1, ccw); }
99
+ ellipse(x: number, y: number, rx: number, ry: number, rotation: number, a0: number, a1: number, ccw = false): void {
100
+ let sweep = a1 - a0;
101
+ if (!ccw && sweep < 0) sweep = (sweep % (2 * Math.PI)) + 2 * Math.PI; if (ccw && sweep > 0) sweep = (sweep % (2 * Math.PI)) - 2 * Math.PI;
102
+ if (Math.abs(a1 - a0) >= 2 * Math.PI) sweep = ccw ? -2 * Math.PI : 2 * Math.PI;
103
+ const steps = Math.max(8, Math.ceil(Math.abs(sweep) / (2 * Math.PI) * 48)), c = Math.cos(rotation), s = Math.sin(rotation);
104
+ for (let i = 0; i <= steps; i++) {
105
+ const a = a0 + sweep * (i / steps), px = Math.cos(a) * rx, py = Math.sin(a) * ry;
106
+ this.lineTo(x + px * c - py * s, y + px * s + py * c);
107
+ }
108
+ }
109
+ rect(x: number, y: number, w: number, h: number): void { this.moveTo(x, y); this.lineTo(x + w, y); this.lineTo(x + w, y + h); this.lineTo(x, y + h); this.closePath(); }
110
+ fillRect(x: number, y: number, w: number, h: number): void { const saved = this.path; this.path = []; this.rect(x, y, w, h); this.fill(); this.path = saved; }
111
+ clearRect(x: number, y: number, w: number, h: number): void {
112
+ for (let py = Math.max(0, Math.floor(y)); py < Math.min(this.height, Math.ceil(y + h)); py++) for (let px = Math.max(0, Math.floor(x)); px < Math.min(this.width, Math.ceil(x + w)); px++) this.pixels.fill(0, (py * this.width + px) * 4, (py * this.width + px) * 4 + 4);
113
+ }
114
+ fill(): void { this.cover(this.path, this.state.fillStyle); }
115
+ stroke(): void {
116
+ const half = this.state.lineWidth / 2, polygons: [number, number][][] = [];
117
+ const [a, b, c, d] = this.state.transform, scale = Math.sqrt(Math.abs(a * d - b * c)) * half;
118
+ for (const sub of this.path) for (let i = 0; i + 1 < sub.length; i++) {
119
+ const p = sub[i], q = sub[i + 1]; if (p === undefined || q === undefined) continue;
120
+ const dx = q[0] - p[0], dy = q[1] - p[1], len = Math.hypot(dx, dy); if (len === 0) continue;
121
+ const nx = -dy / len * scale, ny = dx / len * scale;
122
+ polygons.push([[p[0] + nx, p[1] + ny], [q[0] + nx, q[1] + ny], [q[0] - nx, q[1] - ny], [p[0] - nx, p[1] - ny], [p[0] + nx, p[1] + ny]]);
123
+ }
124
+ for (const polygon of polygons) this.cover([polygon], this.state.strokeStyle);
125
+ }
126
+ createLinearGradient(x0: number, y0: number, x1: number, y1: number): Gradient { return this.gradient('linear', [x0, y0, x1, y1]); }
127
+ createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): Gradient { return this.gradient('radial', [x0, y0, r0, x1, y1, r1]); }
128
+ private gradient(kind: Gradient['kind'], at: number[]): Gradient {
129
+ const stops: [number, Colour][] = [];
130
+ return { kind, at, stops, addColorStop: (offset, colour) => { stops.push([offset, parseColour(colour)]); stops.sort((p, q) => p[0] - q[0]); } };
131
+ }
132
+ createImageData(w: number, h: number): { width: number; height: number; data: Uint8ClampedArray } { return { width: w, height: h, data: new Uint8ClampedArray(w * h * 4) }; }
133
+ putImageData(image: { width: number; height: number; data: Uint8ClampedArray }, dx: number, dy: number): void {
134
+ for (let y = 0; y < image.height; y++) for (let x = 0; x < image.width; x++) {
135
+ const tx = x + dx, ty = y + dy; if (tx < 0 || ty < 0 || tx >= this.width || ty >= this.height) continue;
136
+ const from = (y * image.width + x) * 4, to = (ty * this.width + tx) * 4;
137
+ this.pixels[to] = image.data[from] ?? 0; this.pixels[to + 1] = image.data[from + 1] ?? 0; this.pixels[to + 2] = image.data[from + 2] ?? 0; this.pixels[to + 3] = (image.data[from + 3] ?? 0) / 255;
138
+ }
139
+ }
140
+ /** 5x7 bitmap capitals; the font's pixel size sets the cap height. */
141
+ fillText(text: string, x: number, y: number): void {
142
+ const size = Number.parseFloat(/(\d+(?:\.\d+)?)px/u.exec(this.state.font)?.[1] ?? '10'), cell = size * 0.7 / 7, advance = cell * 6, width = text.length * advance - cell;
143
+ const left = this.state.textAlign === 'center' ? x - width / 2 : this.state.textAlign === 'right' ? x - width : x;
144
+ const top = this.state.textBaseline === 'middle' ? y - cell * 3.5 : this.state.textBaseline === 'top' ? y : y - cell * 7;
145
+ const saved = this.path; this.path = [];
146
+ [...text].forEach((char, i) => {
147
+ const glyph = GLYPHS[char] ?? GLYPHS[char.toUpperCase()];
148
+ if (glyph === undefined) return;
149
+ for (let row = 0; row < 7; row++) for (let col = 0; col < 5; col++) if (glyph[row * 5 + col] === '1') this.rect(left + i * advance + col * cell, top + row * cell, cell, cell);
150
+ });
151
+ this.fill(); this.path = saved;
152
+ }
153
+
154
+ private sample(style: Style, x: number, y: number): Colour {
155
+ if (typeof style === 'string') return parseColour(style);
156
+ const [u, v] = this.inverse([x, y]);
157
+ let t: number;
158
+ if (style.kind === 'linear') { const [x0 = 0, y0 = 0, x1 = 0, y1 = 0] = style.at, dx = x1 - x0, dy = y1 - y0; t = ((u - x0) * dx + (v - y0) * dy) / (dx * dx + dy * dy || 1); }
159
+ else { const x0 = style.at[0] ?? 0, y0 = style.at[1] ?? 0, r0 = style.at[2] ?? 0, r1 = style.at[5] ?? 1; t = (Math.hypot(u - x0, v - y0) - r0) / (r1 - r0 || 1); }
160
+ const stops = style.stops, first = stops[0], last = stops.at(-1);
161
+ if (first === undefined || last === undefined) return [0, 0, 0, 0];
162
+ if (t <= first[0]) return first[1]; if (t >= last[0]) return last[1];
163
+ for (let i = 1; i < stops.length; i++) {
164
+ const [o1, c1] = stops[i] ?? first, [o0, c0] = stops[i - 1] ?? first;
165
+ if (t <= o1) { const k = (t - o0) / (o1 - o0 || 1); return [c0[0] + (c1[0] - c0[0]) * k, c0[1] + (c1[1] - c0[1]) * k, c0[2] + (c1[2] - c0[2]) * k, c0[3] + (c1[3] - c0[3]) * k]; }
166
+ }
167
+ return last[1];
168
+ }
169
+ /** Nonzero-rule coverage of pixel centres, composited with the current style, alpha and operation. */
170
+ private cover(path: [number, number][][], style: Style): void {
171
+ const edges: [number, number, number, number, number][] = [];
172
+ let minY = Infinity, maxY = -Infinity;
173
+ for (const sub of path) for (let i = 0; i + 1 < sub.length; i++) {
174
+ const p = sub[i], q = sub[i + 1]; if (p === undefined || q === undefined || p[1] === q[1]) continue;
175
+ edges.push(p[1] < q[1] ? [p[0], p[1], q[0], q[1], 1] : [q[0], q[1], p[0], p[1], -1]);
176
+ minY = Math.min(minY, p[1], q[1]); maxY = Math.max(maxY, p[1], q[1]);
177
+ }
178
+ // an open subpath fills as if closed
179
+ for (const sub of path) { const p = sub.at(-1), q = sub[0]; if (p !== undefined && q !== undefined && sub.length > 2 && (p[0] !== q[0] || p[1] !== q[1]) && p[1] !== q[1]) { edges.push(p[1] < q[1] ? [p[0], p[1], q[0], q[1], 1] : [q[0], q[1], p[0], p[1], -1]); minY = Math.min(minY, p[1], q[1]); maxY = Math.max(maxY, p[1], q[1]); } }
180
+ const solid = typeof style === 'string' ? parseColour(style) : null, alpha = this.state.globalAlpha, out = this.state.globalCompositeOperation === 'destination-out';
181
+ for (let py = Math.max(0, Math.floor(minY)); py < Math.min(this.height, Math.ceil(maxY)); py++) {
182
+ const cy = py + 0.5, crossings: [number, number][] = [];
183
+ for (const [x0, y0, x1, y1, w] of edges) if (cy >= y0 && cy < y1) crossings.push([x0 + (cy - y0) / (y1 - y0) * (x1 - x0), w]);
184
+ crossings.sort((p, q) => p[0] - q[0]);
185
+ let winding = 0;
186
+ for (let i = 0; i + 1 < crossings.length; i++) {
187
+ winding += crossings[i]?.[1] ?? 0;
188
+ if (winding === 0) continue;
189
+ const start = crossings[i]?.[0] ?? 0, cx = crossings[i + 1]?.[0] ?? 0;
190
+ for (let px = Math.max(0, Math.ceil(start - 0.5)); px < Math.min(this.width, Math.ceil(cx - 0.5)); px++) {
191
+ const [r, g, b, a] = solid ?? this.sample(style, px + 0.5, cy), sa = a * alpha, at = (py * this.width + px) * 4, da = this.pixels[at + 3] ?? 0;
192
+ if (out) { this.pixels[at + 3] = da * (1 - sa); continue; }
193
+ const oa = sa + da * (1 - sa); if (oa <= 0) continue;
194
+ for (let c = 0; c < 3; c++) this.pixels[at + c] = ([r, g, b][c] ?? 0) * sa / oa + (this.pixels[at + c] ?? 0) * da * (1 - sa) / oa;
195
+ this.pixels[at + 3] = oa;
196
+ }
197
+ }
198
+ }
199
+ }
200
+ /** The painted bytes, rows top first. */
201
+ bytes(): Uint8Array {
202
+ const out = new Uint8Array(this.width * this.height * 4);
203
+ for (let i = 0; i < out.length; i += 4) { out[i] = byte(this.pixels[i] ?? 0); out[i + 1] = byte(this.pixels[i + 1] ?? 0); out[i + 2] = byte(this.pixels[i + 2] ?? 0); out[i + 3] = byte((this.pixels[i + 3] ?? 0) * 255); }
204
+ return out;
205
+ }
206
+ }
207
+
208
+ /** `paintCanvas(w, h, (ctx) => ...)`: a cleanroom canvas painter, run at compile time, as a sampled texture. */
209
+ export function paintCanvas(width: number, height: number, draw: (ctx: PaintContext) => void, options: { colourSpace?: 'srgb' | 'linear' } = {}): DataTexture {
210
+ checkSize(width, height);
211
+ return memoPainted('canvas', width, height, draw, options, () => { const ctx = new PaintContext(width, height); draw(ctx); return ctx.bytes(); });
212
+ }
@@ -0,0 +1,223 @@
1
+ import type { DetailLayer } from '@wildshard/format/detail-layer';
2
+ /**
3
+ * AUTHORING-PARITY AP1: the scene description. An author writes an ordinary three.js scene inside `defineShard`; the
4
+ * walker (`lower.ts`) reads it once into this plain, serialisable shape, and both back ends read only this: the shardfile
5
+ * back end (`shardfile.ts`, `wildshard build`) and the dev transport (`../watch`, `wildshard watch`).
6
+ *
7
+ * Every number is in world metres and linear colour. Geometry is kept in its own frame and deduplicated (a shared
8
+ * `BoxGeometry` is one entry), so a part of 1,000 placed boxes is one geometry and 1,000 matrices, as three draws it.
9
+ * Each part carries a content hash, so a re-run that changes one part changes only that part's hash.
10
+ */
11
+
12
+ import type { GraphIr } from '@wildshard/format/materialGraph';
13
+ import type { MaterialEntry } from '@wildshard/format/materials';
14
+
15
+ /** Linear RGB, each 0..n (an HDR emissive may exceed 1). */
16
+ export type Rgb = readonly [number, number, number];
17
+ export type Vec3 = readonly [number, number, number];
18
+
19
+ /** An RGBA8 raster the author painted (`paint`) or handed in as a `DataTexture`. Row 0 is v = 0 (three's DataTexture). */
20
+ export interface SceneTexture {
21
+ readonly key: string;
22
+ readonly width: number;
23
+ readonly height: number;
24
+ readonly rgba: Uint8Array;
25
+ readonly colourSpace: 'srgb' | 'linear';
26
+ }
27
+
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`. */
38
+ export interface SceneMaterial {
39
+ readonly key: string;
40
+ /** the author's `material.name`, or the key */
41
+ readonly name: string;
42
+ readonly kind: 'standard' | 'basic' | 'sprite' | 'points';
43
+ readonly colour: Rgb;
44
+ readonly roughness: number;
45
+ readonly metalness: number;
46
+ readonly emissive: Rgb;
47
+ readonly emissiveIntensity: number;
48
+ /** a `SceneTexture` key */
49
+ readonly map: string | null;
50
+ /** the map's `repeat` and `offset` (uv' = uv * repeat + offset) */
51
+ readonly repeat: readonly [number, number];
52
+ readonly offset: readonly [number, number];
53
+ readonly alphaTest: number;
54
+ readonly side: 'front' | 'back' | 'double';
55
+ readonly vertexColours: boolean;
56
+ readonly transparent: boolean;
57
+ readonly opacity: number;
58
+ readonly blending: 'normal' | 'additive';
59
+ readonly depthWrite: boolean;
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;
67
+ }
68
+
69
+ /** One geometry in its own frame. `colour` is 3 floats per vertex when present. */
70
+ export interface SceneGeometry {
71
+ readonly key: string;
72
+ readonly position: Float32Array;
73
+ readonly normal: Float32Array;
74
+ readonly uv: Float32Array | null;
75
+ readonly colour: Float32Array | null;
76
+ readonly index: Uint32Array | null;
77
+ /** triangles in one copy */
78
+ readonly triangles: number;
79
+ }
80
+
81
+ /** One mesh draw: a geometry in one material at a world matrix, optionally instanced. */
82
+ export interface SceneDraw {
83
+ /** the object's path under its part (`hut/Mesh 3`), for messages and reports */
84
+ readonly path: string;
85
+ readonly geometry: string;
86
+ readonly material: string;
87
+ /** column-major world matrix */
88
+ readonly matrix: readonly number[];
89
+ /** an `InstancedMesh`'s live instances: their local matrices (16 floats each, column-major) and colours (3 each) */
90
+ readonly instances: { readonly count: number; readonly matrices: Float32Array; readonly colours: Float32Array | null } | null;
91
+ readonly castShadow: boolean;
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;
95
+ }
96
+
97
+ /** A `Sprite`: a camera-facing card at a world point. */
98
+ export interface SceneSprite {
99
+ readonly path: string;
100
+ readonly material: string;
101
+ readonly position: Vec3;
102
+ readonly scale: readonly [number, number];
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;
115
+ }
116
+
117
+ export interface SceneLight {
118
+ readonly path: string;
119
+ readonly kind: 'point' | 'directional' | 'hemisphere' | 'ambient';
120
+ readonly colour: Rgb;
121
+ /** hemisphere only */
122
+ readonly groundColour: Rgb | null;
123
+ readonly intensity: number;
124
+ /** point only: three's range (0 = infinite) and decay */
125
+ readonly distance: number;
126
+ readonly decay: number;
127
+ readonly position: Vec3;
128
+ /** directional only: where it points */
129
+ readonly target: Vec3 | null;
130
+ readonly castShadow: boolean;
131
+ /** AP12: a point light's `flicker`; null: steady */
132
+ readonly motion: SceneMotion | null;
133
+ }
134
+
135
+ /** A solid box, said once by `solid(mesh)`: the mesh's own bounds in its world frame. */
136
+ export interface SceneCollider {
137
+ readonly path: string;
138
+ readonly kind: 'cuboid';
139
+ readonly centre: Vec3;
140
+ readonly half: Vec3;
141
+ /** world rotation quaternion (x, y, z, w) */
142
+ readonly rotation: readonly [number, number, number, number];
143
+ }
144
+
145
+ /** A `Water` surface: its outline (world x, z) and level, taken from its own geometry. */
146
+ export interface SceneWater {
147
+ readonly path: string;
148
+ readonly outline: readonly (readonly [number, number])[];
149
+ readonly level: number;
150
+ readonly tint: Rgb;
151
+ readonly reflect: 'planar' | 'sky';
152
+ /** the surface triangles in world space (x, y, z per vertex, non-indexed), for the dev page */
153
+ readonly triangles: Float32Array;
154
+ }
155
+
156
+ export interface ScenePart {
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;
160
+ /** content hash of everything below and of the materials, textures and geometries it uses */
161
+ readonly hash: string;
162
+ readonly draws: readonly SceneDraw[];
163
+ readonly sprites: readonly SceneSprite[];
164
+ readonly points: readonly ScenePoints[];
165
+ readonly lights: readonly SceneLight[];
166
+ readonly colliders: readonly SceneCollider[];
167
+ readonly water: readonly SceneWater[];
168
+ readonly materials: readonly string[];
169
+ readonly textures: readonly string[];
170
+ readonly geometries: readonly string[];
171
+ }
172
+
173
+ /** `world.post(...)`: the cleanroom's composer, as numbers. */
174
+ export interface ScenePost {
175
+ readonly tone: 'aces' | 'neutral' | 'none';
176
+ readonly exposure: number;
177
+ readonly bloom: { readonly strength: number; readonly radius: number; readonly threshold: number } | null;
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;
188
+ }
189
+
190
+ export interface SceneLook {
191
+ /** AP14: null or absent: the format's two-colour dome */
192
+ readonly sky?: SceneSky | null;
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;
194
+ readonly background: Rgb | null;
195
+ readonly post: ScenePost | null;
196
+ }
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
+
201
+ /** The ground the author declared with `world.ground(heightAt)`: closures stay at compile time, never on the wire. */
202
+ export interface SceneGround {
203
+ readonly heightAt: (x: number, z: number) => number;
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;
207
+ /** a hash of the height field sampled on a 2 m grid, so a re-run knows whether the ground changed */
208
+ readonly hash: string;
209
+ }
210
+
211
+ export interface ShardIdentityInput { readonly slug: string; readonly name: string; readonly author?: string; readonly revision?: number; readonly seed?: number }
212
+
213
+ /** Everything the walker read from one run of the author's scene. */
214
+ export interface ShardScene {
215
+ readonly identity: ShardIdentityInput;
216
+ readonly parts: readonly ScenePart[];
217
+ readonly materials: Readonly<Record<string, SceneMaterial>>;
218
+ readonly textures: Readonly<Record<string, SceneTexture>>;
219
+ readonly geometries: Readonly<Record<string, SceneGeometry>>;
220
+ readonly look: SceneLook;
221
+ readonly ground: SceneGround | null;
222
+ readonly spawn: { readonly position: Vec3; readonly yaw: number };
223
+ }
@@ -0,0 +1,23 @@
1
+ /** AP1: a small, stable content hash for scene parts (two FNV-1a lanes, 64 bits as hex). Not a security hash: it only
2
+ * tells a re-run which parts changed. Pure JavaScript, so it runs in an author bundle and in the dev page alike. */
3
+ export class ContentHash {
4
+ private a = 0x811c9dc5;
5
+ private b = 0x01000193 ^ 0x5bd1e995;
6
+ bytes(view: ArrayBufferView): this {
7
+ const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
8
+ let a = this.a, b = this.b;
9
+ for (let i = 0; i < bytes.length; i++) {
10
+ const byte = bytes[i] ?? 0;
11
+ a = Math.imul(a ^ byte, 0x01000193);
12
+ b = Math.imul(b ^ byte, 0x5bd1e995) ^ (b >>> 15);
13
+ }
14
+ this.a = a; this.b = b;
15
+ return this;
16
+ }
17
+ text(value: string): this { return this.bytes(new TextEncoder().encode(`${value}\u0000`)); }
18
+ numbers(values: readonly number[]): this { return this.bytes(Float64Array.from(values)); }
19
+ json(value: unknown): this { return this.text(JSON.stringify(value)); }
20
+ hex(): string { return (this.a >>> 0).toString(16).padStart(8, '0') + (this.b >>> 0).toString(16).padStart(8, '0'); }
21
+ }
22
+
23
+ export const hashOf = (fill: (hash: ContentHash) => void): string => { const hash = new ContentHash(); fill(hash); return hash.hex(); };