@ignifx/editor-host 0.9.0 → 0.10.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.
@@ -0,0 +1,2628 @@
1
+ import { n as isEditorOrigin, t as EditorHostErrorCode } from "./error-codes.js";
2
+ import { App, AssetsCreateOptions, ConcreteComponentType, Extension, RenderSurface, SceneInstance, SettingsInput } from "@ignifx/core";
3
+ //#region src/protocol/connect.d.ts
4
+ /**
5
+ * The `type` of the window message that hands a host its `MessagePort`.
6
+ *
7
+ * @remarks
8
+ * The editor posts `{ type: EDITOR_CONNECT_MESSAGE_TYPE }` to the view's window, targeted at the
9
+ * view's origin, with the port as the one transferred object. It posts a fresh one after every load
10
+ * of the view: a port that has been transferred once cannot be sent again, and the newest port
11
+ * replaces the previous one. The host ignores the message unless `event.origin` is the editor's
12
+ * origin, the data is this shape, and exactly one port is attached.
13
+ *
14
+ * @example
15
+ * ```ts
16
+ * const channel = new MessageChannel();
17
+ * frame.contentWindow?.postMessage({ type: EDITOR_CONNECT_MESSAGE_TYPE }, "http://127.0.0.1:5173", [channel.port2]);
18
+ * ```
19
+ *
20
+ * @public
21
+ */
22
+ export declare const EDITOR_CONNECT_MESSAGE_TYPE = "ignifx-editor/connect";
23
+ /**
24
+ * The window message that hands a host its `MessagePort`; the port travels as its one transferred
25
+ * object, not inside the data.
26
+ *
27
+ * @public
28
+ */
29
+ interface EditorConnectMessage {
30
+ /** Always {@link EDITOR_CONNECT_MESSAGE_TYPE}. */
31
+ readonly type: typeof EDITOR_CONNECT_MESSAGE_TYPE;
32
+ }
33
+ /**
34
+ * Tells whether a window message's data is the connect message. It checks the data only; the
35
+ * caller still checks `event.origin` and that `event.ports` holds exactly one port.
36
+ *
37
+ * @param value - The `data` of a received `MessageEvent`.
38
+ * @returns True when `value` is an object whose `type` is {@link EDITOR_CONNECT_MESSAGE_TYPE}.
39
+ *
40
+ * @public
41
+ */
42
+ export declare function isEditorConnectMessage(value: unknown): value is EditorConnectMessage;
43
+ //#endregion
44
+ //#region src/protocol/rpc.d.ts
45
+ /**
46
+ * JSON-RPC 2.0 envelopes (https://www.jsonrpc.org/specification) shared by every editor channel:
47
+ * editor↔host and editor↔play over a `MessagePort`.
48
+ */
49
+ /**
50
+ * The value of every envelope's `jsonrpc` field.
51
+ *
52
+ * @public
53
+ */
54
+ export declare const JSON_RPC_VERSION = "2.0";
55
+ /**
56
+ * A request id, chosen by the sender and echoed in the response.
57
+ *
58
+ * @public
59
+ */
60
+ type RpcId = string | number;
61
+ /**
62
+ * The error codes a peer may send. The first five are JSON-RPC's own; the rest use the range
63
+ * JSON-RPC reserves for implementations (-32000 to -32099).
64
+ *
65
+ * @remarks
66
+ * `as const` object plus derived union rather than an `enum` (engine coding standards §5.2, §5.3).
67
+ *
68
+ * @public
69
+ */
70
+ export declare const RpcErrorCode: {
71
+ /** The message was not valid JSON. */
72
+ readonly parseError: -32_700;
73
+ /** The message was JSON but not a valid request. */
74
+ readonly invalidRequest: -32_600;
75
+ /** No handler exists for the method. */
76
+ readonly methodNotFound: -32_601;
77
+ /** The method exists but its `params` are wrong. */
78
+ readonly invalidParams: -32_602;
79
+ /** The handler failed. */
80
+ readonly internalError: -32_603;
81
+ /** The peers' protocol versions are incompatible (see `protocolVersionIsCompatible`). */
82
+ readonly incompatibleProtocol: -32_000;
83
+ /**
84
+ * The peer cannot answer this method yet: it has not finished its handshake, or (a scene host)
85
+ * its app has not started.
86
+ */
87
+ readonly notReady: -32_001;
88
+ /** A scene method that needs an open scene was called while none is open (`SceneMethod`). */
89
+ readonly noScene: -32_002;
90
+ };
91
+ /**
92
+ * The union of the codes in `RpcErrorCode`.
93
+ *
94
+ * @public
95
+ */
96
+ export type RpcErrorCode = (typeof RpcErrorCode)[keyof typeof RpcErrorCode];
97
+ /**
98
+ * The `error` member of a failed response.
99
+ *
100
+ * @public
101
+ */
102
+ interface RpcError {
103
+ /** What kind of failure it was. */
104
+ readonly code: RpcErrorCode;
105
+ /** A short, human-readable description. */
106
+ readonly message: string;
107
+ /** Extra detail for debugging; its shape depends on the method. */
108
+ readonly data?: unknown;
109
+ }
110
+ /**
111
+ * A call that expects a response with the same `id`.
112
+ *
113
+ * @typeParam M - The method name.
114
+ * @typeParam P - The parameters; omitted when the method takes none.
115
+ *
116
+ * @public
117
+ */
118
+ interface RpcRequest<M extends string = string, P = unknown> {
119
+ /** Always `"2.0"`. */
120
+ readonly jsonrpc: typeof JSON_RPC_VERSION;
121
+ /** Matches the response to this request. */
122
+ readonly id: RpcId;
123
+ /** The method to call. */
124
+ readonly method: M;
125
+ /** The method's arguments, an object or an array in JSON. */
126
+ readonly params?: P;
127
+ }
128
+ /**
129
+ * A one-way message: like a request, but with no `id` and no response.
130
+ *
131
+ * @typeParam M - The method name.
132
+ * @typeParam P - The parameters; omitted when the method takes none.
133
+ *
134
+ * @public
135
+ */
136
+ interface RpcNotification<M extends string = string, P = unknown> {
137
+ /** Always `"2.0"`. */
138
+ readonly jsonrpc: typeof JSON_RPC_VERSION;
139
+ /** The event or method being signalled. */
140
+ readonly method: M;
141
+ /** The message's arguments, an object or an array in JSON. */
142
+ readonly params?: P;
143
+ }
144
+ /**
145
+ * The answer to a request that succeeded.
146
+ *
147
+ * @typeParam R - The result.
148
+ *
149
+ * @public
150
+ */
151
+ interface RpcSuccessResponse<R = unknown> {
152
+ /** Always `"2.0"`. */
153
+ readonly jsonrpc: typeof JSON_RPC_VERSION;
154
+ /** The `id` of the request being answered. */
155
+ readonly id: RpcId;
156
+ /** What the method returned. */
157
+ readonly result: R;
158
+ }
159
+ /**
160
+ * The answer to a request that failed.
161
+ *
162
+ * @public
163
+ */
164
+ interface RpcErrorResponse {
165
+ /** Always `"2.0"`. */
166
+ readonly jsonrpc: typeof JSON_RPC_VERSION;
167
+ /** The `id` of the request being answered, or `null` when it could not be read. */
168
+ readonly id: RpcId | null;
169
+ /** Why the request failed. */
170
+ readonly error: RpcError;
171
+ }
172
+ /**
173
+ * The answer to a request: a result or an error, never both.
174
+ *
175
+ * @typeParam R - The result on success.
176
+ *
177
+ * @public
178
+ */
179
+ type RpcResponse<R = unknown> = RpcSuccessResponse<R> | RpcErrorResponse;
180
+ /**
181
+ * Any message that can travel on an editor channel.
182
+ *
183
+ * @public
184
+ */
185
+ type RpcMessage = RpcRequest | RpcNotification | RpcResponse;
186
+ /**
187
+ * Checks the envelope of a received message: a request, a notification, or a response. It does not
188
+ * check a method's `params` or `result`; that is the handler's job.
189
+ *
190
+ * @param value - A value parsed from JSON or received through `postMessage`.
191
+ * @returns True when `value` is a well-formed JSON-RPC 2.0 message with a known error code, if any.
192
+ *
193
+ * @public
194
+ */
195
+ export declare function isRpcMessage(value: unknown): value is RpcMessage;
196
+ //#endregion
197
+ //#region src/protocol/version.d.ts
198
+ /**
199
+ * The protocol's own version, separate from the editor's and the engine's package versions.
200
+ */
201
+ /**
202
+ * A protocol version. `major` changes when a message changes incompatibly; `minor` when messages
203
+ * or fields are added in a way an older peer can ignore. Before 1.0 the minor plays the role of the
204
+ * major (ADR-E008), so every 0.x minor is its own incompatible line.
205
+ *
206
+ * @public
207
+ */
208
+ interface ProtocolVersion {
209
+ /** Incremented for incompatible changes. Peers must agree on it. */
210
+ readonly major: number;
211
+ /** Incremented for additions. From 1.0 peers may differ in it; before 1.0 they must agree on it too. */
212
+ readonly minor: number;
213
+ }
214
+ /**
215
+ * The protocol version this package describes. The editor sends it in `hello` and the host in
216
+ * `ready`.
217
+ *
218
+ * @public
219
+ */
220
+ export declare const PROTOCOL_VERSION: ProtocolVersion;
221
+ /**
222
+ * Tells whether two peers can talk.
223
+ *
224
+ * @remarks
225
+ * The rule is ADR-E008's: the protocol follows SemVer, and until 1.0 its minor plays the role of the
226
+ * major, as the engine's minors do. So from 1.0 two peers are compatible when their majors are
227
+ * equal and the minors are free to differ; before 1.0 the major and the minor must both be equal.
228
+ * The check is symmetric. Which versions the editor accepts beyond it (ADR-E008 has the editor
229
+ * support the current protocol line and the previous one) is the editor's decision, not this
230
+ * function's.
231
+ *
232
+ * @example
233
+ * ```ts
234
+ * protocolVersionIsCompatible({ major: 0, minor: 3 }, { major: 0, minor: 2 }); // false
235
+ * protocolVersionIsCompatible({ major: 1, minor: 0 }, { major: 1, minor: 4 }); // true
236
+ * ```
237
+ *
238
+ * @param a - One peer's protocol version.
239
+ * @param b - The other peer's protocol version.
240
+ * @returns `true` when the versions are on the same compatible line.
241
+ *
242
+ * @public
243
+ */
244
+ export declare function protocolVersionIsCompatible(a: ProtocolVersion, b: ProtocolVersion): boolean;
245
+ //#endregion
246
+ //#region src/protocol/handshake.d.ts
247
+ /**
248
+ * The method names of the handshake.
249
+ *
250
+ * @remarks
251
+ * `as const` object plus derived union rather than an `enum` (engine coding standards §5.2, §5.3).
252
+ *
253
+ * @public
254
+ */
255
+ export declare const HandshakeMethod: {
256
+ /** Editor → host: the first message on a new channel. */
257
+ readonly hello: "hello";
258
+ /** Either direction: a liveness check, answered with `"pong"`. */
259
+ readonly ping: "ping";
260
+ };
261
+ /**
262
+ * The union of the names in `HandshakeMethod`.
263
+ *
264
+ * @public
265
+ */
266
+ export type HandshakeMethod = (typeof HandshakeMethod)[keyof typeof HandshakeMethod];
267
+ /**
268
+ * Which kind of view a host runs.
269
+ *
270
+ * @public
271
+ */
272
+ export declare const HostKind: {
273
+ /** The scene view: an edit-mode app that applies document ops and draws gizmos. */
274
+ readonly scene: "scene";
275
+ /** The play view: the project's own page, running the game. */
276
+ readonly play: "play";
277
+ };
278
+ /**
279
+ * The union of the kinds in `HostKind`.
280
+ *
281
+ * @public
282
+ */
283
+ export type HostKind = (typeof HostKind)[keyof typeof HostKind];
284
+ /**
285
+ * The optional features a host lists in its `ready` result.
286
+ *
287
+ * @remarks
288
+ * The play controls send `["heartbeat", "playControls"]`. The scene host sends `"heartbeat"` and
289
+ * whichever of `"gizmos"`, `"screenshot"`, `"viewMode2d"` and `"pick2d"` it supports; every
290
+ * `SceneMethod` not tied to one of them is required of a 0.3 scene host.
291
+ *
292
+ * @public
293
+ */
294
+ export declare const HostCapability: {
295
+ /** The host sends `heartbeat` notifications after `ready` (see `HostNotification`). */
296
+ readonly heartbeat: "heartbeat";
297
+ /** The host answers the methods in `PlayMethod`. */
298
+ readonly playControls: "playControls";
299
+ /**
300
+ * The scene host draws gizmos on the primary selection, answers `setGizmo`, and sends
301
+ * `transformDragging` and `transformDragged`.
302
+ */
303
+ readonly gizmos: "gizmos";
304
+ /** The scene host answers `screenshot`. */
305
+ readonly screenshot: "screenshot";
306
+ /** The scene host accepts `setViewMode` with `"2d"`: a 2D editor camera and planar gizmos. */
307
+ readonly viewMode2d: "viewMode2d";
308
+ /**
309
+ * The scene host picks sprites in 2D view mode (`app.twoD.pickAt` from `@ignifx/2d`); without it,
310
+ * `pick` and view clicks in 2D mode resolve through the 3D picker only.
311
+ */
312
+ readonly pick2d: "pick2d";
313
+ /**
314
+ * The host relays the app's reports: `log` lines with the first `Error` each carries, a
315
+ * `hostError` with `AppErrorData` (entity, component, phase, stack) for every `app.onError`
316
+ * report, and `hotReloaded` with each error's stack. The scene view sends them as scene
317
+ * notifications, the play view as play notifications. Additive in 0.3.
318
+ */
319
+ readonly logRelay: "logRelay";
320
+ /**
321
+ * After a script's hot reload changes a field's default, the scene host gives the field its new
322
+ * default wherever the document leaves it out: on each document component whose record omits the
323
+ * field, and on the members of each prefab instance (rebuilt from the prefab, with the instance's
324
+ * overrides). A value the document sets is kept. An editor need not reopen the scene for changed
325
+ * defaults. Additive in 0.3.
326
+ */
327
+ readonly hotReloadDefaults: "hotReloadDefaults";
328
+ };
329
+ /**
330
+ * The union of the names in `HostCapability`.
331
+ *
332
+ * @public
333
+ */
334
+ export type HostCapability = (typeof HostCapability)[keyof typeof HostCapability];
335
+ /**
336
+ * What the editor says about itself in `hello`.
337
+ *
338
+ * @public
339
+ */
340
+ interface HelloParams {
341
+ /** The editor's own version, for example `"0.1.0"`. */
342
+ readonly editorVersion: string;
343
+ /** The protocol version the editor speaks. */
344
+ readonly protocol: ProtocolVersion;
345
+ }
346
+ /**
347
+ * Editor → host: the first request on a new channel.
348
+ *
349
+ * @public
350
+ */
351
+ interface HelloRequest extends RpcRequest<typeof HandshakeMethod.hello, HelloParams> {
352
+ /** What the editor says about itself. */
353
+ readonly params: HelloParams;
354
+ }
355
+ /**
356
+ * What a host says about itself in answer to `hello`.
357
+ *
358
+ * @public
359
+ */
360
+ interface ReadyResult {
361
+ /** The version of `@ignifx/core` the project runs, for example `"0.9.0"`. */
362
+ readonly engineVersion: string;
363
+ /** The protocol version the host speaks. */
364
+ readonly protocol: ProtocolVersion;
365
+ /**
366
+ * Optional features the host supports, named by `HostCapability`. Names are added as the
367
+ * protocol grows; a peer ignores names it does not know.
368
+ */
369
+ readonly capabilities: readonly string[];
370
+ /** Which view the host runs. */
371
+ readonly hostKind: HostKind;
372
+ }
373
+ /**
374
+ * Host → editor: the successful answer to {@link HelloRequest}.
375
+ *
376
+ * @public
377
+ */
378
+ type ReadyResponse = RpcSuccessResponse<ReadyResult>;
379
+ /**
380
+ * Either direction: a liveness check. It takes no parameters.
381
+ *
382
+ * @public
383
+ */
384
+ type PingRequest = RpcRequest<typeof HandshakeMethod.ping, never>;
385
+ /**
386
+ * The answer to {@link PingRequest}.
387
+ *
388
+ * @public
389
+ */
390
+ type PongResponse = RpcSuccessResponse<"pong">;
391
+ /**
392
+ * The `data` of the `RpcErrorCode.incompatibleProtocol` error a host answers `hello` with when
393
+ * the protocol versions differ.
394
+ *
395
+ * @public
396
+ */
397
+ interface IncompatibleProtocolData {
398
+ /** The protocol version the host speaks. */
399
+ readonly host: ProtocolVersion;
400
+ /** The version of `@ignifx/core` the project runs. */
401
+ readonly engineVersion: string;
402
+ }
403
+ /**
404
+ * Tells whether a value is a protocol version: two non-negative integers.
405
+ *
406
+ * @param value - The value to test.
407
+ * @returns True for `{ major, minor }` with non-negative safe integers.
408
+ *
409
+ * @public
410
+ */
411
+ export declare function isProtocolVersion(value: unknown): value is ProtocolVersion;
412
+ /**
413
+ * Checks the `result` of a `hello` answer.
414
+ *
415
+ * @param value - The received `result`.
416
+ * @returns True when it has a string `engineVersion`, a protocol version, an array of capability
417
+ * strings, and a known `hostKind`.
418
+ *
419
+ * @public
420
+ */
421
+ export declare function isReadyResult(value: unknown): value is ReadyResult;
422
+ /**
423
+ * Checks the `data` of an `incompatibleProtocol` answer to `hello`.
424
+ *
425
+ * @param value - The received `error.data`.
426
+ * @returns True when it names the host's protocol version and the engine version.
427
+ *
428
+ * @public
429
+ */
430
+ export declare function isIncompatibleProtocolData(value: unknown): value is IncompatibleProtocolData;
431
+ //#endregion
432
+ //#region src/protocol/heartbeat.d.ts
433
+ /**
434
+ * The notifications a host sends on its own.
435
+ *
436
+ * @remarks
437
+ * `as const` object plus derived union rather than an `enum` (engine coding standards §5.2, §5.3).
438
+ *
439
+ * @public
440
+ */
441
+ export declare const HostNotification: {
442
+ /** Host → editor, every {@link DEFAULT_HEARTBEAT_INTERVAL_MS} by default after `ready`: the view is alive. */
443
+ readonly heartbeat: "heartbeat";
444
+ };
445
+ /**
446
+ * The union of the names in `HostNotification`.
447
+ *
448
+ * @public
449
+ */
450
+ export type HostNotification = (typeof HostNotification)[keyof typeof HostNotification];
451
+ /**
452
+ * The milliseconds between heartbeats when the host is not configured otherwise: one second, so a
453
+ * dead view is noticed within a few.
454
+ *
455
+ * @remarks
456
+ * A host starts its heartbeat after it has answered a compatible `hello` with `ready`, sends it on
457
+ * the current port only, and stops it when that port is replaced or closed. A host that lists
458
+ * `HostCapability.heartbeat` in `ready` sends it, and the editor treats a missing heartbeat as a
459
+ * dead view.
460
+ *
461
+ * @public
462
+ */
463
+ export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 1e3;
464
+ /**
465
+ * Host → editor: the view is alive. It carries no parameters, so `params` is absent on the wire:
466
+ * `{"jsonrpc":"2.0","method":"heartbeat"}`.
467
+ *
468
+ * @public
469
+ */
470
+ type HeartbeatNotification = RpcNotification<typeof HostNotification.heartbeat, never>;
471
+ //#endregion
472
+ //#region src/protocol/play.d.ts
473
+ /**
474
+ * The methods the play view answers after `ready`. `play`, `pause`, `step` and `stop` answer with a
475
+ * {@link PlayState}; `playState` answers with a {@link PlayStateReport}; `playStats` answers with
476
+ * {@link PlayStats}.
477
+ *
478
+ * @remarks
479
+ * A host that answers them lists `HostCapability.playControls` in `ready`. Sent before `ready`, they
480
+ * fail with `RpcErrorCode.notReady`; sent to a host without them, with `RpcErrorCode.methodNotFound`.
481
+ * `playState` and `playStats` are additive 0.3 methods: a host from before one answers it with
482
+ * `RpcErrorCode.methodNotFound`.
483
+ *
484
+ * @public
485
+ */
486
+ export declare const PlayMethod: {
487
+ /** Clears `app.time.paused` and starts the frame loop if it is stopped. */
488
+ readonly play: "play";
489
+ /** Sets `app.time.paused`; scripts marked `updateWhenPaused` keep running. */
490
+ readonly pause: "pause";
491
+ /** Stops the frame loop, then advances exactly one frame with `app.step()` and leaves the game paused. */
492
+ readonly step: "step";
493
+ /** Stops the frame loop with `app.stop()`. The editor reloads the view to reset the game. */
494
+ readonly stop: "stop";
495
+ /** Reads the game's state without changing it. Takes no parameters. */
496
+ readonly playState: "playState";
497
+ /**
498
+ * Reads the game's frame rate, frame time, entity count and frame count without changing
499
+ * anything. Takes no parameters. The editor polls it; no notification carries it.
500
+ */
501
+ readonly playStats: "playStats";
502
+ };
503
+ /**
504
+ * The union of the names in `PlayMethod`.
505
+ *
506
+ * @public
507
+ */
508
+ export type PlayMethod = (typeof PlayMethod)[keyof typeof PlayMethod];
509
+ /**
510
+ * The parameters of the `step` method.
511
+ *
512
+ * @public
513
+ */
514
+ interface StepParams {
515
+ /**
516
+ * The frame delta in seconds, a positive finite number. Defaults to `app.time.fixedDeltaTime`;
517
+ * any other value fails with `RpcErrorCode.invalidParams`.
518
+ */
519
+ readonly deltaSeconds?: number;
520
+ }
521
+ /**
522
+ * Editor → play view: one of the `PlayMethod`s. Only `step` takes parameters.
523
+ *
524
+ * @public
525
+ */
526
+ type PlayRequest = RpcRequest<typeof PlayMethod.play, never> | RpcRequest<typeof PlayMethod.pause, never> | RpcRequest<typeof PlayMethod.step, StepParams> | RpcRequest<typeof PlayMethod.stop, never> | RpcRequest<typeof PlayMethod.playState, never> | RpcRequest<typeof PlayMethod.playStats, never>;
527
+ /**
528
+ * What the play view reports after every `PlayMethod`.
529
+ *
530
+ * @public
531
+ */
532
+ interface PlayState {
533
+ /** Whether the frame loop runs (`app.isRunning`). */
534
+ readonly isRunning: boolean;
535
+ /** Whether game time is paused (`app.time.paused`). */
536
+ readonly isPaused: boolean;
537
+ /** How many frames have started (`app.time.frameCount`). */
538
+ readonly frameCount: number;
539
+ }
540
+ /**
541
+ * Play view → editor: the answer to `play`, `pause`, `step` or `stop`.
542
+ *
543
+ * @public
544
+ */
545
+ type PlayResponse = RpcSuccessResponse<PlayState>;
546
+ /**
547
+ * The notifications the play view sends after `ready`.
548
+ *
549
+ * @remarks
550
+ * Additive in 0.3: a host from before them sends none, and answers `playState` with
551
+ * `RpcErrorCode.methodNotFound`. `log`, `hostError` and `hotReloaded` came later still: only a host
552
+ * that lists `HostCapability.logRelay` in `ready` sends them.
553
+ *
554
+ * @public
555
+ */
556
+ export declare const PlayNotification: {
557
+ /**
558
+ * After the game's {@link PlayStateReport.state} changed. A change a `PlayMethod` makes is sent
559
+ * right after that method's answer; one the game makes itself, such as setting
560
+ * `app.time.paused`, within one heartbeat interval.
561
+ */
562
+ readonly playStateChanged: "playStateChanged";
563
+ /**
564
+ * One line from the game's logger, with the same `LogParams` as the scene view's `log`. Sent by a
565
+ * host that lists `HostCapability.logRelay`; lines logged before the handshake are kept (the
566
+ * newest few hundred) and sent right after `ready`.
567
+ */
568
+ readonly log: "log";
569
+ /**
570
+ * An error the game's app reported through `app.onError`: the same `HostErrorParams` as the scene
571
+ * view's `hostError`, with `AppErrorData` as its `data`. Sent by a host that lists
572
+ * `HostCapability.logRelay`, kept before the handshake as `log` is.
573
+ */
574
+ readonly hostError: "hostError";
575
+ /**
576
+ * After every `app.hotReload` operation in the game: the same `HotReloadedParams` as the scene
577
+ * view's `hotReloaded`. Sent by a host that lists `HostCapability.logRelay`.
578
+ */
579
+ readonly hotReloaded: "hotReloaded";
580
+ };
581
+ /**
582
+ * The union of the names in `PlayNotification`.
583
+ *
584
+ * @public
585
+ */
586
+ export type PlayNotification = (typeof PlayNotification)[keyof typeof PlayNotification];
587
+ /**
588
+ * Whether the game plays, is paused, or is stopped, as {@link PlayStateReport.state} reports it.
589
+ *
590
+ * @public
591
+ */
592
+ export declare const PlayPhase: {
593
+ /** The frame loop runs (`app.isRunning`) and game time is not paused. */
594
+ readonly playing: "playing";
595
+ /**
596
+ * Game time is paused (`app.time.paused`): after `pause`, or after `step`, which leaves the frame
597
+ * loop stopped on the stepped frame.
598
+ */
599
+ readonly paused: "paused";
600
+ /** The frame loop does not run: before the game starts it, or after `stop`. */
601
+ readonly stopped: "stopped";
602
+ };
603
+ /**
604
+ * The union of the names in `PlayPhase`.
605
+ *
606
+ * @public
607
+ */
608
+ export type PlayPhase = (typeof PlayPhase)[keyof typeof PlayPhase];
609
+ /**
610
+ * The game's state as `playState` answers it and `playStateChanged` reports it.
611
+ *
612
+ * @public
613
+ */
614
+ interface PlayStateReport {
615
+ /** Whether the game plays, is paused, or is stopped. */
616
+ readonly state: PlayPhase;
617
+ /** How many frames have started (`app.time.frameCount`). */
618
+ readonly frameCount: number;
619
+ /** Scaled seconds of game time since the app started running frames (`app.time.time`). */
620
+ readonly time: number;
621
+ }
622
+ /**
623
+ * Play view → editor: the answer to `playState`.
624
+ *
625
+ * @public
626
+ */
627
+ type PlayStateResponse = RpcSuccessResponse<PlayStateReport>;
628
+ /**
629
+ * The game's performance as `playStats` answers it.
630
+ *
631
+ * @public
632
+ */
633
+ interface PlayStats {
634
+ /**
635
+ * Frames per second: `1000 / frameTimeMs`, or `0` when `frameTimeMs` is `0`. Rendered frames
636
+ * count whether or not game time is paused.
637
+ */
638
+ readonly fps: number;
639
+ /**
640
+ * The mean wall-clock time between the frames of the last second, in milliseconds, from the
641
+ * frame history in `app.diagnostics` (each frame's `rawDeltaMs`); `0` while the frame loop does
642
+ * not run (stopped, or stepped and paused on a frame) or before its first frame.
643
+ */
644
+ readonly frameTimeMs: number;
645
+ /** How many entities the game's world holds, in every scene instance, persistent ones included. */
646
+ readonly entityCount: number;
647
+ /** How many frames have started (`app.time.frameCount`). */
648
+ readonly frameCount: number;
649
+ }
650
+ /**
651
+ * Play view → editor: the answer to `playStats`.
652
+ *
653
+ * @public
654
+ */
655
+ type PlayStatsResponse = RpcSuccessResponse<PlayStats>;
656
+ /**
657
+ * Play view → editor: the game's state changed.
658
+ *
659
+ * @public
660
+ */
661
+ interface PlayStateChangedNotification extends RpcNotification<typeof PlayNotification.playStateChanged, PlayStateReport> {
662
+ /** The game's state after the change. */
663
+ readonly params: PlayStateReport;
664
+ }
665
+ /**
666
+ * Checks the `result` of a play method's response.
667
+ *
668
+ * @param value - The received `result`.
669
+ * @returns True when `value` has boolean `isRunning` and `isPaused` and a non-negative integer
670
+ * `frameCount`.
671
+ *
672
+ * @public
673
+ */
674
+ export declare function isPlayState(value: unknown): value is PlayState;
675
+ /**
676
+ * Checks the `result` of `playState` and the `params` of `playStateChanged`.
677
+ *
678
+ * @param value - The received value.
679
+ * @returns True when `value` has a `state` that is a `PlayPhase`, a non-negative integer
680
+ * `frameCount`, and a non-negative finite `time`.
681
+ *
682
+ * @public
683
+ */
684
+ export declare function isPlayStateReport(value: unknown): value is PlayStateReport;
685
+ /**
686
+ * Checks the `result` of `playStats`.
687
+ *
688
+ * @param value - The received `result`.
689
+ * @returns True when `value` has non-negative finite `fps` and `frameTimeMs` and non-negative
690
+ * integer `entityCount` and `frameCount`.
691
+ *
692
+ * @public
693
+ */
694
+ export declare function isPlayStats(value: unknown): value is PlayStats;
695
+ //#endregion
696
+ //#region src/protocol/scene-file.d.ts
697
+ /**
698
+ * Any JSON value. The engine's `JsonValue`.
699
+ *
700
+ * @public
701
+ */
702
+ type JsonValue = string | number | boolean | null | JsonArray | JsonObject;
703
+ /**
704
+ * A JSON array. The engine's `JsonArray`.
705
+ *
706
+ * @public
707
+ */
708
+ type JsonArray = readonly JsonValue[];
709
+ /**
710
+ * A JSON object. The engine's `JsonObject`.
711
+ *
712
+ * @public
713
+ */
714
+ type JsonObject = {
715
+ readonly [key: string]: JsonValue;
716
+ };
717
+ /**
718
+ * A serialized asset reference: `{ "$asset": "<address>", "type"?: "<type>" }`. The engine's
719
+ * `SceneFileAssetRef`.
720
+ *
721
+ * @public
722
+ */
723
+ interface SceneFileAssetRef {
724
+ /** The address the asset is registered under. */
725
+ readonly $asset: string;
726
+ /** The asset type name, written only when the address extension does not identify it. */
727
+ readonly type?: string;
728
+ }
729
+ /**
730
+ * An entity's local transform. The engine's `SceneFileTransform`.
731
+ *
732
+ * @public
733
+ */
734
+ interface SceneFileTransform {
735
+ /** Local position, `[x, y, z]`, in metres. */
736
+ readonly position: readonly [number, number, number];
737
+ /** Local rotation quaternion, `[x, y, z, w]`. */
738
+ readonly rotation: readonly [number, number, number, number];
739
+ /** Local scale, `[x, y, z]`. */
740
+ readonly scale: readonly [number, number, number];
741
+ }
742
+ /**
743
+ * One component of one entity. The engine's `SceneFileComponent`.
744
+ *
745
+ * @public
746
+ */
747
+ interface SceneFileComponent {
748
+ /** ULID, unique within the file. */
749
+ readonly uid: string;
750
+ /** The component class's registered `typeId`. */
751
+ readonly type: string;
752
+ /** Omitted when `true`, the default. */
753
+ readonly enabled?: boolean;
754
+ /** Written only when the class's `schemaVersion` differs from `1`. */
755
+ readonly schemaVersion?: number;
756
+ /** Values in the component schema's declaration order. */
757
+ readonly props?: JsonObject;
758
+ }
759
+ /**
760
+ * One override patch applied to an instanced scene. The engine's `SceneFileOverride`.
761
+ *
762
+ * @public
763
+ */
764
+ interface SceneFileOverride {
765
+ /** `"replace"` (the default) patches a value, `"remove"` deletes a component, `"add"` appends one. */
766
+ readonly op?: "replace" | "remove" | "add";
767
+ /** The path into the instanced file, in the engine's override path grammar. */
768
+ readonly path: string;
769
+ /** The new value, for `"replace"` and `"add"`. */
770
+ readonly value?: JsonValue;
771
+ }
772
+ /**
773
+ * The `instance` entry that makes an entity the root of an instanced scene (a prefab instance).
774
+ * The engine's `SceneFileInstance`.
775
+ *
776
+ * @public
777
+ */
778
+ interface SceneFileInstance {
779
+ /** The scene asset to instance. */
780
+ readonly scene: SceneFileAssetRef;
781
+ /** The content hash of that asset at save time. */
782
+ readonly hash?: string;
783
+ /** The patches applied to the instanced entities, in order. */
784
+ readonly overrides?: readonly SceneFileOverride[];
785
+ }
786
+ /**
787
+ * One entity of a scene file. The engine's `SceneFileEntity`.
788
+ *
789
+ * @public
790
+ */
791
+ interface SceneFileEntity {
792
+ /** ULID, unique within the file. */
793
+ readonly uid: string;
794
+ /** The display name. */
795
+ readonly name: string;
796
+ /** The parent's uid, or `null` for a root. */
797
+ readonly parent: string | null;
798
+ /** Omitted when `true`, the default. */
799
+ readonly active?: boolean;
800
+ /** Omitted when `false`, the default. */
801
+ readonly static?: boolean;
802
+ /** The layer name, omitted when `"Default"`. */
803
+ readonly layer?: string;
804
+ /** The tags, omitted when empty. */
805
+ readonly tags?: readonly string[];
806
+ /** Always present. */
807
+ readonly transform: SceneFileTransform;
808
+ /** Present only on instance roots. */
809
+ readonly instance?: SceneFileInstance;
810
+ /** The entity's own components; on an instance root, the ones added on top of the instance. */
811
+ readonly components?: readonly SceneFileComponent[];
812
+ }
813
+ /**
814
+ * A whole scene or prefab file. The engine's `SceneFile`.
815
+ *
816
+ * @public
817
+ */
818
+ interface SceneFile {
819
+ /** Always `"ignifx.scene"`. */
820
+ readonly format: string;
821
+ /** `1` for every file the engine writes before 1.0. */
822
+ readonly formatVersion: number;
823
+ /** The `@ignifx/core` version that wrote the file; informational. */
824
+ readonly engineVersion?: string;
825
+ /** The scene's name. */
826
+ readonly name: string;
827
+ /** Scene-level values interpreted by systems. */
828
+ readonly settings?: JsonObject;
829
+ /** Every entity, in tree order: parents before children, siblings in order. */
830
+ readonly entities: readonly SceneFileEntity[];
831
+ }
832
+ /**
833
+ * Tells whether a value is JSON: `null`, a boolean, a string, a finite number, or an array or
834
+ * plain object of JSON values, nested at most 256 levels deep.
835
+ *
836
+ * @param value - The value to test.
837
+ * @returns True for a JSON value.
838
+ *
839
+ * @public
840
+ */
841
+ export declare function isJsonValue(value: unknown): value is JsonValue;
842
+ /**
843
+ * Tells whether a value is a JSON object.
844
+ *
845
+ * @param value - The value to test.
846
+ * @returns True for a plain object of JSON values.
847
+ *
848
+ * @public
849
+ */
850
+ export declare function isJsonObject(value: unknown): value is JsonObject;
851
+ /**
852
+ * Checks an asset reference.
853
+ *
854
+ * @param value - The value to test.
855
+ * @returns True for `{ $asset: string, type?: string }`.
856
+ *
857
+ * @public
858
+ */
859
+ export declare function isSceneFileAssetRef(value: unknown): value is SceneFileAssetRef;
860
+ /**
861
+ * Checks a local transform.
862
+ *
863
+ * @param value - The value to test.
864
+ * @returns True for three, four and three finite numbers in `position`, `rotation` and `scale`.
865
+ *
866
+ * @public
867
+ */
868
+ export declare function isSceneFileTransform(value: unknown): value is SceneFileTransform;
869
+ /**
870
+ * Checks a component record.
871
+ *
872
+ * @param value - The value to test.
873
+ * @returns True for a record with a uid, a type and well-typed optional fields.
874
+ *
875
+ * @public
876
+ */
877
+ export declare function isSceneFileComponent(value: unknown): value is SceneFileComponent;
878
+ /**
879
+ * Checks an override patch.
880
+ *
881
+ * @param value - The value to test.
882
+ * @returns True for `{ op?, path, value? }` with a known `op` and a JSON `value`.
883
+ *
884
+ * @public
885
+ */
886
+ export declare function isSceneFileOverride(value: unknown): value is SceneFileOverride;
887
+ /**
888
+ * Checks an `instance` entry.
889
+ *
890
+ * @param value - The value to test.
891
+ * @returns True for `{ scene, hash?, overrides? }`.
892
+ *
893
+ * @public
894
+ */
895
+ export declare function isSceneFileInstance(value: unknown): value is SceneFileInstance;
896
+ /**
897
+ * Checks an entity record.
898
+ *
899
+ * @param value - The value to test.
900
+ * @returns True for a record with a uid, a name, a parent, a transform and well-typed optional
901
+ * fields.
902
+ *
903
+ * @public
904
+ */
905
+ export declare function isSceneFileEntity(value: unknown): value is SceneFileEntity;
906
+ /**
907
+ * Checks a whole scene file's structure.
908
+ *
909
+ * @param value - The value to test.
910
+ * @returns True for a file object whose header fields and entity records have the right types.
911
+ *
912
+ * @public
913
+ */
914
+ export declare function isSceneFile(value: unknown): value is SceneFile;
915
+ //#endregion
916
+ //#region src/protocol/scene-ops.d.ts
917
+ /**
918
+ * The `op` discriminant of every scene op.
919
+ *
920
+ * @remarks
921
+ * `as const` object plus derived union rather than an `enum` (engine coding standards §5.2, §5.3).
922
+ *
923
+ * @public
924
+ */
925
+ export declare const SceneOpKind: {
926
+ /** Creates an entity, optionally with a subtree. */
927
+ readonly createEntity: "createEntity";
928
+ /** Destroys an entity and its subtree. */
929
+ readonly destroyEntity: "destroyEntity";
930
+ /** Moves an entity under another parent, keeping its local transform. */
931
+ readonly reparent: "reparent";
932
+ /** Moves an entity among its siblings. */
933
+ readonly reorder: "reorder";
934
+ /** Sets `name`, `active`, `static`, `layer` or `tags`. */
935
+ readonly setEntityField: "setEntityField";
936
+ /** Sets an entity's local transform. */
937
+ readonly setTransform: "setTransform";
938
+ /** Adds a component. */
939
+ readonly addComponent: "addComponent";
940
+ /** Removes a component. */
941
+ readonly removeComponent: "removeComponent";
942
+ /** Sets or removes a value inside a component's `props`. */
943
+ readonly setProp: "setProp";
944
+ /** Sets or removes a value inside the scene's `settings`. */
945
+ readonly setSceneSetting: "setSceneSetting";
946
+ /** Creates an instance root (a prefab instance). */
947
+ readonly instantiate: "instantiate";
948
+ /** Sets an override on an instance root. */
949
+ readonly setOverride: "setOverride";
950
+ /** Removes an override from an instance root. */
951
+ readonly removeOverride: "removeOverride";
952
+ };
953
+ /**
954
+ * The union of the names in `SceneOpKind`.
955
+ *
956
+ * @public
957
+ */
958
+ export type SceneOpKind = (typeof SceneOpKind)[keyof typeof SceneOpKind];
959
+ /**
960
+ * The entity properties {@link SetEntityFieldOp} writes, and their value types.
961
+ *
962
+ * @public
963
+ */
964
+ interface EntityFieldValues {
965
+ /** The display name. */
966
+ readonly name: string;
967
+ /** `false` deactivates the entity and its subtree. */
968
+ readonly active: boolean;
969
+ /** The static flag. */
970
+ readonly static: boolean;
971
+ /** The layer name; `"Default"` is the default. */
972
+ readonly layer: string;
973
+ /** The tags; stored deduplicated and sorted, as the serializer writes them. */
974
+ readonly tags: readonly string[];
975
+ }
976
+ /**
977
+ * The name of an entity property {@link SetEntityFieldOp} writes.
978
+ *
979
+ * @public
980
+ */
981
+ type EntityField = keyof EntityFieldValues;
982
+ /**
983
+ * A path into a JSON object: object keys as strings, array indices as whole numbers.
984
+ *
985
+ * @public
986
+ */
987
+ type JsonPath = readonly (string | number)[];
988
+ /**
989
+ * Creates an entity, optionally with a whole subtree below it. `entity.parent` places it; `index`
990
+ * is its place among the parent's children (default: last); `descendants` are further records,
991
+ * parents first.
992
+ *
993
+ * @public
994
+ */
995
+ interface CreateEntityOp {
996
+ /** The discriminant. */
997
+ readonly op: "createEntity";
998
+ /** The new entity's record, including its components and, for an instance root, its `instance`. */
999
+ readonly entity: SceneFileEntity;
1000
+ /** The entity's index among its siblings; defaults to the end. */
1001
+ readonly index?: number;
1002
+ /** The rest of the subtree, parents first. */
1003
+ readonly descendants?: readonly SceneFileEntity[];
1004
+ }
1005
+ /**
1006
+ * Destroys an entity and its whole subtree.
1007
+ *
1008
+ * @public
1009
+ */
1010
+ interface DestroyEntityOp {
1011
+ /** The discriminant. */
1012
+ readonly op: "destroyEntity";
1013
+ /** The entity's uid. */
1014
+ readonly entity: string;
1015
+ }
1016
+ /**
1017
+ * Moves an entity under another parent, keeping its local transform.
1018
+ *
1019
+ * @public
1020
+ */
1021
+ interface ReparentOp {
1022
+ /** The discriminant. */
1023
+ readonly op: "reparent";
1024
+ /** The entity's uid. */
1025
+ readonly entity: string;
1026
+ /** The new parent's uid, or `null` to make the entity a root. */
1027
+ readonly parent: string | null;
1028
+ /** The entity's index among its new siblings; defaults to the end. */
1029
+ readonly index?: number;
1030
+ }
1031
+ /**
1032
+ * Moves an entity among its siblings; `index` is its place after the move.
1033
+ *
1034
+ * @public
1035
+ */
1036
+ interface ReorderOp {
1037
+ /** The discriminant. */
1038
+ readonly op: "reorder";
1039
+ /** The entity's uid. */
1040
+ readonly entity: string;
1041
+ /** The new index among its siblings. */
1042
+ readonly index: number;
1043
+ }
1044
+ /**
1045
+ * Sets one entity property.
1046
+ *
1047
+ * @public
1048
+ */
1049
+ type SetEntityFieldOp = { readonly [F in EntityField]: {
1050
+ /** The discriminant. */
1051
+ readonly op: "setEntityField";
1052
+ /** The entity's uid. */
1053
+ readonly entity: string;
1054
+ /** Which property. */
1055
+ readonly field: F;
1056
+ /** The new value. */
1057
+ readonly value: EntityFieldValues[F];
1058
+ }; }[EntityField];
1059
+ /**
1060
+ * Sets an entity's local transform. `before` is informational and ignored when applying.
1061
+ *
1062
+ * @public
1063
+ */
1064
+ interface SetTransformOp {
1065
+ /** The discriminant. */
1066
+ readonly op: "setTransform";
1067
+ /** The entity's uid. */
1068
+ readonly entity: string;
1069
+ /** The new local transform. */
1070
+ readonly after: SceneFileTransform;
1071
+ /** The local transform the emitter saw before the change; ignored when applying. */
1072
+ readonly before?: SceneFileTransform;
1073
+ }
1074
+ /**
1075
+ * Adds a component to an entity.
1076
+ *
1077
+ * @public
1078
+ */
1079
+ interface AddComponentOp {
1080
+ /** The discriminant. */
1081
+ readonly op: "addComponent";
1082
+ /** The entity's uid. */
1083
+ readonly entity: string;
1084
+ /** The component's record; its uid must be new to the document. */
1085
+ readonly component: SceneFileComponent;
1086
+ /** The component's index on the entity; defaults to the end. */
1087
+ readonly index?: number;
1088
+ }
1089
+ /**
1090
+ * Removes a component.
1091
+ *
1092
+ * @public
1093
+ */
1094
+ interface RemoveComponentOp {
1095
+ /** The discriminant. */
1096
+ readonly op: "removeComponent";
1097
+ /** The component's uid. */
1098
+ readonly component: string;
1099
+ }
1100
+ /**
1101
+ * Sets, or removes, a value inside a component's `props`. `path[0]` is the field name; an absent
1102
+ * `value` removes the key; the empty path addresses `props` itself.
1103
+ *
1104
+ * @public
1105
+ */
1106
+ interface SetPropOp {
1107
+ /** The discriminant. */
1108
+ readonly op: "setProp";
1109
+ /** The component's uid. */
1110
+ readonly component: string;
1111
+ /** The path into `props`. */
1112
+ readonly path: JsonPath;
1113
+ /** The new value; absent removes the key. */
1114
+ readonly value?: JsonValue;
1115
+ }
1116
+ /**
1117
+ * Sets, or removes, a value inside the scene's `settings`, with {@link SetPropOp}'s path rules.
1118
+ *
1119
+ * @public
1120
+ */
1121
+ interface SetSceneSettingOp {
1122
+ /** The discriminant. */
1123
+ readonly op: "setSceneSetting";
1124
+ /** The path into `settings`; `path[0]` is the setting's key. */
1125
+ readonly path: JsonPath;
1126
+ /** The new value; absent removes the key. */
1127
+ readonly value?: JsonValue;
1128
+ }
1129
+ /**
1130
+ * Creates an instance root: an entity carrying an `instance` entry.
1131
+ *
1132
+ * @public
1133
+ */
1134
+ interface InstantiateOp {
1135
+ /** The discriminant. */
1136
+ readonly op: "instantiate";
1137
+ /** The new entity's uid. */
1138
+ readonly entity: string;
1139
+ /** Its name; usually the prefab root's name. */
1140
+ readonly name: string;
1141
+ /** Its parent's uid, or `null` for a root. */
1142
+ readonly parent: string | null;
1143
+ /** Its index among its siblings; defaults to the end. */
1144
+ readonly index?: number;
1145
+ /** Its local transform. */
1146
+ readonly transform: SceneFileTransform;
1147
+ /** The instance entry: the scene asset, its hash, and any overrides. */
1148
+ readonly instance: SceneFileInstance;
1149
+ }
1150
+ /**
1151
+ * Sets an override on an instance root's entry, replacing the override with the same identity or
1152
+ * inserting a new one at `index` (default: last).
1153
+ *
1154
+ * @public
1155
+ */
1156
+ interface SetOverrideOp {
1157
+ /** The discriminant. */
1158
+ readonly op: "setOverride";
1159
+ /** The instance root's uid. */
1160
+ readonly entity: string;
1161
+ /** The override. */
1162
+ readonly override: SceneFileOverride;
1163
+ /** Where a new override goes; defaults to the end. */
1164
+ readonly index?: number;
1165
+ }
1166
+ /**
1167
+ * Removes an override from an instance root's entry.
1168
+ *
1169
+ * @public
1170
+ */
1171
+ interface RemoveOverrideOp {
1172
+ /** The discriminant. */
1173
+ readonly op: "removeOverride";
1174
+ /** The instance root's uid. */
1175
+ readonly entity: string;
1176
+ /** The override's path. */
1177
+ readonly path: string;
1178
+ /** The override's `op`; defaults to what the path implies. */
1179
+ readonly overrideOp?: "replace" | "remove" | "add";
1180
+ /** For a component `add`, the uid of the component it adds. */
1181
+ readonly added?: string;
1182
+ }
1183
+ /**
1184
+ * One scene op: the closed vocabulary of plan §3.4, identical to `@ignifx/editor-core`'s `SceneOp`.
1185
+ *
1186
+ * @public
1187
+ */
1188
+ type SceneOp = CreateEntityOp | DestroyEntityOp | ReparentOp | ReorderOp | SetEntityFieldOp | SetTransformOp | AddComponentOp | RemoveComponentOp | SetPropOp | SetSceneSettingOp | InstantiateOp | SetOverrideOp | RemoveOverrideOp;
1189
+ /**
1190
+ * Checks the structure of one scene op: a known `op` and fields of the right types.
1191
+ *
1192
+ * @remarks
1193
+ * It answers "is this an op of the vocabulary", not "does it apply": uids are checked to be
1194
+ * non-empty strings, indices to be non-negative integers, values to be JSON, and records to have the
1195
+ * scene format's shape. Unknown extra fields are ignored. A `setProp` or `setSceneSetting` value may
1196
+ * be any JSON; that the empty path receives an object is the applier's check.
1197
+ *
1198
+ * @param value - A received op.
1199
+ * @returns True when `value` is a structurally valid {@link SceneOp}.
1200
+ *
1201
+ * @example
1202
+ * ```ts
1203
+ * isSceneOp({ op: "setEntityField", entity: "01J9Z6M7E5S3A0V2Q4R8T1Y6WX", field: "name", value: "Player" }); // true
1204
+ * isSceneOp({ op: "setEntityField", entity: "01J9Z6M7E5S3A0V2Q4R8T1Y6WX", field: "name", value: 3 }); // false
1205
+ * ```
1206
+ *
1207
+ * @public
1208
+ */
1209
+ export declare function isSceneOp(value: unknown): value is SceneOp;
1210
+ //#endregion
1211
+ //#region src/protocol/scene.d.ts
1212
+ /**
1213
+ * Editor → scene host: the methods of protocol 0.3, answered after `ready`.
1214
+ *
1215
+ * @remarks
1216
+ * `as const` object plus derived union rather than an `enum` (engine coding standards §5.2, §5.3).
1217
+ *
1218
+ * The host handles these requests one at a time, in the order they arrive: a request starts only
1219
+ * after the previous one has been answered, so `applyOps` sent right after `openScene` sees the new
1220
+ * scene. Until the host's app has started, every one of them fails with `RpcErrorCode.notReady`;
1221
+ * the host's first `schemasChanged` is the editor's cue that they are accepted. A method that needs
1222
+ * an open scene fails with `RpcErrorCode.noScene` while none is open. A method whose capability the
1223
+ * host does not list in `ready` fails with `RpcErrorCode.methodNotFound`.
1224
+ *
1225
+ * @public
1226
+ */
1227
+ export declare const SceneMethod: {
1228
+ /** Opens a scene from the editor's document, replacing any open scene. Answers {@link OpenSceneResult}. */
1229
+ readonly openScene: "openScene";
1230
+ /** Unloads the open scene, if any. Answers `null`. */
1231
+ readonly closeScene: "closeScene";
1232
+ /** Applies one command's ops to the open scene, in order. Answers {@link ApplyOpsResult}. */
1233
+ readonly applyOps: "applyOps";
1234
+ /** Serializes entities of the open scene as the live world has them. Answers {@link ReadBackResult}. */
1235
+ readonly readBack: "readBack";
1236
+ /** Sets the selection the view outlines and attaches the gizmo to. Answers {@link EntitySelection}. */
1237
+ readonly select: "select";
1238
+ /** Sets the gizmo's mode, space and snapping. Needs `HostCapability.gizmos`. Answers `null`. */
1239
+ readonly setGizmo: "setGizmo";
1240
+ /** Moves the editor camera to frame entities. Answers `null`. */
1241
+ readonly frame: "frame";
1242
+ /** Asks which entity is under a point of the view, without selecting it. Answers {@link PickResult}. */
1243
+ readonly pick: "pick";
1244
+ /** Captures the view as an image. Needs `HostCapability.screenshot`. Answers {@link ScreenshotResult}. */
1245
+ readonly screenshot: "screenshot";
1246
+ /** Describes every registered component's schema. Answers {@link SchemaSet}. */
1247
+ readonly getSchemas: "getSchemas";
1248
+ /**
1249
+ * Describes the project's settings sections and the values the app resolved for them. Answers
1250
+ * {@link SettingsSet}. A host from before it answers `RpcErrorCode.methodNotFound`.
1251
+ */
1252
+ readonly describeSettings: "describeSettings";
1253
+ /** Switches the view between the 3D and the 2D editor camera. Answers `null`. */
1254
+ readonly setViewMode: "setViewMode";
1255
+ };
1256
+ /**
1257
+ * The union of the names in `SceneMethod`.
1258
+ *
1259
+ * @public
1260
+ */
1261
+ export type SceneMethod = (typeof SceneMethod)[keyof typeof SceneMethod];
1262
+ /**
1263
+ * Scene host → editor: the notifications of protocol 0.3. None has an answer.
1264
+ *
1265
+ * @remarks
1266
+ * There is no `reloadScripts` method: script hot reload is Vite's. When a script changes, Vite
1267
+ * replaces the module in the host page, `acceptHotReload(app)` hands the new classes to
1268
+ * `app.hotReload.apply`, and the host reports the outcome with `hotReloaded` and `schemasChanged`.
1269
+ * A change that Vite cannot hot-replace reloads the host page, which the editor sees as a new load:
1270
+ * a new port, a new handshake, and `openScene` again.
1271
+ *
1272
+ * @public
1273
+ */
1274
+ export declare const SceneNotification: {
1275
+ /** After the answer to every successful `openScene`: what was opened. */
1276
+ readonly sceneOpened: "sceneOpened";
1277
+ /** Once the app has started (after `ready`), and after every hot reload: the component schemas. */
1278
+ readonly schemasChanged: "schemasChanged";
1279
+ /** After every `app.hotReload` operation: its report. */
1280
+ readonly hotReloaded: "hotReloaded";
1281
+ /** After a click in the view changed the selection: the new selection. */
1282
+ readonly selectionChanged: "selectionChanged";
1283
+ /** During a gizmo drag, at most every {@link TRANSFORM_DRAGGING_INTERVAL_MS}: for display only. */
1284
+ readonly transformDragging: "transformDragging";
1285
+ /** Once per gizmo gesture, at pointer-up: the editor turns it into a `setTransform` command. */
1286
+ readonly transformDragged: "transformDragged";
1287
+ /** A failure that answers no request: an error the app reported, a failed hot reload. */
1288
+ readonly hostError: "hostError";
1289
+ /** One line from the app's logger, for the editor's Console. */
1290
+ readonly log: "log";
1291
+ /**
1292
+ * After the host reloaded an asset that changed on disk, in place: its address, its type, and
1293
+ * the document's instance roots rebuilt from it. A host from before it sends nothing.
1294
+ */
1295
+ readonly assetReloaded: "assetReloaded";
1296
+ };
1297
+ /**
1298
+ * The union of the names in `SceneNotification`.
1299
+ *
1300
+ * @public
1301
+ */
1302
+ export type SceneNotification = (typeof SceneNotification)[keyof typeof SceneNotification];
1303
+ /**
1304
+ * The fewest milliseconds between two `transformDragging` notifications for the same gesture: at
1305
+ * most 20 a second, which S0.2 measured as smooth enough for an inspector to follow a drag.
1306
+ *
1307
+ * @public
1308
+ */
1309
+ export declare const TRANSFORM_DRAGGING_INTERVAL_MS = 50;
1310
+ /**
1311
+ * The largest width and height, in pixels, of a `screenshot`. A request for more fails with
1312
+ * `invalidParams`; a request without a size gets the view's own size scaled down to fit. It keeps
1313
+ * an image well under what an MCP client accepts inline (plan §3.11).
1314
+ *
1315
+ * @public
1316
+ */
1317
+ export declare const SCREENSHOT_MAX_SIZE = 2048;
1318
+ /**
1319
+ * A world-space point, `[x, y, z]`, in metres.
1320
+ *
1321
+ * @public
1322
+ */
1323
+ type Vec3 = readonly [number, number, number];
1324
+ /**
1325
+ * One recoverable problem the engine reported while building or serializing a scene: the engine's
1326
+ * `SceneLoadIssue` and `SerializeIssue`.
1327
+ *
1328
+ * @public
1329
+ */
1330
+ interface SceneIssue {
1331
+ /** The engine's diagnostic code, for example `"IGX-0602"`. */
1332
+ readonly code: string;
1333
+ /** The engine's actionable sentence. */
1334
+ readonly message: string;
1335
+ }
1336
+ /**
1337
+ * One structural problem in a scene file: the engine's `SceneFileIssue`, from `validateSceneFile`.
1338
+ *
1339
+ * @public
1340
+ */
1341
+ interface SceneFileIssue {
1342
+ /** Where the problem is, for example `"entities/3/transform"`. */
1343
+ readonly path: string;
1344
+ /** An actionable description. */
1345
+ readonly message: string;
1346
+ }
1347
+ /**
1348
+ * The parameters of `openScene`.
1349
+ *
1350
+ * @public
1351
+ */
1352
+ interface OpenSceneParams {
1353
+ /**
1354
+ * The whole scene file, as the editor's document holds it: the engine's `SceneFile` object, not
1355
+ * its text. It may differ from the file on disk (unsaved edits), so it is the only source the
1356
+ * host builds from.
1357
+ */
1358
+ readonly file: SceneFile;
1359
+ /**
1360
+ * The asset address the document is saved at, for example `"scenes/level01.scene.json"`, or
1361
+ * `null` for a document that has never been saved. The host names the scene's asset with it and
1362
+ * never loads the file from it.
1363
+ */
1364
+ readonly address: string | null;
1365
+ }
1366
+ /**
1367
+ * The answer to `openScene`, once every entity is built.
1368
+ *
1369
+ * @public
1370
+ */
1371
+ interface OpenSceneResult {
1372
+ /** How many entities the host built, including those expanded from instanced scenes. */
1373
+ readonly entityCount: number;
1374
+ /** Every recoverable problem the build reported, in order (`SceneBuildResult.issues`). */
1375
+ readonly warnings: readonly SceneIssue[];
1376
+ /**
1377
+ * The editor camera the scene is made for, as the host's engine sees it: `"2d"` when the project
1378
+ * draws sprites only (`twoD.mode: "sprite"`) or the scene's cameras are all `Camera2D`, else
1379
+ * `"3d"`. The host does not switch to it; the editor sends `setViewMode`. Absent from a host from
1380
+ * before it.
1381
+ */
1382
+ readonly viewMode?: ViewMode;
1383
+ }
1384
+ /**
1385
+ * The `data` of the `invalidParams` error `openScene` answers when `validateSceneFile` refuses the
1386
+ * file.
1387
+ *
1388
+ * @public
1389
+ */
1390
+ interface InvalidSceneFileData {
1391
+ /** What `validateSceneFile` reported. */
1392
+ readonly issues: readonly SceneFileIssue[];
1393
+ }
1394
+ /**
1395
+ * The parameters of `applyOps`: one command, as the editor applied it to its document.
1396
+ *
1397
+ * @public
1398
+ */
1399
+ interface ApplyOpsParams {
1400
+ /** The ops, in the order they apply. Undo sends the inverse ops; redo sends the ops again. */
1401
+ readonly ops: readonly SceneOp[];
1402
+ /** The command's label, for example `"Move Player"`, for the host's log. */
1403
+ readonly commandName: string;
1404
+ /** The editor's id for this command, unique on the channel, for correlating logs and failures. */
1405
+ readonly commandId: string;
1406
+ }
1407
+ /**
1408
+ * Why the host could not apply one op.
1409
+ *
1410
+ * @remarks
1411
+ * The first ten are `@ignifx/editor-core`'s `OpErrorCode`s, with its meanings, for a world that
1412
+ * disagrees with the document the op was checked against. The last two are the host's own.
1413
+ *
1414
+ * @public
1415
+ */
1416
+ export declare const ApplyOpFailureCode: {
1417
+ /** Not an op of the vocabulary. */
1418
+ readonly invalidOp: "invalidOp";
1419
+ /** The target entity uid is not in the open scene. */
1420
+ readonly unknownEntity: "unknownEntity";
1421
+ /** The target component uid is not in the open scene. */
1422
+ readonly unknownComponent: "unknownComponent";
1423
+ /** A new entity or component reuses a uid. */
1424
+ readonly duplicateUid: "duplicateUid";
1425
+ /** A parent outside the scene, or a move under its own subtree. */
1426
+ readonly invalidParent: "invalidParent";
1427
+ /** An index outside the list it positions in. */
1428
+ readonly invalidIndex: "invalidIndex";
1429
+ /** A value of the wrong shape for its field. */
1430
+ readonly invalidValue: "invalidValue";
1431
+ /** A JSON path or override path that does not resolve. */
1432
+ readonly invalidPath: "invalidPath";
1433
+ /** An override op on an entity without an `instance` entry. */
1434
+ readonly notAnInstance: "notAnInstance";
1435
+ /** No override with that identity. */
1436
+ readonly unknownOverride: "unknownOverride";
1437
+ /** The host cannot apply this op to a live world yet; the editor reopens the scene instead. */
1438
+ readonly unsupportedOp: "unsupportedOp";
1439
+ /** The engine threw while applying the op; `diagnostic` carries its `IGX-` code when it had one. */
1440
+ readonly engineError: "engineError";
1441
+ };
1442
+ /**
1443
+ * The union of the codes in `ApplyOpFailureCode`.
1444
+ *
1445
+ * @public
1446
+ */
1447
+ export type ApplyOpFailureCode = (typeof ApplyOpFailureCode)[keyof typeof ApplyOpFailureCode];
1448
+ /**
1449
+ * One op the host could not apply.
1450
+ *
1451
+ * @public
1452
+ */
1453
+ interface ApplyOpFailure {
1454
+ /** The op's index in `ApplyOpsParams.ops`. */
1455
+ readonly index: number;
1456
+ /** Why it failed. */
1457
+ readonly code: ApplyOpFailureCode;
1458
+ /** An actionable sentence. */
1459
+ readonly message: string;
1460
+ /** The engine's diagnostic code, for example `"IGX-0307"`, when the engine reported one. */
1461
+ readonly diagnostic?: string;
1462
+ }
1463
+ /**
1464
+ * The answer to `applyOps`.
1465
+ *
1466
+ * @remarks
1467
+ * The host applies the ops in order and does not stop at a failure, so `applied + failures.length`
1468
+ * is the number of ops sent. Any failure means the live world no longer mirrors the document; the
1469
+ * editor then sends `openScene` with the whole document again.
1470
+ *
1471
+ * @public
1472
+ */
1473
+ interface ApplyOpsResult {
1474
+ /** How many ops were applied. */
1475
+ readonly applied: number;
1476
+ /** The ops that were not, in order. */
1477
+ readonly failures: readonly ApplyOpFailure[];
1478
+ }
1479
+ /**
1480
+ * The parameters of `readBack`.
1481
+ *
1482
+ * @public
1483
+ */
1484
+ interface ReadBackParams {
1485
+ /** The entities to serialize; absent for every entity of the open scene. */
1486
+ readonly entities?: readonly string[];
1487
+ }
1488
+ /**
1489
+ * The answer to `readBack`: the open scene's entities as `serializeScene` writes them from the live
1490
+ * world, which is what the document should hold when the mirror is exact.
1491
+ *
1492
+ * @public
1493
+ */
1494
+ interface ReadBackResult {
1495
+ /** The entity records, in tree order, as `serializeScene` writes them. */
1496
+ readonly entities: readonly SceneFileEntity[];
1497
+ /** The requested uids that name no entity of the open scene, in request order. */
1498
+ readonly missing: readonly string[];
1499
+ /** The scene's `settings`, or `null` when it has none. */
1500
+ readonly settings: JsonObject | null;
1501
+ /** What the serializer reported (`SerializeIssue`), in order. */
1502
+ readonly issues: readonly SceneIssue[];
1503
+ }
1504
+ /**
1505
+ * A selection: the parameters and the answer of `select`, and the parameters of `selectionChanged`.
1506
+ *
1507
+ * @public
1508
+ */
1509
+ interface EntitySelection {
1510
+ /** The selected entities' uids. The last one is the primary selection, which the gizmo follows. */
1511
+ readonly entities: readonly string[];
1512
+ }
1513
+ /**
1514
+ * What the gizmo does.
1515
+ *
1516
+ * @public
1517
+ */
1518
+ export declare const GizmoMode: {
1519
+ /** Move along axes and planes. */
1520
+ readonly translate: "translate";
1521
+ /** Rotate around axes. */
1522
+ readonly rotate: "rotate";
1523
+ /** Scale along axes and uniformly. */
1524
+ readonly scale: "scale";
1525
+ /** No gizmo; the selection is only outlined. */
1526
+ readonly none: "none";
1527
+ };
1528
+ /**
1529
+ * The union of the modes in `GizmoMode`.
1530
+ *
1531
+ * @public
1532
+ */
1533
+ export type GizmoMode = (typeof GizmoMode)[keyof typeof GizmoMode];
1534
+ /**
1535
+ * The gizmo modes a drag can happen in: every `GizmoMode` but `none`.
1536
+ *
1537
+ * @public
1538
+ */
1539
+ type GizmoDragMode = Exclude<GizmoMode, typeof GizmoMode.none>;
1540
+ /**
1541
+ * Which axes the gizmo follows.
1542
+ *
1543
+ * @public
1544
+ */
1545
+ export declare const GizmoSpace: {
1546
+ /** The entity's own axes. */
1547
+ readonly local: "local";
1548
+ /** The world's axes. */
1549
+ readonly world: "world";
1550
+ };
1551
+ /**
1552
+ * The union of the spaces in `GizmoSpace`.
1553
+ *
1554
+ * @public
1555
+ */
1556
+ export type GizmoSpace = (typeof GizmoSpace)[keyof typeof GizmoSpace];
1557
+ /**
1558
+ * The gizmo's snapping increments. `0` turns snapping off for that mode.
1559
+ *
1560
+ * @public
1561
+ */
1562
+ interface GizmoSnap {
1563
+ /** The translation step, in metres. */
1564
+ readonly translate: number;
1565
+ /** The rotation step, in degrees. */
1566
+ readonly rotate: number;
1567
+ /** The scale step, as a factor added per step (`0.1` snaps scale to tenths). */
1568
+ readonly scale: number;
1569
+ }
1570
+ /**
1571
+ * The parameters of `setGizmo`.
1572
+ *
1573
+ * @public
1574
+ */
1575
+ interface SetGizmoParams {
1576
+ /** What the gizmo does. */
1577
+ readonly mode: GizmoMode;
1578
+ /** Which axes it follows. */
1579
+ readonly space: GizmoSpace;
1580
+ /** The snapping increments, or `null` for no snapping. */
1581
+ readonly snap: GizmoSnap | null;
1582
+ }
1583
+ /**
1584
+ * The parameters of `frame`.
1585
+ *
1586
+ * @public
1587
+ */
1588
+ interface FrameParams {
1589
+ /** The entities to fit in the view, or `"all"` for the whole open scene. */
1590
+ readonly entities: readonly string[] | "all";
1591
+ }
1592
+ /**
1593
+ * The unit of a `pick` point (S0.2 §6.1).
1594
+ *
1595
+ * @public
1596
+ */
1597
+ export declare const PickUnit: {
1598
+ /** CSS pixels from the view's top-left corner: a DOM event's `offsetX` and `offsetY`. */
1599
+ readonly css: "css";
1600
+ /** The canvas's backing-store pixels: CSS pixels times `canvas.width / canvas.clientWidth`. */
1601
+ readonly backing: "backing";
1602
+ };
1603
+ /**
1604
+ * The union of the units in `PickUnit`.
1605
+ *
1606
+ * @public
1607
+ */
1608
+ export type PickUnit = (typeof PickUnit)[keyof typeof PickUnit];
1609
+ /**
1610
+ * The parameters of `pick`.
1611
+ *
1612
+ * @public
1613
+ */
1614
+ interface PickParams {
1615
+ /** The point's x, from the view's left edge, in `unit`. */
1616
+ readonly x: number;
1617
+ /** The point's y, from the view's top edge, in `unit`. */
1618
+ readonly y: number;
1619
+ /** The unit of `x` and `y`; the host converts it to whatever its engine's picker takes. */
1620
+ readonly unit: PickUnit;
1621
+ }
1622
+ /**
1623
+ * A world-space ray from the view's camera through a point of the view.
1624
+ *
1625
+ * @public
1626
+ */
1627
+ interface PickRay {
1628
+ /** Where the ray starts, in metres: the point under the cursor on the camera's near plane. */
1629
+ readonly origin: Vec3;
1630
+ /** Which way it points: a unit vector. */
1631
+ readonly direction: Vec3;
1632
+ }
1633
+ /**
1634
+ * The answer to `pick`.
1635
+ *
1636
+ * @public
1637
+ */
1638
+ interface PickResult {
1639
+ /** The scene entity hit, or `null` for a miss. A hit inside an instanced scene names its instance root. */
1640
+ readonly entity: string | null;
1641
+ /** The world-space hit point, or `null` for a miss or when the picker does not report one. */
1642
+ readonly point: Vec3 | null;
1643
+ /** How far along the camera ray the hit is, in metres, or `null` for a miss or a 2D pick. */
1644
+ readonly distance: number | null;
1645
+ /**
1646
+ * The ray the view's camera casts through the point, hit or miss, so that an editor can place
1647
+ * something where nothing was hit (a 3D editor intersects it with its ground plane, `y = 0`).
1648
+ * Absent when the host builds no ray (a headless view, a point outside the canvas) and from a host
1649
+ * from before it.
1650
+ */
1651
+ readonly ray?: PickRay;
1652
+ /**
1653
+ * Where `ray` meets the 2D world plane `z = 0`, as `[x, y, 0]`: in a 2D scene, the world point
1654
+ * under the cursor. Absent when `ray` is, and when the ray runs parallel to the plane or meets it
1655
+ * behind its origin.
1656
+ */
1657
+ readonly plane?: Vec3;
1658
+ }
1659
+ /**
1660
+ * The image formats of a `screenshot`.
1661
+ *
1662
+ * @public
1663
+ */
1664
+ export declare const ScreenshotFormat: {
1665
+ /** Lossless, `image/png`. */
1666
+ readonly png: "png";
1667
+ /** Lossy, `image/jpeg`. */
1668
+ readonly jpeg: "jpeg";
1669
+ };
1670
+ /**
1671
+ * The union of the formats in `ScreenshotFormat`.
1672
+ *
1673
+ * @public
1674
+ */
1675
+ export type ScreenshotFormat = (typeof ScreenshotFormat)[keyof typeof ScreenshotFormat];
1676
+ /**
1677
+ * The parameters of `screenshot`.
1678
+ *
1679
+ * @public
1680
+ */
1681
+ interface ScreenshotParams {
1682
+ /** The image width in pixels, 1 to {@link SCREENSHOT_MAX_SIZE}; absent to follow the view. */
1683
+ readonly width?: number;
1684
+ /** The image height in pixels, 1 to {@link SCREENSHOT_MAX_SIZE}; absent to follow the view. */
1685
+ readonly height?: number;
1686
+ /** The image format. */
1687
+ readonly format: ScreenshotFormat;
1688
+ /** The JPEG quality, from 0 to 1; the host's default (0.9) when absent. Ignored for PNG. */
1689
+ readonly quality?: number;
1690
+ }
1691
+ /**
1692
+ * The answer to `screenshot`.
1693
+ *
1694
+ * @public
1695
+ */
1696
+ interface ScreenshotResult {
1697
+ /** The image as a `data:image/png;base64,…` or `data:image/jpeg;base64,…` URL. */
1698
+ readonly dataUrl: string;
1699
+ /** The image width in pixels. */
1700
+ readonly width: number;
1701
+ /** The image height in pixels. */
1702
+ readonly height: number;
1703
+ }
1704
+ /**
1705
+ * One field of a component schema: the engine's `SchemaFieldDescription`.
1706
+ *
1707
+ * @public
1708
+ */
1709
+ interface SchemaFieldDescription {
1710
+ /** The field kind, for example `"f32"` or `"asset"`; an editor shows a kind it does not know as JSON. */
1711
+ readonly kind: string;
1712
+ /** The field's default value, encoded as JSON. */
1713
+ readonly default?: JsonValue;
1714
+ /** The field's tooltip. */
1715
+ readonly description?: string;
1716
+ /**
1717
+ * The increment of the inspector's drag and spinner controls (`FieldOptions.step`), present only
1718
+ * when the field declares one; in degrees for a `quat` field, which an inspector edits as Euler
1719
+ * angles.
1720
+ */
1721
+ readonly step?: number;
1722
+ /** `FieldOptions.hidden`: the inspector leaves the field out; it is still saved. */
1723
+ readonly hidden?: boolean;
1724
+ /** `FieldOptions.readonly`: the inspector shows the field but does not let it be edited. */
1725
+ readonly readonly?: boolean;
1726
+ /** `FieldOptions.group`: the inspector group the field folds into. */
1727
+ readonly group?: string;
1728
+ /**
1729
+ * An `asset` field's asset type name (`asset(TextureAsset)` → `"texture"`), the `type` an asset
1730
+ * reference to it carries; absent when the asset token names no type.
1731
+ */
1732
+ readonly assetType?: string;
1733
+ /**
1734
+ * A `componentRef` field's accepted component, as its `typeId`, or `null` when the class it was
1735
+ * declared with carries no `typeId`; present on every `componentRef` field a 0.3 host describes
1736
+ * with core's `describeRegisteredSchemas`.
1737
+ */
1738
+ readonly componentType?: string | null;
1739
+ }
1740
+ /**
1741
+ * One component schema: the engine's `SchemaDescription`, plus the JSON Schema of its `props`.
1742
+ *
1743
+ * @public
1744
+ */
1745
+ interface SchemaDescription {
1746
+ /** The human-readable name. */
1747
+ readonly title: string;
1748
+ /** `"components"` for a component; a file format's name for the engine's file-format entries. */
1749
+ readonly format: string;
1750
+ /** A one-line summary. */
1751
+ readonly description?: string;
1752
+ /** Every declared field, in declaration order. */
1753
+ readonly fields: Readonly<Record<string, SchemaFieldDescription>>;
1754
+ /**
1755
+ * Whether an entity may hold more than one of the component (the class's `static allowMultiple`,
1756
+ * `true` when it declares nothing); absent on file-format entries and from a host from before
1757
+ * core's `describeRegisteredSchemas`, where an editor assumes `true`.
1758
+ */
1759
+ readonly allowMultiple?: boolean;
1760
+ /**
1761
+ * Who registered the component: the extension's `name` (the npm package name, for example
1762
+ * `@ignifx/3d`), or, for a class the game registered itself, its type id's namespace (`game` for
1763
+ * `game/Health`); absent on file-format entries and from a host from before
1764
+ * `describeRegisteredSchemas`.
1765
+ */
1766
+ readonly package?: string;
1767
+ /**
1768
+ * `true` for the one component every entity carries itself, `ignifx/Transform`: it is never in a
1769
+ * scene file's `components` list, an editor neither adds nor removes it, and its fields are the
1770
+ * entity record's `transform` block, edited whole with the `setTransform` op rather than prop by
1771
+ * prop. Absent on every other entry. A host from before the engine described the transform (engine
1772
+ * ask E4) sends no such member.
1773
+ */
1774
+ readonly builtIn?: boolean;
1775
+ /**
1776
+ * The JSON Schema of the component's `props` (the engine's `toJsonSchema(schema)`), which adds
1777
+ * each field's `minimum`, `maximum`, `enum` and nested shapes; absent for file-format entries.
1778
+ */
1779
+ readonly propsSchema?: JsonObject;
1780
+ }
1781
+ /**
1782
+ * Every schema the host's app knows: the answer to `getSchemas` and the parameters of
1783
+ * `schemasChanged`.
1784
+ *
1785
+ * @public
1786
+ */
1787
+ interface SchemaSet {
1788
+ /** The descriptions, keyed by component `typeId` (file formats by `ignifx/<format>-file`). */
1789
+ readonly schemas: Readonly<Record<string, SchemaDescription>>;
1790
+ }
1791
+ /**
1792
+ * The project's settings as the host's app has them: the answer to `describeSettings`.
1793
+ *
1794
+ * @public
1795
+ */
1796
+ interface SettingsSet {
1797
+ /**
1798
+ * Every settings section the app registered (core's and each extension's), keyed by section name,
1799
+ * in registration order: the engine's `describeSettings(app)`. Each has `format: "settings"`, the
1800
+ * registering extension as `package`, field defaults in the settings form (a vector is
1801
+ * `{ x, y, z }` and a colour `{ r, g, b, a }`, not the scene file's arrays), and as `propsSchema`
1802
+ * the JSON Schema of the section as `ignifx.settings.json` may write it (its entry in the engine's
1803
+ * `settingsJsonSchema(app)`).
1804
+ */
1805
+ readonly sections: Readonly<Record<string, SchemaDescription>>;
1806
+ /**
1807
+ * The values the app resolved for each section, keyed by section name, in the same settings form:
1808
+ * the project's settings over the section's defaults. A value JSON cannot carry (a function, a
1809
+ * non-finite number) is left out.
1810
+ */
1811
+ readonly values: Readonly<Record<string, JsonObject>>;
1812
+ }
1813
+ /**
1814
+ * The editor cameras the view can use.
1815
+ *
1816
+ * @public
1817
+ */
1818
+ export declare const ViewMode: {
1819
+ /** The 3D editor camera, gizmos and grid. */
1820
+ readonly threeD: "3d";
1821
+ /** The 2D editor camera, planar gizmos and pixel grid. Needs `HostCapability.viewMode2d`. */
1822
+ readonly twoD: "2d";
1823
+ };
1824
+ /**
1825
+ * The union of the modes in `ViewMode`.
1826
+ *
1827
+ * @public
1828
+ */
1829
+ export type ViewMode = (typeof ViewMode)[keyof typeof ViewMode];
1830
+ /**
1831
+ * The parameters of `setViewMode`.
1832
+ *
1833
+ * @public
1834
+ */
1835
+ interface SetViewModeParams {
1836
+ /** The editor camera to use. */
1837
+ readonly mode: ViewMode;
1838
+ }
1839
+ /**
1840
+ * The parameters of `sceneOpened`.
1841
+ *
1842
+ * @public
1843
+ */
1844
+ interface SceneOpenedParams {
1845
+ /** The address `openScene` was given. */
1846
+ readonly address: string | null;
1847
+ /** The file's `name`. */
1848
+ readonly name: string;
1849
+ /** As in {@link OpenSceneResult}. */
1850
+ readonly entityCount: number;
1851
+ /** As in {@link OpenSceneResult}. */
1852
+ readonly warnings: readonly SceneIssue[];
1853
+ /** As in {@link OpenSceneResult}. */
1854
+ readonly viewMode?: ViewMode;
1855
+ }
1856
+ /**
1857
+ * One error a hot reload ran into.
1858
+ *
1859
+ * @public
1860
+ */
1861
+ interface HotReloadError {
1862
+ /** The error's message (`String(error)` when it is not an `Error`). */
1863
+ readonly message: string;
1864
+ /** Its `IGX-` code when it is an `IgnifxError`, else `null`. */
1865
+ readonly code: string | null;
1866
+ /** Its `stack`, or `null` when it has none. Additive in 0.3: a host from before it leaves it out. */
1867
+ readonly stack?: string | null;
1868
+ }
1869
+ /**
1870
+ * What one hot reload did: the engine's `HotReloadReport`, with its errors made JSON.
1871
+ *
1872
+ * @public
1873
+ */
1874
+ interface HotReloadReport {
1875
+ /** Which operation: a prototype swap, a recreate of instances, or a scene rebuild. */
1876
+ readonly kind: "patch" | "recreate" | "scene";
1877
+ /** The `typeId`s reloaded, in the order applied. */
1878
+ readonly typeIds: readonly string[];
1879
+ /** How many live component instances were swapped or re-created, or entities rebuilt. */
1880
+ readonly instances: number;
1881
+ /** How long it took, in milliseconds. */
1882
+ readonly durationMs: number;
1883
+ /** Everything that threw on the way. */
1884
+ readonly errors: readonly HotReloadError[];
1885
+ }
1886
+ /**
1887
+ * The parameters of `hotReloaded`.
1888
+ *
1889
+ * @public
1890
+ */
1891
+ interface HotReloadedParams {
1892
+ /** The report `app.hotReload.onApplied` emitted. */
1893
+ readonly report: HotReloadReport;
1894
+ }
1895
+ /**
1896
+ * The parameters of `assetReloaded`.
1897
+ *
1898
+ * @remarks
1899
+ * The host reloads an asset in place when the dev server reports it changed on disk and the scene
1900
+ * view's app has it loaded: a scene or prefab (`"scene"`), whose document instances it rebuilds from
1901
+ * the new file with their uids, transforms and overrides, and a model, mesh, material, sprite atlas
1902
+ * or shader, which the renderers pick up on their next frame. Any other type, such as a texture, is
1903
+ * left as it was loaded and sends nothing. The open document's own file is never reloaded.
1904
+ *
1905
+ * @public
1906
+ */
1907
+ interface AssetReloadedParams {
1908
+ /** The asset's address, relative to the asset root. */
1909
+ readonly address: string;
1910
+ /** Its asset type, as the manifest records it: `"scene"` for a scene or a prefab. */
1911
+ readonly type: string;
1912
+ /**
1913
+ * The uids of the document's instance roots rebuilt from the new file, in document order: those
1914
+ * that instance it, directly or through another scene. Empty for any other type.
1915
+ */
1916
+ readonly entities: readonly string[];
1917
+ }
1918
+ /**
1919
+ * The parameters of `transformDragging`.
1920
+ *
1921
+ * @public
1922
+ */
1923
+ interface TransformDraggingParams {
1924
+ /** The dragged entity's uid. */
1925
+ readonly entity: string;
1926
+ /** The gizmo mode of the drag. */
1927
+ readonly mode: GizmoDragMode;
1928
+ /** Its local transform now, rounded as the engine writes numbers. */
1929
+ readonly after: SceneFileTransform;
1930
+ }
1931
+ /**
1932
+ * The parameters of `transformDragged`: the shape of a `setTransform` op plus the drag's mode.
1933
+ *
1934
+ * @public
1935
+ */
1936
+ interface TransformDraggedParams {
1937
+ /** The dragged entity's uid. */
1938
+ readonly entity: string;
1939
+ /** The gizmo mode of the drag, for the command's name. */
1940
+ readonly mode: GizmoDragMode;
1941
+ /** Its local transform when the drag started. */
1942
+ readonly before: SceneFileTransform;
1943
+ /** Its local transform at pointer-up. */
1944
+ readonly after: SceneFileTransform;
1945
+ }
1946
+ /**
1947
+ * The parameters of `hostError`.
1948
+ *
1949
+ * @public
1950
+ */
1951
+ interface HostErrorParams {
1952
+ /** The engine's `IGX-` code, or `null` when the error had none. */
1953
+ readonly code: string | null;
1954
+ /** An actionable sentence. */
1955
+ readonly message: string;
1956
+ /** Extra detail as JSON, when there is any. */
1957
+ readonly data?: JsonValue;
1958
+ }
1959
+ /**
1960
+ * The `data` of a `hostError` the host sends for an error the app reported through `app.onError`:
1961
+ * where it was caught. The host's `message` and `code` are the thrown error's.
1962
+ *
1963
+ * @remarks
1964
+ * `source`, `phase` and `entity` are in every 0.3 host; the other fields are additive in 0.3, sent by
1965
+ * a host that lists `HostCapability.logRelay`.
1966
+ *
1967
+ * @public
1968
+ */
1969
+ interface AppErrorData {
1970
+ /** Which boundary caught it: the engine's `ErrorReport.source`, such as `"lifecycle"`. */
1971
+ readonly source: string;
1972
+ /** The phase that was running, as the engine's `Phase` value, or `null` outside a phase. */
1973
+ readonly phase: number | null;
1974
+ /** That phase's name in the engine's `Phase`, such as `"Update"`, or `null`. */
1975
+ readonly phaseName?: string | null;
1976
+ /** The uid of the entity involved, or `null`. */
1977
+ readonly entity: string | null;
1978
+ /** The name of the entity involved, or `null`. */
1979
+ readonly entityName?: string | null;
1980
+ /** The `typeId` of the component involved (its class name when it has none), or `null`. */
1981
+ readonly component?: string | null;
1982
+ /** The thrown error's `stack`, or `null` when it has none. */
1983
+ readonly stack?: string | null;
1984
+ }
1985
+ /**
1986
+ * A log line's severity: the engine's `LogLevel`.
1987
+ *
1988
+ * @public
1989
+ */
1990
+ type LogLevel = "debug" | "info" | "warn" | "error";
1991
+ /**
1992
+ * An `Error` a log line carried among its extras, made JSON.
1993
+ *
1994
+ * @public
1995
+ */
1996
+ interface LoggedError {
1997
+ /** The error's message. */
1998
+ readonly message: string;
1999
+ /** Its `IGX-` code when it is an `IgnifxError`, else `null`. */
2000
+ readonly code: string | null;
2001
+ /** Its `stack`, or `null` when it has none. */
2002
+ readonly stack: string | null;
2003
+ }
2004
+ /**
2005
+ * The parameters of `log`: the engine's `LogRecord` without its `data`, which is not JSON, but for
2006
+ * the first `Error` in it.
2007
+ *
2008
+ * @public
2009
+ */
2010
+ interface LogParams {
2011
+ /** The severity. */
2012
+ readonly level: LogLevel;
2013
+ /** The logger's dotted scope, or `null` for the root logger. */
2014
+ readonly scope: string | null;
2015
+ /** The message. */
2016
+ readonly message: string;
2017
+ /** The logger clock's reading, in milliseconds. */
2018
+ readonly timeMs: number;
2019
+ /**
2020
+ * The first `Error` among the record's extras, such as the one the app's default `onError` handler
2021
+ * logs. Additive in 0.3: a host from before it leaves it out.
2022
+ */
2023
+ readonly error?: LoggedError;
2024
+ }
2025
+ /**
2026
+ * A request whose `params` are required.
2027
+ *
2028
+ * @typeParam M - The method name.
2029
+ * @typeParam P - The parameters.
2030
+ *
2031
+ * @public
2032
+ */
2033
+ interface RpcRequestWithParams<M extends string, P> extends RpcRequest<M, P> {
2034
+ /** The method's parameters. */
2035
+ readonly params: P;
2036
+ }
2037
+ /**
2038
+ * A notification whose `params` are required.
2039
+ *
2040
+ * @typeParam M - The method name.
2041
+ * @typeParam P - The parameters.
2042
+ *
2043
+ * @public
2044
+ */
2045
+ interface RpcNotificationWithParams<M extends string, P> extends RpcNotification<M, P> {
2046
+ /** The notification's parameters. */
2047
+ readonly params: P;
2048
+ }
2049
+ /**
2050
+ * Editor → scene host: one of the `SceneMethod`s. `closeScene`, `getSchemas` and `describeSettings`
2051
+ * take no parameters.
2052
+ *
2053
+ * @public
2054
+ */
2055
+ type SceneRequest = RpcRequestWithParams<typeof SceneMethod.openScene, OpenSceneParams> | RpcRequest<typeof SceneMethod.closeScene, never> | RpcRequestWithParams<typeof SceneMethod.applyOps, ApplyOpsParams> | RpcRequestWithParams<typeof SceneMethod.readBack, ReadBackParams> | RpcRequestWithParams<typeof SceneMethod.select, EntitySelection> | RpcRequestWithParams<typeof SceneMethod.setGizmo, SetGizmoParams> | RpcRequestWithParams<typeof SceneMethod.frame, FrameParams> | RpcRequestWithParams<typeof SceneMethod.pick, PickParams> | RpcRequestWithParams<typeof SceneMethod.screenshot, ScreenshotParams> | RpcRequest<typeof SceneMethod.getSchemas, never> | RpcRequest<typeof SceneMethod.describeSettings, never> | RpcRequestWithParams<typeof SceneMethod.setViewMode, SetViewModeParams>;
2056
+ /**
2057
+ * The success answer of the `SceneMethod`s that return nothing: `closeScene`, `setGizmo`, `frame`
2058
+ * and `setViewMode`.
2059
+ *
2060
+ * @public
2061
+ */
2062
+ type NullResponse = RpcSuccessResponse<null>;
2063
+ /**
2064
+ * The success answer to `openScene`.
2065
+ *
2066
+ * @public
2067
+ */
2068
+ type OpenSceneResponse = RpcSuccessResponse<OpenSceneResult>;
2069
+ /**
2070
+ * The success answer to `applyOps`.
2071
+ *
2072
+ * @public
2073
+ */
2074
+ type ApplyOpsResponse = RpcSuccessResponse<ApplyOpsResult>;
2075
+ /**
2076
+ * The success answer to `readBack`.
2077
+ *
2078
+ * @public
2079
+ */
2080
+ type ReadBackResponse = RpcSuccessResponse<ReadBackResult>;
2081
+ /**
2082
+ * The success answer to `select`.
2083
+ *
2084
+ * @public
2085
+ */
2086
+ type SelectResponse = RpcSuccessResponse<EntitySelection>;
2087
+ /**
2088
+ * The success answer to `pick`.
2089
+ *
2090
+ * @public
2091
+ */
2092
+ type PickResponse = RpcSuccessResponse<PickResult>;
2093
+ /**
2094
+ * The success answer to `screenshot`.
2095
+ *
2096
+ * @public
2097
+ */
2098
+ type ScreenshotResponse = RpcSuccessResponse<ScreenshotResult>;
2099
+ /**
2100
+ * The success answer to `getSchemas`.
2101
+ *
2102
+ * @public
2103
+ */
2104
+ type GetSchemasResponse = RpcSuccessResponse<SchemaSet>;
2105
+ /**
2106
+ * The success answer to `describeSettings`.
2107
+ *
2108
+ * @public
2109
+ */
2110
+ type DescribeSettingsResponse = RpcSuccessResponse<SettingsSet>;
2111
+ /**
2112
+ * Scene host → editor: one of the `SceneNotification`s.
2113
+ *
2114
+ * @public
2115
+ */
2116
+ type SceneHostNotification = RpcNotificationWithParams<typeof SceneNotification.sceneOpened, SceneOpenedParams> | RpcNotificationWithParams<typeof SceneNotification.schemasChanged, SchemaSet> | RpcNotificationWithParams<typeof SceneNotification.hotReloaded, HotReloadedParams> | RpcNotificationWithParams<typeof SceneNotification.selectionChanged, EntitySelection> | RpcNotificationWithParams<typeof SceneNotification.transformDragging, TransformDraggingParams> | RpcNotificationWithParams<typeof SceneNotification.transformDragged, TransformDraggedParams> | RpcNotificationWithParams<typeof SceneNotification.hostError, HostErrorParams> | RpcNotificationWithParams<typeof SceneNotification.log, LogParams> | RpcNotificationWithParams<typeof SceneNotification.assetReloaded, AssetReloadedParams>;
2117
+ /**
2118
+ * Checks one engine issue.
2119
+ *
2120
+ * @param value - The value to test.
2121
+ * @returns True for `{ code: string, message: string }`.
2122
+ *
2123
+ * @public
2124
+ */
2125
+ export declare function isSceneIssue(value: unknown): value is SceneIssue;
2126
+ /**
2127
+ * Checks the parameters of `openScene`.
2128
+ *
2129
+ * @param value - The received `params`.
2130
+ * @returns True for a structurally valid scene file and a string or `null` address.
2131
+ *
2132
+ * @public
2133
+ */
2134
+ export declare function isOpenSceneParams(value: unknown): value is OpenSceneParams;
2135
+ /**
2136
+ * Checks the result of `openScene`.
2137
+ *
2138
+ * @param value - The received `result`.
2139
+ * @returns True for a count, a list of issues, and an optional view mode.
2140
+ *
2141
+ * @public
2142
+ */
2143
+ export declare function isOpenSceneResult(value: unknown): value is OpenSceneResult;
2144
+ /**
2145
+ * Checks the `data` of the `invalidParams` error `openScene` answers for a file
2146
+ * `validateSceneFile` refuses.
2147
+ *
2148
+ * @param value - The received `error.data`.
2149
+ * @returns True for `{ issues: [{ path, message }] }`.
2150
+ *
2151
+ * @public
2152
+ */
2153
+ export declare function isInvalidSceneFileData(value: unknown): value is InvalidSceneFileData;
2154
+ /**
2155
+ * Checks the parameters of `applyOps`.
2156
+ *
2157
+ * @param value - The received `params`.
2158
+ * @returns True when every op passes {@link isSceneOp} and the command has a name and an id.
2159
+ *
2160
+ * @public
2161
+ */
2162
+ export declare function isApplyOpsParams(value: unknown): value is ApplyOpsParams;
2163
+ /**
2164
+ * Checks the result of `applyOps`.
2165
+ *
2166
+ * @param value - The received `result`.
2167
+ * @returns True for a count of applied ops and a list of failures with known codes.
2168
+ *
2169
+ * @public
2170
+ */
2171
+ export declare function isApplyOpsResult(value: unknown): value is ApplyOpsResult;
2172
+ /**
2173
+ * Checks the parameters of `readBack`.
2174
+ *
2175
+ * @param value - The received `params`.
2176
+ * @returns True for an object with an optional list of uids.
2177
+ *
2178
+ * @public
2179
+ */
2180
+ export declare function isReadBackParams(value: unknown): value is ReadBackParams;
2181
+ /**
2182
+ * Checks the result of `readBack`.
2183
+ *
2184
+ * @param value - The received `result`.
2185
+ * @returns True for entity records, missing uids, settings or `null`, and issues.
2186
+ *
2187
+ * @public
2188
+ */
2189
+ export declare function isReadBackResult(value: unknown): value is ReadBackResult;
2190
+ /**
2191
+ * Checks a selection: the parameters and result of `select` and the parameters of
2192
+ * `selectionChanged`.
2193
+ *
2194
+ * @param value - The received `params` or `result`.
2195
+ * @returns True for `{ entities: uid[] }`.
2196
+ *
2197
+ * @public
2198
+ */
2199
+ export declare function isEntitySelection(value: unknown): value is EntitySelection;
2200
+ /**
2201
+ * Checks the parameters of `setGizmo`.
2202
+ *
2203
+ * @param value - The received `params`.
2204
+ * @returns True for a known mode and space and a snap of three non-negative numbers, or `null`.
2205
+ *
2206
+ * @public
2207
+ */
2208
+ export declare function isSetGizmoParams(value: unknown): value is SetGizmoParams;
2209
+ /**
2210
+ * Checks the parameters of `frame`.
2211
+ *
2212
+ * @param value - The received `params`.
2213
+ * @returns True for a list of uids or `"all"`.
2214
+ *
2215
+ * @public
2216
+ */
2217
+ export declare function isFrameParams(value: unknown): value is FrameParams;
2218
+ /**
2219
+ * Checks the parameters of `pick`.
2220
+ *
2221
+ * @param value - The received `params`.
2222
+ * @returns True for finite `x` and `y` and a known unit.
2223
+ *
2224
+ * @public
2225
+ */
2226
+ export declare function isPickParams(value: unknown): value is PickParams;
2227
+ /**
2228
+ * Checks the result of `pick`.
2229
+ *
2230
+ * @param value - The received `result`.
2231
+ * @returns True for a uid or `null`, a point or `null`, a non-negative distance or `null`, an
2232
+ * optional ray and an optional plane point.
2233
+ *
2234
+ * @public
2235
+ */
2236
+ export declare function isPickResult(value: unknown): value is PickResult;
2237
+ /**
2238
+ * Checks the parameters of `screenshot`.
2239
+ *
2240
+ * @param value - The received `params`.
2241
+ * @returns True for a known format, sizes in range when given, and a quality from 0 to 1 when given.
2242
+ *
2243
+ * @public
2244
+ */
2245
+ export declare function isScreenshotParams(value: unknown): value is ScreenshotParams;
2246
+ /**
2247
+ * Checks the result of `screenshot`.
2248
+ *
2249
+ * @param value - The received `result`.
2250
+ * @returns True for a PNG or JPEG data URL and sizes in range.
2251
+ *
2252
+ * @public
2253
+ */
2254
+ export declare function isScreenshotResult(value: unknown): value is ScreenshotResult;
2255
+ /**
2256
+ * Checks the result of `getSchemas` and the parameters of `schemasChanged`.
2257
+ *
2258
+ * @param value - The received `result` or `params`.
2259
+ * @returns True for `{ schemas }` whose every entry is a schema description.
2260
+ *
2261
+ * @public
2262
+ */
2263
+ export declare function isSchemaSet(value: unknown): value is SchemaSet;
2264
+ /**
2265
+ * Checks the result of `describeSettings`.
2266
+ *
2267
+ * @param value - The received `result`.
2268
+ * @returns True for `{ sections, values }`: every section a schema description, every value an
2269
+ * object.
2270
+ *
2271
+ * @public
2272
+ */
2273
+ export declare function isSettingsSet(value: unknown): value is SettingsSet;
2274
+ /**
2275
+ * Checks the parameters of `setViewMode`.
2276
+ *
2277
+ * @param value - The received `params`.
2278
+ * @returns True for `{ mode: "3d" | "2d" }`.
2279
+ *
2280
+ * @public
2281
+ */
2282
+ export declare function isSetViewModeParams(value: unknown): value is SetViewModeParams;
2283
+ /**
2284
+ * Checks the parameters of `sceneOpened`.
2285
+ *
2286
+ * @param value - The received `params`.
2287
+ * @returns True for an address or `null`, a name, a count, issues, and an optional view mode.
2288
+ *
2289
+ * @public
2290
+ */
2291
+ export declare function isSceneOpenedParams(value: unknown): value is SceneOpenedParams;
2292
+ /**
2293
+ * Checks the parameters of `hotReloaded`.
2294
+ *
2295
+ * @param value - The received `params`.
2296
+ * @returns True for `{ report }` with a known kind, type ids, counts and JSON errors.
2297
+ *
2298
+ * @public
2299
+ */
2300
+ export declare function isHotReloadedParams(value: unknown): value is HotReloadedParams;
2301
+ /**
2302
+ * Checks the parameters of `assetReloaded`.
2303
+ *
2304
+ * @param value - The received `params`.
2305
+ * @returns True for `{ address, type, entities }` with a non-empty address and type.
2306
+ *
2307
+ * @public
2308
+ */
2309
+ export declare function isAssetReloadedParams(value: unknown): value is AssetReloadedParams;
2310
+ /**
2311
+ * Checks the parameters of `transformDragging`.
2312
+ *
2313
+ * @param value - The received `params`.
2314
+ * @returns True for an entity, a drag mode and a transform.
2315
+ *
2316
+ * @public
2317
+ */
2318
+ export declare function isTransformDraggingParams(value: unknown): value is TransformDraggingParams;
2319
+ /**
2320
+ * Checks the parameters of `transformDragged`.
2321
+ *
2322
+ * @param value - The received `params`.
2323
+ * @returns True for an entity, a drag mode and two transforms.
2324
+ *
2325
+ * @public
2326
+ */
2327
+ export declare function isTransformDraggedParams(value: unknown): value is TransformDraggedParams;
2328
+ /**
2329
+ * Checks the parameters of `hostError`.
2330
+ *
2331
+ * @param value - The received `params`.
2332
+ * @returns True for a code or `null`, a message and optional JSON data.
2333
+ *
2334
+ * @public
2335
+ */
2336
+ export declare function isHostErrorParams(value: unknown): value is HostErrorParams;
2337
+ /**
2338
+ * Checks the `data` of a `hostError` for an error the app reported.
2339
+ *
2340
+ * @param value - The received `data`.
2341
+ * @returns True for a boundary name, a phase or `null`, an entity uid or `null`, and, when present,
2342
+ * a phase name, an entity name, a component and a stack, each a string or `null`.
2343
+ *
2344
+ * @public
2345
+ */
2346
+ export declare function isAppErrorData(value: unknown): value is AppErrorData;
2347
+ /**
2348
+ * Checks the parameters of `log`.
2349
+ *
2350
+ * @param value - The received `params`.
2351
+ * @returns True for a known level, a scope or `null`, a message and a finite time.
2352
+ *
2353
+ * @public
2354
+ */
2355
+ export declare function isLogParams(value: unknown): value is LogParams;
2356
+ //#endregion
2357
+ //#region src/channel.d.ts
2358
+ /**
2359
+ * Where a host listens for the editor's connect message: the view's `window` in a browser, or any
2360
+ * `EventTarget` that dispatches `MessageEvent`s, which is how a headless test stands in for one.
2361
+ * Events that are not `MessageEvent`s are ignored.
2362
+ *
2363
+ * @beta
2364
+ */
2365
+ interface EditorMessageTarget {
2366
+ /**
2367
+ * Subscribes to window messages.
2368
+ *
2369
+ * @param type - Always `"message"`.
2370
+ * @param listener - Receives each message.
2371
+ */
2372
+ addEventListener(type: "message", listener: (event: Event) => void): void;
2373
+ /**
2374
+ * Unsubscribes a listener added with `addEventListener`.
2375
+ *
2376
+ * @param type - Always `"message"`.
2377
+ * @param listener - The listener to remove.
2378
+ */
2379
+ removeEventListener(type: "message", listener: (event: Event) => void): void;
2380
+ }
2381
+ //#endregion
2382
+ //#region src/scene/asset-reload.d.ts
2383
+ /**
2384
+ * A change on disk to one asset, as `@ignifx/vite-plugin`'s `ignifx:asset-changed` event reports
2385
+ * it; the event's payload is accepted as it is.
2386
+ *
2387
+ * @beta
2388
+ */
2389
+ interface EditorAssetChange {
2390
+ /** The asset's address, relative to the asset root. */
2391
+ readonly address: string;
2392
+ /** What happened to the file. */
2393
+ readonly kind: "added" | "changed" | "removed";
2394
+ }
2395
+ //#endregion
2396
+ //#region src/host.d.ts
2397
+ /**
2398
+ * Options accepted by {@link startEditorHost}. The app options are the ones the project's `main.ts`
2399
+ * passes to `createApp`; the editor host's Vite plugin generates the call that supplies them.
2400
+ *
2401
+ * @beta
2402
+ */
2403
+ interface EditorHostOptions {
2404
+ /**
2405
+ * The origin the editor is served from, for example `"ignifx://app"`. A port posted from any
2406
+ * other origin is ignored.
2407
+ */
2408
+ readonly editorOrigin: string;
2409
+ /** Which view this host runs. Only `"scene"` exists in this release. Defaults to `"scene"`. */
2410
+ readonly hostKind?: typeof HostKind.scene;
2411
+ /** The canvas to render into. Without one the app is headless. */
2412
+ readonly canvas?: RenderSurface;
2413
+ /** Run on Babylon Lite's null engine. Defaults to `true` when there is no `canvas`. */
2414
+ readonly headless?: boolean;
2415
+ /**
2416
+ * Build the app in edit mode (`createApp({ editMode })`, ADR-0028), so the scene view shows the
2417
+ * scene without playing it: only scripts whose class sets `static runInEditMode = true` get
2418
+ * callbacks, and physics and other game-clock systems hold or skip. Defaults to `true`; pass
2419
+ * `false` to run the scene view as a game.
2420
+ */
2421
+ readonly editMode?: boolean;
2422
+ /** The project's extensions, in the order its `main.ts` registers them. */
2423
+ readonly extensions?: readonly Extension[];
2424
+ /** The project's component classes, registered with `app.registerComponents`. */
2425
+ readonly scripts?: readonly ConcreteComponentType[];
2426
+ /** Project settings, as `ignifx.config.ts` supplies them (`import.meta.env.IGNIFX_CONFIG`). */
2427
+ readonly settings?: SettingsInput;
2428
+ /** The asset manifest and `fetch`, as the project's `main.ts` passes them. */
2429
+ readonly assets?: AssetsCreateOptions;
2430
+ /** A scene address to load before the app starts, through the normal loader. Defaults to none. */
2431
+ readonly bootScene?: string | null;
2432
+ /**
2433
+ * The project's `@ignifx/core` version, reported in `ready`. Used only while core's own
2434
+ * `VERSION` is the unstamped `"0.0.0"`; the Vite plugin reads it from the project's installed
2435
+ * `@ignifx/core/package.json`.
2436
+ */
2437
+ readonly engineVersion?: string;
2438
+ /** Milliseconds between heartbeats once the editor has said `hello`. Defaults to `1000`. */
2439
+ readonly heartbeatIntervalMs?: number;
2440
+ /** Where the editor's connect message arrives. Defaults to the page's `window`. */
2441
+ readonly messageTarget?: EditorMessageTarget;
2442
+ }
2443
+ /**
2444
+ * A running scene-view host. The host owns its app: disposing the host disposes the app.
2445
+ *
2446
+ * @beta
2447
+ */
2448
+ interface EditorHost {
2449
+ /** The app the scene view shows. */
2450
+ readonly app: App;
2451
+ /** The instance of `bootScene`, or `null` when none was given. */
2452
+ readonly bootScene: SceneInstance | null;
2453
+ /**
2454
+ * The persistent scene instance named `editor` that holds the host's own objects, such as the
2455
+ * editor camera. It survives every scene the editor opens and is never part of the document.
2456
+ */
2457
+ readonly editorScene: SceneInstance;
2458
+ /** The engine version the host reports in `ready`. */
2459
+ readonly engineVersion: string;
2460
+ /** Whether the editor has handed the host a port that is still open. */
2461
+ readonly isConnected: boolean;
2462
+ /**
2463
+ * Reloads an asset that changed on disk, in place, through `app.assets.reload`. The generated
2464
+ * scene-view module calls it on every `ignifx:asset-changed` event.
2465
+ *
2466
+ * @remarks
2467
+ * Only an asset the app has loaded is reloaded, and only one of the types the renderers follow:
2468
+ * a scene or prefab, whose instances in the open document are then rebuilt from the new file with
2469
+ * their uids, transforms and overrides, or a model, mesh, material, sprite atlas or shader, which
2470
+ * the renderers pick up on their next frame. A texture, a removed file and the open document's
2471
+ * own file are left alone. Once the new value is in, the host sends `assetReloaded` with the
2472
+ * address, the type and the rebuilt instance roots, so the editor can compare its document with
2473
+ * the view instead of reloading it.
2474
+ *
2475
+ * @param change - The address and what happened to it.
2476
+ * @returns Whether the asset was reloaded; `false` when it was left alone or the reload failed,
2477
+ * which the app reports as an error (`hostError`).
2478
+ */
2479
+ assetChanged(change: EditorAssetChange): Promise<boolean>;
2480
+ /** Stops the heartbeat, closes the port, and disposes the app. Idempotent. */
2481
+ dispose(): void;
2482
+ /** Same as {@link EditorHost.dispose}, for `using`. */
2483
+ [Symbol.dispose](): void;
2484
+ }
2485
+ /**
2486
+ * Starts the scene view's host: listens for the editor's port, creates the app from the project's
2487
+ * own `@ignifx/core` (in edit mode unless `editMode` is `false`), registers the project's scripts,
2488
+ * loads `bootScene` if one is given, starts the app, and serves the editor protocol's scene methods
2489
+ * (protocol 0.3, `docs/architecture/17-editor-host.md` §6).
2490
+ *
2491
+ * @remarks
2492
+ * The host answers `hello` with `ready` and `ping` with `"pong"` as soon as a port arrives, even
2493
+ * while the app is still being created; the scene methods answer `notReady` until the app has
2494
+ * started, and the host's first `schemasChanged` says they are accepted. It accepts a new port
2495
+ * whenever the editor sends one, closing the previous port.
2496
+ *
2497
+ * With a `canvas` the host draws Babylon Lite's gizmos and a selection outline in core's render
2498
+ * overlay (`app.renderer.openOverlay()`), answers `screenshot`, and has a 2D view mode
2499
+ * (`setViewMode`), which shows the sprites through an editor-owned `Camera2D` and picks them with
2500
+ * `app.twoD.pickAt` when the project registers `@ignifx/2d`. A headless host serves every method
2501
+ * that needs no GPU.
2502
+ *
2503
+ * @param options - The editor's origin and the project's app options.
2504
+ * @returns The running host, once the app has started.
2505
+ * @throws IgnifxError `IGX-1801` for a malformed `editorOrigin`, `IGX-1802` with no window and no
2506
+ * `messageTarget`, `IGX-1803` for a bad `heartbeatIntervalMs`. Whatever `createApp`, the scene
2507
+ * load, or `start` throws is rethrown after the channel is closed.
2508
+ *
2509
+ * @example
2510
+ * ```ts
2511
+ * import { startEditorHost } from "@ignifx/editor-host";
2512
+ *
2513
+ * const host = await startEditorHost({ editorOrigin: "ignifx://app", canvas, extensions: [], scripts });
2514
+ * ```
2515
+ *
2516
+ * @beta
2517
+ */
2518
+ export declare function startEditorHost(options: EditorHostOptions): Promise<EditorHost>;
2519
+ //#endregion
2520
+ //#region src/play-controls.d.ts
2521
+ /**
2522
+ * Options accepted by {@link startEditorPlayControls}.
2523
+ *
2524
+ * @beta
2525
+ */
2526
+ interface EditorPlayControlsOptions {
2527
+ /** The origin the editor is served from; a port posted from any other origin is ignored. */
2528
+ readonly editorOrigin: string;
2529
+ /** The project's `@ignifx/core` version, reported in `ready` while core's `VERSION` is unstamped. */
2530
+ readonly engineVersion?: string;
2531
+ /** Milliseconds between heartbeats once the editor has said `hello`. Defaults to `1000`. */
2532
+ readonly heartbeatIntervalMs?: number;
2533
+ /** Where the editor's connect message arrives. Defaults to the page's `window`. */
2534
+ readonly messageTarget?: EditorMessageTarget;
2535
+ }
2536
+ /**
2537
+ * The play view's side of an editor channel. The game keeps its app; the controls only drive it.
2538
+ *
2539
+ * @beta
2540
+ */
2541
+ interface EditorPlayControls {
2542
+ /** Whether the editor has handed the page a port that is still open. */
2543
+ readonly isConnected: boolean;
2544
+ /** Stops the heartbeat and closes the port. The app is left as it is. Idempotent. */
2545
+ dispose(): void;
2546
+ /** Same as {@link EditorPlayControls.dispose}, for `using`. */
2547
+ [Symbol.dispose](): void;
2548
+ }
2549
+ /**
2550
+ * A play view whose page listens for the editor's port before the game's app exists, so the
2551
+ * editor's first connect message is kept rather than lost.
2552
+ *
2553
+ * @beta
2554
+ */
2555
+ interface EditorPlayConnector {
2556
+ /** Whether a port has arrived and waits for {@link EditorPlayConnector.attach}. */
2557
+ readonly hasPendingPort: boolean;
2558
+ /**
2559
+ * Starts the play controls for the game's app on the port that has arrived, if any, and from
2560
+ * then on on every new one. Only the first call takes the waiting port; a later call, or one after
2561
+ * `dispose`, opens controls that wait for the editor's next port.
2562
+ *
2563
+ * @param app - The game's app. The controls never dispose it.
2564
+ * @returns The controls.
2565
+ */
2566
+ attach(app: App): EditorPlayControls;
2567
+ /** Stops listening, closes a waiting port, and disposes the controls it attached. Idempotent. */
2568
+ dispose(): void;
2569
+ /** Same as {@link EditorPlayConnector.dispose}, for `using`. */
2570
+ [Symbol.dispose](): void;
2571
+ }
2572
+ /**
2573
+ * Lets the editor drive a running game: answers the handshake with `hostKind: "play"`, then `play`,
2574
+ * `pause`, `step`, `stop`, `playState` and `playStats`, and sends `playStateChanged` when the game's phase
2575
+ * changes, and `log`, `hostError` and `hotReloaded` for the game's log lines, `app.onError` reports
2576
+ * and hot reloads (the newest 256 from before the handshake right after it).
2577
+ *
2578
+ * @remarks
2579
+ * A game does not call this directly. It calls `attachEditorPlayControls(app)` from
2580
+ * `virtual:ignifx/editor`, which the editor host's Vite plugin serves: in `vite dev` that module
2581
+ * calls this function, and in a production build it is an empty function, so no editor code ships.
2582
+ *
2583
+ * @param app - The game's app. The controls never dispose it.
2584
+ * @param options - The editor's origin and the reporting options.
2585
+ * @returns The controls; dispose them to stop listening.
2586
+ * @throws IgnifxError `IGX-1801` for a malformed `editorOrigin`, `IGX-1802` with no window and no
2587
+ * `messageTarget`, `IGX-1803` for a bad `heartbeatIntervalMs`.
2588
+ *
2589
+ * @example
2590
+ * ```ts
2591
+ * const controls = startEditorPlayControls(app, { editorOrigin: "ignifx://app" });
2592
+ * controls.dispose();
2593
+ * ```
2594
+ *
2595
+ * @beta
2596
+ */
2597
+ export declare function startEditorPlayControls(app: App, options: EditorPlayControlsOptions): EditorPlayControls;
2598
+ /**
2599
+ * Listens for the editor's connect message before the game's app exists, and keeps the newest port
2600
+ * until {@link EditorPlayConnector.attach} hands it the app.
2601
+ *
2602
+ * @remarks
2603
+ * The editor posts its port on the play view's `load` event, which can fire while the game's
2604
+ * `main.ts` still awaits `createApp`. `virtual:ignifx/editor` calls this when the module is
2605
+ * evaluated, which is before `main.ts` runs, and `attachEditorPlayControls(app)` calls `attach`, so
2606
+ * the handshake runs on the port the editor sent first. A port is accepted only from exactly
2607
+ * `editorOrigin`; a newer one replaces and closes the one waiting. Nothing is read from the port
2608
+ * before `attach`: the editor's `hello` waits in it.
2609
+ *
2610
+ * @param options - The editor's origin and the reporting options.
2611
+ * @returns The connector; dispose it to stop listening.
2612
+ * @throws IgnifxError `IGX-1801` for a malformed `editorOrigin`, `IGX-1802` with no window and no
2613
+ * `messageTarget`, `IGX-1803` for a bad `heartbeatIntervalMs`.
2614
+ *
2615
+ * @example
2616
+ * ```ts
2617
+ * const connector = listenForEditorPlayControls({ editorOrigin: "ignifx://app" });
2618
+ * const app = await createApp({ headless: true });
2619
+ * const controls = connector.attach(app);
2620
+ * connector.dispose();
2621
+ * ```
2622
+ *
2623
+ * @beta
2624
+ */
2625
+ export declare function listenForEditorPlayControls(options: EditorPlayControlsOptions): EditorPlayConnector;
2626
+ //#endregion
2627
+ export { type AddComponentOp, type AppErrorData, type ApplyOpFailure, type ApplyOpsParams, type ApplyOpsResponse, type ApplyOpsResult, type AssetReloadedParams, type CreateEntityOp, type DescribeSettingsResponse, type DestroyEntityOp, type EditorAssetChange, type EditorConnectMessage, type EditorHost, EditorHostErrorCode, type EditorHostOptions, type EditorMessageTarget, type EditorPlayConnector, type EditorPlayControls, type EditorPlayControlsOptions, type EntityField, type EntityFieldValues, type EntitySelection, type FrameParams, type GetSchemasResponse, type GizmoDragMode, type GizmoSnap, type HeartbeatNotification, type HelloParams, type HelloRequest, type HostErrorParams, type HotReloadError, type HotReloadReport, type HotReloadedParams, type IncompatibleProtocolData, type InstantiateOp, type InvalidSceneFileData, type JsonArray, type JsonObject, type JsonPath, type JsonValue, type LogLevel, type LogParams, type LoggedError, type NullResponse, type OpenSceneParams, type OpenSceneResponse, type OpenSceneResult, type PickParams, type PickRay, type PickResponse, type PickResult, type PingRequest, type PlayRequest, type PlayResponse, type PlayState, type PlayStateChangedNotification, type PlayStateReport, type PlayStateResponse, type PlayStats, type PlayStatsResponse, type PongResponse, type ProtocolVersion, type ReadBackParams, type ReadBackResponse, type ReadBackResult, type ReadyResponse, type ReadyResult, type RemoveComponentOp, type RemoveOverrideOp, type ReorderOp, type ReparentOp, type RpcError, type RpcErrorResponse, type RpcId, type RpcMessage, type RpcNotification, type RpcNotificationWithParams, type RpcRequest, type RpcRequestWithParams, type RpcResponse, type RpcSuccessResponse, type SceneFile, type SceneFileAssetRef, type SceneFileComponent, type SceneFileEntity, type SceneFileInstance, type SceneFileIssue, type SceneFileOverride, type SceneFileTransform, type SceneHostNotification, type SceneIssue, type SceneOp, type SceneOpenedParams, type SceneRequest, type SchemaDescription, type SchemaFieldDescription, type SchemaSet, type ScreenshotParams, type ScreenshotResponse, type ScreenshotResult, type SelectResponse, type SetEntityFieldOp, type SetGizmoParams, type SetOverrideOp, type SetPropOp, type SetSceneSettingOp, type SetTransformOp, type SetViewModeParams, type SettingsSet, type StepParams, type TransformDraggedParams, type TransformDraggingParams, type Vec3, isEditorOrigin };
2628
+ //# sourceMappingURL=index.d.ts.map