@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.
Files changed (54) hide show
  1. package/decoders/draco3dgltf.LICENSE.md +201 -0
  2. package/decoders/draco_decoder.js +116 -0
  3. package/decoders/draco_decoder_gltf.wasm +0 -0
  4. package/decoders/vendored.json +22 -0
  5. package/dist/{decoders-CHJ7vduE.js → decoders-BUQrlS8U.js} +3 -2
  6. package/dist/decoders-BUQrlS8U.js.map +1 -0
  7. package/dist/{environment-DPi0_0SP.js → environment-CMpzGXTz.js} +2 -2
  8. package/dist/{environment-DPi0_0SP.js.map → environment-CMpzGXTz.js.map} +1 -1
  9. package/dist/{ignifx-error-oYdVnT1S.js → ignifx-error-Der0bpHK.js} +7 -1
  10. package/dist/ignifx-error-Der0bpHK.js.map +1 -0
  11. package/dist/index.d.ts +29 -14609
  12. package/dist/index.d.ts.map +1 -1
  13. package/dist/index.js +1715 -4899
  14. package/dist/index.js.map +1 -1
  15. package/dist/{instanced-mesh-instance-NnODkvqK.js → instanced-mesh-instance-BMhREEfx.js} +3 -2
  16. package/dist/{instanced-mesh-instance-NnODkvqK.js.map → instanced-mesh-instance-BMhREEfx.js.map} +1 -1
  17. package/dist/{material-plugin-BUlqLsap.js → material-plugin-B-hartHR.js} +2 -2
  18. package/dist/{material-plugin-BUlqLsap.js.map → material-plugin-B-hartHR.js.map} +1 -1
  19. package/dist/node-DznSvwap.js +301 -0
  20. package/dist/node-DznSvwap.js.map +1 -0
  21. package/dist/{post-effect-BHl7U56q.js → post-effect-CuoYvrhb.js} +3 -30
  22. package/dist/post-effect-CuoYvrhb.js.map +1 -0
  23. package/dist/{post-effect-compiler-CRek8VxQ.js → post-effect-compiler-Bps8QbiJ.js} +3 -3
  24. package/dist/{post-effect-compiler-CRek8VxQ.js.map → post-effect-compiler-Bps8QbiJ.js.map} +1 -1
  25. package/dist/prefab-overrides-76IhcF-e.d.ts +14925 -0
  26. package/dist/prefab-overrides-76IhcF-e.d.ts.map +1 -0
  27. package/dist/prefab-overrides-DGiGTSN-.js +2396 -0
  28. package/dist/prefab-overrides-DGiGTSN-.js.map +1 -0
  29. package/dist/prefab.d.ts +2 -0
  30. package/dist/prefab.js +2 -0
  31. package/dist/reflection-probe-C0pzGrG_.js +1883 -0
  32. package/dist/reflection-probe-C0pzGrG_.js.map +1 -0
  33. package/dist/reflection-probes-B8_vK9YR.js +551 -0
  34. package/dist/reflection-probes-B8_vK9YR.js.map +1 -0
  35. package/dist/{render-texture-C_TnaSz2.js → render-texture-UqRHRLQy.js} +15 -2
  36. package/dist/{render-texture-C_TnaSz2.js.map → render-texture-UqRHRLQy.js.map} +1 -1
  37. package/dist/rolldown-runtime-D7D4PA-g.js +13 -0
  38. package/dist/{shader-material-B6p66wB8.js → shader-material-Cjfq7nFS.js} +5 -16
  39. package/dist/{shader-material-B6p66wB8.js.map → shader-material-Cjfq7nFS.js.map} +1 -1
  40. package/dist/{shader-material-C0TAUr4t.js → shader-material-DCjYDdkh.js} +2 -2
  41. package/dist/{shader-material-C0TAUr4t.js.map → shader-material-DCjYDdkh.js.map} +1 -1
  42. package/dist/{shader-pragma-BKCoZTTA.js → shader-pragma-cjEC-EPK.js} +2 -2
  43. package/dist/{shader-pragma-BKCoZTTA.js.map → shader-pragma-cjEC-EPK.js.map} +1 -1
  44. package/dist/{surface-shader-BaK0kvBB.js → surface-shader-D40hXQ8c.js} +4 -4
  45. package/dist/{surface-shader-BaK0kvBB.js.map → surface-shader-D40hXQ8c.js.map} +1 -1
  46. package/dist/{vec3-D-0Y2mzE.js → vec3-Cc19wl4r.js} +3 -300
  47. package/dist/vec3-Cc19wl4r.js.map +1 -0
  48. package/package.json +11 -5
  49. package/dist/decoders-CHJ7vduE.js.map +0 -1
  50. package/dist/ignifx-error-oYdVnT1S.js.map +0 -1
  51. package/dist/json-CzZZ6K4x.js +0 -24
  52. package/dist/json-CzZZ6K4x.js.map +0 -1
  53. package/dist/post-effect-BHl7U56q.js.map +0 -1
  54. package/dist/vec3-D-0Y2mzE.js.map +0 -1
@@ -0,0 +1,1883 @@
1
+ import { o as CoreErrorCode, t as IgnifxError } from "./ignifx-error-Der0bpHK.js";
2
+ import { F as throwSchemaError, N as SchemaIssueCode } from "./prefab-overrides-DGiGTSN-.js";
3
+ import { c as readNodeTag, s as parentNode } from "./node-DznSvwap.js";
4
+ import { pickWithRay } from "@babylonjs/lite";
5
+ //#region src/signal/signal.ts
6
+ /** One attached handler. `handler === null` marks the entry dead and awaiting compaction. */
7
+ var Connection = class {
8
+ handler;
9
+ once;
10
+ deferred;
11
+ /** Index into the owning signal's connection list; kept current by swap-remove. */
12
+ index;
13
+ /** Detaches the auto-disconnect handler from `owner.onDestroyed`. */
14
+ ownerDisconnect = null;
15
+ constructor(handler, once, deferred, index) {
16
+ this.handler = handler;
17
+ this.once = once;
18
+ this.deferred = deferred;
19
+ this.index = index;
20
+ }
21
+ };
22
+ /** Returned when connecting to a signal on behalf of an already-destroyed owner. */
23
+ function noopDisconnect() {}
24
+ /**
25
+ * A typed, synchronous, many-listener event (`docs/architecture/02-scene-graph.md` §8). Signals are
26
+ * the "signal up" half of the engine's *call down, signal up* convention: a parent calls methods on
27
+ * the children it owns, a child announces what happened and lets interested parties subscribe.
28
+ *
29
+ * @remarks
30
+ * Delivery guarantees:
31
+ *
32
+ * - Handlers run in connection order, synchronously, inside {@link Signal.emit}.
33
+ * - A handler connected *during* an emit runs on the next emit, never the one in flight.
34
+ * - A handler disconnected during an emit never runs again, including in the emit in flight.
35
+ * - One handler throwing does not stop delivery to the others.
36
+ * - Nothing is allocated per emit on the non-deferred path (coding standards §7).
37
+ *
38
+ * The payload type `T` defaults to `void`, so `signal.emit()` takes no argument.
39
+ *
40
+ * @example
41
+ * ```ts
42
+ * class Health extends Script {
43
+ * readonly onDied = new Signal<Entity>();
44
+ * damage(amount: number): void {
45
+ * this.hp -= amount;
46
+ * if (this.hp <= 0) {
47
+ * this.onDied.emit(this.entity);
48
+ * }
49
+ * }
50
+ * }
51
+ *
52
+ * health.onDied.connect((entity) => this.spawnLoot(entity), { owner: this, once: true });
53
+ * ```
54
+ *
55
+ * @public
56
+ */
57
+ var Signal = class {
58
+ #connections = [];
59
+ #deferredQueue;
60
+ #onHandlerError;
61
+ #liveCount = 0;
62
+ #deadCount = 0;
63
+ #emitDepth = 0;
64
+ /**
65
+ * Creates a signal.
66
+ *
67
+ * @param options - The deferred-delivery scheduler and the handler-error reporter. Both are
68
+ * supplied by the app for engine signals; a signal a script owns usually needs neither.
69
+ */
70
+ constructor(options) {
71
+ this.#deferredQueue = options?.deferredQueue ?? null;
72
+ this.#onHandlerError = options?.onHandlerError ?? null;
73
+ }
74
+ /**
75
+ * How many handlers are currently attached.
76
+ *
77
+ * @returns The live connection count.
78
+ */
79
+ get connectionCount() {
80
+ return this.#liveCount;
81
+ }
82
+ /**
83
+ * Attaches a handler.
84
+ *
85
+ * @param handler - The listener.
86
+ * @param options - `once` to detach after the first delivery, `deferred` to queue delivery on the
87
+ * signal's {@link DeferredQueue}, and `owner` to detach when the owner is destroyed.
88
+ * @returns A function that detaches the handler; calling it twice is a no-op.
89
+ * @throws IgnifxError with code `IGX-0103` when `deferred` is requested and the signal was
90
+ * constructed without a {@link DeferredQueue}.
91
+ *
92
+ * @example
93
+ * ```ts
94
+ * const stop = app.events.onSceneLoaded.connect((scene) => this.spawn(scene), { owner: this });
95
+ * stop();
96
+ * ```
97
+ */
98
+ connect(handler, options) {
99
+ const deferred = options?.deferred ?? false;
100
+ if (deferred && this.#deferredQueue === null) throw new IgnifxError(CoreErrorCode.deferredSignalWithoutScheduler, "Deferred signal delivery needs a scheduler; construct the signal with a deferred queue.", { hint: "Engine signals reached through the app already have one; a signal you own does not." });
101
+ const owner = options?.owner;
102
+ if (owner !== void 0 && owner.isDestroyed) return noopDisconnect;
103
+ const connection = new Connection(handler, options?.once ?? false, deferred, this.#connections.length);
104
+ this.#connections.push(connection);
105
+ this.#liveCount += 1;
106
+ if (owner !== void 0) connection.ownerDisconnect = owner.onDestroyed.connect(() => {
107
+ this.#remove(connection);
108
+ });
109
+ return () => {
110
+ this.#remove(connection);
111
+ };
112
+ }
113
+ /**
114
+ * Delivers a value to every attached handler, in connection order.
115
+ *
116
+ * @param value - The payload. Omitted for `Signal<void>`.
117
+ * @throws IgnifxError with code `IGX-0104` wrapping the first handler exception, when the signal
118
+ * was constructed without an `onHandlerError` reporter.
119
+ */
120
+ emit(value) {
121
+ const connections = this.#connections;
122
+ const count = connections.length;
123
+ if (count === 0) return;
124
+ this.#emitDepth += 1;
125
+ let firstError = null;
126
+ let errorCount = 0;
127
+ for (let index = 0; index < count; index += 1) {
128
+ const connection = connections[index];
129
+ if (connection === void 0) continue;
130
+ const handler = connection.handler;
131
+ if (handler === null) continue;
132
+ const isOnce = connection.once;
133
+ if (isOnce) this.#remove(connection);
134
+ try {
135
+ if (connection.deferred && this.#deferredQueue !== null) this.#deferredQueue.enqueue(() => {
136
+ if (isOnce || connection.handler !== null) handler(value);
137
+ });
138
+ else handler(value);
139
+ } catch (error) {
140
+ errorCount += 1;
141
+ if (this.#onHandlerError === null) {
142
+ if (errorCount === 1) firstError = error;
143
+ } else this.#onHandlerError(error, this);
144
+ }
145
+ }
146
+ this.#emitDepth -= 1;
147
+ if (this.#emitDepth === 0 && this.#deadCount > 0) this.#compact();
148
+ if (errorCount > 0 && this.#onHandlerError === null) throw new IgnifxError(CoreErrorCode.signalHandlerThrew, "A signal handler threw.", {
149
+ cause: firstError,
150
+ context: {
151
+ errorCount,
152
+ handlerCount: count
153
+ },
154
+ hint: "Handle the failure in the handler, or give the signal an onHandlerError reporter."
155
+ });
156
+ }
157
+ /**
158
+ * Detaches the first connection made with this handler. Detaching a handler that is not connected
159
+ * is a no-op.
160
+ *
161
+ * @param handler - The listener to detach.
162
+ */
163
+ disconnect(handler) {
164
+ for (const connection of this.#connections) if (connection.handler === handler) {
165
+ this.#remove(connection);
166
+ return;
167
+ }
168
+ }
169
+ /** Detaches every handler, including the auto-disconnect hooks held on owners. */
170
+ clear() {
171
+ for (const connection of this.#connections.slice()) this.#remove(connection);
172
+ }
173
+ /**
174
+ * Marks a connection dead and, when no emit is in flight, removes it by swapping the last entry
175
+ * into its slot. During an emit the entry is left as a tombstone so indices stay stable, and the
176
+ * outermost emit compacts.
177
+ *
178
+ * @param connection - The connection to detach.
179
+ */
180
+ #remove(connection) {
181
+ if (connection.handler === null) return;
182
+ connection.handler = null;
183
+ this.#liveCount -= 1;
184
+ const ownerDisconnect = connection.ownerDisconnect;
185
+ if (ownerDisconnect !== null) {
186
+ connection.ownerDisconnect = null;
187
+ ownerDisconnect();
188
+ }
189
+ if (this.#emitDepth > 0) {
190
+ this.#deadCount += 1;
191
+ return;
192
+ }
193
+ this.#swapRemove(connection.index);
194
+ }
195
+ /** Removes every tombstone left behind by an emit. */
196
+ #compact() {
197
+ const connections = this.#connections;
198
+ for (let index = connections.length - 1; index >= 0; index -= 1) {
199
+ const connection = connections[index];
200
+ if (connection !== void 0 && connection.handler === null) this.#swapRemove(index);
201
+ }
202
+ this.#deadCount = 0;
203
+ }
204
+ /**
205
+ * Removes the entry at an index by moving the last entry into its place.
206
+ *
207
+ * @param index - The slot to vacate.
208
+ */
209
+ #swapRemove(index) {
210
+ const connections = this.#connections;
211
+ const last = connections.length - 1;
212
+ if (index !== last) {
213
+ const moved = connections[last];
214
+ if (moved !== void 0) {
215
+ connections[index] = moved;
216
+ moved.index = index;
217
+ }
218
+ }
219
+ connections.pop();
220
+ }
221
+ };
222
+ //#endregion
223
+ //#region src/schema/schema.ts
224
+ /**
225
+ * Property names a schema may not use, because `Component`/`Script` already define them
226
+ * (`docs/architecture/03-scripting-and-components.md` §1 and §2). A schema field becomes a property
227
+ * on the generated base class, so reusing one of these would shadow engine state and break the
228
+ * lifecycle silently.
229
+ *
230
+ * @internal
231
+ */
232
+ const RESERVED_FIELD_NAMES = [
233
+ "uid",
234
+ "entity",
235
+ "transform",
236
+ "world",
237
+ "app",
238
+ "enabled",
239
+ "isDestroyed",
240
+ "isEnabledInHierarchy",
241
+ "destroy",
242
+ "getComponent",
243
+ "requireComponent",
244
+ "awake",
245
+ "onEnable",
246
+ "start",
247
+ "fixedUpdate",
248
+ "update",
249
+ "lateUpdate",
250
+ "onDisable",
251
+ "onDestroy",
252
+ "startCoroutine",
253
+ "stopCoroutine",
254
+ "stopAllCoroutines"
255
+ ];
256
+ /**
257
+ * A field name must read like a plain JavaScript identifier so that `this.<name>` works without
258
+ * bracket syntax, and must not start with `_`, which the standards reserve for adapter-internal
259
+ * mirrors (coding standards §5.1).
260
+ *
261
+ * @internal
262
+ */
263
+ const FIELD_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9]*$/u;
264
+ /**
265
+ * Refuses a field name that every plain object already has through `Object.prototype`:
266
+ * `constructor`, `toString`, `valueOf`, `hasOwnProperty`, `__proto__` and the rest. Encoders,
267
+ * decoders, and the inspector walk a schema and read each field as `values[name]`, so a value that
268
+ * omits such a field yields the inherited member instead of `undefined`; and they write it as
269
+ * `out[name] = …`, which for `__proto__` replaces the object's prototype instead of adding a key.
270
+ * Refusing the name once, where the schema is declared, keeps every one of those sites correct.
271
+ * `prototype` is not inherited by plain objects, so it stays a legal name.
272
+ *
273
+ * A literal `{ __proto__: f32(1) }` (not computed) never makes a key at all: it sets the object's
274
+ * prototype, so the field would vanish without a word. The fields object must therefore be a plain
275
+ * object (its prototype `Object.prototype`, or `null`).
276
+ *
277
+ * @param fields - The field definitions being declared.
278
+ * @param where - What declares them, for the message: `"schema"` or `"record"`.
279
+ * @throws IgnifxError with code `IGX-0607` when a name is an `Object.prototype` member, or the
280
+ * fields object is not a plain object.
281
+ *
282
+ * @internal
283
+ */
284
+ function assertNoInheritedFieldNames(fields, where) {
285
+ const prototype = Object.getPrototypeOf(fields);
286
+ if (prototype !== Object.prototype && prototype !== null) throwSchemaError(SchemaIssueCode.unknownField, `${where} fields are not a plain object, so a field is hidden in its prototype; a literal "__proto__: …" key sets the prototype instead of declaring a field. Rename the field.`);
287
+ for (const name of Object.keys(fields)) if (Object.hasOwn(Object.prototype, name)) throwSchemaError(SchemaIssueCode.unknownField, `${where} field "${name}" names a member every object inherits (Object.prototype.${name}); rename the field.`);
288
+ }
289
+ /**
290
+ * Rewrites a JavaScript value into a mutable string-keyed view. Schema-shaped objects are always
291
+ * plain records built by this module, so the assertion holds by construction; it exists because a
292
+ * mapped type such as `FieldsOf<S>` cannot be indexed generically (coding standards §5.2 permits
293
+ * assertions at boundaries like this one, with the invariant stated).
294
+ *
295
+ * @param value - The object to view.
296
+ * @returns The same object, typed as a mutable record.
297
+ *
298
+ * @internal
299
+ */
300
+ function mutableView(value) {
301
+ return value;
302
+ }
303
+ /**
304
+ * Rewrites a plain record into the field object a schema describes. Safe because `createDefaults`
305
+ * fills exactly the schema's keys with values built by that key's own field definition.
306
+ *
307
+ * @param value - The record to view.
308
+ * @returns The same object, typed as the schema's field object.
309
+ *
310
+ * @internal
311
+ */
312
+ function fieldsView(value) {
313
+ return value;
314
+ }
315
+ /**
316
+ * Declares a component's serialized fields. The helper is an identity function at runtime — it
317
+ * returns the object it was given — but it checks every field name and, because it is generic,
318
+ * preserves the exact literal type of the schema so `FieldsOf` can project it.
319
+ *
320
+ * `Script.define` and `Component.define` call this before they build a base class.
321
+ *
322
+ * @param fields - The field definitions, keyed by the property name they become.
323
+ * @returns The same object, with its precise type preserved.
324
+ * @throws IgnifxError with code `IGX-0607` when a field name is not identifier-like, starts with
325
+ * `_`, collides with a `Component`/`Script` member such as `enabled` or `update`, or names an
326
+ * `Object.prototype` member such as `constructor` or `toString`, or when `fields` is not a plain
327
+ * object (a literal `__proto__: …` key sets its prototype rather than declaring a field).
328
+ *
329
+ * @example
330
+ * ```ts
331
+ * const moverSchema = defineSchema({
332
+ * speed: f32(5, { min: 0, max: 50 }),
333
+ * waypoints: array(vec3()),
334
+ * });
335
+ * ```
336
+ *
337
+ * @public
338
+ */
339
+ function defineSchema(fields) {
340
+ assertNoInheritedFieldNames(fields, "schema");
341
+ for (const name of Object.keys(fields)) {
342
+ if (!FIELD_NAME_PATTERN.test(name)) throwSchemaError(SchemaIssueCode.unknownField, `schema field "${name}" is not a valid field name: use a letter followed by letters or digits, and do not start with "_".`);
343
+ if (RESERVED_FIELD_NAMES.includes(name)) throwSchemaError(SchemaIssueCode.unknownField, `schema field "${name}" collides with a Component or Script member; rename the field.`);
344
+ }
345
+ return fields;
346
+ }
347
+ /**
348
+ * Builds the initial field object for a schema. Every value is freshly allocated by its field's
349
+ * own `createDefault`, so two components declared from the same schema never share a mutable
350
+ * default such as a `vec3` or an `array`.
351
+ *
352
+ * @param schema - The schema to instantiate.
353
+ * @returns A new object holding one default per declared field.
354
+ *
355
+ * @example
356
+ * ```ts
357
+ * const a = createDefaults(moverSchema);
358
+ * const b = createDefaults(moverSchema);
359
+ * a.offset === b.offset; // false — each call allocates
360
+ * ```
361
+ *
362
+ * @public
363
+ */
364
+ function createDefaults(schema) {
365
+ const defaults = {};
366
+ for (const [name, field] of Object.entries(schema)) defaults[name] = field.createDefault();
367
+ return fieldsView(defaults);
368
+ }
369
+ /**
370
+ * Overwrites defaults with caller-supplied values. Only names the schema declares are copied, and
371
+ * a value of `undefined` leaves the default in place — matching the loader's rule that omitted
372
+ * props take schema defaults (`docs/architecture/06-serialization-and-scene-format.md` §2).
373
+ *
374
+ * @param target - The field object to write into, normally the result of `createDefaults`.
375
+ * @param schema - The schema that says which names are legal.
376
+ * @param init - The values to apply.
377
+ * @returns The same `target` object, for chaining.
378
+ *
379
+ * @example
380
+ * ```ts
381
+ * const fields = applyInit(createDefaults(moverSchema), moverSchema, { speed: 12 });
382
+ * ```
383
+ *
384
+ * @public
385
+ */
386
+ function applyInit(target, schema, init) {
387
+ const writable = mutableView(target);
388
+ const supplied = mutableView(init);
389
+ for (const name of Object.keys(schema)) {
390
+ const value = supplied[name];
391
+ if (value !== void 0) writable[name] = value;
392
+ }
393
+ return target;
394
+ }
395
+ //#endregion
396
+ //#region src/handles/handle.ts
397
+ /**
398
+ * The handle value that never resolves. Allocated handles always carry a generation of at least
399
+ * one, so zero is unreachable and doubles as "no handle".
400
+ *
401
+ * @public
402
+ */
403
+ const INVALID_HANDLE = 0;
404
+ /**
405
+ * Brands a raw allocator handle as an entity handle.
406
+ *
407
+ * @param value - The number {@link HandleAllocator.allocate} returned.
408
+ * @returns The same number, typed as an entity handle.
409
+ *
410
+ * @internal
411
+ */
412
+ function toEntityHandle(value) {
413
+ return value;
414
+ }
415
+ /**
416
+ * Brands a raw allocator handle as a component handle.
417
+ *
418
+ * @param value - The number {@link HandleAllocator.allocate} returned.
419
+ * @returns The same number, typed as a component handle.
420
+ *
421
+ * @internal
422
+ */
423
+ function toComponentHandle(value) {
424
+ return value;
425
+ }
426
+ //#endregion
427
+ //#region src/component/internals.ts
428
+ /**
429
+ * The engine-owned state of a component, kept off the public type.
430
+ *
431
+ * @remarks
432
+ * Components are constructed with `new Type()` and only *then* handed their entity, uid, and
433
+ * handle, so the state cannot live in constructor parameters. It lives behind a module symbol
434
+ * instead: the property is unreachable by name, invisible to `Object.keys`, and impossible to
435
+ * collide with a schema field — while staying fully typed, with no `any` and no assertion
436
+ * (coding standards §5.2).
437
+ */
438
+ /**
439
+ * The key the engine state hangs off. Exported so that `Entity`, the lifecycle queue, and the world
440
+ * can reach it; unreachable from game code, which has no way to name the symbol.
441
+ *
442
+ * @internal
443
+ */
444
+ const COMPONENT_INTERNALS = Symbol("ignifx.component.internals");
445
+ /**
446
+ * Reads a component's engine-owned state.
447
+ *
448
+ * @param component - The component.
449
+ * @returns Its internal state.
450
+ *
451
+ * @internal
452
+ */
453
+ function componentInternals(component) {
454
+ return component[COMPONENT_INTERNALS];
455
+ }
456
+ /**
457
+ * Builds the initial engine state of a freshly constructed, not yet attached component.
458
+ *
459
+ * @returns The state, with no entity and no identity yet.
460
+ *
461
+ * @internal
462
+ */
463
+ function createComponentInternals() {
464
+ return {
465
+ entity: null,
466
+ uid: "",
467
+ handle: toComponentHandle(0),
468
+ info: null,
469
+ serial: 0,
470
+ enabled: true,
471
+ isEnabledNow: false,
472
+ isEnableQueued: false,
473
+ isStartQueued: false,
474
+ hasAwoken: false,
475
+ hasStarted: false,
476
+ isDestroyed: false,
477
+ isReleased: false,
478
+ isDestroyQueued: false,
479
+ storeSlots: [],
480
+ onDestroyed: null
481
+ };
482
+ }
483
+ //#endregion
484
+ //#region src/component/component.ts
485
+ /**
486
+ * Typed data and behaviour attached to an entity
487
+ * (`docs/architecture/03-scripting-and-components.md` §1). Engine-owned components
488
+ * (`MeshRenderer`, `Rigidbody`, `AudioSource`) are plain `Component`s driven by systems; game
489
+ * behaviour extends `Script`, which adds the frame lifecycle.
490
+ *
491
+ * @remarks
492
+ * A component class must have a no-argument constructor: the engine constructs it, then assigns
493
+ * `entity`, `uid`, and `handle`, then applies schema defaults and the `init` object, then calls
494
+ * `onAttach`. Reading `this.entity` from a constructor therefore throws `IGX-0206`; cache lookups
495
+ * in `onAttach` or `awake` instead.
496
+ *
497
+ * **Where the statics are declared.** `typeId`, `schema`, `requires`, and `allowMultiple` are not
498
+ * members of this class. Declaring them here would make every `static typeId = "mygame/Mover"` an
499
+ * override and force the `override` keyword on it under `noImplicitOverride` (coding standards §3)
500
+ * — the same reasoning that keeps the callbacks on {@link ComponentHooks}. The shape lives on
501
+ * {@link ComponentStatics} instead, and `ComponentRegistry` reads it once per class and supplies
502
+ * the defaults (`allowMultiple` is `true` when the class declares nothing).
503
+ *
504
+ * @example
505
+ * ```ts
506
+ * class Health extends Component.define({ maximum: f32(100) }) {
507
+ * static typeId = "mygame/Health";
508
+ * current = 0;
509
+ * onAttach(): void {
510
+ * this.current = this.maximum;
511
+ * }
512
+ * }
513
+ * ```
514
+ *
515
+ * @public
516
+ */
517
+ var Component = class {
518
+ /** Creates a component. The engine constructs components; game code never calls `new`. */
519
+ constructor() {
520
+ this[COMPONENT_INTERNALS] = createComponentInternals();
521
+ }
522
+ /**
523
+ * Declares a component's serialized fields and returns the base class to extend (ADR-0004,
524
+ * `docs/architecture/03-scripting-and-components.md` §3). The returned class exposes every field
525
+ * as a typed instance property, applies the defaults in its constructor, and carries the schema
526
+ * for the serializer, the inspector, and the docs harness.
527
+ *
528
+ * @typeParam S - The schema being declared.
529
+ * @param schema - The field definitions, keyed by the property name they become.
530
+ * @returns An abstract class to extend.
531
+ * @throws IgnifxError with code `IGX-0607` when a field name is not identifier-like, collides
532
+ * with a `Component`/`Script` member, or names an `Object.prototype` member such as `constructor`.
533
+ *
534
+ * @example
535
+ * ```ts
536
+ * class Spinner extends Component.define({
537
+ * degreesPerSecond: f32(90, { min: -360, max: 360 }),
538
+ * axis: vec3({ x: 0, y: 1, z: 0 }),
539
+ * }) {
540
+ * static typeId = "mygame/Spinner";
541
+ * }
542
+ * ```
543
+ */
544
+ static define(schema) {
545
+ const fields = defineSchema(schema);
546
+ class Defined extends Component {
547
+ static schema = fields;
548
+ constructor() {
549
+ super();
550
+ Object.assign(this, createDefaults(fields));
551
+ }
552
+ }
553
+ return Defined;
554
+ }
555
+ /**
556
+ * The stable ULID; the key files use to reference this component.
557
+ *
558
+ * @returns The identifier.
559
+ */
560
+ get uid() {
561
+ return this.#attached().uid;
562
+ }
563
+ /**
564
+ * The dense runtime handle; invalid after destruction.
565
+ *
566
+ * @returns The handle.
567
+ */
568
+ get handle() {
569
+ return this.#attached().handle;
570
+ }
571
+ /**
572
+ * The entity this component is attached to.
573
+ *
574
+ * @returns The owning entity.
575
+ */
576
+ get entity() {
577
+ const entity = this.#attached().entity;
578
+ if (entity === null) throw notAttached(this);
579
+ return entity;
580
+ }
581
+ /**
582
+ * The entity's transform — sugar for `this.entity.transform`, the most-used lookup there is.
583
+ *
584
+ * @returns The entity's transform.
585
+ */
586
+ get transform() {
587
+ return this.entity.transform;
588
+ }
589
+ /**
590
+ * The world the entity belongs to.
591
+ *
592
+ * @returns The world.
593
+ */
594
+ get world() {
595
+ return this.entity.world;
596
+ }
597
+ /**
598
+ * The app that owns the world.
599
+ *
600
+ * @returns The app.
601
+ */
602
+ get app() {
603
+ return this.entity.world.app;
604
+ }
605
+ /**
606
+ * The component's own enabled flag; `true` by default. Setting it runs the enable or disable
607
+ * transition (`docs/architecture/01-lifecycle-and-time.md` §6): `onDisable` runs immediately,
608
+ * `awake`/`onEnable` run in the next lifecycle flush — or immediately and nested when the change
609
+ * happens inside a callback.
610
+ *
611
+ * @returns `true` when the component's own flag is set.
612
+ */
613
+ get enabled() {
614
+ return componentInternals(this).enabled;
615
+ }
616
+ set enabled(value) {
617
+ const internals = componentInternals(this);
618
+ if (internals.enabled === value) return;
619
+ if (internals.isDestroyed) throw new IgnifxError(CoreErrorCode.mutationAfterDestroy, "This component has been destroyed.", { context: {
620
+ target: "component",
621
+ uid: internals.uid,
622
+ operation: "enabled"
623
+ } });
624
+ internals.enabled = value;
625
+ const entity = internals.entity;
626
+ if (entity !== null) entity.world.lifecycle.refreshEnabled(this);
627
+ }
628
+ /**
629
+ * `true` when the component's own flag is set **and** its entity is active in the hierarchy.
630
+ *
631
+ * @returns `true` when the component is effectively enabled.
632
+ */
633
+ get isEnabledInHierarchy() {
634
+ const internals = componentInternals(this);
635
+ const entity = internals.entity;
636
+ return internals.enabled && !internals.isDestroyed && entity !== null && entity.activeInHierarchy;
637
+ }
638
+ /**
639
+ * `true` from the moment `destroy()` is called, long before the destroy flush runs.
640
+ *
641
+ * @returns `true` once the component has been queued for destruction.
642
+ */
643
+ get isDestroyed() {
644
+ return componentInternals(this).isDestroyed;
645
+ }
646
+ /**
647
+ * Emitted once when the component is destroyed, in the destroy flush. Connecting with
648
+ * `{ owner: this }` elsewhere uses it to detach handlers automatically
649
+ * (`docs/architecture/02-scene-graph.md` §8).
650
+ *
651
+ * @returns The signal. It is created on first access, so a component nobody listens to allocates
652
+ * nothing.
653
+ */
654
+ get onDestroyed() {
655
+ const internals = componentInternals(this);
656
+ internals.onDestroyed ??= new Signal();
657
+ return internals.onDestroyed;
658
+ }
659
+ /**
660
+ * Queues this component for destruction. It stays usable until the destroy flush of the current
661
+ * frame, but reports `isDestroyed === true` immediately
662
+ * (`docs/architecture/01-lifecycle-and-time.md` §6). Calling it twice is a no-op.
663
+ */
664
+ destroy() {
665
+ const internals = componentInternals(this);
666
+ const entity = internals.entity;
667
+ if (entity === null) {
668
+ internals.isDestroyed = true;
669
+ return;
670
+ }
671
+ entity.removeComponent(this);
672
+ }
673
+ /**
674
+ * Finds another component on the same entity — sugar for `this.entity.getComponent`.
675
+ *
676
+ * @typeParam T - The component type to look for.
677
+ * @param type - The component class; matching is by class identity **and** inheritance.
678
+ * @returns The first match in attach order, or `null`.
679
+ */
680
+ getComponent(type) {
681
+ return this.entity.getComponent(type);
682
+ }
683
+ /**
684
+ * Finds another component on the same entity, requiring it to be there — the supported way to
685
+ * link components (`docs/architecture/03-scripting-and-components.md` §8).
686
+ *
687
+ * @typeParam T - The component type to look for.
688
+ * @param type - The component class.
689
+ * @returns The first match in attach order.
690
+ * @throws IgnifxError with code `IGX-0201` when the entity has no such component.
691
+ */
692
+ requireComponent(type) {
693
+ return this.entity.requireComponent(type);
694
+ }
695
+ /**
696
+ * The engine state, with the "attached" invariant checked once.
697
+ *
698
+ * @returns The internals.
699
+ */
700
+ #attached() {
701
+ const internals = componentInternals(this);
702
+ if (internals.entity === null) throw notAttached(this);
703
+ return internals;
704
+ }
705
+ };
706
+ /**
707
+ * Builds the "used before the engine attached it" error.
708
+ *
709
+ * @param component - The component that was read too early.
710
+ * @returns The error to throw.
711
+ */
712
+ function notAttached(component) {
713
+ return new IgnifxError(CoreErrorCode.componentNotAttached, `${component.constructor.name} is not attached to an entity yet.`, {
714
+ context: { component: component.constructor.name },
715
+ hint: "The engine assigns entity, uid, and handle after construction; read them in onAttach or awake."
716
+ });
717
+ }
718
+ //#endregion
719
+ //#region src/lite/picking.ts
720
+ /**
721
+ * Creates a reusable ray, pointing along `+Z` from the origin.
722
+ *
723
+ * @returns A fresh ray. **Allocates** — create one per picking site, not per pick.
724
+ *
725
+ * @example
726
+ * ```ts
727
+ * const ray = createPickRay();
728
+ * screenToRay(camera, x, y, width, height, ray);
729
+ * const hit = raycastScene(scene, ray);
730
+ * ```
731
+ *
732
+ * @internal
733
+ */
734
+ function createPickRay() {
735
+ return {
736
+ origin: [
737
+ 0,
738
+ 0,
739
+ 0
740
+ ],
741
+ direction: [
742
+ 0,
743
+ 0,
744
+ 1
745
+ ],
746
+ length: Number.MAX_VALUE
747
+ };
748
+ }
749
+ /**
750
+ * Points a ray at a world-space origin and direction, in place.
751
+ *
752
+ * @param ray - The ray to rewrite.
753
+ * @param originX - The world-space origin x.
754
+ * @param originY - The world-space origin y.
755
+ * @param originZ - The world-space origin z.
756
+ * @param directionX - The direction x; it need not be normalized.
757
+ * @param directionY - The direction y.
758
+ * @param directionZ - The direction z.
759
+ * @param length - How far the ray reaches, in metres.
760
+ *
761
+ * @internal
762
+ */
763
+ function setPickRay(ray, originX, originY, originZ, directionX, directionY, directionZ, length) {
764
+ const origin = ray.origin;
765
+ origin[0] = originX;
766
+ origin[1] = originY;
767
+ origin[2] = originZ;
768
+ const magnitude = Math.hypot(directionX, directionY, directionZ);
769
+ const scale = magnitude > 0 ? 1 / magnitude : 0;
770
+ const direction = ray.direction;
771
+ direction[0] = directionX * scale;
772
+ direction[1] = directionY * scale;
773
+ direction[2] = directionZ * scale;
774
+ ray.length = length;
775
+ }
776
+ /**
777
+ * Casts a ray against every renderable mesh in a scene, on the CPU.
778
+ *
779
+ * @remarks
780
+ * This is `world.raycastRender`. It is distinct from a physics raycast
781
+ * (`docs/architecture/09-physics.md` §5): it hits render geometry, including meshes that carry no
782
+ * collider.
783
+ *
784
+ * @param scene - The render scene.
785
+ * @param ray - The ray to cast.
786
+ * @param options - An optional mesh predicate.
787
+ * @returns Lite's picking info. Check `hit` before reading anything else. **Allocates** one result
788
+ * object per call — Lite builds it.
789
+ *
790
+ * @internal
791
+ */
792
+ function raycastScene(scene, ray, options) {
793
+ return pickWithRay(scene, ray, options);
794
+ }
795
+ /**
796
+ * The ignifx tag that owns a node: its own, or the nearest tagged ancestor's.
797
+ *
798
+ * @remarks
799
+ * A `MeshRenderer` tags the mesh it clones, but a `Model` tags only the cloned glTF root, and the
800
+ * meshes Lite draws are that root's descendants (`render/gpu/model-instance.ts`). Walking up to the
801
+ * nearest tag resolves both, and any other renderable that parents several Lite nodes under one
802
+ * tagged node, to the entity and component that created them (editor spike S0.2 §6.1). The walk
803
+ * stops at the first tag, so an entity parented under a model's bone still owns its own meshes.
804
+ *
805
+ * @param node - The picked node, usually a mesh.
806
+ * @returns The nearest tag, or `null` when no node on the way to the root carries one.
807
+ *
808
+ * @internal
809
+ */
810
+ function readOwnerTag(node) {
811
+ for (let current = node; current !== null; current = parentNode(current)) {
812
+ const tag = readNodeTag(current);
813
+ if (tag !== null) return tag;
814
+ }
815
+ return null;
816
+ }
817
+ /**
818
+ * Casts a ray against a scene's renderable meshes, considering only the meshes a predicate accepts.
819
+ *
820
+ * @remarks
821
+ * The predicate is stated over the owning *tag* rather than over Lite's `Mesh` so the component
822
+ * layer can filter by entity without naming a Lite type (`CONSTITUTION.md` §3.4). Lite's own
823
+ * `pickable === false` exclusion still runs first.
824
+ *
825
+ * @param scene - The render scene.
826
+ * @param ray - The ray to cast.
827
+ * @param accept - Decides whether a mesh may be picked, from the ignifx tag that owns it.
828
+ * @returns Lite's picking info.
829
+ *
830
+ * @internal
831
+ */
832
+ function raycastSceneWhere(scene, ray, accept) {
833
+ return pickWithRay(scene, ray, { predicate: (mesh) => accept(readOwnerTag(mesh), mesh) });
834
+ }
835
+ /**
836
+ * Resolves a hit back to the ignifx entity and component that own the mesh.
837
+ *
838
+ * @param info - A result from {@link raycastScene}, {@link raycastMeshes}, or the GPU picker.
839
+ * @returns The owning tag — the picked mesh's own or its nearest tagged ancestor's, so a glTF mesh
840
+ * inside a `Model` resolves to the model — or `null` when the ray missed or no node on the way to
841
+ * the root is one ignifx created.
842
+ *
843
+ * @internal
844
+ */
845
+ function readPickedTag(info) {
846
+ const mesh = info.pickedMesh;
847
+ if (mesh === null) return null;
848
+ return readOwnerTag(mesh);
849
+ }
850
+ /**
851
+ * The name of the mesh a hit landed on.
852
+ *
853
+ * @param info - A hit.
854
+ * @returns The Lite mesh's name — for a glTF model, the name the file gives the node or primitive —
855
+ * or `""` for a miss or an unnamed mesh.
856
+ *
857
+ * @internal
858
+ */
859
+ function readPickedMeshName(info) {
860
+ const name = info.pickedMesh?.name;
861
+ return typeof name === "string" ? name : "";
862
+ }
863
+ /**
864
+ * Reads the identity of a hit, for a later pick to ignore.
865
+ *
866
+ * @param info - A hit.
867
+ * @returns The mesh and thin instance, or `null` for a miss or a hit on something other than a
868
+ * regular Lite mesh (a Gaussian-splatting mesh, which Lite's `ignore` cannot name).
869
+ *
870
+ * @internal
871
+ */
872
+ function readPickedIdentity(info) {
873
+ const mesh = info.pickedMesh;
874
+ if (mesh === null || !("material" in mesh)) return null;
875
+ return {
876
+ mesh,
877
+ thinInstanceIndex: info.thinInstanceIndex
878
+ };
879
+ }
880
+ //#endregion
881
+ //#region src/schema/types.ts
882
+ /**
883
+ * Field kinds supported by component schemas.
884
+ *
885
+ * @public
886
+ */
887
+ const FieldKind = {
888
+ /** A 32-bit-ranged floating point number. */
889
+ f32: "f32",
890
+ /** A double-precision floating point number. */
891
+ f64: "f64",
892
+ /** A signed 32-bit integer. */
893
+ i32: "i32",
894
+ /** An unsigned 32-bit integer. */
895
+ u32: "u32",
896
+ /** A boolean toggle. */
897
+ bool: "bool",
898
+ /** A UTF-8 string. */
899
+ str: "str",
900
+ /** A 2D vector. */
901
+ vec2: "vec2",
902
+ /** A 3D vector. */
903
+ vec3: "vec3",
904
+ /** A 4D vector. */
905
+ vec4: "vec4",
906
+ /** A rotation quaternion. */
907
+ quat: "quat",
908
+ /** An RGBA color. */
909
+ color: "color",
910
+ /** One of a fixed set of string values. */
911
+ enum: "enum",
912
+ /** A reference to another entity in the same scene file. */
913
+ entityRef: "entityRef",
914
+ /** A reference to a component on an entity in the same scene file. */
915
+ componentRef: "componentRef",
916
+ /** A reference to an addressable asset. */
917
+ asset: "asset",
918
+ /** A list of values of one kind. */
919
+ array: "array",
920
+ /** A fixed group of named sub-fields. */
921
+ record: "record",
922
+ /** A string-keyed dictionary of values of one kind. */
923
+ map: "map",
924
+ /** A value that may also be `null`. */
925
+ optional: "optional",
926
+ /** A set of layer names. */
927
+ layerMask: "layerMask",
928
+ /** An animation curve. */
929
+ curve: "curve",
930
+ /** A value with a hand-written encoder and decoder. */
931
+ custom: "custom"
932
+ };
933
+ //#endregion
934
+ //#region src/schema/field-kinds.ts
935
+ /**
936
+ * The default a `vec2()` field takes when none is given.
937
+ *
938
+ * @internal
939
+ */
940
+ const ZERO2 = {
941
+ x: 0,
942
+ y: 0
943
+ };
944
+ /**
945
+ * The default a `vec3()` field takes when none is given.
946
+ *
947
+ * @internal
948
+ */
949
+ const ZERO3 = {
950
+ x: 0,
951
+ y: 0,
952
+ z: 0
953
+ };
954
+ /**
955
+ * The default a `vec4()` field takes when none is given.
956
+ *
957
+ * @internal
958
+ */
959
+ const ZERO4 = {
960
+ x: 0,
961
+ y: 0,
962
+ z: 0,
963
+ w: 0
964
+ };
965
+ /**
966
+ * The identity rotation, the default a `quat()` field takes when none is given.
967
+ *
968
+ * @internal
969
+ */
970
+ const IDENTITY_QUAT = {
971
+ x: 0,
972
+ y: 0,
973
+ z: 0,
974
+ w: 1
975
+ };
976
+ /**
977
+ * Opaque white, the default a `color()` field takes when none is given.
978
+ *
979
+ * @internal
980
+ */
981
+ const WHITE = {
982
+ r: 1,
983
+ g: 1,
984
+ b: 1,
985
+ a: 1
986
+ };
987
+ /**
988
+ * The default a `curve()` field takes when none is given.
989
+ *
990
+ * @internal
991
+ */
992
+ const EMPTY_CURVE = { keys: [] };
993
+ /**
994
+ * Matches `#rgb`, `#rgba`, `#rrggbb`, and `#rrggbbaa`.
995
+ *
996
+ * @internal
997
+ */
998
+ const HEX_COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/u;
999
+ /**
1000
+ * Assembles a field definition. Centralising construction keeps `kind` and `spec.kind` in step and
1001
+ * keeps every field a plain, frozen-by-convention data object.
1002
+ *
1003
+ * @param spec - The kind-specific data, which also supplies the discriminant.
1004
+ * @param options - Inspector and serializer metadata, if any.
1005
+ * @param createDefault - Factory for a fresh default value.
1006
+ * @returns The field definition.
1007
+ *
1008
+ * @internal
1009
+ */
1010
+ function field(spec, options, createDefault) {
1011
+ return {
1012
+ kind: spec.kind,
1013
+ spec,
1014
+ options: options ?? {},
1015
+ createDefault
1016
+ };
1017
+ }
1018
+ /**
1019
+ * Parses a CSS-style hexadecimal color into normalized sRGB channels.
1020
+ *
1021
+ * @param hex - `#rgb`, `#rgba`, `#rrggbb`, or `#rrggbbaa`.
1022
+ * @returns The parsed color with channels in the 0–1 range.
1023
+ * @throws A `TypeError` when the string is not one of the accepted forms.
1024
+ *
1025
+ * @internal
1026
+ */
1027
+ function parseHexColor(hex) {
1028
+ if (!HEX_COLOR_PATTERN.test(hex)) throwSchemaError(SchemaIssueCode.typeMismatch, `color("${hex}") is not a hexadecimal color; use #rgb, #rgba, #rrggbb, or #rrggbbaa.`);
1029
+ const digits = hex.slice(1);
1030
+ const short = digits.length <= 4;
1031
+ const size = short ? 1 : 2;
1032
+ const scale = short ? 15 : 255;
1033
+ const channel = (index) => {
1034
+ const start = index * size;
1035
+ if (start >= digits.length) return 1;
1036
+ return Number.parseInt(digits.slice(start, start + size), 16) / scale;
1037
+ };
1038
+ return {
1039
+ r: channel(0),
1040
+ g: channel(1),
1041
+ b: channel(2),
1042
+ a: channel(3)
1043
+ };
1044
+ }
1045
+ /**
1046
+ * Declares a single-precision floating point field.
1047
+ *
1048
+ * @param defaultValue - The value a new component starts with.
1049
+ * @param options - Inspector and serializer metadata.
1050
+ * @returns The field definition.
1051
+ *
1052
+ * @example
1053
+ * ```ts
1054
+ * speed: f32(5, { min: 0, max: 50, tooltip: "Units per second" });
1055
+ * ```
1056
+ *
1057
+ * @public
1058
+ */
1059
+ function f32(defaultValue = 0, options) {
1060
+ return field({ kind: FieldKind.f32 }, options, () => defaultValue);
1061
+ }
1062
+ /**
1063
+ * Declares a double-precision floating point field.
1064
+ *
1065
+ * @param defaultValue - The value a new component starts with.
1066
+ * @param options - Inspector and serializer metadata.
1067
+ * @returns The field definition.
1068
+ *
1069
+ * @public
1070
+ */
1071
+ function f64(defaultValue = 0, options) {
1072
+ return field({ kind: FieldKind.f64 }, options, () => defaultValue);
1073
+ }
1074
+ /**
1075
+ * Declares a signed 32-bit integer field. Validation rejects fractional values and values outside
1076
+ * the signed 32-bit range with `IGX-0606`.
1077
+ *
1078
+ * @param defaultValue - The value a new component starts with.
1079
+ * @param options - Inspector and serializer metadata.
1080
+ * @returns The field definition.
1081
+ *
1082
+ * @public
1083
+ */
1084
+ function i32(defaultValue = 0, options) {
1085
+ return field({ kind: FieldKind.i32 }, options, () => defaultValue);
1086
+ }
1087
+ /**
1088
+ * Declares an unsigned 32-bit integer field. Validation rejects fractional and negative values, and
1089
+ * values above 4294967295, with `IGX-0606`.
1090
+ *
1091
+ * @param defaultValue - The value a new component starts with.
1092
+ * @param options - Inspector and serializer metadata.
1093
+ * @returns The field definition.
1094
+ *
1095
+ * @public
1096
+ */
1097
+ function u32(defaultValue = 0, options) {
1098
+ return field({ kind: FieldKind.u32 }, options, () => defaultValue);
1099
+ }
1100
+ /**
1101
+ * Declares a boolean field.
1102
+ *
1103
+ * @param defaultValue - The value a new component starts with.
1104
+ * @param options - Inspector and serializer metadata.
1105
+ * @returns The field definition.
1106
+ *
1107
+ * @public
1108
+ */
1109
+ function bool(defaultValue = false, options) {
1110
+ return field({ kind: FieldKind.bool }, options, () => defaultValue);
1111
+ }
1112
+ /**
1113
+ * Declares a string field.
1114
+ *
1115
+ * @param defaultValue - The value a new component starts with.
1116
+ * @param options - Inspector and serializer metadata.
1117
+ * @returns The field definition.
1118
+ *
1119
+ * @public
1120
+ */
1121
+ function str(defaultValue = "", options) {
1122
+ return field({ kind: FieldKind.str }, options, () => defaultValue);
1123
+ }
1124
+ /**
1125
+ * Declares a 2D vector field. The runtime value type is the structural `Vec2Like`, so the engine's
1126
+ * `Vec2` class and plain object literals are both accepted.
1127
+ *
1128
+ * @param defaultValue - The value a new component starts with; defaults to the origin.
1129
+ * @param options - Inspector and serializer metadata.
1130
+ * @returns The field definition.
1131
+ *
1132
+ * @public
1133
+ */
1134
+ function vec2(defaultValue = ZERO2, options) {
1135
+ const { x, y } = defaultValue;
1136
+ return field({
1137
+ kind: FieldKind.vec2,
1138
+ components: 2
1139
+ }, options, () => ({
1140
+ x,
1141
+ y
1142
+ }));
1143
+ }
1144
+ /**
1145
+ * Declares a 3D vector field.
1146
+ *
1147
+ * @param defaultValue - The value a new component starts with; defaults to the origin.
1148
+ * @param options - Inspector and serializer metadata.
1149
+ * @returns The field definition.
1150
+ *
1151
+ * @example
1152
+ * ```ts
1153
+ * offset: vec3({ x: 0, y: 1, z: 0 });
1154
+ * ```
1155
+ *
1156
+ * @public
1157
+ */
1158
+ function vec3(defaultValue = ZERO3, options) {
1159
+ const { x, y, z } = defaultValue;
1160
+ return field({
1161
+ kind: FieldKind.vec3,
1162
+ components: 3
1163
+ }, options, () => ({
1164
+ x,
1165
+ y,
1166
+ z
1167
+ }));
1168
+ }
1169
+ /**
1170
+ * Declares a 4D vector field.
1171
+ *
1172
+ * @param defaultValue - The value a new component starts with; defaults to all zeroes.
1173
+ * @param options - Inspector and serializer metadata.
1174
+ * @returns The field definition.
1175
+ *
1176
+ * @public
1177
+ */
1178
+ function vec4(defaultValue = ZERO4, options) {
1179
+ const { x, y, z, w } = defaultValue;
1180
+ return field({
1181
+ kind: FieldKind.vec4,
1182
+ components: 4
1183
+ }, options, () => ({
1184
+ x,
1185
+ y,
1186
+ z,
1187
+ w
1188
+ }));
1189
+ }
1190
+ /**
1191
+ * Declares a rotation field.
1192
+ *
1193
+ * @param defaultValue - The value a new component starts with; defaults to the identity rotation.
1194
+ * @param options - Inspector and serializer metadata.
1195
+ * @returns The field definition.
1196
+ *
1197
+ * @public
1198
+ */
1199
+ function quat(defaultValue = IDENTITY_QUAT, options) {
1200
+ const { x, y, z, w } = defaultValue;
1201
+ return field({
1202
+ kind: FieldKind.quat,
1203
+ components: 4
1204
+ }, options, () => ({
1205
+ x,
1206
+ y,
1207
+ z,
1208
+ w
1209
+ }));
1210
+ }
1211
+ /**
1212
+ * Declares an RGBA color field. Channels are sRGB in the 0–1 range, in memory and in files alike:
1213
+ * conversion to linear space belongs to the renderer, not the schema
1214
+ * (`docs/architecture/06-serialization-and-scene-format.md` §3).
1215
+ *
1216
+ * @param defaultValue - The starting color, either as channels or as a `#rgb`/`#rgba`/`#rrggbb`/
1217
+ * `#rrggbbaa` string; defaults to opaque white.
1218
+ * @param options - Inspector and serializer metadata.
1219
+ * @returns The field definition.
1220
+ * @throws A `TypeError` when a string default is not a valid hexadecimal color.
1221
+ *
1222
+ * @example
1223
+ * ```ts
1224
+ * tint: color("#ffffff");
1225
+ * ```
1226
+ *
1227
+ * @public
1228
+ */
1229
+ function color(defaultValue = WHITE, options) {
1230
+ const { r, g, b, a } = typeof defaultValue === "string" ? parseHexColor(defaultValue) : defaultValue;
1231
+ return field({ kind: FieldKind.color }, options, () => ({
1232
+ r,
1233
+ g,
1234
+ b,
1235
+ a
1236
+ }));
1237
+ }
1238
+ /**
1239
+ * Declares a field restricted to a fixed set of string values.
1240
+ *
1241
+ * @param values - Every accepted value, in the order the inspector should list them.
1242
+ * @param defaultValue - The value a new component starts with; `NoInfer` keeps it out of the
1243
+ * inference for `T`, so passing a value `values` does not contain is a compile error as well as a
1244
+ * runtime one.
1245
+ * @param options - Inspector and serializer metadata.
1246
+ * @returns The field definition.
1247
+ * @throws A `TypeError` when `defaultValue` is not one of `values`.
1248
+ *
1249
+ * @example
1250
+ * ```ts
1251
+ * mode: enumOf(["walk", "run"] as const, "walk");
1252
+ * ```
1253
+ *
1254
+ * @public
1255
+ */
1256
+ function enumOf(values, defaultValue, options) {
1257
+ if (!values.includes(defaultValue)) throwSchemaError(SchemaIssueCode.outOfRange, `enumOf default "${defaultValue}" is not one of [${values.join(", ")}].`);
1258
+ return field({
1259
+ kind: FieldKind.enum,
1260
+ values: [...values]
1261
+ }, options, () => defaultValue);
1262
+ }
1263
+ /**
1264
+ * Declares a reference to another entity in the same scene file. The value is `null` until the
1265
+ * scene is fully constructed and is nulled again when the target is destroyed
1266
+ * (`docs/architecture/03-scripting-and-components.md` §3).
1267
+ *
1268
+ * The entity type is supplied by the caller because `Entity` lives in the kernel, which is layered
1269
+ * above this module.
1270
+ *
1271
+ * @typeParam E - The entity type the reference resolves to.
1272
+ * @param options - Inspector and serializer metadata.
1273
+ * @returns The field definition.
1274
+ *
1275
+ * @example
1276
+ * ```ts
1277
+ * target: entityRef<Entity>();
1278
+ * ```
1279
+ *
1280
+ * @public
1281
+ */
1282
+ function entityRef(options) {
1283
+ return field({ kind: FieldKind.entityRef }, options, () => null);
1284
+ }
1285
+ /**
1286
+ * Declares a reference to a component on an entity in the same scene file.
1287
+ *
1288
+ * @typeParam C - The component type the reference resolves to, inferred from the class.
1289
+ * @param type - The component class the field may point at.
1290
+ * @param options - Inspector and serializer metadata.
1291
+ * @returns The field definition.
1292
+ *
1293
+ * @example
1294
+ * ```ts
1295
+ * follow: componentRef(Camera); // Camera | null
1296
+ * ```
1297
+ *
1298
+ * @public
1299
+ */
1300
+ function componentRef(type, options) {
1301
+ return field({
1302
+ kind: FieldKind.componentRef,
1303
+ componentType: type
1304
+ }, options, () => null);
1305
+ }
1306
+ /**
1307
+ * Declares a reference to an addressable asset. The **runtime** value is the loaded
1308
+ * {@link AssetHandle}, not an address: a component's `asset()` fields are resolved before its props
1309
+ * are written, so `awake` can already read `this.mesh.value`
1310
+ * (`docs/architecture/05-assets-and-loading.md` §3).
1311
+ *
1312
+ * @remarks
1313
+ * Files store the address instead — `{ "$asset": "models/hero.glb", "type"?: "model" }`
1314
+ * (`06-serialization-and-scene-format.md` §3). Encoding reads `handle.address`; decoding hands that
1315
+ * address to the `asset` resolver of the `ReferenceDecoder` the scene loader supplies, which answers
1316
+ * with the handle the scene already retains. Two consequences game code sees:
1317
+ *
1318
+ * - An address the resolver cannot answer decodes to `null` and reports `IGX-0602`; the component
1319
+ * keeps working with a missing asset rather than failing the whole scene.
1320
+ * - An **in-code** asset — anything from `Assets.register`, which includes `MeshAsset.box(…)` and
1321
+ * `createMaterialAsset(app, pbrMaterialDefinition({ … }))` — lives at a `memory:` address that names no file, so serializing a
1322
+ * component that holds one writes `null` and reports the loss. Save the asset as a file when it
1323
+ * has to survive a round trip.
1324
+ *
1325
+ * The field does **not** retain the handle: the scene instance that loaded it owns the reference
1326
+ * count and releases it on unload.
1327
+ *
1328
+ * @typeParam A - The asset type the reference points at, inferred from the class.
1329
+ * @param type - The asset class the field may point at.
1330
+ * @param options - Inspector and serializer metadata.
1331
+ * @returns The field definition.
1332
+ *
1333
+ * @example
1334
+ * ```ts
1335
+ * class Hero extends Component.define({ clip: asset(AudioClip) }) {
1336
+ * static typeId = "mygame/Hero";
1337
+ * awake(): void {
1338
+ * this.clip?.value.play();
1339
+ * }
1340
+ * }
1341
+ * ```
1342
+ *
1343
+ * @public
1344
+ */
1345
+ function asset(type, options) {
1346
+ const typeName = type.assetType ?? null;
1347
+ return field({
1348
+ kind: FieldKind.asset,
1349
+ assetType: type,
1350
+ typeName
1351
+ }, options, () => null);
1352
+ }
1353
+ /**
1354
+ * Declares a list field. The runtime value type is a *mutable* array because game code is expected
1355
+ * to push to it (`this.waypoints.push(p)`); the default is copied on every instantiation, shallowly,
1356
+ * so element objects supplied as defaults are shared and should be treated as immutable.
1357
+ *
1358
+ * @typeParam T - The element value type, inferred from `item`.
1359
+ * @param item - The field definition every element follows.
1360
+ * @param defaultValue - The list a new component starts with; defaults to empty.
1361
+ * @param options - Inspector and serializer metadata.
1362
+ * @returns The field definition.
1363
+ *
1364
+ * @example
1365
+ * ```ts
1366
+ * waypoints: array(vec3()); // Vec3Like[]
1367
+ * ```
1368
+ *
1369
+ * @public
1370
+ */
1371
+ function array(item, defaultValue = [], options) {
1372
+ const snapshot = [...defaultValue];
1373
+ return field({
1374
+ kind: FieldKind.array,
1375
+ item
1376
+ }, options, () => [...snapshot]);
1377
+ }
1378
+ /**
1379
+ * Declares a fixed group of named sub-fields. Sub-fields are serialized as a nested JSON object in
1380
+ * declaration order and validated recursively.
1381
+ *
1382
+ * @typeParam S - The sub-schema, inferred from `fields`.
1383
+ * @param fields - The sub-fields.
1384
+ * @param options - Inspector and serializer metadata.
1385
+ * @returns The field definition.
1386
+ * @throws IgnifxError with code `IGX-0607` when a sub-field name is an `Object.prototype` member
1387
+ * such as `__proto__`, `constructor`, or `toString`.
1388
+ *
1389
+ * @example
1390
+ * ```ts
1391
+ * stats: record({ hp: i32(10), armor: f32(0) }); // { hp: number; armor: number }
1392
+ * ```
1393
+ *
1394
+ * @public
1395
+ */
1396
+ function record(fields, options) {
1397
+ assertNoInheritedFieldNames(fields, "record");
1398
+ return field({
1399
+ kind: FieldKind.record,
1400
+ fields
1401
+ }, options, () => createDefaults(fields));
1402
+ }
1403
+ /**
1404
+ * Declares a string-keyed dictionary field. Keys are written in lexicographic order so that two
1405
+ * saves of the same state are byte-identical
1406
+ * (`docs/architecture/06-serialization-and-scene-format.md` §1).
1407
+ *
1408
+ * @typeParam T - The entry value type, inferred from `value`.
1409
+ * @param value - The field definition every entry's value follows.
1410
+ * @param options - Inspector and serializer metadata.
1411
+ * @returns The field definition.
1412
+ *
1413
+ * @example
1414
+ * ```ts
1415
+ * ammo: map(i32(0)); // Record<string, number>
1416
+ * ```
1417
+ *
1418
+ * @public
1419
+ */
1420
+ function map(value, options) {
1421
+ return field({
1422
+ kind: FieldKind.map,
1423
+ value
1424
+ }, options, () => ({}));
1425
+ }
1426
+ /**
1427
+ * Declares a field that may also be `null`, defaulting to `null` (coding standards §5.5: `null` is
1428
+ * "absent value", `undefined` never reaches a file).
1429
+ *
1430
+ * @typeParam T - The value type when present, inferred from `inner`.
1431
+ * @param inner - The field definition a non-`null` value follows.
1432
+ * @param options - Inspector and serializer metadata.
1433
+ * @returns The field definition.
1434
+ *
1435
+ * @example
1436
+ * ```ts
1437
+ * nickname: optional(str()); // string | null
1438
+ * ```
1439
+ *
1440
+ * @public
1441
+ */
1442
+ function optional(inner, options) {
1443
+ return field({
1444
+ kind: FieldKind.optional,
1445
+ inner
1446
+ }, options, () => null);
1447
+ }
1448
+ /**
1449
+ * Declares a set of layers. Layers are stored by *name*, not by bit value, so renaming a layer in
1450
+ * project settings does not silently repoint existing files
1451
+ * (`docs/architecture/06-serialization-and-scene-format.md` §3).
1452
+ *
1453
+ * The field's value is a read-only array of names. The kernel's `LayerMask` satisfies the same
1454
+ * structural shape, so a component may hold either.
1455
+ *
1456
+ * @param defaultValue - The names a new component starts with; defaults to empty.
1457
+ * @param options - Inspector and serializer metadata.
1458
+ * @returns The field definition.
1459
+ *
1460
+ * @example
1461
+ * ```ts
1462
+ * collidesWith: layerMask(["Default", "Enemy"]);
1463
+ * ```
1464
+ *
1465
+ * @public
1466
+ */
1467
+ function layerMask(defaultValue = [], options) {
1468
+ const snapshot = [...defaultValue];
1469
+ return field({ kind: FieldKind.layerMask }, options, () => [...snapshot]);
1470
+ }
1471
+ /**
1472
+ * Declares an animation curve field.
1473
+ *
1474
+ * @param defaultValue - The curve a new component starts with; defaults to no keys.
1475
+ * @param options - Inspector and serializer metadata.
1476
+ * @returns The field definition.
1477
+ *
1478
+ * @example
1479
+ * ```ts
1480
+ * falloff: curve({ keys: [[0, 1, 0, 0], [1, 0, 0, 0]] });
1481
+ * ```
1482
+ *
1483
+ * @public
1484
+ */
1485
+ function curve(defaultValue = EMPTY_CURVE, options) {
1486
+ const keys = defaultValue.keys.map((key) => [
1487
+ key[0],
1488
+ key[1],
1489
+ key[2],
1490
+ key[3]
1491
+ ]);
1492
+ return field({ kind: FieldKind.curve }, options, () => ({ keys: [...keys] }));
1493
+ }
1494
+ /**
1495
+ * Declares a field whose JSON form is written by hand. Use it for value types the built-in kinds
1496
+ * cannot express; the codec owns the default, the encoding, and the generated JSON Schema fragment.
1497
+ *
1498
+ * @typeParam T - The runtime value type.
1499
+ * @param codec - The default factory, `serialize`, `deserialize`, and optional `jsonSchema`.
1500
+ * @param options - Inspector and serializer metadata.
1501
+ * @returns The field definition.
1502
+ *
1503
+ * @example
1504
+ * ```ts
1505
+ * grid: custom({
1506
+ * createDefault: () => new Uint8Array(16),
1507
+ * serialize: (value) => [...value],
1508
+ * deserialize: (json) => Uint8Array.from(Array.isArray(json) ? json.map(Number) : []),
1509
+ * jsonSchema: { type: "array", items: { type: "integer" } },
1510
+ * });
1511
+ * ```
1512
+ *
1513
+ * @public
1514
+ */
1515
+ function custom(codec, options) {
1516
+ return field({
1517
+ kind: FieldKind.custom,
1518
+ codec
1519
+ }, options, () => codec.createDefault());
1520
+ }
1521
+ //#endregion
1522
+ //#region src/render/render-texture.ts
1523
+ /**
1524
+ * The largest side of a render texture, in pixels.
1525
+ *
1526
+ * @public
1527
+ */
1528
+ const RENDER_TEXTURE_MAX_SIZE = 4096;
1529
+ /**
1530
+ * The Babylon Lite `metadata` key that keeps a render-scene mesh out of every render texture.
1531
+ *
1532
+ * @remarks
1533
+ * A mesh whose `metadata[EDITOR_ONLY_METADATA_KEY]` is `true` draws in the main view but never in
1534
+ * a {@link RenderTexture}: an editor's grid or helper that must not show in its game view or
1535
+ * thumbnails. Set it on a mesh reached through a `.lite` escape hatch, such as
1536
+ * `RenderOverlay.lite.mainScene` (no stability guarantee, `CONSTITUTION.md` §3.4).
1537
+ *
1538
+ * @beta
1539
+ */
1540
+ const EDITOR_ONLY_METADATA_KEY = "ignifxEditorOnly";
1541
+ /**
1542
+ * Checks a render texture's size.
1543
+ *
1544
+ * @param width - The requested width.
1545
+ * @param height - The requested height.
1546
+ * @throws IgnifxError with code `IGX-0730` for a side that is not a whole number from 1 to
1547
+ * {@link RENDER_TEXTURE_MAX_SIZE}.
1548
+ *
1549
+ * @internal
1550
+ */
1551
+ function assertRenderTextureSize(width, height) {
1552
+ const isSide = (side) => Number.isSafeInteger(side) && side >= 1 && side <= 4096;
1553
+ if (!isSide(width) || !isSide(height)) throw new IgnifxError(CoreErrorCode.invalidRenderTextureSize, `A render texture of ${String(width)}x${String(height)}: each side must be a whole number from 1 to ${String(RENDER_TEXTURE_MAX_SIZE)}.`, { context: {
1554
+ member: "app.renderer.createRenderTexture()",
1555
+ width,
1556
+ height,
1557
+ max: RENDER_TEXTURE_MAX_SIZE
1558
+ } });
1559
+ }
1560
+ /**
1561
+ * Tells each live texture which enabled, attached camera renders into it this frame.
1562
+ *
1563
+ * @param cameras - Every camera in the world, in creation order; the last one per texture wins.
1564
+ * @param live - The renderer's live textures; a camera aiming at any other is ignored.
1565
+ *
1566
+ * @internal
1567
+ */
1568
+ function bindFrameCameras(cameras, live) {
1569
+ for (const camera of cameras) {
1570
+ const target = camera.renderTarget;
1571
+ const lite = camera.lite.camera;
1572
+ if (target instanceof RenderTextureImpl && live.has(target) && lite !== null && camera.isEnabledInHierarchy) target.setFrameCamera(lite);
1573
+ }
1574
+ }
1575
+ /**
1576
+ * The renderer's render texture: the per-frame camera choice and the one-frame requests.
1577
+ *
1578
+ * @internal
1579
+ */
1580
+ var RenderTextureImpl = class {
1581
+ width;
1582
+ height;
1583
+ #owner;
1584
+ #pass = null;
1585
+ #creating = null;
1586
+ /** The camera whose `renderTarget` this is, as the current frame's sync found it. */
1587
+ #frameCamera = null;
1588
+ #requests = [];
1589
+ #isDisposed = false;
1590
+ /**
1591
+ * Creates the texture; its GPU pass is created on first use.
1592
+ *
1593
+ * @param owner - The renderer.
1594
+ * @param width - The checked width.
1595
+ * @param height - The checked height.
1596
+ */
1597
+ constructor(owner, width, height) {
1598
+ this.#owner = owner;
1599
+ this.width = width;
1600
+ this.height = height;
1601
+ }
1602
+ get isDisposed() {
1603
+ return this.#isDisposed;
1604
+ }
1605
+ /**
1606
+ * Resolves the texture's GPU pass, creating it once.
1607
+ *
1608
+ * @param member - The API member asking, for the error.
1609
+ * @returns The pass.
1610
+ */
1611
+ async pass(member) {
1612
+ this.assertUsable(member);
1613
+ this.#creating ??= this.#owner.createPass(this.width, this.height, member).then((pass) => {
1614
+ if (this.#isDisposed) pass.dispose();
1615
+ else this.#pass = pass;
1616
+ return pass;
1617
+ }, (error) => {
1618
+ this.#creating = null;
1619
+ throw error;
1620
+ });
1621
+ const pass = await this.#creating;
1622
+ this.assertUsable(member);
1623
+ return pass;
1624
+ }
1625
+ /**
1626
+ * Queues a render through a camera on the next frame.
1627
+ *
1628
+ * @param camera - The Lite camera.
1629
+ * @returns A promise that settles once that frame has been submitted.
1630
+ */
1631
+ request(camera) {
1632
+ return new Promise((resolve) => {
1633
+ this.#requests.push({
1634
+ camera,
1635
+ resolve
1636
+ });
1637
+ });
1638
+ }
1639
+ /**
1640
+ * Notes the camera that renders into this texture every frame. The render sync system calls it
1641
+ * for every enabled camera whose `renderTarget` this is, before {@link RenderTextureImpl.flush}.
1642
+ *
1643
+ * @param camera - The Lite camera.
1644
+ */
1645
+ setFrameCamera(camera) {
1646
+ this.#frameCamera = camera;
1647
+ if (this.#pass === null && this.#creating === null) this.pass("Camera.renderTarget").catch(() => null);
1648
+ }
1649
+ /**
1650
+ * Points the pass at this frame's camera: the oldest request's, else the `renderTarget` one's,
1651
+ * else none. Requests for that camera settle once the frame is submitted.
1652
+ */
1653
+ flush() {
1654
+ const pass = this.#pass;
1655
+ const requested = this.#requests[0]?.camera ?? null;
1656
+ const camera = requested ?? this.#frameCamera;
1657
+ this.#frameCamera = null;
1658
+ if (pass === null) return;
1659
+ pass.setCamera(camera);
1660
+ if (requested === null) return;
1661
+ const served = [];
1662
+ for (let index = this.#requests.length - 1; index >= 0; index -= 1) {
1663
+ const pending = this.#requests[index];
1664
+ if (pending !== void 0 && pending.camera === requested) {
1665
+ served.push(pending);
1666
+ this.#requests.splice(index, 1);
1667
+ }
1668
+ }
1669
+ queueMicrotask(() => {
1670
+ for (const pending of served) pending.resolve();
1671
+ });
1672
+ }
1673
+ async readPixels() {
1674
+ const data = await (await this.pass("RenderTexture.readPixels()")).read();
1675
+ return {
1676
+ width: this.width,
1677
+ height: this.height,
1678
+ data
1679
+ };
1680
+ }
1681
+ dispose() {
1682
+ if (this.#isDisposed) return;
1683
+ this.#isDisposed = true;
1684
+ this.#pass?.dispose();
1685
+ this.#pass = null;
1686
+ this.#owner.release(this);
1687
+ for (const pending of this.#requests.splice(0)) pending.resolve();
1688
+ }
1689
+ /**
1690
+ * Refuses a disposed texture.
1691
+ *
1692
+ * @param member - The API member asking.
1693
+ * @throws IgnifxError with code `IGX-0731` once disposed.
1694
+ */
1695
+ assertUsable(member) {
1696
+ if (this.#isDisposed) throw renderTextureUnusableError(member);
1697
+ }
1698
+ };
1699
+ /**
1700
+ * The error for a disposed or foreign render texture.
1701
+ *
1702
+ * @param member - The API member asking.
1703
+ * @returns The error.
1704
+ *
1705
+ * @internal
1706
+ */
1707
+ function renderTextureUnusableError(member) {
1708
+ return new IgnifxError(CoreErrorCode.renderTextureUnusable, `${member}: the render texture is disposed or belongs to another app.`, {
1709
+ context: { member },
1710
+ hint: "Create a render texture with this app's app.renderer.createRenderTexture() and keep it until you dispose it."
1711
+ });
1712
+ }
1713
+ //#endregion
1714
+ //#region src/render/reflection-probe.ts
1715
+ /**
1716
+ * The `ReflectionProbe` component (`docs/plan/2026-11-gi-phase-2-execution-plan.md`, step B1).
1717
+ *
1718
+ * The component only holds settings and the "capture again" request. The renderer loads the probe's
1719
+ * GPU code (`./gpu/reflection-probes.ts`, `../lite/gpu/reflection-probe.ts`) only once a world has
1720
+ * a probe, so a project without one pays nothing for it (`CONSTITUTION.md` §2.5). Headless, a probe
1721
+ * captures nothing.
1722
+ */
1723
+ /**
1724
+ * The `as const` name table behind {@link ReflectionProbeRefreshMode}.
1725
+ *
1726
+ * @public
1727
+ */
1728
+ const REFLECTION_PROBE_REFRESH_MODES = [
1729
+ "once",
1730
+ "onDemand",
1731
+ "everyFrame"
1732
+ ];
1733
+ /** The smallest and largest cube face, in pixels. */
1734
+ const MIN_SIZE = 16;
1735
+ const MAX_SIZE = 1024;
1736
+ /**
1737
+ * A point that captures the scene around it into a cube map, which nearby shiny PBR materials then
1738
+ * reflect instead of the scene environment.
1739
+ *
1740
+ * @remarks
1741
+ * Each lit PBR material reflects the nearest enabled probe that has captured: a probe whose
1742
+ * `boxProjection` box holds the mesh wins over one that does not, then the closer probe wins. With no
1743
+ * probe, materials reflect the `Environment` again. A material shared by several meshes follows the
1744
+ * first of them. Diffuse lighting still comes from the scene environment.
1745
+ *
1746
+ * The probe needs a loaded `Environment` (it reuses its lighting tables) and a canvas-backed app.
1747
+ * Mip levels are box-filtered, so very rough materials look blurrier than with a prefiltered `.env`.
1748
+ *
1749
+ * @example
1750
+ * ```ts
1751
+ * const probe = world.createEntity("Room probe", { position: { x: 0, y: 1.5, z: 0 } });
1752
+ * probe.addComponent(ReflectionProbe, { size: 128, boxProjection: { x: 8, y: 3, z: 8 } });
1753
+ * ```
1754
+ *
1755
+ * @beta
1756
+ */
1757
+ var ReflectionProbe = class ReflectionProbe extends Component {
1758
+ /** The namespaced registration id. */
1759
+ static typeId = "ignifx/ReflectionProbe";
1760
+ /** What the component does, in one line, for an inspector. */
1761
+ static description = "Captures the scene around it into a cube map that nearby PBR materials reflect.";
1762
+ /** One probe per entity. */
1763
+ static allowMultiple = false;
1764
+ /** The serialized field declarations (ADR-0004). */
1765
+ static schema = reflectionProbeSchema();
1766
+ /** Applies the schema defaults, exactly as `Component.define` would. */
1767
+ constructor() {
1768
+ super();
1769
+ Object.assign(this, createDefaults(ReflectionProbe.schema));
1770
+ }
1771
+ #isRefreshRequested = false;
1772
+ /**
1773
+ * Asks the probe to capture again from the next frame, whatever its `refreshMode`.
1774
+ *
1775
+ * @remarks
1776
+ * Call it after the static scene around the probe changed, such as a door opening. A capture
1777
+ * repeats over a few frames, so meshes whose materials are still compiling are caught.
1778
+ */
1779
+ refresh() {
1780
+ this.#isRefreshRequested = true;
1781
+ }
1782
+ /**
1783
+ * Reads and clears the request {@link ReflectionProbe.refresh} made.
1784
+ *
1785
+ * @returns Whether a capture was requested since the last call.
1786
+ *
1787
+ * @internal
1788
+ */
1789
+ consumeRefreshRequest() {
1790
+ const requested = this.#isRefreshRequested;
1791
+ this.#isRefreshRequested = false;
1792
+ return requested;
1793
+ }
1794
+ };
1795
+ /**
1796
+ * The cube face size a probe captures at.
1797
+ *
1798
+ * @param size - The authored size.
1799
+ * @returns `size` rounded down to a power of two and clamped to 16..1024; 128 for a value that is not
1800
+ * a finite number.
1801
+ *
1802
+ * @internal
1803
+ */
1804
+ function resolveReflectionProbeSize(size) {
1805
+ if (!Number.isFinite(size)) return 128;
1806
+ return 2 ** Math.floor(Math.log2(Math.min(MAX_SIZE, Math.max(MIN_SIZE, Math.floor(size)))));
1807
+ }
1808
+ /**
1809
+ * Picks the probe a point reflects.
1810
+ *
1811
+ * @remarks
1812
+ * A probe whose box holds the point wins, the smallest such box first; with none, the closest
1813
+ * probe centre wins. Ties keep the earlier probe.
1814
+ *
1815
+ * @param x - The point's world X.
1816
+ * @param y - The point's world Y.
1817
+ * @param z - The point's world Z.
1818
+ * @param candidates - The enabled probes that have captured.
1819
+ * @returns The index of the chosen probe, or `-1` when there is none.
1820
+ *
1821
+ * @internal
1822
+ */
1823
+ function selectReflectionProbe(x, y, z, candidates) {
1824
+ let inside = -1;
1825
+ let insideVolume = Number.POSITIVE_INFINITY;
1826
+ let nearest = -1;
1827
+ let nearestDistance = Number.POSITIVE_INFINITY;
1828
+ for (let index = 0; index < candidates.length; index += 1) {
1829
+ const probe = candidates[index];
1830
+ if (probe === void 0) continue;
1831
+ const dx = x - probe.x;
1832
+ const dy = y - probe.y;
1833
+ const dz = z - probe.z;
1834
+ const box = probe.box;
1835
+ if (box !== null && Math.abs(dx) <= box.x / 2 && Math.abs(dy) <= box.y / 2 && Math.abs(dz) <= box.z / 2) {
1836
+ const volume = box.x * box.y * box.z;
1837
+ if (volume < insideVolume) {
1838
+ inside = index;
1839
+ insideVolume = volume;
1840
+ }
1841
+ }
1842
+ const distance = dx * dx + dy * dy + dz * dz;
1843
+ if (distance < nearestDistance) {
1844
+ nearest = index;
1845
+ nearestDistance = distance;
1846
+ }
1847
+ }
1848
+ return inside >= 0 ? inside : nearest;
1849
+ }
1850
+ /**
1851
+ * Builds the component's declared fields.
1852
+ *
1853
+ * @returns The schema. Built inside a function: module scope holds declarations and immutable
1854
+ * constants only (`CONSTITUTION.md` §3.5).
1855
+ */
1856
+ function reflectionProbeSchema() {
1857
+ return defineSchema({
1858
+ size: u32(128, {
1859
+ min: MIN_SIZE,
1860
+ max: MAX_SIZE,
1861
+ tooltip: "Cube face size in pixels, rounded down to a power of two. Larger is sharper and slower to capture."
1862
+ }),
1863
+ refreshMode: enumOf(REFLECTION_PROBE_REFRESH_MODES, "once", { tooltip: "once: capture when ready and on refresh(); onDemand: only on refresh(); everyFrame: every frame (costly; one probe, desktop high tier only)." }),
1864
+ boxProjection: optional(vec3({
1865
+ x: 10,
1866
+ y: 10,
1867
+ z: 10
1868
+ }), { tooltip: "Full size in metres of the box, centred on the probe, that reflections are projected onto; null for none." }),
1869
+ cullingMask: layerMask([], { tooltip: "The layers the probe captures; empty captures every layer." }),
1870
+ near: f32(.1, {
1871
+ min: .001,
1872
+ tooltip: "Near clip distance of the capture, in metres."
1873
+ }),
1874
+ far: f32(1e3, {
1875
+ min: .01,
1876
+ tooltip: "Far clip distance of the capture, in metres."
1877
+ })
1878
+ });
1879
+ }
1880
+ //#endregion
1881
+ export { vec2 as A, readPickedTag as B, layerMask as C, record as D, quat as E, raycastScene as F, toComponentHandle as G, Component as H, raycastSceneWhere as I, assertNoInheritedFieldNames as J, toEntityHandle as K, readOwnerTag as L, vec4 as M, FieldKind as N, str as O, createPickRay as P, readPickedIdentity as R, i32 as S, optional as T, componentInternals as U, setPickRay as V, INVALID_HANDLE as W, defineSchema as X, createDefaults as Y, Signal as Z, custom as _, EDITOR_ONLY_METADATA_KEY as a, f32 as b, assertRenderTextureSize as c, array as d, asset as f, curve as g, componentRef as h, selectReflectionProbe as i, vec3 as j, u32 as k, bindFrameCameras as l, color as m, ReflectionProbe as n, RENDER_TEXTURE_MAX_SIZE as o, bool as p, applyInit as q, resolveReflectionProbeSize as r, RenderTextureImpl as s, REFLECTION_PROBE_REFRESH_MODES as t, renderTextureUnusableError as u, entityRef as v, map as w, f64 as x, enumOf as y, readPickedMeshName as z };
1882
+
1883
+ //# sourceMappingURL=reflection-probe-C0pzGrG_.js.map