@ignifx/core 0.15.0 → 0.17.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/decoders/draco3dgltf.LICENSE.md +201 -0
- package/decoders/draco_decoder.js +116 -0
- package/decoders/draco_decoder_gltf.wasm +0 -0
- package/decoders/vendored.json +22 -0
- package/dist/{decoders-CHJ7vduE.js → decoders-BUQrlS8U.js} +3 -2
- package/dist/decoders-BUQrlS8U.js.map +1 -0
- package/dist/{environment-DPi0_0SP.js → environment-CMpzGXTz.js} +2 -2
- package/dist/{environment-DPi0_0SP.js.map → environment-CMpzGXTz.js.map} +1 -1
- package/dist/{ignifx-error-oYdVnT1S.js → ignifx-error-Der0bpHK.js} +7 -1
- package/dist/ignifx-error-Der0bpHK.js.map +1 -0
- package/dist/index.d.ts +29 -14609
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1715 -4899
- package/dist/index.js.map +1 -1
- package/dist/{instanced-mesh-instance-NnODkvqK.js → instanced-mesh-instance-BMhREEfx.js} +3 -2
- package/dist/{instanced-mesh-instance-NnODkvqK.js.map → instanced-mesh-instance-BMhREEfx.js.map} +1 -1
- package/dist/{material-plugin-BUlqLsap.js → material-plugin-B-hartHR.js} +2 -2
- package/dist/{material-plugin-BUlqLsap.js.map → material-plugin-B-hartHR.js.map} +1 -1
- package/dist/node-DznSvwap.js +301 -0
- package/dist/node-DznSvwap.js.map +1 -0
- package/dist/{post-effect-BHl7U56q.js → post-effect-CuoYvrhb.js} +3 -30
- package/dist/post-effect-CuoYvrhb.js.map +1 -0
- package/dist/{post-effect-compiler-CRek8VxQ.js → post-effect-compiler-Bps8QbiJ.js} +3 -3
- package/dist/{post-effect-compiler-CRek8VxQ.js.map → post-effect-compiler-Bps8QbiJ.js.map} +1 -1
- package/dist/prefab-overrides-76IhcF-e.d.ts +14925 -0
- package/dist/prefab-overrides-76IhcF-e.d.ts.map +1 -0
- package/dist/prefab-overrides-DGiGTSN-.js +2396 -0
- package/dist/prefab-overrides-DGiGTSN-.js.map +1 -0
- package/dist/prefab.d.ts +2 -0
- package/dist/prefab.js +2 -0
- package/dist/reflection-probe-C0pzGrG_.js +1883 -0
- package/dist/reflection-probe-C0pzGrG_.js.map +1 -0
- package/dist/reflection-probes-B8_vK9YR.js +551 -0
- package/dist/reflection-probes-B8_vK9YR.js.map +1 -0
- package/dist/{render-texture-C_TnaSz2.js → render-texture-UqRHRLQy.js} +15 -2
- package/dist/{render-texture-C_TnaSz2.js.map → render-texture-UqRHRLQy.js.map} +1 -1
- package/dist/rolldown-runtime-D7D4PA-g.js +13 -0
- package/dist/{shader-material-B6p66wB8.js → shader-material-Cjfq7nFS.js} +5 -16
- package/dist/{shader-material-B6p66wB8.js.map → shader-material-Cjfq7nFS.js.map} +1 -1
- package/dist/{shader-material-C0TAUr4t.js → shader-material-DCjYDdkh.js} +2 -2
- package/dist/{shader-material-C0TAUr4t.js.map → shader-material-DCjYDdkh.js.map} +1 -1
- package/dist/{shader-pragma-BKCoZTTA.js → shader-pragma-cjEC-EPK.js} +2 -2
- package/dist/{shader-pragma-BKCoZTTA.js.map → shader-pragma-cjEC-EPK.js.map} +1 -1
- package/dist/{surface-shader-BaK0kvBB.js → surface-shader-D40hXQ8c.js} +4 -4
- package/dist/{surface-shader-BaK0kvBB.js.map → surface-shader-D40hXQ8c.js.map} +1 -1
- package/dist/{vec3-D-0Y2mzE.js → vec3-Cc19wl4r.js} +3 -300
- package/dist/vec3-Cc19wl4r.js.map +1 -0
- package/package.json +11 -5
- package/dist/decoders-CHJ7vduE.js.map +0 -1
- package/dist/ignifx-error-oYdVnT1S.js.map +0 -1
- package/dist/json-CzZZ6K4x.js +0 -24
- package/dist/json-CzZZ6K4x.js.map +0 -1
- package/dist/post-effect-BHl7U56q.js.map +0 -1
- package/dist/vec3-D-0Y2mzE.js.map +0 -1
|
@@ -0,0 +1,2396 @@
|
|
|
1
|
+
import { n as assertNever, o as CoreErrorCode, t as IgnifxError } from "./ignifx-error-Der0bpHK.js";
|
|
2
|
+
//#region src/assets/address.ts
|
|
3
|
+
/**
|
|
4
|
+
* Address arithmetic (`docs/architecture/05-assets-and-loading.md` §2): splitting the sub-asset
|
|
5
|
+
* fragment off, recognising the URL forms that bypass the asset root, joining a relative address
|
|
6
|
+
* onto that root, and picking the longest registered extension an address ends with.
|
|
7
|
+
*
|
|
8
|
+
* Everything here is a pure function over strings so the rules can be tested without a service, an
|
|
9
|
+
* app, or a network.
|
|
10
|
+
*/
|
|
11
|
+
/** The URL schemes §2 accepts verbatim: an address in one of these is never joined to the root. */
|
|
12
|
+
const ABSOLUTE_PREFIXES = Object.freeze([
|
|
13
|
+
"http://",
|
|
14
|
+
"https://",
|
|
15
|
+
"blob:",
|
|
16
|
+
"data:"
|
|
17
|
+
]);
|
|
18
|
+
/** The separator between an address and its sub-asset fragment. */
|
|
19
|
+
const FRAGMENT_SEPARATOR = "#";
|
|
20
|
+
/** The separator between the asset root and a relative address. */
|
|
21
|
+
const PATH_SEPARATOR = "/";
|
|
22
|
+
/**
|
|
23
|
+
* Splits a sub-asset fragment off an address.
|
|
24
|
+
*
|
|
25
|
+
* @remarks
|
|
26
|
+
* Only the *first* `#` separates; everything after it is the fragment, so a grammar such as
|
|
27
|
+
* `#frame:a#b` reaches the loader intact. A `data:` URL is never split: its payload may legitimately
|
|
28
|
+
* contain a `#`, and it has no sub-assets to name.
|
|
29
|
+
*
|
|
30
|
+
* @param address - The address as game code wrote it.
|
|
31
|
+
* @returns The path and the fragment.
|
|
32
|
+
*
|
|
33
|
+
* @example
|
|
34
|
+
* ```ts
|
|
35
|
+
* splitFragment("models/hero.glb#animation:Run"); // { path: "models/hero.glb", fragment: "animation:Run" }
|
|
36
|
+
* ```
|
|
37
|
+
*
|
|
38
|
+
* @internal
|
|
39
|
+
*/
|
|
40
|
+
function splitFragment(address) {
|
|
41
|
+
if (address.startsWith("data:")) return {
|
|
42
|
+
path: address,
|
|
43
|
+
fragment: null
|
|
44
|
+
};
|
|
45
|
+
const index = address.indexOf(FRAGMENT_SEPARATOR);
|
|
46
|
+
if (index < 0) return {
|
|
47
|
+
path: address,
|
|
48
|
+
fragment: null
|
|
49
|
+
};
|
|
50
|
+
return {
|
|
51
|
+
path: address.slice(0, index),
|
|
52
|
+
fragment: address.slice(index + 1)
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Reports whether an address is already a URL the service can fetch as it stands.
|
|
57
|
+
*
|
|
58
|
+
* @param path - A fragment-free address.
|
|
59
|
+
* @returns `true` for `http://`, `https://`, `blob:`, and `data:`.
|
|
60
|
+
*
|
|
61
|
+
* @internal
|
|
62
|
+
*/
|
|
63
|
+
function isAbsoluteAddress(path) {
|
|
64
|
+
for (let index = 0; index < ABSOLUTE_PREFIXES.length; index += 1) {
|
|
65
|
+
const prefix = ABSOLUTE_PREFIXES[index];
|
|
66
|
+
if (prefix !== void 0 && path.startsWith(prefix)) return true;
|
|
67
|
+
}
|
|
68
|
+
return false;
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Joins a relative address onto the asset root with exactly one separator.
|
|
72
|
+
*
|
|
73
|
+
* @param root - The asset root; an empty root leaves the address alone.
|
|
74
|
+
* @param path - A fragment-free relative address.
|
|
75
|
+
* @returns The URL to fetch.
|
|
76
|
+
*
|
|
77
|
+
* @example
|
|
78
|
+
* ```ts
|
|
79
|
+
* joinRoot("assets/", "models/hero.glb"); // "assets/models/hero.glb"
|
|
80
|
+
* ```
|
|
81
|
+
*
|
|
82
|
+
* @internal
|
|
83
|
+
*/
|
|
84
|
+
function joinRoot(root, path) {
|
|
85
|
+
if (root.length === 0) return path;
|
|
86
|
+
const base = root.endsWith(PATH_SEPARATOR) ? root.slice(0, -1) : root;
|
|
87
|
+
const tail = path.startsWith(PATH_SEPARATOR) ? path.slice(1) : path;
|
|
88
|
+
return `${base}${PATH_SEPARATOR}${tail}`;
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* Picks the longest registered extension an address ends with, so `.scene.json` wins over `.json`.
|
|
92
|
+
*
|
|
93
|
+
* @param path - A fragment-free address.
|
|
94
|
+
* @param extensions - Every registered extension, each with its leading dot.
|
|
95
|
+
* @returns The winning extension in lower case, or `null` when none matches.
|
|
96
|
+
*
|
|
97
|
+
* @example
|
|
98
|
+
* ```ts
|
|
99
|
+
* matchExtension("levels/1.scene.json", [".json", ".scene.json"]); // ".scene.json"
|
|
100
|
+
* ```
|
|
101
|
+
*
|
|
102
|
+
* @internal
|
|
103
|
+
*/
|
|
104
|
+
function matchExtension(path, extensions) {
|
|
105
|
+
const lower = path.toLowerCase();
|
|
106
|
+
let best = null;
|
|
107
|
+
for (const extension of extensions) if (lower.endsWith(extension) && (best === null || extension.length > best.length)) best = extension;
|
|
108
|
+
return best;
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Normalises an extension the way the registry stores it: lower case, with a leading dot.
|
|
112
|
+
*
|
|
113
|
+
* @param extension - The extension as an extension author wrote it.
|
|
114
|
+
* @returns The normalised form.
|
|
115
|
+
*
|
|
116
|
+
* @internal
|
|
117
|
+
*/
|
|
118
|
+
function normalizeExtension(extension) {
|
|
119
|
+
const lower = extension.toLowerCase();
|
|
120
|
+
return lower.startsWith(".") ? lower : `.${lower}`;
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* The scheme in-memory assets are registered under (`Assets.register`). An address that starts with
|
|
124
|
+
* it names a value built in code — a `MeshAsset.box(...)`, a `MaterialAsset.pbr(...)` — rather than
|
|
125
|
+
* a file, so nothing fetches it and nothing can write it into a scene file.
|
|
126
|
+
*
|
|
127
|
+
* @internal
|
|
128
|
+
*/
|
|
129
|
+
const MEMORY_ADDRESS_PREFIX = "memory:";
|
|
130
|
+
/**
|
|
131
|
+
* Reports whether an address names an in-memory asset rather than a file.
|
|
132
|
+
*
|
|
133
|
+
* @param address - The address to test.
|
|
134
|
+
* @returns `true` when the address carries the `memory:` scheme.
|
|
135
|
+
*
|
|
136
|
+
* @example
|
|
137
|
+
* ```ts
|
|
138
|
+
* isMemoryAddress("memory:mesh/01J9Z6M7E5S3A0V2Q4R8T1Y6WX"); // true
|
|
139
|
+
* ```
|
|
140
|
+
*
|
|
141
|
+
* @internal
|
|
142
|
+
*/
|
|
143
|
+
function isMemoryAddress(address) {
|
|
144
|
+
return address.startsWith(MEMORY_ADDRESS_PREFIX);
|
|
145
|
+
}
|
|
146
|
+
//#endregion
|
|
147
|
+
//#region src/schema/issues.ts
|
|
148
|
+
/**
|
|
149
|
+
* Diagnostic codes this module reports. They live in the `06xx` serialization range registered in
|
|
150
|
+
* `docs/architecture/15-devtools-and-diagnostics.md` §1. Codes `IGX-0601` to `IGX-0604` are already
|
|
151
|
+
* spoken for by the scene loader (`docs/architecture/06-serialization-and-scene-format.md`), so the
|
|
152
|
+
* schema-level checks continue from `IGX-0605`.
|
|
153
|
+
*
|
|
154
|
+
* @public
|
|
155
|
+
*/
|
|
156
|
+
const SchemaIssueCode = {
|
|
157
|
+
/** A number was `NaN`, `Infinity`, or `-Infinity` and therefore cannot be written to JSON. */
|
|
158
|
+
nonFiniteNumber: "IGX-0601",
|
|
159
|
+
/** An entity or component reference could not be resolved to a uid. */
|
|
160
|
+
unresolvedReference: "IGX-0602",
|
|
161
|
+
/** A value had the wrong JavaScript or JSON type for the field kind. */
|
|
162
|
+
typeMismatch: "IGX-0605",
|
|
163
|
+
/** A value had the right type but fell outside the field's declared value domain. */
|
|
164
|
+
outOfRange: "IGX-0606",
|
|
165
|
+
/**
|
|
166
|
+
* A property was supplied that the schema does not declare, or a schema declaration named a field
|
|
167
|
+
* it may not use: not identifier-like, a `Component`/`Script` member, or an `Object.prototype`
|
|
168
|
+
* member such as `constructor` or `__proto__`.
|
|
169
|
+
*/
|
|
170
|
+
unknownField: "IGX-0607"
|
|
171
|
+
};
|
|
172
|
+
/**
|
|
173
|
+
* Builds an issue record.
|
|
174
|
+
*
|
|
175
|
+
* @param code - The diagnostic code.
|
|
176
|
+
* @param path - The property path the problem was found at.
|
|
177
|
+
* @param message - An actionable description.
|
|
178
|
+
* @returns The issue.
|
|
179
|
+
*
|
|
180
|
+
* @internal
|
|
181
|
+
*/
|
|
182
|
+
function issue(code, path, message) {
|
|
183
|
+
return {
|
|
184
|
+
path,
|
|
185
|
+
message,
|
|
186
|
+
code
|
|
187
|
+
};
|
|
188
|
+
}
|
|
189
|
+
/**
|
|
190
|
+
* Throws for a mistake in a *schema declaration* — as opposed to a bad value, which is reported as
|
|
191
|
+
* a {@link SchemaIssue}. Declarations are authored by hand, so a mistake there is API misuse and
|
|
192
|
+
* must be loud (`CONSTITUTION.md` §3.9).
|
|
193
|
+
*
|
|
194
|
+
* @param code - The diagnostic code carried by the thrown error.
|
|
195
|
+
* @param message - An actionable description of the mistake.
|
|
196
|
+
* @throws IgnifxError carrying `code`. The `06xx` serialization range is registered in
|
|
197
|
+
* `docs/architecture/15-devtools-and-diagnostics.md` section 1.
|
|
198
|
+
*
|
|
199
|
+
* @internal
|
|
200
|
+
*/
|
|
201
|
+
function throwSchemaError(code, message) {
|
|
202
|
+
throw new IgnifxError(code, message, { hint: "Schema declarations are authored by hand; fix the declaration rather than the value." });
|
|
203
|
+
}
|
|
204
|
+
//#endregion
|
|
205
|
+
//#region src/schema/json.ts
|
|
206
|
+
/**
|
|
207
|
+
* Sets a key on an object being built from JSON as an own, enumerable data property — what
|
|
208
|
+
* `JSON.parse` does. A plain `target[key] = value` treats the key `__proto__` as the prototype
|
|
209
|
+
* setter, so a file carrying that key would change the copy's prototype instead of holding data.
|
|
210
|
+
*
|
|
211
|
+
* @param target - The object under construction.
|
|
212
|
+
* @param key - The key, taken from parsed JSON.
|
|
213
|
+
* @param value - The value.
|
|
214
|
+
*
|
|
215
|
+
* @internal
|
|
216
|
+
*/
|
|
217
|
+
function setOwnJsonProperty(target, key, value) {
|
|
218
|
+
Object.defineProperty(target, key, {
|
|
219
|
+
value,
|
|
220
|
+
enumerable: true,
|
|
221
|
+
writable: true,
|
|
222
|
+
configurable: true
|
|
223
|
+
});
|
|
224
|
+
}
|
|
225
|
+
//#endregion
|
|
226
|
+
//#region src/serialization/json-view.ts
|
|
227
|
+
/**
|
|
228
|
+
* Narrows a JSON value to an object. `Array.isArray` alone does not remove `JsonArray` from the
|
|
229
|
+
* `JsonValue` union in a way that lets the object half be indexed by an arbitrary string, so the
|
|
230
|
+
* whole discrimination lives here rather than being repeated with an assertion at every call site.
|
|
231
|
+
*
|
|
232
|
+
* @param value - The JSON to narrow.
|
|
233
|
+
* @returns The object, or `null` when the value is an array, `null`, or a primitive.
|
|
234
|
+
*
|
|
235
|
+
* @internal
|
|
236
|
+
*/
|
|
237
|
+
function asJsonObject(value) {
|
|
238
|
+
if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
|
|
239
|
+
return value;
|
|
240
|
+
}
|
|
241
|
+
/**
|
|
242
|
+
* Narrows a JSON value to an array.
|
|
243
|
+
*
|
|
244
|
+
* @param value - The JSON to narrow.
|
|
245
|
+
* @returns The array, or `null` when the value is not one.
|
|
246
|
+
*
|
|
247
|
+
* @internal
|
|
248
|
+
*/
|
|
249
|
+
function asJsonArray(value) {
|
|
250
|
+
return Array.isArray(value) ? value : null;
|
|
251
|
+
}
|
|
252
|
+
//#endregion
|
|
253
|
+
//#region src/schema/internal.ts
|
|
254
|
+
/**
|
|
255
|
+
* Guards and path helpers shared by validation, encoding, and decoding. Nothing here is exported
|
|
256
|
+
* from the package barrel.
|
|
257
|
+
*/
|
|
258
|
+
/**
|
|
259
|
+
* The component names of a vector value, in encoded order.
|
|
260
|
+
*
|
|
261
|
+
* @internal
|
|
262
|
+
*/
|
|
263
|
+
const VECTOR_COMPONENTS = [
|
|
264
|
+
"x",
|
|
265
|
+
"y",
|
|
266
|
+
"z",
|
|
267
|
+
"w"
|
|
268
|
+
];
|
|
269
|
+
/**
|
|
270
|
+
* The channel names of a color value, in encoded order.
|
|
271
|
+
*
|
|
272
|
+
* @internal
|
|
273
|
+
*/
|
|
274
|
+
const COLOR_CHANNELS = [
|
|
275
|
+
"r",
|
|
276
|
+
"g",
|
|
277
|
+
"b",
|
|
278
|
+
"a"
|
|
279
|
+
];
|
|
280
|
+
/**
|
|
281
|
+
* Extends a property path with a named child.
|
|
282
|
+
*
|
|
283
|
+
* @param path - The parent path, possibly empty.
|
|
284
|
+
* @param name - The child property name.
|
|
285
|
+
* @returns The child path.
|
|
286
|
+
*
|
|
287
|
+
* @internal
|
|
288
|
+
*/
|
|
289
|
+
function childPath(path, name) {
|
|
290
|
+
return path === "" ? name : `${path}.${name}`;
|
|
291
|
+
}
|
|
292
|
+
/**
|
|
293
|
+
* Extends a property path with an array index or map key.
|
|
294
|
+
*
|
|
295
|
+
* @param path - The parent path.
|
|
296
|
+
* @param key - The index or key.
|
|
297
|
+
* @returns The child path.
|
|
298
|
+
*
|
|
299
|
+
* @internal
|
|
300
|
+
*/
|
|
301
|
+
function indexPath(path, key) {
|
|
302
|
+
return typeof key === "number" ? `${path}[${key}]` : `${path}[${JSON.stringify(key)}]`;
|
|
303
|
+
}
|
|
304
|
+
/**
|
|
305
|
+
* Narrows a value to a read-only array without widening its elements to `any`, which is what the
|
|
306
|
+
* built-in `Array.isArray` predicate does for an `unknown` input.
|
|
307
|
+
*
|
|
308
|
+
* @param value - The value to test.
|
|
309
|
+
* @returns Whether the value is an array.
|
|
310
|
+
*
|
|
311
|
+
* @internal
|
|
312
|
+
*/
|
|
313
|
+
function isArray(value) {
|
|
314
|
+
return Array.isArray(value);
|
|
315
|
+
}
|
|
316
|
+
/**
|
|
317
|
+
* Narrows a value to a plain object, excluding arrays and `null`.
|
|
318
|
+
*
|
|
319
|
+
* @param value - The value to test.
|
|
320
|
+
* @returns Whether the value is a plain object.
|
|
321
|
+
*
|
|
322
|
+
* @internal
|
|
323
|
+
*/
|
|
324
|
+
function isPlainObject(value) {
|
|
325
|
+
return typeof value === "object" && value !== null && !isArray(value);
|
|
326
|
+
}
|
|
327
|
+
/**
|
|
328
|
+
* Reinterprets a decoded JavaScript value as the field's declared type. Decoders are the JSON
|
|
329
|
+
* boundary coding standards §5.2 allows assertions at: the value was just built from the field's
|
|
330
|
+
* own definition, so it matches by construction, but that fact is not expressible in the type
|
|
331
|
+
* system without threading the value type through every recursive step.
|
|
332
|
+
*
|
|
333
|
+
* @param value - The decoded value.
|
|
334
|
+
* @returns The same value, typed as the field's value type.
|
|
335
|
+
*
|
|
336
|
+
* @internal
|
|
337
|
+
*/
|
|
338
|
+
function asFieldValue(value) {
|
|
339
|
+
return value;
|
|
340
|
+
}
|
|
341
|
+
//#endregion
|
|
342
|
+
//#region src/schema/encode.ts
|
|
343
|
+
/**
|
|
344
|
+
* Rounds a number to the file format's precision: six decimal places, with `-0` normalized to `0`
|
|
345
|
+
* (`docs/architecture/06-serialization-and-scene-format.md` §3). The rule is idempotent, so
|
|
346
|
+
* save → load → save is byte-identical.
|
|
347
|
+
*
|
|
348
|
+
* @param value - The number to canonicalize.
|
|
349
|
+
* @returns The canonical form of the number.
|
|
350
|
+
*
|
|
351
|
+
* @example
|
|
352
|
+
* ```ts
|
|
353
|
+
* canonicalizeNumber(0.1 + 0.2); // 0.3
|
|
354
|
+
* canonicalizeNumber(-0); // 0
|
|
355
|
+
* ```
|
|
356
|
+
*
|
|
357
|
+
* @public
|
|
358
|
+
*/
|
|
359
|
+
function canonicalizeNumber(value) {
|
|
360
|
+
const rounded = Math.round(value * 1e6) / 1e6;
|
|
361
|
+
return rounded === 0 ? 0 : rounded;
|
|
362
|
+
}
|
|
363
|
+
/**
|
|
364
|
+
* Reports a value that does not match its field and yields the JSON stand-in for it.
|
|
365
|
+
*
|
|
366
|
+
* @param issues - The collector to append to.
|
|
367
|
+
* @param path - The property path the problem was found at.
|
|
368
|
+
* @param message - An actionable description.
|
|
369
|
+
* @returns `null`, the placeholder written for an unrepresentable value.
|
|
370
|
+
*
|
|
371
|
+
* @internal
|
|
372
|
+
*/
|
|
373
|
+
function unrepresentable(issues, path, message) {
|
|
374
|
+
issues.push(issue(SchemaIssueCode.typeMismatch, path, message));
|
|
375
|
+
return null;
|
|
376
|
+
}
|
|
377
|
+
/**
|
|
378
|
+
* Encodes one number, reporting `NaN` and the infinities.
|
|
379
|
+
*
|
|
380
|
+
* @param value - The candidate number.
|
|
381
|
+
* @param path - The property path for reported issues.
|
|
382
|
+
* @param issues - The collector to append to.
|
|
383
|
+
* @returns The canonical number, or `null` when it cannot be written.
|
|
384
|
+
*
|
|
385
|
+
* @internal
|
|
386
|
+
*/
|
|
387
|
+
function encodeNumber(value, path, issues) {
|
|
388
|
+
if (typeof value !== "number") return unrepresentable(issues, path, `expected a number, received ${typeof value}.`);
|
|
389
|
+
if (!Number.isFinite(value)) {
|
|
390
|
+
issues.push(issue(SchemaIssueCode.nonFiniteNumber, path, `${String(value)} cannot be written to JSON.`));
|
|
391
|
+
return null;
|
|
392
|
+
}
|
|
393
|
+
return canonicalizeNumber(value);
|
|
394
|
+
}
|
|
395
|
+
/**
|
|
396
|
+
* Encodes the named channels of an object value as a JSON number array.
|
|
397
|
+
*
|
|
398
|
+
* @param names - The channel names to read, in encoded order.
|
|
399
|
+
* @param label - How the value is named in messages.
|
|
400
|
+
* @param value - The candidate value.
|
|
401
|
+
* @param path - The property path for reported issues.
|
|
402
|
+
* @param issues - The collector to append to.
|
|
403
|
+
* @returns The number array, or `null` when a channel is missing or unrepresentable.
|
|
404
|
+
*
|
|
405
|
+
* @internal
|
|
406
|
+
*/
|
|
407
|
+
function encodeChannels(names, label, value, path, issues) {
|
|
408
|
+
if (!isPlainObject(value)) return unrepresentable(issues, path, `expected a ${label} object, received ${typeof value}.`);
|
|
409
|
+
const encoded = [];
|
|
410
|
+
for (const name of names) {
|
|
411
|
+
const channel = encodeNumber(value[name], childPath(path, name), issues);
|
|
412
|
+
if (channel === null) return null;
|
|
413
|
+
encoded.push(channel);
|
|
414
|
+
}
|
|
415
|
+
return encoded;
|
|
416
|
+
}
|
|
417
|
+
/**
|
|
418
|
+
* Encodes one value against one field definition.
|
|
419
|
+
*
|
|
420
|
+
* @param field - The field to encode against.
|
|
421
|
+
* @param value - The value to encode.
|
|
422
|
+
* @param references - How to resolve entity and component references to uids.
|
|
423
|
+
* @param path - The property path for reported issues.
|
|
424
|
+
* @param issues - The collector to append to.
|
|
425
|
+
* @returns The JSON representation.
|
|
426
|
+
*
|
|
427
|
+
* @internal
|
|
428
|
+
*/
|
|
429
|
+
function encodeInto(field, value, references, path, issues) {
|
|
430
|
+
const { spec } = field;
|
|
431
|
+
switch (spec.kind) {
|
|
432
|
+
case "f32":
|
|
433
|
+
case "f64":
|
|
434
|
+
case "i32":
|
|
435
|
+
case "u32": return encodeNumber(value, path, issues);
|
|
436
|
+
case "bool": return typeof value === "boolean" ? value : unrepresentable(issues, path, `expected a boolean, received ${typeof value}.`);
|
|
437
|
+
case "str": return typeof value === "string" ? value : unrepresentable(issues, path, `expected a string, received ${typeof value}.`);
|
|
438
|
+
case "vec2":
|
|
439
|
+
case "vec3":
|
|
440
|
+
case "vec4":
|
|
441
|
+
case "quat": return encodeChannels(VECTOR_COMPONENTS.slice(0, spec.components), spec.kind, value, path, issues);
|
|
442
|
+
case "color": return encodeChannels(COLOR_CHANNELS, "color", value, path, issues);
|
|
443
|
+
case "enum": return typeof value === "string" ? value : unrepresentable(issues, path, `expected a string, received ${typeof value}.`);
|
|
444
|
+
case "entityRef": {
|
|
445
|
+
if (value === null) return null;
|
|
446
|
+
const uid = references.entityUid(value);
|
|
447
|
+
if (uid === null) {
|
|
448
|
+
issues.push(issue(SchemaIssueCode.unresolvedReference, path, `the referenced entity is not in this file.`));
|
|
449
|
+
return null;
|
|
450
|
+
}
|
|
451
|
+
return { $entity: uid };
|
|
452
|
+
}
|
|
453
|
+
case "componentRef": {
|
|
454
|
+
if (value === null) return null;
|
|
455
|
+
const uid = references.componentUid(value);
|
|
456
|
+
if (uid === null) {
|
|
457
|
+
issues.push(issue(SchemaIssueCode.unresolvedReference, path, `the referenced component is not in this file.`));
|
|
458
|
+
return null;
|
|
459
|
+
}
|
|
460
|
+
return { $component: uid };
|
|
461
|
+
}
|
|
462
|
+
case "asset": {
|
|
463
|
+
if (value === null) return null;
|
|
464
|
+
if (!isPlainObject(value) || typeof value["address"] !== "string") return unrepresentable(issues, path, `expected a loaded asset handle, or null.`);
|
|
465
|
+
const address = value["address"];
|
|
466
|
+
if (isMemoryAddress(address)) {
|
|
467
|
+
issues.push(issue(SchemaIssueCode.unresolvedReference, path, `the asset was created in code (${address}) and has no file to reference.`));
|
|
468
|
+
return null;
|
|
469
|
+
}
|
|
470
|
+
const declared = value["type"];
|
|
471
|
+
const typeName = typeof declared === "string" ? declared : spec.typeName;
|
|
472
|
+
return typeName === null ? { $asset: address } : {
|
|
473
|
+
$asset: address,
|
|
474
|
+
type: typeName
|
|
475
|
+
};
|
|
476
|
+
}
|
|
477
|
+
case "array": {
|
|
478
|
+
if (!isArray(value)) return unrepresentable(issues, path, `expected an array, received ${typeof value}.`);
|
|
479
|
+
const encoded = [];
|
|
480
|
+
for (let index = 0; index < value.length; index += 1) encoded.push(encodeInto(spec.item, value[index], references, indexPath(path, index), issues));
|
|
481
|
+
return encoded;
|
|
482
|
+
}
|
|
483
|
+
case "record":
|
|
484
|
+
if (!isPlainObject(value)) return unrepresentable(issues, path, `expected an object, received ${typeof value}.`);
|
|
485
|
+
return encodeFields(spec.fields, value, references, path, issues);
|
|
486
|
+
case "map": {
|
|
487
|
+
if (!isPlainObject(value)) return unrepresentable(issues, path, `expected an object, received ${typeof value}.`);
|
|
488
|
+
const encoded = {};
|
|
489
|
+
for (const key of Object.keys(value).toSorted()) setOwnJsonProperty(encoded, key, encodeInto(spec.value, value[key], references, indexPath(path, key), issues));
|
|
490
|
+
return encoded;
|
|
491
|
+
}
|
|
492
|
+
case "optional": return value === null ? null : encodeInto(spec.inner, value, references, path, issues);
|
|
493
|
+
case "layerMask": {
|
|
494
|
+
if (!isArray(value)) return unrepresentable(issues, path, `expected an array of layer names.`);
|
|
495
|
+
const encoded = [];
|
|
496
|
+
for (let index = 0; index < value.length; index += 1) {
|
|
497
|
+
const name = value[index];
|
|
498
|
+
if (typeof name !== "string") return unrepresentable(issues, indexPath(path, index), `expected a layer name string.`);
|
|
499
|
+
encoded.push(name);
|
|
500
|
+
}
|
|
501
|
+
return encoded;
|
|
502
|
+
}
|
|
503
|
+
case "curve": {
|
|
504
|
+
if (!isPlainObject(value)) return unrepresentable(issues, path, `expected a curve object.`);
|
|
505
|
+
const keys = value["keys"];
|
|
506
|
+
const keysAt = childPath(path, "keys");
|
|
507
|
+
if (!isArray(keys)) return unrepresentable(issues, keysAt, `expected an array of curve keys.`);
|
|
508
|
+
const encoded = [];
|
|
509
|
+
for (let index = 0; index < keys.length; index += 1) {
|
|
510
|
+
const key = keys[index];
|
|
511
|
+
const keyAt = indexPath(keysAt, index);
|
|
512
|
+
if (!isArray(key) || key.length !== 4) return unrepresentable(issues, keyAt, `expected [time, value, inTangent, outTangent].`);
|
|
513
|
+
encoded.push([
|
|
514
|
+
encodeNumber(key[0], indexPath(keyAt, 0), issues),
|
|
515
|
+
encodeNumber(key[1], indexPath(keyAt, 1), issues),
|
|
516
|
+
encodeNumber(key[2], indexPath(keyAt, 2), issues),
|
|
517
|
+
encodeNumber(key[3], indexPath(keyAt, 3), issues)
|
|
518
|
+
]);
|
|
519
|
+
}
|
|
520
|
+
return { keys: encoded };
|
|
521
|
+
}
|
|
522
|
+
case "custom": return spec.codec.serialize(value);
|
|
523
|
+
default: return assertNever(spec, "schema field kind");
|
|
524
|
+
}
|
|
525
|
+
}
|
|
526
|
+
/**
|
|
527
|
+
* Encodes a bag of values against a schema in canonical (declaration) key order, skipping fields
|
|
528
|
+
* marked `transient` (`docs/architecture/06-serialization-and-scene-format.md` §5).
|
|
529
|
+
*
|
|
530
|
+
* @param schema - The schema that fixes the key order.
|
|
531
|
+
* @param values - The values to encode, keyed by field name; missing names take the field default.
|
|
532
|
+
* @param references - How to resolve entity and component references to uids.
|
|
533
|
+
* @param path - The property path prefix for reported issues.
|
|
534
|
+
* @param issues - The collector to append to.
|
|
535
|
+
* @returns The JSON object.
|
|
536
|
+
*
|
|
537
|
+
* @internal
|
|
538
|
+
*/
|
|
539
|
+
function encodeFields(schema, values, references, path, issues) {
|
|
540
|
+
const encoded = {};
|
|
541
|
+
for (const [name, field] of Object.entries(schema)) {
|
|
542
|
+
if (field.options.transient === true) continue;
|
|
543
|
+
const supplied = values[name];
|
|
544
|
+
encoded[name] = encodeInto(field, supplied === void 0 ? field.createDefault() : supplied, references, childPath(path, name), issues);
|
|
545
|
+
}
|
|
546
|
+
return encoded;
|
|
547
|
+
}
|
|
548
|
+
/**
|
|
549
|
+
* Encodes one value into the JSON form the scene format defines
|
|
550
|
+
* (`docs/architecture/06-serialization-and-scene-format.md` §3). Numbers are canonicalized,
|
|
551
|
+
* vectors and colors become arrays, and references become tagged objects.
|
|
552
|
+
*
|
|
553
|
+
* Encoding is total: it always returns valid JSON. A value that cannot be represented — a `NaN`, a
|
|
554
|
+
* reference to something outside the file, a value of the wrong type — is written as `null` and
|
|
555
|
+
* reported through `issues`. Call {@link validateValue} when you want the check without the output.
|
|
556
|
+
*
|
|
557
|
+
* @typeParam T - The field's value type.
|
|
558
|
+
* @param field - The field to encode against.
|
|
559
|
+
* @param value - The value to encode.
|
|
560
|
+
* @param references - How to resolve entity and component references to uids.
|
|
561
|
+
* @param issues - An optional collector; problems are appended to it in discovery order.
|
|
562
|
+
* @returns The JSON representation.
|
|
563
|
+
*
|
|
564
|
+
* @example
|
|
565
|
+
* ```ts
|
|
566
|
+
* encodeValue(vec3(), { x: 1, y: 2.0000004, z: -0 }, references); // [1, 2, 0]
|
|
567
|
+
* ```
|
|
568
|
+
*
|
|
569
|
+
* @public
|
|
570
|
+
*/
|
|
571
|
+
function encodeValue(field, value, references, issues = []) {
|
|
572
|
+
return encodeInto(field, value, references, "", issues);
|
|
573
|
+
}
|
|
574
|
+
/**
|
|
575
|
+
* Encodes a component's props in canonical key order. Fields the schema declares but `props` omits
|
|
576
|
+
* take their default; fields marked `transient` are skipped.
|
|
577
|
+
*
|
|
578
|
+
* @typeParam S - The schema being encoded.
|
|
579
|
+
* @param schema - The schema that fixes the key order.
|
|
580
|
+
* @param props - The values to encode, keyed by field name.
|
|
581
|
+
* @param references - How to resolve entity and component references to uids.
|
|
582
|
+
* @param issues - An optional collector; problems are appended to it in discovery order.
|
|
583
|
+
* @returns The JSON object written under `props` in a scene file.
|
|
584
|
+
*
|
|
585
|
+
* @public
|
|
586
|
+
*/
|
|
587
|
+
function encodeProps(schema, props, references, issues = []) {
|
|
588
|
+
return encodeFields(schema, asFieldValue(props), references, "", issues);
|
|
589
|
+
}
|
|
590
|
+
/**
|
|
591
|
+
* Decodes one JSON value against one field definition.
|
|
592
|
+
*
|
|
593
|
+
* @param field - The field to decode against.
|
|
594
|
+
* @param json - The JSON to read.
|
|
595
|
+
* @param references - How to resolve uids back to entities and components.
|
|
596
|
+
* @param path - The property path for reported issues.
|
|
597
|
+
* @param issues - The collector to append to.
|
|
598
|
+
* @returns The decoded value, or the field's fresh default when the JSON could not be read.
|
|
599
|
+
*
|
|
600
|
+
* @internal
|
|
601
|
+
*/
|
|
602
|
+
function decodeInto(field, json, references, path, issues) {
|
|
603
|
+
const { spec } = field;
|
|
604
|
+
switch (spec.kind) {
|
|
605
|
+
case "f32":
|
|
606
|
+
case "f64":
|
|
607
|
+
case "i32":
|
|
608
|
+
case "u32":
|
|
609
|
+
if (typeof json !== "number" || !Number.isFinite(json)) return rejected(field, issues, path, `expected a finite number.`);
|
|
610
|
+
return canonicalizeNumber(json);
|
|
611
|
+
case "bool": return typeof json === "boolean" ? json : rejected(field, issues, path, `expected a boolean.`);
|
|
612
|
+
case "str": return typeof json === "string" ? json : rejected(field, issues, path, `expected a string.`);
|
|
613
|
+
case "vec2":
|
|
614
|
+
case "vec3":
|
|
615
|
+
case "vec4":
|
|
616
|
+
case "quat": return decodeChannels(VECTOR_COMPONENTS.slice(0, spec.components), field, json, path, issues);
|
|
617
|
+
case "color": return decodeChannels(COLOR_CHANNELS, field, json, path, issues);
|
|
618
|
+
case "enum":
|
|
619
|
+
if (typeof json !== "string" || !spec.values.includes(json)) return rejected(field, issues, path, `expected one of [${spec.values.join(", ")}].`);
|
|
620
|
+
return json;
|
|
621
|
+
case "entityRef": return decodeReference(field, json, "$entity", (uid) => references.entity(uid), path, issues);
|
|
622
|
+
case "componentRef": return decodeReference(field, json, "$component", (uid) => references.component(uid), path, issues);
|
|
623
|
+
case "asset": {
|
|
624
|
+
if (json === null) return null;
|
|
625
|
+
if (!isPlainObject(json) || typeof json["$asset"] !== "string") return rejected(field, issues, path, `expected { "$asset": "<address>" } or null.`);
|
|
626
|
+
const address = json["$asset"];
|
|
627
|
+
const declared = json["type"];
|
|
628
|
+
const typeName = typeof declared === "string" ? declared : spec.typeName;
|
|
629
|
+
const handle = references.asset(address, typeName);
|
|
630
|
+
if (handle === null || handle === void 0) {
|
|
631
|
+
issues.push(issue(SchemaIssueCode.unresolvedReference, path, `no loaded asset stands at the address "${address}".`));
|
|
632
|
+
return null;
|
|
633
|
+
}
|
|
634
|
+
return handle;
|
|
635
|
+
}
|
|
636
|
+
case "array": {
|
|
637
|
+
if (!isArray(json)) return rejected(field, issues, path, `expected an array.`);
|
|
638
|
+
const decoded = [];
|
|
639
|
+
for (let index = 0; index < json.length; index += 1) decoded.push(decodeInto(spec.item, json[index] ?? null, references, indexPath(path, index), issues));
|
|
640
|
+
return decoded;
|
|
641
|
+
}
|
|
642
|
+
case "record":
|
|
643
|
+
if (!isPlainObject(json)) return rejected(field, issues, path, `expected an object.`);
|
|
644
|
+
return decodeFields(spec.fields, json, references, path, issues);
|
|
645
|
+
case "map": {
|
|
646
|
+
if (!isPlainObject(json)) return rejected(field, issues, path, `expected an object.`);
|
|
647
|
+
const decoded = {};
|
|
648
|
+
for (const key of Object.keys(json).toSorted()) setOwnJsonProperty(decoded, key, decodeInto(spec.value, json[key] ?? null, references, indexPath(path, key), issues));
|
|
649
|
+
return decoded;
|
|
650
|
+
}
|
|
651
|
+
case "optional": return json === null ? null : decodeInto(spec.inner, json, references, path, issues);
|
|
652
|
+
case "layerMask": {
|
|
653
|
+
if (!isArray(json)) return rejected(field, issues, path, `expected an array of layer names.`);
|
|
654
|
+
const names = [];
|
|
655
|
+
for (let index = 0; index < json.length; index += 1) {
|
|
656
|
+
const name = json[index];
|
|
657
|
+
if (typeof name !== "string") return rejected(field, issues, indexPath(path, index), `expected a layer name string.`);
|
|
658
|
+
names.push(name);
|
|
659
|
+
}
|
|
660
|
+
return names;
|
|
661
|
+
}
|
|
662
|
+
case "curve": {
|
|
663
|
+
if (!isPlainObject(json)) return rejected(field, issues, path, `expected a curve object.`);
|
|
664
|
+
const keysAt = childPath(path, "keys");
|
|
665
|
+
const rawKeys = json["keys"];
|
|
666
|
+
if (!isArray(rawKeys)) return rejected(field, issues, keysAt, `expected an array of curve keys.`);
|
|
667
|
+
const keys = [];
|
|
668
|
+
for (let index = 0; index < rawKeys.length; index += 1) {
|
|
669
|
+
const key = rawKeys[index];
|
|
670
|
+
if (!isArray(key) || key.length !== 4) return rejected(field, issues, indexPath(keysAt, index), `expected [time, value, inTangent, outTangent].`);
|
|
671
|
+
const at = (slot) => {
|
|
672
|
+
const component = key[slot];
|
|
673
|
+
return typeof component === "number" && Number.isFinite(component) ? canonicalizeNumber(component) : 0;
|
|
674
|
+
};
|
|
675
|
+
keys.push([
|
|
676
|
+
at(0),
|
|
677
|
+
at(1),
|
|
678
|
+
at(2),
|
|
679
|
+
at(3)
|
|
680
|
+
]);
|
|
681
|
+
}
|
|
682
|
+
return { keys };
|
|
683
|
+
}
|
|
684
|
+
case "custom": return spec.codec.deserialize(json);
|
|
685
|
+
default: return assertNever(spec, "schema field kind");
|
|
686
|
+
}
|
|
687
|
+
}
|
|
688
|
+
/**
|
|
689
|
+
* Reports unreadable JSON and yields the field's fresh default in its place.
|
|
690
|
+
*
|
|
691
|
+
* @param field - The field being decoded.
|
|
692
|
+
* @param issues - The collector to append to.
|
|
693
|
+
* @param path - The property path the problem was found at.
|
|
694
|
+
* @param message - An actionable description.
|
|
695
|
+
* @returns A newly built default value.
|
|
696
|
+
*
|
|
697
|
+
* @internal
|
|
698
|
+
*/
|
|
699
|
+
function rejected(field, issues, path, message) {
|
|
700
|
+
issues.push(issue(SchemaIssueCode.typeMismatch, path, message));
|
|
701
|
+
return field.createDefault();
|
|
702
|
+
}
|
|
703
|
+
/**
|
|
704
|
+
* Decodes a JSON number array back into a channel object.
|
|
705
|
+
*
|
|
706
|
+
* @param names - The channel names to write, in encoded order.
|
|
707
|
+
* @param field - The field being decoded, used for its default on failure.
|
|
708
|
+
* @param json - The JSON to read.
|
|
709
|
+
* @param path - The property path for reported issues.
|
|
710
|
+
* @param issues - The collector to append to.
|
|
711
|
+
* @returns The channel object, or the field's default.
|
|
712
|
+
*
|
|
713
|
+
* @internal
|
|
714
|
+
*/
|
|
715
|
+
function decodeChannels(names, field, json, path, issues) {
|
|
716
|
+
if (!isArray(json) || json.length !== names.length) return rejected(field, issues, path, `expected an array of ${names.length} numbers.`);
|
|
717
|
+
const decoded = {};
|
|
718
|
+
for (let index = 0; index < names.length; index += 1) {
|
|
719
|
+
const component = json[index];
|
|
720
|
+
const name = names[index];
|
|
721
|
+
if (typeof component !== "number" || !Number.isFinite(component) || name === void 0) return rejected(field, issues, indexPath(path, index), `expected a finite number.`);
|
|
722
|
+
decoded[name] = canonicalizeNumber(component);
|
|
723
|
+
}
|
|
724
|
+
return decoded;
|
|
725
|
+
}
|
|
726
|
+
/**
|
|
727
|
+
* Decodes a tagged reference object back into a live target.
|
|
728
|
+
*
|
|
729
|
+
* @param field - The field being decoded, used for its default on failure.
|
|
730
|
+
* @param json - The JSON to read.
|
|
731
|
+
* @param tag - The tag property, `$entity` or `$component`.
|
|
732
|
+
* @param resolve - How to turn a uid into a target.
|
|
733
|
+
* @param path - The property path for reported issues.
|
|
734
|
+
* @param issues - The collector to append to.
|
|
735
|
+
* @returns The resolved target, or `null`.
|
|
736
|
+
*
|
|
737
|
+
* @internal
|
|
738
|
+
*/
|
|
739
|
+
function decodeReference(field, json, tag, resolve, path, issues) {
|
|
740
|
+
if (json === null) return null;
|
|
741
|
+
if (!isPlainObject(json) || typeof json[tag] !== "string") return rejected(field, issues, path, `expected { "${tag}": "<uid>" } or null.`);
|
|
742
|
+
const uid = json[tag];
|
|
743
|
+
const target = resolve(uid);
|
|
744
|
+
if (target === null || target === void 0) {
|
|
745
|
+
issues.push(issue(SchemaIssueCode.unresolvedReference, path, `no target in this file has uid "${uid}".`));
|
|
746
|
+
return null;
|
|
747
|
+
}
|
|
748
|
+
return target;
|
|
749
|
+
}
|
|
750
|
+
/**
|
|
751
|
+
* Decodes a JSON object against a schema, filling omitted fields with their defaults.
|
|
752
|
+
*
|
|
753
|
+
* @param schema - The schema to decode against.
|
|
754
|
+
* @param json - The JSON object to read.
|
|
755
|
+
* @param references - How to resolve uids back to entities and components.
|
|
756
|
+
* @param path - The property path prefix for reported issues.
|
|
757
|
+
* @param issues - The collector to append to.
|
|
758
|
+
* @returns A record holding one value per declared field.
|
|
759
|
+
*
|
|
760
|
+
* @internal
|
|
761
|
+
*/
|
|
762
|
+
function decodeFields(schema, json, references, path, issues) {
|
|
763
|
+
for (const name of Object.keys(json)) if (!Object.hasOwn(schema, name)) issues.push(issue(SchemaIssueCode.unknownField, childPath(path, name), `the schema declares no field "${name}".`));
|
|
764
|
+
const decoded = {};
|
|
765
|
+
for (const [name, field] of Object.entries(schema)) {
|
|
766
|
+
const raw = json[name];
|
|
767
|
+
decoded[name] = raw === void 0 ? field.createDefault() : decodeInto(field, raw, references, childPath(path, name), issues);
|
|
768
|
+
}
|
|
769
|
+
return decoded;
|
|
770
|
+
}
|
|
771
|
+
/**
|
|
772
|
+
* Decodes one JSON value back into a field value. Decoding never throws and never returns a broken
|
|
773
|
+
* value: unreadable JSON yields the field's freshly built default plus an issue, so a corrupt file
|
|
774
|
+
* degrades one field rather than failing a whole scene
|
|
775
|
+
* (`docs/architecture/06-serialization-and-scene-format.md` §4).
|
|
776
|
+
*
|
|
777
|
+
* @typeParam T - The field's value type.
|
|
778
|
+
* @param field - The field to decode against.
|
|
779
|
+
* @param json - The JSON to read.
|
|
780
|
+
* @param references - How to resolve uids back to entities and components.
|
|
781
|
+
* @returns The decoded value and every problem found.
|
|
782
|
+
*
|
|
783
|
+
* @example
|
|
784
|
+
* ```ts
|
|
785
|
+
* decodeValue(vec3(), [1, 2, 3], references); // { value: { x: 1, y: 2, z: 3 }, issues: [] }
|
|
786
|
+
* ```
|
|
787
|
+
*
|
|
788
|
+
* @public
|
|
789
|
+
*/
|
|
790
|
+
function decodeValue(field, json, references) {
|
|
791
|
+
const issues = [];
|
|
792
|
+
return {
|
|
793
|
+
value: asFieldValue(decodeInto(field, json, references, "", issues)),
|
|
794
|
+
issues
|
|
795
|
+
};
|
|
796
|
+
}
|
|
797
|
+
/**
|
|
798
|
+
* Decodes a component's `props` object. Fields the file omits take their schema default; names the
|
|
799
|
+
* schema does not declare are reported as `IGX-0607` and ignored.
|
|
800
|
+
*
|
|
801
|
+
* @typeParam S - The schema being decoded.
|
|
802
|
+
* @param schema - The schema to decode against.
|
|
803
|
+
* @param json - The `props` object read from the file.
|
|
804
|
+
* @param references - How to resolve uids back to entities and components.
|
|
805
|
+
* @returns The decoded field object and every problem found.
|
|
806
|
+
*
|
|
807
|
+
* @public
|
|
808
|
+
*/
|
|
809
|
+
function decodeProps(schema, json, references) {
|
|
810
|
+
const issues = [];
|
|
811
|
+
return {
|
|
812
|
+
value: asFieldValue(decodeFields(schema, json, references, "", issues)),
|
|
813
|
+
issues
|
|
814
|
+
};
|
|
815
|
+
}
|
|
816
|
+
//#endregion
|
|
817
|
+
//#region src/schema/describe.ts
|
|
818
|
+
/**
|
|
819
|
+
* Resolves references to nothing. Describing a schema means describing its *defaults*, and a
|
|
820
|
+
* reference field's default is always `null`, so no world is needed.
|
|
821
|
+
*
|
|
822
|
+
* @returns An encoder that resolves every reference to `null`.
|
|
823
|
+
*
|
|
824
|
+
* @internal
|
|
825
|
+
*/
|
|
826
|
+
function noReferences() {
|
|
827
|
+
return {
|
|
828
|
+
entityUid: () => null,
|
|
829
|
+
componentUid: () => null
|
|
830
|
+
};
|
|
831
|
+
}
|
|
832
|
+
/**
|
|
833
|
+
* Builds the JSON Schema fragment for one field, at any depth: its encoded form plus an
|
|
834
|
+
* `x-ignifx-*` keyword for each inspector option it declares. JSON Schema validators ignore
|
|
835
|
+
* keywords they do not know, and the `x-` prefix keeps these clear of any future standard one.
|
|
836
|
+
*
|
|
837
|
+
* @param field - The field to describe.
|
|
838
|
+
* @returns The fragment.
|
|
839
|
+
*
|
|
840
|
+
* @internal
|
|
841
|
+
*/
|
|
842
|
+
function fieldJsonSchema(field) {
|
|
843
|
+
const fragment = { ...kindJsonSchema(field) };
|
|
844
|
+
const { step, hidden, readonly, group, transient } = field.options;
|
|
845
|
+
if (step !== void 0) fragment["x-ignifx-step"] = step;
|
|
846
|
+
if (hidden !== void 0) fragment["x-ignifx-hidden"] = hidden;
|
|
847
|
+
if (readonly !== void 0) {
|
|
848
|
+
fragment["x-ignifx-readonly"] = readonly;
|
|
849
|
+
if (readonly) fragment["readOnly"] = true;
|
|
850
|
+
}
|
|
851
|
+
if (group !== void 0) fragment["x-ignifx-group"] = group;
|
|
852
|
+
if (transient !== void 0) fragment["x-ignifx-transient"] = transient;
|
|
853
|
+
return fragment;
|
|
854
|
+
}
|
|
855
|
+
/**
|
|
856
|
+
* Builds the JSON Schema fragment for one field's encoded form.
|
|
857
|
+
*
|
|
858
|
+
* @param field - The field to describe.
|
|
859
|
+
* @returns The fragment describing the field's encoded form.
|
|
860
|
+
*
|
|
861
|
+
* @internal
|
|
862
|
+
*/
|
|
863
|
+
function kindJsonSchema(field) {
|
|
864
|
+
const { spec } = field;
|
|
865
|
+
switch (spec.kind) {
|
|
866
|
+
case "f32":
|
|
867
|
+
case "f64": return { type: "number" };
|
|
868
|
+
case "i32": return {
|
|
869
|
+
type: "integer",
|
|
870
|
+
minimum: -2147483648,
|
|
871
|
+
maximum: 2147483647
|
|
872
|
+
};
|
|
873
|
+
case "u32": return {
|
|
874
|
+
type: "integer",
|
|
875
|
+
minimum: 0,
|
|
876
|
+
maximum: 4294967295
|
|
877
|
+
};
|
|
878
|
+
case "bool": return { type: "boolean" };
|
|
879
|
+
case "str": return { type: "string" };
|
|
880
|
+
case "vec2":
|
|
881
|
+
case "vec3":
|
|
882
|
+
case "vec4":
|
|
883
|
+
case "quat": return {
|
|
884
|
+
type: "array",
|
|
885
|
+
items: { type: "number" },
|
|
886
|
+
minItems: spec.components,
|
|
887
|
+
maxItems: spec.components
|
|
888
|
+
};
|
|
889
|
+
case "color": return {
|
|
890
|
+
type: "array",
|
|
891
|
+
items: {
|
|
892
|
+
type: "number",
|
|
893
|
+
minimum: 0,
|
|
894
|
+
maximum: 1
|
|
895
|
+
},
|
|
896
|
+
minItems: 4,
|
|
897
|
+
maxItems: 4
|
|
898
|
+
};
|
|
899
|
+
case "enum": return {
|
|
900
|
+
type: "string",
|
|
901
|
+
enum: [...spec.values]
|
|
902
|
+
};
|
|
903
|
+
case "entityRef": return taggedReferenceSchema("$entity");
|
|
904
|
+
case "componentRef": {
|
|
905
|
+
const typeId = spec.componentType.typeId;
|
|
906
|
+
return {
|
|
907
|
+
...taggedReferenceSchema("$component"),
|
|
908
|
+
...typeId === void 0 ? {} : { "x-ignifx-component-type": typeId }
|
|
909
|
+
};
|
|
910
|
+
}
|
|
911
|
+
case "asset": return {
|
|
912
|
+
oneOf: [{
|
|
913
|
+
type: "object",
|
|
914
|
+
properties: {
|
|
915
|
+
$asset: { type: "string" },
|
|
916
|
+
type: { type: "string" }
|
|
917
|
+
},
|
|
918
|
+
required: ["$asset"],
|
|
919
|
+
additionalProperties: false
|
|
920
|
+
}, { type: "null" }],
|
|
921
|
+
...spec.typeName === null ? {} : { "x-ignifx-asset-type": spec.typeName }
|
|
922
|
+
};
|
|
923
|
+
case "array": return {
|
|
924
|
+
type: "array",
|
|
925
|
+
items: fieldJsonSchema(spec.item)
|
|
926
|
+
};
|
|
927
|
+
case "record": return schemaJsonSchema(spec.fields);
|
|
928
|
+
case "map": return {
|
|
929
|
+
type: "object",
|
|
930
|
+
additionalProperties: fieldJsonSchema(spec.value)
|
|
931
|
+
};
|
|
932
|
+
case "optional": return { oneOf: [fieldJsonSchema(spec.inner), { type: "null" }] };
|
|
933
|
+
case "layerMask": return {
|
|
934
|
+
type: "array",
|
|
935
|
+
items: { type: "string" }
|
|
936
|
+
};
|
|
937
|
+
case "curve": return {
|
|
938
|
+
type: "object",
|
|
939
|
+
properties: { keys: {
|
|
940
|
+
type: "array",
|
|
941
|
+
items: {
|
|
942
|
+
type: "array",
|
|
943
|
+
items: { type: "number" },
|
|
944
|
+
minItems: 4,
|
|
945
|
+
maxItems: 4
|
|
946
|
+
}
|
|
947
|
+
} },
|
|
948
|
+
required: ["keys"],
|
|
949
|
+
additionalProperties: false
|
|
950
|
+
};
|
|
951
|
+
case "custom": return spec.codec.jsonSchema ?? {};
|
|
952
|
+
default: return assertNever(spec, "schema field kind");
|
|
953
|
+
}
|
|
954
|
+
}
|
|
955
|
+
/**
|
|
956
|
+
* Builds the fragment for a tagged reference: an object carrying one uid property, or `null`.
|
|
957
|
+
*
|
|
958
|
+
* @param tag - The tag property, `$entity` or `$component`.
|
|
959
|
+
* @returns The fragment.
|
|
960
|
+
*
|
|
961
|
+
* @internal
|
|
962
|
+
*/
|
|
963
|
+
function taggedReferenceSchema(tag) {
|
|
964
|
+
return { oneOf: [{
|
|
965
|
+
type: "object",
|
|
966
|
+
properties: { [tag]: { type: "string" } },
|
|
967
|
+
required: [tag],
|
|
968
|
+
additionalProperties: false
|
|
969
|
+
}, { type: "null" }] };
|
|
970
|
+
}
|
|
971
|
+
/**
|
|
972
|
+
* Decorates a field's fragment with the metadata the inspector and the docs already carry.
|
|
973
|
+
*
|
|
974
|
+
* @param field - The field to describe.
|
|
975
|
+
* @returns The fragment plus `default`, `description`, and numeric bounds where they apply.
|
|
976
|
+
*
|
|
977
|
+
* @internal
|
|
978
|
+
*/
|
|
979
|
+
function annotatedFieldJsonSchema(field) {
|
|
980
|
+
const base = { ...fieldJsonSchema(field) };
|
|
981
|
+
const { tooltip, min, max } = field.options;
|
|
982
|
+
if (tooltip !== void 0) base["description"] = tooltip;
|
|
983
|
+
if (min !== void 0) base["minimum"] = min;
|
|
984
|
+
if (max !== void 0) base["maximum"] = max;
|
|
985
|
+
base["default"] = encodeValue(field, field.createDefault(), noReferences());
|
|
986
|
+
return base;
|
|
987
|
+
}
|
|
988
|
+
/**
|
|
989
|
+
* Builds the object fragment for a whole schema.
|
|
990
|
+
*
|
|
991
|
+
* @param schema - The schema to describe.
|
|
992
|
+
* @returns The fragment.
|
|
993
|
+
*
|
|
994
|
+
* @internal
|
|
995
|
+
*/
|
|
996
|
+
function schemaJsonSchema(schema) {
|
|
997
|
+
const properties = {};
|
|
998
|
+
for (const [name, field] of Object.entries(schema)) properties[name] = annotatedFieldJsonSchema(field);
|
|
999
|
+
return {
|
|
1000
|
+
type: "object",
|
|
1001
|
+
properties,
|
|
1002
|
+
additionalProperties: false
|
|
1003
|
+
};
|
|
1004
|
+
}
|
|
1005
|
+
/**
|
|
1006
|
+
* Describes a component schema in the shape the documentation harness and an external inspector
|
|
1007
|
+
* consume. A package exports a record of these keyed by `typeId`; `pnpm docs:schemas` reads it from
|
|
1008
|
+
* the built entry point and regenerates the format pages and `ignifx.schemas.json` from it
|
|
1009
|
+
* (`scripts/README.md`, `docs/architecture/16-docs-harness-and-skill.md` §3). Each field carries
|
|
1010
|
+
* its inspector options and what its kind declares ({@link SchemaFieldDescription}); to describe
|
|
1011
|
+
* an app's registered components with `allowMultiple` and `package` filled in, use
|
|
1012
|
+
* {@link describeRegisteredSchemas}.
|
|
1013
|
+
*
|
|
1014
|
+
* @param typeId - The component's namespaced registration id, for example `mygame/Mover`.
|
|
1015
|
+
* @param schema - The component's declared fields.
|
|
1016
|
+
* @param meta - Overrides for the title, format grouping, and summary, and the component's
|
|
1017
|
+
* `allowMultiple`, `package`, `builtIn` and `requires` when the caller knows them.
|
|
1018
|
+
* @returns The description entry.
|
|
1019
|
+
*
|
|
1020
|
+
* @example
|
|
1021
|
+
* ```ts
|
|
1022
|
+
* export const schemas = {
|
|
1023
|
+
* "mygame/Mover": describeSchema("mygame/Mover", moverSchema, { description: "Moves an entity." }),
|
|
1024
|
+
* };
|
|
1025
|
+
* ```
|
|
1026
|
+
*
|
|
1027
|
+
* @public
|
|
1028
|
+
*/
|
|
1029
|
+
function describeSchema(typeId, schema, meta) {
|
|
1030
|
+
const derivedTitle = typeId.slice(typeId.lastIndexOf("/") + 1);
|
|
1031
|
+
return {
|
|
1032
|
+
title: meta?.title ?? derivedTitle,
|
|
1033
|
+
format: meta?.format ?? "components",
|
|
1034
|
+
...meta?.description === void 0 ? {} : { description: meta.description },
|
|
1035
|
+
fields: describeFields(schema, noReferences()),
|
|
1036
|
+
...meta?.allowMultiple === void 0 ? {} : { allowMultiple: meta.allowMultiple },
|
|
1037
|
+
...meta?.package === void 0 ? {} : { package: meta.package },
|
|
1038
|
+
...meta?.builtIn === void 0 ? {} : { builtIn: meta.builtIn },
|
|
1039
|
+
...meta?.requires === void 0 ? {} : { requires: meta.requires }
|
|
1040
|
+
};
|
|
1041
|
+
}
|
|
1042
|
+
/**
|
|
1043
|
+
* Describes every field of a schema, in declaration order.
|
|
1044
|
+
*
|
|
1045
|
+
* @param schema - The fields.
|
|
1046
|
+
* @param references - The encoder for the defaults.
|
|
1047
|
+
* @returns The descriptions, keyed by field name.
|
|
1048
|
+
*
|
|
1049
|
+
* @internal
|
|
1050
|
+
*/
|
|
1051
|
+
function describeFields(schema, references) {
|
|
1052
|
+
const fields = {};
|
|
1053
|
+
for (const [name, field] of Object.entries(schema)) fields[name] = describeField(field, references);
|
|
1054
|
+
return fields;
|
|
1055
|
+
}
|
|
1056
|
+
/**
|
|
1057
|
+
* Describes one field: its kind, default and tooltip, its inspector options, and what its kind
|
|
1058
|
+
* declares, recursing into nested fields.
|
|
1059
|
+
*
|
|
1060
|
+
* @param field - The field.
|
|
1061
|
+
* @param references - The encoder for the default.
|
|
1062
|
+
* @returns The description.
|
|
1063
|
+
*
|
|
1064
|
+
* @internal
|
|
1065
|
+
*/
|
|
1066
|
+
function describeField(field, references) {
|
|
1067
|
+
const { tooltip } = field.options;
|
|
1068
|
+
return {
|
|
1069
|
+
kind: field.kind,
|
|
1070
|
+
default: encodeValue(field, field.createDefault(), references),
|
|
1071
|
+
...tooltip === void 0 ? {} : { description: tooltip },
|
|
1072
|
+
...describeOptions(field.options),
|
|
1073
|
+
...describeKind(field, references)
|
|
1074
|
+
};
|
|
1075
|
+
}
|
|
1076
|
+
/**
|
|
1077
|
+
* Copies the inspector options a field declares.
|
|
1078
|
+
*
|
|
1079
|
+
* @param options - The field's options.
|
|
1080
|
+
* @returns Only the declared options.
|
|
1081
|
+
*
|
|
1082
|
+
* @internal
|
|
1083
|
+
*/
|
|
1084
|
+
function describeOptions(options) {
|
|
1085
|
+
const { min, max, step, hidden, readonly, group, transient } = options;
|
|
1086
|
+
return {
|
|
1087
|
+
...min === void 0 ? {} : { min },
|
|
1088
|
+
...max === void 0 ? {} : { max },
|
|
1089
|
+
...step === void 0 ? {} : { step },
|
|
1090
|
+
...hidden === void 0 ? {} : { hidden },
|
|
1091
|
+
...readonly === void 0 ? {} : { readonly },
|
|
1092
|
+
...group === void 0 ? {} : { group },
|
|
1093
|
+
...transient === void 0 ? {} : { transient }
|
|
1094
|
+
};
|
|
1095
|
+
}
|
|
1096
|
+
/**
|
|
1097
|
+
* Describes what a field's kind declares beyond the kind itself.
|
|
1098
|
+
*
|
|
1099
|
+
* @param field - The field.
|
|
1100
|
+
* @param references - The encoder for nested defaults.
|
|
1101
|
+
* @returns The kind's members; empty for a kind that declares nothing more.
|
|
1102
|
+
*
|
|
1103
|
+
* @internal
|
|
1104
|
+
*/
|
|
1105
|
+
function describeKind(field, references) {
|
|
1106
|
+
const { spec } = field;
|
|
1107
|
+
switch (spec.kind) {
|
|
1108
|
+
case "enum": return { values: [...spec.values] };
|
|
1109
|
+
case "asset": return spec.typeName === null ? {} : { assetType: spec.typeName };
|
|
1110
|
+
case "componentRef": return { componentType: spec.componentType.typeId ?? null };
|
|
1111
|
+
case "array": return { item: describeField(spec.item, references) };
|
|
1112
|
+
case "record": return { fields: describeFields(spec.fields, references) };
|
|
1113
|
+
case "map": return { value: describeField(spec.value, references) };
|
|
1114
|
+
case "optional": return { inner: describeField(spec.inner, references) };
|
|
1115
|
+
case "f32":
|
|
1116
|
+
case "f64":
|
|
1117
|
+
case "i32":
|
|
1118
|
+
case "u32":
|
|
1119
|
+
case "bool":
|
|
1120
|
+
case "str":
|
|
1121
|
+
case "vec2":
|
|
1122
|
+
case "vec3":
|
|
1123
|
+
case "vec4":
|
|
1124
|
+
case "quat":
|
|
1125
|
+
case "color":
|
|
1126
|
+
case "entityRef":
|
|
1127
|
+
case "layerMask":
|
|
1128
|
+
case "curve":
|
|
1129
|
+
case "custom": return {};
|
|
1130
|
+
default: return assertNever(spec, "schema field kind");
|
|
1131
|
+
}
|
|
1132
|
+
}
|
|
1133
|
+
/**
|
|
1134
|
+
* Generates the JSON Schema (draft 2020-12) for a component's `props` object. The harness and the
|
|
1135
|
+
* Vite plugin assemble these into `ignifx.schemas.json`, which drives build-time validation and
|
|
1136
|
+
* editor autocompletion (`docs/architecture/06-serialization-and-scene-format.md` §8).
|
|
1137
|
+
*
|
|
1138
|
+
* @param schema - The schema to convert.
|
|
1139
|
+
* @returns The object fragment describing every declared prop.
|
|
1140
|
+
*
|
|
1141
|
+
* @public
|
|
1142
|
+
*/
|
|
1143
|
+
function toJsonSchema(schema) {
|
|
1144
|
+
return schemaJsonSchema(schema);
|
|
1145
|
+
}
|
|
1146
|
+
//#endregion
|
|
1147
|
+
//#region src/serialization/scene-file.ts
|
|
1148
|
+
/**
|
|
1149
|
+
* The `format` discriminator every scene and prefab file carries
|
|
1150
|
+
* (`docs/architecture/06-serialization-and-scene-format.md` §2). Levels (`*.scene.json`) and
|
|
1151
|
+
* prefabs (`*.prefab.json`) share it: a prefab is a scene instanced inside another scene
|
|
1152
|
+
* (ADR-0005), not a second file type.
|
|
1153
|
+
*
|
|
1154
|
+
* @public
|
|
1155
|
+
*/
|
|
1156
|
+
const SCENE_FILE_FORMAT = "ignifx.scene";
|
|
1157
|
+
/**
|
|
1158
|
+
* The `formatVersion` this build writes and is the only one it can read. Before 1.0 the number
|
|
1159
|
+
* stays `1` and an incompatible change invalidates files rather than migrating them
|
|
1160
|
+
* (`CONSTITUTION.md` §4.2); a file declaring anything else is rejected with `IGX-0603`.
|
|
1161
|
+
*
|
|
1162
|
+
* @public
|
|
1163
|
+
*/
|
|
1164
|
+
const SCENE_FORMAT_VERSION = 1;
|
|
1165
|
+
/**
|
|
1166
|
+
* The file extensions the scene loader claims.
|
|
1167
|
+
*
|
|
1168
|
+
* @public
|
|
1169
|
+
*/
|
|
1170
|
+
const SCENE_FILE_EXTENSIONS = Object.freeze([".scene.json", ".prefab.json"]);
|
|
1171
|
+
/**
|
|
1172
|
+
* The asset type name the scene loader registers under.
|
|
1173
|
+
*
|
|
1174
|
+
* @public
|
|
1175
|
+
*/
|
|
1176
|
+
const SCENE_ASSET_TYPE = "scene";
|
|
1177
|
+
/**
|
|
1178
|
+
* Writes a scene file as the canonical UTF-8 JSON text: two-space indentation, keys in the order
|
|
1179
|
+
* the serializer built them, numbers already canonicalized by
|
|
1180
|
+
* {@link canonicalizeNumber}. Two saves of the same state produce byte-identical text
|
|
1181
|
+
* (`docs/architecture/06-serialization-and-scene-format.md` §1).
|
|
1182
|
+
*
|
|
1183
|
+
* @param file - The file object, normally from `serializeScene`.
|
|
1184
|
+
* @returns The JSON text, without a trailing newline.
|
|
1185
|
+
*
|
|
1186
|
+
* @example
|
|
1187
|
+
* ```ts
|
|
1188
|
+
* stringifySceneFile(serializeScene(instance)) === stringifySceneFile(serializeScene(instance));
|
|
1189
|
+
* ```
|
|
1190
|
+
*
|
|
1191
|
+
* @public
|
|
1192
|
+
*/
|
|
1193
|
+
function stringifySceneFile(file) {
|
|
1194
|
+
return JSON.stringify(file, null, 2);
|
|
1195
|
+
}
|
|
1196
|
+
/**
|
|
1197
|
+
* Reports whether a parsed JSON value carries the `ignifx.scene` header. It is the cheap check the
|
|
1198
|
+
* loader runs before anything else, so a `.json` asset handed to the wrong loader fails with
|
|
1199
|
+
* `IGX-0308` rather than a confusing field error.
|
|
1200
|
+
*
|
|
1201
|
+
* @param value - The parsed JSON.
|
|
1202
|
+
* @returns `true` when the value is an object whose `format` is {@link SCENE_FILE_FORMAT}.
|
|
1203
|
+
*
|
|
1204
|
+
* @public
|
|
1205
|
+
*/
|
|
1206
|
+
function isSceneFileHeader(value) {
|
|
1207
|
+
if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
|
|
1208
|
+
return value["format"] === SCENE_FILE_FORMAT;
|
|
1209
|
+
}
|
|
1210
|
+
/**
|
|
1211
|
+
* The draft 2020-12 JSON Schema for a scene file, with `components[].props` narrowed per registered
|
|
1212
|
+
* component `typeId` (`docs/architecture/06-serialization-and-scene-format.md` §8). The Vite plugin
|
|
1213
|
+
* and the `ignifx schemas` CLI command emit this into `ignifx.schemas.json`, which drives
|
|
1214
|
+
* build-time validation and editor autocompletion.
|
|
1215
|
+
*
|
|
1216
|
+
* @param registry - The component table whose registered classes narrow `props`. Classes without a
|
|
1217
|
+
* schema contribute a `type` match with a free-form `props` object.
|
|
1218
|
+
* @returns The schema document.
|
|
1219
|
+
*
|
|
1220
|
+
* @example
|
|
1221
|
+
* ```ts
|
|
1222
|
+
* const schema = sceneFileJsonSchema(app.world.registry);
|
|
1223
|
+
* await writeFile("ignifx.schemas.json", JSON.stringify(schema, null, 2));
|
|
1224
|
+
* ```
|
|
1225
|
+
*
|
|
1226
|
+
* @public
|
|
1227
|
+
*/
|
|
1228
|
+
function sceneFileJsonSchema(registry) {
|
|
1229
|
+
return {
|
|
1230
|
+
$schema: "https://json-schema.org/draft/2020-12/schema",
|
|
1231
|
+
$id: "https://ignifx.com/schemas/ignifx.scene.v1.json",
|
|
1232
|
+
title: "ignifx scene file",
|
|
1233
|
+
type: "object",
|
|
1234
|
+
required: [
|
|
1235
|
+
"format",
|
|
1236
|
+
"formatVersion",
|
|
1237
|
+
"name",
|
|
1238
|
+
"entities"
|
|
1239
|
+
],
|
|
1240
|
+
additionalProperties: false,
|
|
1241
|
+
properties: {
|
|
1242
|
+
format: { const: SCENE_FILE_FORMAT },
|
|
1243
|
+
formatVersion: { const: 1 },
|
|
1244
|
+
engineVersion: { type: "string" },
|
|
1245
|
+
name: { type: "string" },
|
|
1246
|
+
settings: { type: "object" },
|
|
1247
|
+
entities: {
|
|
1248
|
+
type: "array",
|
|
1249
|
+
items: { $ref: "#/$defs/entity" }
|
|
1250
|
+
}
|
|
1251
|
+
},
|
|
1252
|
+
$defs: {
|
|
1253
|
+
uid: {
|
|
1254
|
+
type: "string",
|
|
1255
|
+
minLength: 1
|
|
1256
|
+
},
|
|
1257
|
+
assetRef: {
|
|
1258
|
+
type: "object",
|
|
1259
|
+
required: ["$asset"],
|
|
1260
|
+
additionalProperties: false,
|
|
1261
|
+
properties: {
|
|
1262
|
+
$asset: { type: "string" },
|
|
1263
|
+
type: { type: "string" }
|
|
1264
|
+
}
|
|
1265
|
+
},
|
|
1266
|
+
transform: {
|
|
1267
|
+
type: "object",
|
|
1268
|
+
required: [
|
|
1269
|
+
"position",
|
|
1270
|
+
"rotation",
|
|
1271
|
+
"scale"
|
|
1272
|
+
],
|
|
1273
|
+
additionalProperties: false,
|
|
1274
|
+
properties: {
|
|
1275
|
+
position: numberTuple(3),
|
|
1276
|
+
rotation: numberTuple(4),
|
|
1277
|
+
scale: numberTuple(3)
|
|
1278
|
+
}
|
|
1279
|
+
},
|
|
1280
|
+
override: {
|
|
1281
|
+
type: "object",
|
|
1282
|
+
required: ["path"],
|
|
1283
|
+
additionalProperties: false,
|
|
1284
|
+
properties: {
|
|
1285
|
+
op: {
|
|
1286
|
+
type: "string",
|
|
1287
|
+
enum: [
|
|
1288
|
+
"replace",
|
|
1289
|
+
"remove",
|
|
1290
|
+
"add"
|
|
1291
|
+
]
|
|
1292
|
+
},
|
|
1293
|
+
path: {
|
|
1294
|
+
type: "string",
|
|
1295
|
+
minLength: 1
|
|
1296
|
+
},
|
|
1297
|
+
value: true
|
|
1298
|
+
}
|
|
1299
|
+
},
|
|
1300
|
+
instance: {
|
|
1301
|
+
type: "object",
|
|
1302
|
+
required: ["scene"],
|
|
1303
|
+
additionalProperties: false,
|
|
1304
|
+
properties: {
|
|
1305
|
+
scene: { $ref: "#/$defs/assetRef" },
|
|
1306
|
+
hash: { type: "string" },
|
|
1307
|
+
overrides: {
|
|
1308
|
+
type: "array",
|
|
1309
|
+
items: { $ref: "#/$defs/override" }
|
|
1310
|
+
}
|
|
1311
|
+
}
|
|
1312
|
+
},
|
|
1313
|
+
component: {
|
|
1314
|
+
type: "object",
|
|
1315
|
+
required: ["uid", "type"],
|
|
1316
|
+
additionalProperties: false,
|
|
1317
|
+
properties: {
|
|
1318
|
+
uid: { $ref: "#/$defs/uid" },
|
|
1319
|
+
type: {
|
|
1320
|
+
type: "string",
|
|
1321
|
+
minLength: 1
|
|
1322
|
+
},
|
|
1323
|
+
enabled: { type: "boolean" },
|
|
1324
|
+
schemaVersion: {
|
|
1325
|
+
type: "integer",
|
|
1326
|
+
minimum: 1
|
|
1327
|
+
},
|
|
1328
|
+
props: { type: "object" }
|
|
1329
|
+
},
|
|
1330
|
+
allOf: componentPropsBranches(registry)
|
|
1331
|
+
},
|
|
1332
|
+
entity: {
|
|
1333
|
+
type: "object",
|
|
1334
|
+
required: [
|
|
1335
|
+
"uid",
|
|
1336
|
+
"name",
|
|
1337
|
+
"parent",
|
|
1338
|
+
"transform"
|
|
1339
|
+
],
|
|
1340
|
+
additionalProperties: false,
|
|
1341
|
+
properties: {
|
|
1342
|
+
uid: { $ref: "#/$defs/uid" },
|
|
1343
|
+
name: { type: "string" },
|
|
1344
|
+
parent: { anyOf: [{ $ref: "#/$defs/uid" }, { type: "null" }] },
|
|
1345
|
+
active: { type: "boolean" },
|
|
1346
|
+
static: { type: "boolean" },
|
|
1347
|
+
layer: { type: "string" },
|
|
1348
|
+
tags: {
|
|
1349
|
+
type: "array",
|
|
1350
|
+
items: { type: "string" }
|
|
1351
|
+
},
|
|
1352
|
+
transform: { $ref: "#/$defs/transform" },
|
|
1353
|
+
instance: { $ref: "#/$defs/instance" },
|
|
1354
|
+
components: {
|
|
1355
|
+
type: "array",
|
|
1356
|
+
items: { $ref: "#/$defs/component" }
|
|
1357
|
+
}
|
|
1358
|
+
}
|
|
1359
|
+
}
|
|
1360
|
+
}
|
|
1361
|
+
};
|
|
1362
|
+
}
|
|
1363
|
+
/**
|
|
1364
|
+
* The docs-harness description of the scene file format
|
|
1365
|
+
* (`scripts/README.md`, "Schema discovery convention"), so `pnpm docs:schemas` can render
|
|
1366
|
+
* `references/formats/scene.md` beside the component pages.
|
|
1367
|
+
*
|
|
1368
|
+
* @returns The description of the top-level file fields.
|
|
1369
|
+
*
|
|
1370
|
+
* @public
|
|
1371
|
+
*/
|
|
1372
|
+
function describeSceneFileFormat() {
|
|
1373
|
+
return {
|
|
1374
|
+
title: "Scene file",
|
|
1375
|
+
format: SCENE_FILE_FORMAT,
|
|
1376
|
+
description: "A level or a prefab: a tree of entities with components, instanced scenes, and overrides. One format for both (ADR-0005).",
|
|
1377
|
+
fields: {
|
|
1378
|
+
format: {
|
|
1379
|
+
kind: "str",
|
|
1380
|
+
default: SCENE_FILE_FORMAT,
|
|
1381
|
+
description: "Always \"ignifx.scene\"."
|
|
1382
|
+
},
|
|
1383
|
+
formatVersion: {
|
|
1384
|
+
kind: "u32",
|
|
1385
|
+
default: 1,
|
|
1386
|
+
description: "The file format version; 1 before ignifx 1.0."
|
|
1387
|
+
},
|
|
1388
|
+
engineVersion: {
|
|
1389
|
+
kind: "str",
|
|
1390
|
+
default: "",
|
|
1391
|
+
description: "The @ignifx/core version that wrote the file."
|
|
1392
|
+
},
|
|
1393
|
+
name: {
|
|
1394
|
+
kind: "str",
|
|
1395
|
+
default: "",
|
|
1396
|
+
description: "The scene's name."
|
|
1397
|
+
},
|
|
1398
|
+
settings: {
|
|
1399
|
+
kind: "map",
|
|
1400
|
+
default: {},
|
|
1401
|
+
description: "Scene-level values interpreted by systems."
|
|
1402
|
+
},
|
|
1403
|
+
entities: {
|
|
1404
|
+
kind: "array",
|
|
1405
|
+
default: [],
|
|
1406
|
+
description: "Every entity, in tree order."
|
|
1407
|
+
}
|
|
1408
|
+
}
|
|
1409
|
+
};
|
|
1410
|
+
}
|
|
1411
|
+
/**
|
|
1412
|
+
* A fixed-length JSON Schema array of numbers.
|
|
1413
|
+
*
|
|
1414
|
+
* @param length - How many entries.
|
|
1415
|
+
* @returns The fragment.
|
|
1416
|
+
*/
|
|
1417
|
+
function numberTuple(length) {
|
|
1418
|
+
return {
|
|
1419
|
+
type: "array",
|
|
1420
|
+
items: { type: "number" },
|
|
1421
|
+
minItems: length,
|
|
1422
|
+
maxItems: length
|
|
1423
|
+
};
|
|
1424
|
+
}
|
|
1425
|
+
/**
|
|
1426
|
+
* One `if`/`then` branch per registered component `typeId`, narrowing `props` to that class's
|
|
1427
|
+
* generated schema.
|
|
1428
|
+
*
|
|
1429
|
+
* @param registry - The component table.
|
|
1430
|
+
* @returns The branches, in `typeId` order so the document is stable.
|
|
1431
|
+
*/
|
|
1432
|
+
function componentPropsBranches(registry) {
|
|
1433
|
+
const branches = [];
|
|
1434
|
+
const entries = [];
|
|
1435
|
+
const registrations = registry.registrations();
|
|
1436
|
+
for (let index = 0; index < registrations.length; index += 1) {
|
|
1437
|
+
const registration = registrations[index];
|
|
1438
|
+
if (registration === void 0) continue;
|
|
1439
|
+
const [typeId, type] = registration;
|
|
1440
|
+
const schema = registry.describe(type).schema;
|
|
1441
|
+
if (schema === null) continue;
|
|
1442
|
+
entries.push({
|
|
1443
|
+
typeId,
|
|
1444
|
+
props: toJsonSchema(schema)
|
|
1445
|
+
});
|
|
1446
|
+
}
|
|
1447
|
+
entries.sort((left, right) => left.typeId < right.typeId ? -1 : left.typeId > right.typeId ? 1 : 0);
|
|
1448
|
+
for (let index = 0; index < entries.length; index += 1) {
|
|
1449
|
+
const entry = entries[index];
|
|
1450
|
+
if (entry === void 0) continue;
|
|
1451
|
+
branches.push({
|
|
1452
|
+
if: {
|
|
1453
|
+
properties: { type: { const: entry.typeId } },
|
|
1454
|
+
required: ["type"]
|
|
1455
|
+
},
|
|
1456
|
+
then: { properties: { props: entry.props } }
|
|
1457
|
+
});
|
|
1458
|
+
}
|
|
1459
|
+
return branches;
|
|
1460
|
+
}
|
|
1461
|
+
//#endregion
|
|
1462
|
+
//#region src/serialization/scene-asset.ts
|
|
1463
|
+
/**
|
|
1464
|
+
* The `asset()` token for a scene or prefab field. `SceneAsset` is an interface, so it cannot be
|
|
1465
|
+
* passed to `asset()` the way a class such as `MeshAsset` can; this token names the type instead:
|
|
1466
|
+
*
|
|
1467
|
+
* ```ts
|
|
1468
|
+
* class Spawner extends Script.define({ prefab: asset(SceneAssetToken) }) {
|
|
1469
|
+
* static typeId = "game/Spawner";
|
|
1470
|
+
* spawn(): void {
|
|
1471
|
+
* const value = this.prefab?.value;
|
|
1472
|
+
* if (value !== undefined) {
|
|
1473
|
+
* this.app.world.instantiate(value, { position: this.transform.position });
|
|
1474
|
+
* }
|
|
1475
|
+
* }
|
|
1476
|
+
* }
|
|
1477
|
+
* ```
|
|
1478
|
+
*
|
|
1479
|
+
* In a scene file the field is written as `{ "$asset": "props/crate.prefab.json" }`.
|
|
1480
|
+
*
|
|
1481
|
+
* @public
|
|
1482
|
+
*/
|
|
1483
|
+
const SceneAssetToken = Object.freeze({ assetType: SCENE_ASSET_TYPE });
|
|
1484
|
+
/** The hash algorithm and the prefix it is written under. */
|
|
1485
|
+
const HASH_ALGORITHM = "SHA-256";
|
|
1486
|
+
/** The prefix `instance.hash` values carry. */
|
|
1487
|
+
const HASH_PREFIX = "sha256:";
|
|
1488
|
+
/**
|
|
1489
|
+
* The content hash of a scene file: SHA-256 over the canonical JSON text, so two saves of the same
|
|
1490
|
+
* state hash the same and an edited prefab does not
|
|
1491
|
+
* (`docs/architecture/06-serialization-and-scene-format.md` §2).
|
|
1492
|
+
*
|
|
1493
|
+
* @param file - The file to hash.
|
|
1494
|
+
* @returns The hash as `sha256:<64 lowercase hex digits>`.
|
|
1495
|
+
* @throws IgnifxError with code `IGX-1420` when the host exposes no Web Crypto `subtle`.
|
|
1496
|
+
*
|
|
1497
|
+
* @example
|
|
1498
|
+
* ```ts
|
|
1499
|
+
* const hash = await computeSceneHash(serializeScene(instance)); // "sha256:9f2c…"
|
|
1500
|
+
* ```
|
|
1501
|
+
*
|
|
1502
|
+
* @public
|
|
1503
|
+
*/
|
|
1504
|
+
async function computeSceneHash(file) {
|
|
1505
|
+
const subtle = globalThis.crypto?.subtle;
|
|
1506
|
+
if (subtle === void 0 || typeof subtle.digest !== "function") throw new IgnifxError(CoreErrorCode.cryptoUnavailable, "This host does not expose Web Crypto subtle.", {
|
|
1507
|
+
context: { file: file.name },
|
|
1508
|
+
hint: "Scene content hashes need crypto.subtle; run on a secure context or Node 19+."
|
|
1509
|
+
});
|
|
1510
|
+
const bytes = new TextEncoder().encode(stringifySceneFile(file));
|
|
1511
|
+
const digest = await subtle.digest(HASH_ALGORITHM, bytes);
|
|
1512
|
+
return HASH_PREFIX + toHex(new Uint8Array(digest));
|
|
1513
|
+
}
|
|
1514
|
+
/**
|
|
1515
|
+
* Builds a `SceneAsset` from a file that is already in memory — the shape the loader returns, and
|
|
1516
|
+
* the one tests and tools use when there is no asset service in play.
|
|
1517
|
+
*
|
|
1518
|
+
* @param address - The address the asset stands at.
|
|
1519
|
+
* @param file - The parsed file.
|
|
1520
|
+
* @param dependencies - Every asset the file references, already loaded.
|
|
1521
|
+
* @returns The asset, with its content hash computed.
|
|
1522
|
+
*
|
|
1523
|
+
* @example
|
|
1524
|
+
* ```ts
|
|
1525
|
+
* const prefab = await createSceneAsset("prefabs/enemy.prefab.json", enemyFile, []);
|
|
1526
|
+
* ```
|
|
1527
|
+
*
|
|
1528
|
+
* @public
|
|
1529
|
+
*/
|
|
1530
|
+
async function createSceneAsset(address, file, dependencies = []) {
|
|
1531
|
+
return {
|
|
1532
|
+
address,
|
|
1533
|
+
file,
|
|
1534
|
+
dependencies,
|
|
1535
|
+
hash: await computeSceneHash(file)
|
|
1536
|
+
};
|
|
1537
|
+
}
|
|
1538
|
+
/**
|
|
1539
|
+
* Finds the loaded scene asset an `instance.scene` reference names, among a scene's dependencies.
|
|
1540
|
+
*
|
|
1541
|
+
* @param asset - The scene whose `instance` entry is being expanded.
|
|
1542
|
+
* @param address - The address the reference carries.
|
|
1543
|
+
* @returns The dependency handle and its value, or `null` when nothing loaded stands at that
|
|
1544
|
+
* address.
|
|
1545
|
+
*
|
|
1546
|
+
* @internal
|
|
1547
|
+
*/
|
|
1548
|
+
function findSceneDependency(asset, address) {
|
|
1549
|
+
const dependencies = asset.dependencies;
|
|
1550
|
+
for (let index = 0; index < dependencies.length; index += 1) {
|
|
1551
|
+
const handle = dependencies[index];
|
|
1552
|
+
if (handle === void 0 || handle.address !== address || handle.state !== "loaded") continue;
|
|
1553
|
+
const value = handle.value;
|
|
1554
|
+
if (!isSceneAsset(value)) continue;
|
|
1555
|
+
return {
|
|
1556
|
+
handle,
|
|
1557
|
+
value
|
|
1558
|
+
};
|
|
1559
|
+
}
|
|
1560
|
+
return null;
|
|
1561
|
+
}
|
|
1562
|
+
/**
|
|
1563
|
+
* Reports whether a loaded asset value is a scene.
|
|
1564
|
+
*
|
|
1565
|
+
* @param value - The handle's value.
|
|
1566
|
+
* @returns `true` when the value carries a scene file and a hash.
|
|
1567
|
+
*
|
|
1568
|
+
* @internal
|
|
1569
|
+
*/
|
|
1570
|
+
function isSceneAsset(value) {
|
|
1571
|
+
if (typeof value !== "object" || value === null) return false;
|
|
1572
|
+
const file = Reflect.get(value, "file");
|
|
1573
|
+
return typeof Reflect.get(value, "hash") === "string" && typeof file === "object" && file !== null;
|
|
1574
|
+
}
|
|
1575
|
+
/** Lowercase hexadecimal digits, indexed by nibble. */
|
|
1576
|
+
const HEX_DIGITS = "0123456789abcdef";
|
|
1577
|
+
/**
|
|
1578
|
+
* Formats bytes as lowercase hexadecimal.
|
|
1579
|
+
*
|
|
1580
|
+
* @param bytes - The digest.
|
|
1581
|
+
* @returns The hex string.
|
|
1582
|
+
*/
|
|
1583
|
+
function toHex(bytes) {
|
|
1584
|
+
let text = "";
|
|
1585
|
+
for (let index = 0; index < bytes.length; index += 1) {
|
|
1586
|
+
const byte = bytes[index] ?? 0;
|
|
1587
|
+
text += (HEX_DIGITS[byte >> 4] ?? "0") + (HEX_DIGITS[byte & 15] ?? "0");
|
|
1588
|
+
}
|
|
1589
|
+
return text;
|
|
1590
|
+
}
|
|
1591
|
+
//#endregion
|
|
1592
|
+
//#region src/serialization/overrides.ts
|
|
1593
|
+
/** The entity fields the grammar accepts, as an `as const` table so the union derives from it. */
|
|
1594
|
+
const ENTITY_FIELDS = Object.freeze([
|
|
1595
|
+
"name",
|
|
1596
|
+
"active",
|
|
1597
|
+
"static",
|
|
1598
|
+
"layer",
|
|
1599
|
+
"tags"
|
|
1600
|
+
]);
|
|
1601
|
+
/** The transform channels the grammar accepts. */
|
|
1602
|
+
const TRANSFORM_CHANNELS = Object.freeze([
|
|
1603
|
+
"position",
|
|
1604
|
+
"rotation",
|
|
1605
|
+
"scale"
|
|
1606
|
+
]);
|
|
1607
|
+
/**
|
|
1608
|
+
* Parses an override path.
|
|
1609
|
+
*
|
|
1610
|
+
* @param path - The `path` string from the file.
|
|
1611
|
+
* @returns The parsed path.
|
|
1612
|
+
* @throws IgnifxError with code `IGX-0609` when the path does not match the grammar, or when a
|
|
1613
|
+
* property step is `__proto__`.
|
|
1614
|
+
*
|
|
1615
|
+
* @example
|
|
1616
|
+
* ```ts
|
|
1617
|
+
* parseOverridePath("01J…ROOT/components/01J…AI/props/aggression");
|
|
1618
|
+
* // { kind: "prop", entity: "01J…ROOT", component: "01J…AI", steps: ["aggression"] }
|
|
1619
|
+
* ```
|
|
1620
|
+
*
|
|
1621
|
+
* @public
|
|
1622
|
+
*/
|
|
1623
|
+
function parseOverridePath(path) {
|
|
1624
|
+
const segments = path.split("/");
|
|
1625
|
+
const entity = segments[0];
|
|
1626
|
+
if (entity === void 0 || entity === "") throw invalidPath(path, "an override path starts with the uid of an entity in the instanced file.");
|
|
1627
|
+
if (segments.length === 1) return {
|
|
1628
|
+
kind: "entity",
|
|
1629
|
+
entity
|
|
1630
|
+
};
|
|
1631
|
+
const second = segments[1] ?? "";
|
|
1632
|
+
if (segments.length === 2) {
|
|
1633
|
+
if (second === "components") return {
|
|
1634
|
+
kind: "componentList",
|
|
1635
|
+
entity
|
|
1636
|
+
};
|
|
1637
|
+
const field = ENTITY_FIELDS.find((candidate) => candidate === second);
|
|
1638
|
+
if (field !== void 0) return {
|
|
1639
|
+
kind: "entityField",
|
|
1640
|
+
entity,
|
|
1641
|
+
field
|
|
1642
|
+
};
|
|
1643
|
+
throw invalidPath(path, `"${second}" is not an entity property an override may patch.`);
|
|
1644
|
+
}
|
|
1645
|
+
if (second === "transform") {
|
|
1646
|
+
const channel = TRANSFORM_CHANNELS.find((candidate) => candidate === segments[2]);
|
|
1647
|
+
if (channel === void 0 || segments.length !== 3) throw invalidPath(path, "a transform override is <uid>/transform/position, /rotation, or /scale.");
|
|
1648
|
+
return {
|
|
1649
|
+
kind: "transform",
|
|
1650
|
+
entity,
|
|
1651
|
+
channel
|
|
1652
|
+
};
|
|
1653
|
+
}
|
|
1654
|
+
if (second !== "components") throw invalidPath(path, `"${second}" is not "components", "transform", or an entity property.`);
|
|
1655
|
+
const component = segments[2] ?? "";
|
|
1656
|
+
if (component === "") throw invalidPath(path, "a component override names the component's uid after /components/.");
|
|
1657
|
+
if (segments.length === 3) return {
|
|
1658
|
+
kind: "component",
|
|
1659
|
+
entity,
|
|
1660
|
+
component
|
|
1661
|
+
};
|
|
1662
|
+
const fourth = segments[3] ?? "";
|
|
1663
|
+
if (fourth === "enabled" && segments.length === 4) return {
|
|
1664
|
+
kind: "componentField",
|
|
1665
|
+
entity,
|
|
1666
|
+
component
|
|
1667
|
+
};
|
|
1668
|
+
if (fourth !== "props" || segments.length < 5) throw invalidPath(path, "a property override is <uid>/components/<uid>/props/<field>.");
|
|
1669
|
+
const steps = segments.slice(4);
|
|
1670
|
+
if (steps.includes("__proto__")) throw invalidPath(path, "\"__proto__\" is not a property name an override may address.");
|
|
1671
|
+
return {
|
|
1672
|
+
kind: "prop",
|
|
1673
|
+
entity,
|
|
1674
|
+
component,
|
|
1675
|
+
steps
|
|
1676
|
+
};
|
|
1677
|
+
}
|
|
1678
|
+
/**
|
|
1679
|
+
* The `op` an override declares, defaulting to `"replace"` as the format document's two-key
|
|
1680
|
+
* examples imply.
|
|
1681
|
+
*
|
|
1682
|
+
* @param override - The override entry.
|
|
1683
|
+
* @returns The operation.
|
|
1684
|
+
*
|
|
1685
|
+
* @internal
|
|
1686
|
+
*/
|
|
1687
|
+
function overrideOp(override) {
|
|
1688
|
+
return override.op ?? "replace";
|
|
1689
|
+
}
|
|
1690
|
+
/**
|
|
1691
|
+
* Applies every override to an expanded entity list, in order
|
|
1692
|
+
* (`docs/architecture/06-serialization-and-scene-format.md` §4 step 3).
|
|
1693
|
+
*
|
|
1694
|
+
* @remarks
|
|
1695
|
+
* The patches run on the *file* representation, before any entity exists, so `add`, `remove`, and
|
|
1696
|
+
* `replace` all reduce to editing plain JSON. Entities are addressed by the uid they carry in the
|
|
1697
|
+
* instanced file; `lookup` maps that uid to the entity object in the expanded list.
|
|
1698
|
+
*
|
|
1699
|
+
* @param overrides - The patches, in file order.
|
|
1700
|
+
* @param lookup - Source uid to the mutable entity record it expanded into.
|
|
1701
|
+
* @param report - Called for a patch that names something the instanced file does not contain.
|
|
1702
|
+
*
|
|
1703
|
+
* @internal
|
|
1704
|
+
*/
|
|
1705
|
+
function applyOverrides(overrides, lookup, report) {
|
|
1706
|
+
for (let index = 0; index < overrides.length; index += 1) {
|
|
1707
|
+
const override = overrides[index];
|
|
1708
|
+
if (override === void 0) continue;
|
|
1709
|
+
const parsed = parseOverridePath(override.path);
|
|
1710
|
+
const target = lookup.get(parsed.entity);
|
|
1711
|
+
if (target === void 0) {
|
|
1712
|
+
report(`the override path "${override.path}" names no entity of the instanced scene.`);
|
|
1713
|
+
continue;
|
|
1714
|
+
}
|
|
1715
|
+
applyOne(overrideOp(override), parsed, override, target, report);
|
|
1716
|
+
}
|
|
1717
|
+
}
|
|
1718
|
+
/**
|
|
1719
|
+
* Applies one parsed override.
|
|
1720
|
+
*
|
|
1721
|
+
* @param op - The operation.
|
|
1722
|
+
* @param parsed - The parsed path.
|
|
1723
|
+
* @param override - The raw entry, for its `value`.
|
|
1724
|
+
* @param target - The entity the path resolved to, with its component uid mapping.
|
|
1725
|
+
* @param report - Called when the patch cannot be applied.
|
|
1726
|
+
*/
|
|
1727
|
+
function applyOne(op, parsed, override, target, report) {
|
|
1728
|
+
const entity = target.data;
|
|
1729
|
+
switch (parsed.kind) {
|
|
1730
|
+
case "entity":
|
|
1731
|
+
report(`"${override.path}" addresses a whole entity; overrides patch properties and components.`);
|
|
1732
|
+
return;
|
|
1733
|
+
case "entityField":
|
|
1734
|
+
applyEntityField(parsed.field, override.value ?? null, entity);
|
|
1735
|
+
return;
|
|
1736
|
+
case "transform": {
|
|
1737
|
+
const numbers = asJsonArray(override.value);
|
|
1738
|
+
if (numbers === null) {
|
|
1739
|
+
report(`"${override.path}" needs an array of numbers.`);
|
|
1740
|
+
return;
|
|
1741
|
+
}
|
|
1742
|
+
entity.transform[parsed.channel] = numberArray(numbers);
|
|
1743
|
+
return;
|
|
1744
|
+
}
|
|
1745
|
+
case "componentList": {
|
|
1746
|
+
if (op !== "add") {
|
|
1747
|
+
report(`"${override.path}" is only valid with { "op": "add" }.`);
|
|
1748
|
+
return;
|
|
1749
|
+
}
|
|
1750
|
+
const added = asComponentEntry(override.value);
|
|
1751
|
+
if (added === null) {
|
|
1752
|
+
report(`"${override.path}" needs a component object with a uid and a type.`);
|
|
1753
|
+
return;
|
|
1754
|
+
}
|
|
1755
|
+
entity.components.push(added);
|
|
1756
|
+
return;
|
|
1757
|
+
}
|
|
1758
|
+
case "component": {
|
|
1759
|
+
if (op !== "remove") {
|
|
1760
|
+
report(`"${override.path}" addresses a whole component; only { "op": "remove" } may patch it.`);
|
|
1761
|
+
return;
|
|
1762
|
+
}
|
|
1763
|
+
const at = indexOfComponent(entity, resolve(target, parsed.component));
|
|
1764
|
+
if (at < 0) {
|
|
1765
|
+
report(`"${override.path}" names no component of that entity.`);
|
|
1766
|
+
return;
|
|
1767
|
+
}
|
|
1768
|
+
entity.components.splice(at, 1);
|
|
1769
|
+
return;
|
|
1770
|
+
}
|
|
1771
|
+
case "componentField": {
|
|
1772
|
+
const uid = resolve(target, parsed.component);
|
|
1773
|
+
const component = componentOf(entity, uid);
|
|
1774
|
+
if (component === null) {
|
|
1775
|
+
report(`"${override.path}" names no component of that entity.`);
|
|
1776
|
+
return;
|
|
1777
|
+
}
|
|
1778
|
+
replaceComponent(entity, uid, {
|
|
1779
|
+
...component,
|
|
1780
|
+
enabled: override.value === true
|
|
1781
|
+
});
|
|
1782
|
+
return;
|
|
1783
|
+
}
|
|
1784
|
+
case "prop": {
|
|
1785
|
+
const uid = resolve(target, parsed.component);
|
|
1786
|
+
const component = componentOf(entity, uid);
|
|
1787
|
+
if (component === null) {
|
|
1788
|
+
report(`"${override.path}" names no component of that entity.`);
|
|
1789
|
+
return;
|
|
1790
|
+
}
|
|
1791
|
+
const props = writeStep(component.props ?? {}, parsed.steps, 0, op, override.value ?? null, override.path, report);
|
|
1792
|
+
replaceComponent(entity, uid, {
|
|
1793
|
+
...component,
|
|
1794
|
+
props
|
|
1795
|
+
});
|
|
1796
|
+
return;
|
|
1797
|
+
}
|
|
1798
|
+
default: return;
|
|
1799
|
+
}
|
|
1800
|
+
}
|
|
1801
|
+
/**
|
|
1802
|
+
* Patches one plain entity property.
|
|
1803
|
+
*
|
|
1804
|
+
* @param field - Which property.
|
|
1805
|
+
* @param value - The new JSON value.
|
|
1806
|
+
* @param entity - The entity to patch.
|
|
1807
|
+
*/
|
|
1808
|
+
function applyEntityField(field, value, entity) {
|
|
1809
|
+
switch (field) {
|
|
1810
|
+
case "name":
|
|
1811
|
+
entity.name = typeof value === "string" ? value : entity.name;
|
|
1812
|
+
return;
|
|
1813
|
+
case "active":
|
|
1814
|
+
entity.active = value === true;
|
|
1815
|
+
return;
|
|
1816
|
+
case "static":
|
|
1817
|
+
entity.static = value === true;
|
|
1818
|
+
return;
|
|
1819
|
+
case "layer":
|
|
1820
|
+
if (typeof value === "string") entity.layer = value;
|
|
1821
|
+
return;
|
|
1822
|
+
case "tags": {
|
|
1823
|
+
const list = asJsonArray(value);
|
|
1824
|
+
if (list !== null) entity.tags = list.filter((tag) => typeof tag === "string");
|
|
1825
|
+
return;
|
|
1826
|
+
}
|
|
1827
|
+
default: return;
|
|
1828
|
+
}
|
|
1829
|
+
}
|
|
1830
|
+
/**
|
|
1831
|
+
* Writes one step of a `props/<field>[/<key>…]` path, rebuilding the containers on the way so the
|
|
1832
|
+
* instanced file's own JSON is never mutated (two instances of one prefab must not share objects).
|
|
1833
|
+
*
|
|
1834
|
+
* @param container - The object or array being descended into.
|
|
1835
|
+
* @param steps - The remaining path segments.
|
|
1836
|
+
* @param at - The index of the segment to apply.
|
|
1837
|
+
* @param op - The operation.
|
|
1838
|
+
* @param value - The new value.
|
|
1839
|
+
* @param path - The whole path, for diagnostics.
|
|
1840
|
+
* @param report - Called when the step cannot be applied.
|
|
1841
|
+
* @returns The rebuilt container.
|
|
1842
|
+
*/
|
|
1843
|
+
function writeStep(container, steps, at, op, value, path, report) {
|
|
1844
|
+
const key = steps[at];
|
|
1845
|
+
if (key === void 0) return container;
|
|
1846
|
+
const copy = { ...container };
|
|
1847
|
+
if (at === steps.length - 1) {
|
|
1848
|
+
if (op === "remove") {
|
|
1849
|
+
const { [key]: _removed, ...rest } = copy;
|
|
1850
|
+
return rest;
|
|
1851
|
+
}
|
|
1852
|
+
setOwnJsonProperty(copy, key, value);
|
|
1853
|
+
return copy;
|
|
1854
|
+
}
|
|
1855
|
+
const next = Object.hasOwn(copy, key) ? copy[key] : void 0;
|
|
1856
|
+
const nextArray = asJsonArray(next);
|
|
1857
|
+
if (nextArray !== null) {
|
|
1858
|
+
setOwnJsonProperty(copy, key, writeArrayStep(nextArray, steps, at + 1, op, value, path, report));
|
|
1859
|
+
return copy;
|
|
1860
|
+
}
|
|
1861
|
+
const nextObject = asJsonObject(next);
|
|
1862
|
+
if (nextObject !== null) {
|
|
1863
|
+
setOwnJsonProperty(copy, key, writeStep(nextObject, steps, at + 1, op, value, path, report));
|
|
1864
|
+
return copy;
|
|
1865
|
+
}
|
|
1866
|
+
report(`"${path}" descends into ${key}, which is not an object or an array.`);
|
|
1867
|
+
return container;
|
|
1868
|
+
}
|
|
1869
|
+
/**
|
|
1870
|
+
* The array form of {@link writeStep}.
|
|
1871
|
+
*
|
|
1872
|
+
* @param container - The array being descended into.
|
|
1873
|
+
* @param steps - The remaining path segments.
|
|
1874
|
+
* @param at - The index of the segment to apply.
|
|
1875
|
+
* @param op - The operation.
|
|
1876
|
+
* @param value - The new value.
|
|
1877
|
+
* @param path - The whole path, for diagnostics.
|
|
1878
|
+
* @param report - Called when the step cannot be applied.
|
|
1879
|
+
* @returns The rebuilt array.
|
|
1880
|
+
*/
|
|
1881
|
+
function writeArrayStep(container, steps, at, op, value, path, report) {
|
|
1882
|
+
const key = steps[at];
|
|
1883
|
+
if (key === void 0) return container;
|
|
1884
|
+
const index = Number.parseInt(key, 10);
|
|
1885
|
+
if (!Number.isInteger(index) || index < 0) {
|
|
1886
|
+
report(`"${path}" indexes an array with "${key}", which is not a whole number.`);
|
|
1887
|
+
return container;
|
|
1888
|
+
}
|
|
1889
|
+
const copy = [...container];
|
|
1890
|
+
if (at === steps.length - 1) {
|
|
1891
|
+
if (op === "remove") {
|
|
1892
|
+
copy.splice(index, 1);
|
|
1893
|
+
return copy;
|
|
1894
|
+
}
|
|
1895
|
+
if (op === "add") {
|
|
1896
|
+
copy.splice(index, 0, value);
|
|
1897
|
+
return copy;
|
|
1898
|
+
}
|
|
1899
|
+
copy[index] = value;
|
|
1900
|
+
return copy;
|
|
1901
|
+
}
|
|
1902
|
+
const next = copy[index];
|
|
1903
|
+
const nextArray = asJsonArray(next);
|
|
1904
|
+
if (nextArray !== null) {
|
|
1905
|
+
copy[index] = writeArrayStep(nextArray, steps, at + 1, op, value, path, report);
|
|
1906
|
+
return copy;
|
|
1907
|
+
}
|
|
1908
|
+
const nextObject = asJsonObject(next);
|
|
1909
|
+
if (nextObject !== null) {
|
|
1910
|
+
copy[index] = writeStep(nextObject, steps, at + 1, op, value, path, report);
|
|
1911
|
+
return copy;
|
|
1912
|
+
}
|
|
1913
|
+
report(`"${path}" descends into [${key}], which is not an object or an array.`);
|
|
1914
|
+
return container;
|
|
1915
|
+
}
|
|
1916
|
+
/**
|
|
1917
|
+
* Resolves the uid an override path names — a uid of the instanced file — to the uid this copy of
|
|
1918
|
+
* the prefab gave the same component.
|
|
1919
|
+
*
|
|
1920
|
+
* @param target - The entity the path resolved to.
|
|
1921
|
+
* @param sourceUid - The uid the path names.
|
|
1922
|
+
* @returns This copy's uid, or the name itself when the mapping does not know it.
|
|
1923
|
+
*/
|
|
1924
|
+
function resolve(target, sourceUid) {
|
|
1925
|
+
return target.components.get(sourceUid) ?? sourceUid;
|
|
1926
|
+
}
|
|
1927
|
+
/**
|
|
1928
|
+
* Finds a component of an entity by uid.
|
|
1929
|
+
*
|
|
1930
|
+
* @param entity - The entity.
|
|
1931
|
+
* @param uid - The component uid.
|
|
1932
|
+
* @returns Its index, or `-1`.
|
|
1933
|
+
*/
|
|
1934
|
+
function indexOfComponent(entity, uid) {
|
|
1935
|
+
for (let index = 0; index < entity.components.length; index += 1) if (entity.components[index]?.uid === uid) return index;
|
|
1936
|
+
return -1;
|
|
1937
|
+
}
|
|
1938
|
+
/**
|
|
1939
|
+
* Reads a component of an entity by uid.
|
|
1940
|
+
*
|
|
1941
|
+
* @param entity - The entity.
|
|
1942
|
+
* @param uid - The component uid.
|
|
1943
|
+
* @returns The component, or `null`.
|
|
1944
|
+
*/
|
|
1945
|
+
function componentOf(entity, uid) {
|
|
1946
|
+
const at = indexOfComponent(entity, uid);
|
|
1947
|
+
return at < 0 ? null : entity.components[at] ?? null;
|
|
1948
|
+
}
|
|
1949
|
+
/**
|
|
1950
|
+
* Replaces a component entry in place, keeping its position in the list.
|
|
1951
|
+
*
|
|
1952
|
+
* @param entity - The entity.
|
|
1953
|
+
* @param uid - The component uid.
|
|
1954
|
+
* @param replacement - The new entry.
|
|
1955
|
+
*/
|
|
1956
|
+
function replaceComponent(entity, uid, replacement) {
|
|
1957
|
+
const at = indexOfComponent(entity, uid);
|
|
1958
|
+
if (at >= 0) entity.components[at] = replacement;
|
|
1959
|
+
}
|
|
1960
|
+
/**
|
|
1961
|
+
* Reads a JSON value as a component entry.
|
|
1962
|
+
*
|
|
1963
|
+
* @param value - The candidate.
|
|
1964
|
+
* @returns The entry, or `null` when it carries no string `uid` and `type`.
|
|
1965
|
+
*/
|
|
1966
|
+
function asComponentEntry(value) {
|
|
1967
|
+
const object = asJsonObject(value);
|
|
1968
|
+
if (object === null || typeof object["uid"] !== "string" || typeof object["type"] !== "string") return null;
|
|
1969
|
+
const enabled = object["enabled"];
|
|
1970
|
+
const version = object["schemaVersion"];
|
|
1971
|
+
return {
|
|
1972
|
+
uid: object["uid"],
|
|
1973
|
+
type: object["type"],
|
|
1974
|
+
...typeof enabled === "boolean" ? { enabled } : {},
|
|
1975
|
+
...typeof version === "number" ? { schemaVersion: version } : {},
|
|
1976
|
+
...asJsonObject(object["props"]) === null ? {} : { props: asJsonObject(object["props"]) ?? {} }
|
|
1977
|
+
};
|
|
1978
|
+
}
|
|
1979
|
+
/**
|
|
1980
|
+
* Coerces a JSON array to numbers, dropping anything else.
|
|
1981
|
+
*
|
|
1982
|
+
* @param value - The JSON array.
|
|
1983
|
+
* @returns The numbers it holds.
|
|
1984
|
+
*/
|
|
1985
|
+
function numberArray(value) {
|
|
1986
|
+
const numbers = [];
|
|
1987
|
+
for (let index = 0; index < value.length; index += 1) {
|
|
1988
|
+
const entry = value[index];
|
|
1989
|
+
if (typeof entry === "number" && Number.isFinite(entry)) numbers.push(entry);
|
|
1990
|
+
}
|
|
1991
|
+
return numbers;
|
|
1992
|
+
}
|
|
1993
|
+
/**
|
|
1994
|
+
* Builds the `IGX-0609` error.
|
|
1995
|
+
*
|
|
1996
|
+
* @param path - The offending path.
|
|
1997
|
+
* @param reason - What the grammar expected.
|
|
1998
|
+
* @returns The error to throw.
|
|
1999
|
+
*/
|
|
2000
|
+
function invalidPath(path, reason) {
|
|
2001
|
+
return new IgnifxError(CoreErrorCode.invalidOverridePath, `${path} is not a valid override path: ${reason}`, {
|
|
2002
|
+
context: { path },
|
|
2003
|
+
hint: "Override paths read \"<entityUid>/components/<componentUid>/props/<field>\"."
|
|
2004
|
+
});
|
|
2005
|
+
}
|
|
2006
|
+
//#endregion
|
|
2007
|
+
//#region src/serialization/prefab-overrides.ts
|
|
2008
|
+
/**
|
|
2009
|
+
* Writes an instance's overrides into the prefab file it instances, so every instance of the prefab
|
|
2010
|
+
* gets them — Unity's "Apply to prefab" (ADR-0005).
|
|
2011
|
+
*
|
|
2012
|
+
* @remarks
|
|
2013
|
+
* A pure function over the two files: nothing is loaded, and the same input always gives
|
|
2014
|
+
* byte-identical output through {@link stringifySceneFile}. The rules:
|
|
2015
|
+
*
|
|
2016
|
+
* - Property, `enabled`, transform, and entity-field overrides change the prefab's record. An `add`
|
|
2017
|
+
* appends the component, keeping its uid; a `remove` deletes the component.
|
|
2018
|
+
* - On a prefab with exactly one root, the instance root's own `name`, `transform`, and other entity
|
|
2019
|
+
* fields are its placement, not prefab content, so overrides of the root's entity fields and
|
|
2020
|
+
* transform are skipped.
|
|
2021
|
+
* - Overrides reach only the prefab's own entities. Content of a scene the prefab itself instances
|
|
2022
|
+
* is not addressable by an override path, so a nested prefab is never edited: an override that
|
|
2023
|
+
* names something the prefab file does not hold is skipped.
|
|
2024
|
+
* - An override is skipped when an earlier override that stays on the instance overlaps its path, so
|
|
2025
|
+
* the instance keeps the value it had.
|
|
2026
|
+
* - A skipped override stays on the returned instance.
|
|
2027
|
+
* - The instance root's own components are not overrides. Pass them as
|
|
2028
|
+
* {@link PrefabApplyOptions.rootComponents} to apply them too: on a prefab with exactly one root
|
|
2029
|
+
* each selected one is appended to that root, keeping its uid, and reported in
|
|
2030
|
+
* {@link PrefabApplyResult.appliedComponents}; one whose uid the prefab already uses, or any when
|
|
2031
|
+
* the prefab has several roots, is skipped.
|
|
2032
|
+
* - Other instances of the prefab keep their overrides, which still win over the new prefab values
|
|
2033
|
+
* at the same path. Record {@link PrefabApplyResult.hash} on them, or loading them logs `IGX-0604`.
|
|
2034
|
+
* - References inside added components (`$entity`, `$component`) are copied unchanged.
|
|
2035
|
+
* - A component an apply moved into the prefab gets a fresh uid per instance from then on, like every
|
|
2036
|
+
* prefab component; a scene reference to it uses the instance form
|
|
2037
|
+
* `{ "$component": "<instanceRootUid>/<componentUid>" }`.
|
|
2038
|
+
*
|
|
2039
|
+
* @param instance - The instance entry whose overrides to apply; its `scene` should name `asset`.
|
|
2040
|
+
* @param asset - The prefab file the entry instances.
|
|
2041
|
+
* @param selection - Which overrides to apply, all of them by default, and the instance root's own
|
|
2042
|
+
* components to apply with them.
|
|
2043
|
+
* @returns The new prefab file and its hash, the instance entry without the applied overrides, and
|
|
2044
|
+
* what was applied or skipped.
|
|
2045
|
+
* @throws IgnifxError with code `IGX-0609` when a selected override path is outside the grammar.
|
|
2046
|
+
*
|
|
2047
|
+
* @example
|
|
2048
|
+
* ```ts
|
|
2049
|
+
* const result = await applyOverridesToAsset(spawn.instance, prefabFile, { rootComponents: spawn.components });
|
|
2050
|
+
* await app.storage.write("prefabs/enemy.prefab.json", stringifySceneFile(result.asset));
|
|
2051
|
+
* ```
|
|
2052
|
+
*
|
|
2053
|
+
* @public
|
|
2054
|
+
*/
|
|
2055
|
+
async function applyOverridesToAsset(instance, asset, selection) {
|
|
2056
|
+
const overrides = instance.overrides ?? [];
|
|
2057
|
+
const records = /* @__PURE__ */ new Map();
|
|
2058
|
+
const lookup = /* @__PURE__ */ new Map();
|
|
2059
|
+
const uids = /* @__PURE__ */ new Set();
|
|
2060
|
+
for (const entity of asset.entities) {
|
|
2061
|
+
const data = mutableEntity(entity);
|
|
2062
|
+
records.set(entity.uid, data);
|
|
2063
|
+
lookup.set(entity.uid, {
|
|
2064
|
+
data,
|
|
2065
|
+
components: /* @__PURE__ */ new Map()
|
|
2066
|
+
});
|
|
2067
|
+
uids.add(entity.uid);
|
|
2068
|
+
for (const component of entity.components ?? []) uids.add(component.uid);
|
|
2069
|
+
}
|
|
2070
|
+
const singleRootUid = singleRootOf(asset);
|
|
2071
|
+
const touched = /* @__PURE__ */ new Set();
|
|
2072
|
+
const own = applyRootComponents(selection, singleRootUid, records, uids, touched);
|
|
2073
|
+
const applied = [];
|
|
2074
|
+
const skipped = [];
|
|
2075
|
+
const remaining = [];
|
|
2076
|
+
for (const override of overrides) {
|
|
2077
|
+
if (!isSelected(override, selection)) {
|
|
2078
|
+
remaining.push(override);
|
|
2079
|
+
continue;
|
|
2080
|
+
}
|
|
2081
|
+
const parsed = parseOverridePath(override.path);
|
|
2082
|
+
let reason = precheck(override, parsed, singleRootUid, uids) ?? shadowedBy(override, remaining);
|
|
2083
|
+
if (reason === null) applyOverrides([override], lookup, (message) => {
|
|
2084
|
+
reason ??= message;
|
|
2085
|
+
});
|
|
2086
|
+
if (reason !== null) {
|
|
2087
|
+
skipped.push({
|
|
2088
|
+
override,
|
|
2089
|
+
reason
|
|
2090
|
+
});
|
|
2091
|
+
remaining.push(override);
|
|
2092
|
+
continue;
|
|
2093
|
+
}
|
|
2094
|
+
touched.add(parsed.entity);
|
|
2095
|
+
const added = addedComponentUid(override);
|
|
2096
|
+
if (added !== null) uids.add(added);
|
|
2097
|
+
applied.push(override);
|
|
2098
|
+
}
|
|
2099
|
+
const next = touched.size === 0 ? asset : {
|
|
2100
|
+
...asset,
|
|
2101
|
+
entities: asset.entities.map((entity) => {
|
|
2102
|
+
const data = records.get(entity.uid);
|
|
2103
|
+
return data === void 0 || !touched.has(entity.uid) ? entity : canonicalEntity(data);
|
|
2104
|
+
})
|
|
2105
|
+
};
|
|
2106
|
+
const hash = await computeSceneHash(next);
|
|
2107
|
+
return {
|
|
2108
|
+
asset: next,
|
|
2109
|
+
hash,
|
|
2110
|
+
instance: withOverrides(instance, remaining, hash),
|
|
2111
|
+
applied,
|
|
2112
|
+
skipped,
|
|
2113
|
+
appliedComponents: own.applied,
|
|
2114
|
+
rootComponents: own.kept,
|
|
2115
|
+
skippedComponents: own.skipped
|
|
2116
|
+
};
|
|
2117
|
+
}
|
|
2118
|
+
/**
|
|
2119
|
+
* Appends the selected components of the instance root to the prefab's single root.
|
|
2120
|
+
*
|
|
2121
|
+
* @param options - The apply options, holding the components and the selection.
|
|
2122
|
+
* @param singleRootUid - The prefab's only root, or `null`.
|
|
2123
|
+
* @param records - The prefab's mutable records, by uid.
|
|
2124
|
+
* @param uids - Every uid the prefab uses; the appended components are added.
|
|
2125
|
+
* @param touched - Filled with the root's uid when anything was appended.
|
|
2126
|
+
* @returns What was applied, what stays on the instance root, and why the skipped ones were.
|
|
2127
|
+
*/
|
|
2128
|
+
function applyRootComponents(options, singleRootUid, records, uids, touched) {
|
|
2129
|
+
const applied = [];
|
|
2130
|
+
const kept = [];
|
|
2131
|
+
const skipped = [];
|
|
2132
|
+
const root = singleRootUid === null ? void 0 : records.get(singleRootUid);
|
|
2133
|
+
for (const component of options?.rootComponents ?? []) {
|
|
2134
|
+
if (!(singleRootUid === null ? options?.paths === void 0 : isPathSelected(`${singleRootUid}/components/${component.uid}`, options))) {
|
|
2135
|
+
kept.push(component);
|
|
2136
|
+
continue;
|
|
2137
|
+
}
|
|
2138
|
+
const reason = root === void 0 ? `The prefab has no single root, so component ${component.uid} of the instance root has nowhere to go.` : uids.has(component.uid) ? `Component ${component.uid} of the instance root has a uid the prefab file already uses.` : null;
|
|
2139
|
+
if (root === void 0 || reason !== null) {
|
|
2140
|
+
skipped.push({
|
|
2141
|
+
component,
|
|
2142
|
+
reason: reason ?? ""
|
|
2143
|
+
});
|
|
2144
|
+
kept.push(component);
|
|
2145
|
+
continue;
|
|
2146
|
+
}
|
|
2147
|
+
root.components.push(component);
|
|
2148
|
+
uids.add(component.uid);
|
|
2149
|
+
touched.add(root.uid);
|
|
2150
|
+
applied.push(component);
|
|
2151
|
+
}
|
|
2152
|
+
return {
|
|
2153
|
+
applied,
|
|
2154
|
+
kept,
|
|
2155
|
+
skipped
|
|
2156
|
+
};
|
|
2157
|
+
}
|
|
2158
|
+
/**
|
|
2159
|
+
* Drops an instance's overrides so it follows its prefab again — Unity's "Revert".
|
|
2160
|
+
*
|
|
2161
|
+
* @remarks
|
|
2162
|
+
* A pure function: the entry's `scene` and `hash` are kept, and `overrides` is omitted when none
|
|
2163
|
+
* remain. Reverting an `add` also reverts the overrides below the added component when the
|
|
2164
|
+
* selection path covers them (`<entityUid>/components/<addedUid>` does).
|
|
2165
|
+
*
|
|
2166
|
+
* @param instance - The instance entry.
|
|
2167
|
+
* @param selection - Which overrides to drop; all of them by default.
|
|
2168
|
+
* @returns The entry without the selected overrides, or `instance` itself when none was selected.
|
|
2169
|
+
*
|
|
2170
|
+
* @example
|
|
2171
|
+
* ```ts
|
|
2172
|
+
* const reverted = revertOverrides(spawn.instance, { paths: [`${rootUid}/components/${aiUid}`] });
|
|
2173
|
+
* ```
|
|
2174
|
+
*
|
|
2175
|
+
* @public
|
|
2176
|
+
*/
|
|
2177
|
+
function revertOverrides(instance, selection) {
|
|
2178
|
+
const overrides = instance.overrides ?? [];
|
|
2179
|
+
const remaining = overrides.filter((override) => !isSelected(override, selection));
|
|
2180
|
+
if (remaining.length === overrides.length) return instance;
|
|
2181
|
+
return withOverrides(instance, remaining, instance.hash);
|
|
2182
|
+
}
|
|
2183
|
+
/**
|
|
2184
|
+
* Whether a selection covers an override.
|
|
2185
|
+
*
|
|
2186
|
+
* @param override - The override.
|
|
2187
|
+
* @param selection - The selection; absent or without `paths`, everything.
|
|
2188
|
+
* @returns `true` when the override's target is a selected path or lies below one.
|
|
2189
|
+
*/
|
|
2190
|
+
function isSelected(override, selection) {
|
|
2191
|
+
return isPathSelected(targetPath(override), selection);
|
|
2192
|
+
}
|
|
2193
|
+
/**
|
|
2194
|
+
* Whether a selection covers a target path.
|
|
2195
|
+
*
|
|
2196
|
+
* @param target - The path acted on.
|
|
2197
|
+
* @param selection - The selection; absent or without `paths`, everything.
|
|
2198
|
+
* @returns `true` when the target is a selected path or lies below one.
|
|
2199
|
+
*/
|
|
2200
|
+
function isPathSelected(target, selection) {
|
|
2201
|
+
const paths = selection?.paths;
|
|
2202
|
+
if (paths === void 0) return true;
|
|
2203
|
+
return paths.some((path) => target === path || target.startsWith(`${path}/`));
|
|
2204
|
+
}
|
|
2205
|
+
/**
|
|
2206
|
+
* The path an override acts on: its own path, or for an `add` to a component list the path of the
|
|
2207
|
+
* component it adds, so a selection can name one added component.
|
|
2208
|
+
*
|
|
2209
|
+
* @param override - The override.
|
|
2210
|
+
* @returns The path.
|
|
2211
|
+
*/
|
|
2212
|
+
function targetPath(override) {
|
|
2213
|
+
const added = addedComponentUid(override);
|
|
2214
|
+
return added === null ? override.path : `${override.path}/${added}`;
|
|
2215
|
+
}
|
|
2216
|
+
/**
|
|
2217
|
+
* The uid of the component an `add` override appends to a component list.
|
|
2218
|
+
*
|
|
2219
|
+
* @param override - The override.
|
|
2220
|
+
* @returns The uid, or `null` when the override is not such an `add` or names no uid.
|
|
2221
|
+
*/
|
|
2222
|
+
function addedComponentUid(override) {
|
|
2223
|
+
if (overrideOp(override) !== "add") return null;
|
|
2224
|
+
const segments = override.path.split("/");
|
|
2225
|
+
if (segments.length !== 2 || segments[1] !== "components") return null;
|
|
2226
|
+
const uid = asJsonObject(override.value)?.["uid"];
|
|
2227
|
+
return typeof uid === "string" ? uid : null;
|
|
2228
|
+
}
|
|
2229
|
+
/**
|
|
2230
|
+
* Checks what the override patcher itself accepts silently but a prefab file must not take.
|
|
2231
|
+
*
|
|
2232
|
+
* @param override - The override.
|
|
2233
|
+
* @param parsed - Its parsed path.
|
|
2234
|
+
* @param singleRootUid - The prefab's only root, or `null`.
|
|
2235
|
+
* @param uids - Every uid the prefab file already uses.
|
|
2236
|
+
* @returns Why the override cannot be applied, or `null`.
|
|
2237
|
+
*/
|
|
2238
|
+
function precheck(override, parsed, singleRootUid, uids) {
|
|
2239
|
+
if (parsed.entity === singleRootUid && (parsed.kind === "entityField" || parsed.kind === "transform")) return `"${override.path}" sets the instance root's own ${parsed.kind === "transform" ? "transform" : parsed.field}, which is its placement, not prefab content.`;
|
|
2240
|
+
if (parsed.kind === "transform") {
|
|
2241
|
+
const numbers = asJsonArray(override.value);
|
|
2242
|
+
const length = parsed.channel === "rotation" ? 4 : 3;
|
|
2243
|
+
if (numbers === null || numbers.length !== length || !numbers.every((entry) => typeof entry === "number" && Number.isFinite(entry))) return `"${override.path}" needs ${String(length)} finite numbers.`;
|
|
2244
|
+
}
|
|
2245
|
+
const added = addedComponentUid(override);
|
|
2246
|
+
if (added !== null && uids.has(added)) return `"${override.path}" adds component ${added}, a uid the prefab file already uses.`;
|
|
2247
|
+
return null;
|
|
2248
|
+
}
|
|
2249
|
+
/**
|
|
2250
|
+
* Why an override must stay on the instance: an earlier override that stays there overlaps it, and
|
|
2251
|
+
* once baked into the prefab the applied one would run first and lose to it.
|
|
2252
|
+
*
|
|
2253
|
+
* @param override - The selected override.
|
|
2254
|
+
* @param remaining - The earlier overrides that stay on the instance.
|
|
2255
|
+
* @returns Why the override cannot be applied, or `null`.
|
|
2256
|
+
*/
|
|
2257
|
+
function shadowedBy(override, remaining) {
|
|
2258
|
+
const key = overlapKey(override);
|
|
2259
|
+
const earlier = remaining.find((candidate) => {
|
|
2260
|
+
const other = overlapKey(candidate);
|
|
2261
|
+
return addedComponentUid(candidate) === null && (key === other || key.startsWith(`${other}/`) || other.startsWith(`${key}/`));
|
|
2262
|
+
});
|
|
2263
|
+
return earlier === void 0 ? null : `"${override.path}" follows "${earlier.path}", which stays on the instance and overlaps it.`;
|
|
2264
|
+
}
|
|
2265
|
+
/**
|
|
2266
|
+
* The part of an override's path that decides overlap: cut at the prop field, so array index shifts
|
|
2267
|
+
* inside one field count.
|
|
2268
|
+
*
|
|
2269
|
+
* @param override - The override.
|
|
2270
|
+
* @returns The key.
|
|
2271
|
+
*/
|
|
2272
|
+
function overlapKey(override) {
|
|
2273
|
+
return override.path.split("/").slice(0, 5).join("/");
|
|
2274
|
+
}
|
|
2275
|
+
/**
|
|
2276
|
+
* The uid of a scene file's only root.
|
|
2277
|
+
*
|
|
2278
|
+
* @param file - The file.
|
|
2279
|
+
* @returns The uid, or `null` when the file has no root or several.
|
|
2280
|
+
*/
|
|
2281
|
+
function singleRootOf(file) {
|
|
2282
|
+
const roots = file.entities.filter((entity) => entity.parent === null);
|
|
2283
|
+
return roots.length === 1 ? roots[0]?.uid ?? null : null;
|
|
2284
|
+
}
|
|
2285
|
+
/**
|
|
2286
|
+
* Copies a file record into the mutable shape the override patcher edits.
|
|
2287
|
+
*
|
|
2288
|
+
* @param entity - The record.
|
|
2289
|
+
* @returns A copy that shares nothing the patcher mutates.
|
|
2290
|
+
*/
|
|
2291
|
+
function mutableEntity(entity) {
|
|
2292
|
+
return {
|
|
2293
|
+
uid: entity.uid,
|
|
2294
|
+
name: entity.name,
|
|
2295
|
+
parent: entity.parent,
|
|
2296
|
+
...entity.active === void 0 ? {} : { active: entity.active },
|
|
2297
|
+
...entity.static === void 0 ? {} : { static: entity.static },
|
|
2298
|
+
...entity.layer === void 0 ? {} : { layer: entity.layer },
|
|
2299
|
+
...entity.tags === void 0 ? {} : { tags: [...entity.tags] },
|
|
2300
|
+
transform: {
|
|
2301
|
+
position: [...entity.transform.position],
|
|
2302
|
+
rotation: [...entity.transform.rotation],
|
|
2303
|
+
scale: [...entity.transform.scale]
|
|
2304
|
+
},
|
|
2305
|
+
...entity.instance === void 0 ? {} : { instance: entity.instance },
|
|
2306
|
+
components: [...entity.components ?? []]
|
|
2307
|
+
};
|
|
2308
|
+
}
|
|
2309
|
+
/**
|
|
2310
|
+
* Writes a patched record back in the serializer's canonical form: its key order, defaults omitted,
|
|
2311
|
+
* tags sorted and unique, numbers canonicalized.
|
|
2312
|
+
*
|
|
2313
|
+
* @param data - The patched record.
|
|
2314
|
+
* @returns The file record.
|
|
2315
|
+
*/
|
|
2316
|
+
function canonicalEntity(data) {
|
|
2317
|
+
const tags = [...new Set(data.tags ?? [])].toSorted();
|
|
2318
|
+
return {
|
|
2319
|
+
uid: data.uid,
|
|
2320
|
+
name: data.name,
|
|
2321
|
+
parent: data.parent,
|
|
2322
|
+
...data.active === false ? { active: false } : {},
|
|
2323
|
+
...data.static === true ? { static: true } : {},
|
|
2324
|
+
...data.layer === void 0 || data.layer === "Default" ? {} : { layer: data.layer },
|
|
2325
|
+
...tags.length === 0 ? {} : { tags },
|
|
2326
|
+
transform: {
|
|
2327
|
+
position: triple(data.transform.position),
|
|
2328
|
+
rotation: [
|
|
2329
|
+
canonicalNumberAt(data.transform.rotation, 0),
|
|
2330
|
+
canonicalNumberAt(data.transform.rotation, 1),
|
|
2331
|
+
canonicalNumberAt(data.transform.rotation, 2),
|
|
2332
|
+
canonicalNumberAt(data.transform.rotation, 3)
|
|
2333
|
+
],
|
|
2334
|
+
scale: triple(data.transform.scale)
|
|
2335
|
+
},
|
|
2336
|
+
...data.instance === void 0 ? {} : { instance: data.instance },
|
|
2337
|
+
...data.components.length === 0 ? {} : { components: data.components.map(canonicalComponent) }
|
|
2338
|
+
};
|
|
2339
|
+
}
|
|
2340
|
+
/**
|
|
2341
|
+
* Writes a component record in the serializer's key order, `enabled` omitted when `true`.
|
|
2342
|
+
*
|
|
2343
|
+
* @param component - The record.
|
|
2344
|
+
* @returns The canonical record.
|
|
2345
|
+
*/
|
|
2346
|
+
function canonicalComponent(component) {
|
|
2347
|
+
return {
|
|
2348
|
+
uid: component.uid,
|
|
2349
|
+
type: component.type,
|
|
2350
|
+
...component.enabled === false ? { enabled: false } : {},
|
|
2351
|
+
...component.schemaVersion === void 0 ? {} : { schemaVersion: component.schemaVersion },
|
|
2352
|
+
...component.props === void 0 ? {} : { props: component.props }
|
|
2353
|
+
};
|
|
2354
|
+
}
|
|
2355
|
+
/**
|
|
2356
|
+
* Reads a three-number transform channel.
|
|
2357
|
+
*
|
|
2358
|
+
* @param values - The channel.
|
|
2359
|
+
* @returns The canonical triple.
|
|
2360
|
+
*/
|
|
2361
|
+
function triple(values) {
|
|
2362
|
+
return [
|
|
2363
|
+
canonicalNumberAt(values, 0),
|
|
2364
|
+
canonicalNumberAt(values, 1),
|
|
2365
|
+
canonicalNumberAt(values, 2)
|
|
2366
|
+
];
|
|
2367
|
+
}
|
|
2368
|
+
/**
|
|
2369
|
+
* Reads one canonical number from a transform channel.
|
|
2370
|
+
*
|
|
2371
|
+
* @param values - The channel.
|
|
2372
|
+
* @param index - Which entry.
|
|
2373
|
+
* @returns The canonical number; `0` when the entry is missing.
|
|
2374
|
+
*/
|
|
2375
|
+
function canonicalNumberAt(values, index) {
|
|
2376
|
+
return canonicalizeNumber(values[index] ?? 0);
|
|
2377
|
+
}
|
|
2378
|
+
/**
|
|
2379
|
+
* Rebuilds an instance entry with a new override list and hash.
|
|
2380
|
+
*
|
|
2381
|
+
* @param instance - The entry.
|
|
2382
|
+
* @param overrides - The overrides to keep.
|
|
2383
|
+
* @param hash - The hash to record, or `undefined` for none.
|
|
2384
|
+
* @returns The entry, in the serializer's key order, `overrides` omitted when empty.
|
|
2385
|
+
*/
|
|
2386
|
+
function withOverrides(instance, overrides, hash) {
|
|
2387
|
+
return {
|
|
2388
|
+
scene: instance.scene,
|
|
2389
|
+
...hash === void 0 ? {} : { hash },
|
|
2390
|
+
...overrides.length === 0 ? {} : { overrides }
|
|
2391
|
+
};
|
|
2392
|
+
}
|
|
2393
|
+
//#endregion
|
|
2394
|
+
export { asJsonArray as A, normalizeExtension as B, encodeValue as C, indexPath as D, childPath as E, throwSchemaError as F, MEMORY_ADDRESS_PREFIX as I, isAbsoluteAddress as L, setOwnJsonProperty as M, SchemaIssueCode as N, isArray as O, issue as P, joinRoot as R, encodeProps as S, VECTOR_COMPONENTS as T, splitFragment as V, describeSchema as _, SceneAssetToken as a, decodeProps as b, findSceneDependency as c, SCENE_FILE_FORMAT as d, SCENE_FORMAT_VERSION as f, stringifySceneFile as g, sceneFileJsonSchema as h, parseOverridePath as i, asJsonObject as j, isPlainObject as k, SCENE_ASSET_TYPE as l, isSceneFileHeader as m, revertOverrides as n, computeSceneHash as o, describeSceneFileFormat as p, applyOverrides as r, createSceneAsset as s, applyOverridesToAsset as t, SCENE_FILE_EXTENSIONS as u, toJsonSchema as v, COLOR_CHANNELS as w, decodeValue as x, canonicalizeNumber as y, matchExtension as z };
|
|
2395
|
+
|
|
2396
|
+
//# sourceMappingURL=prefab-overrides-DGiGTSN-.js.map
|