@ignifx/editor-host 0.12.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { n as isEditorOrigin, t as EditorHostErrorCode } from "./error-codes.js";
2
- import { Camera, Component, CoreErrorCode, IgnifxError, Phase, SCENE_ASSET_TYPE, SCENE_FILE_FORMAT, SCENE_FORMAT_VERSION, Script, Transform, VERSION, addComponentFromRecord, canonicalizeNumber, clamp, createApp, createFrameSample, createRay, createSceneAsset, decodeProps, decodeValue, degToRad, describeRegisteredSchemas, describeSchemas, describeSettings, encodeProps, encodeValue, instantiateScene, isIgnifxError, loadSceneDependencies, parseOverridePath, serializeScene, settingsJsonSchema, toJsonSchema, transformSchema, validateSceneFile } from "@ignifx/core";
2
+ import { Camera, Component, CoreErrorCode, IgnifxError, Phase, SCENE_ASSET_TYPE, SCENE_FILE_FORMAT, SCENE_FORMAT_VERSION, Script, Transform, VERSION, addComponentFromRecord, canonicalizeNumber, clamp, createApp, createFrameSample, createRay, createSceneAsset, decodeProps, decodeValue, degToRad, describeRegisteredSchemas, describeSchemas, describeSettings, encodeProps, encodeValue, instantiateScene, isIgnifxError, loadSceneDependencies, parseOverridePath, serializeEntity, serializeScene, settingsJsonSchema, toJsonSchema, transformSchema, validateSceneFile } from "@ignifx/core";
3
3
  import { addToScene, attachPositionGizmoToNode, attachRotationGizmoToNode, attachScaleGizmoToNode, createLines, createPositionGizmo, createRotationGizmo, createScaleGizmo, isGizmoDragging, isGizmoInteracting, isGizmoPickPending, onBeforeRender, setPositionGizmoLocalCoordinates, setRotationGizmoLocalCoordinates, setScaleGizmoLocalCoordinates } from "@babylonjs/lite";
4
4
  //#region src/protocol/rpc.ts
5
5
  /**
@@ -40,7 +40,20 @@ const RpcErrorCode = {
40
40
  */
41
41
  notReady: -32001,
42
42
  /** A scene method that needs an open scene was called while none is open (`SceneMethod`). */
43
- noScene: -32002
43
+ noScene: -32002,
44
+ /**
45
+ * A play method that needs a running game was called while it does not run. `PlayMethod.screenshot`
46
+ * needs the frame loop: it fails before the game starts it, after `stop`, and after `step`.
47
+ * `PlayMethod.queryRuntime` and `PlayMethod.sendInput` need a game that plays or is paused (a
48
+ * stepped game is paused): they fail before the game starts and after `stop`. Additive in 0.3:
49
+ * only a host that answers one of those methods in the play view sends it.
50
+ */
51
+ notPlaying: -32003,
52
+ /**
53
+ * A play method named an entity uid the game's world does not hold (`PlayMethod.queryRuntime`).
54
+ * Additive in 0.3: only a host that answers `queryRuntime` sends it.
55
+ */
56
+ unknownEntity: -32004
44
57
  };
45
58
  /**
46
59
  * Narrows to a plain object without an `as` assertion. Shared by this package's guards; not
@@ -171,9 +184,11 @@ const HostKind = {
171
184
  * The optional features a host lists in its `ready` result.
172
185
  *
173
186
  * @remarks
174
- * The play controls send `["heartbeat", "playControls"]`. The scene host sends `"heartbeat"` and
175
- * whichever of `"gizmos"`, `"screenshot"`, `"viewMode2d"` and `"pick2d"` it supports; every
176
- * `SceneMethod` not tied to one of them is required of a 0.3 scene host.
187
+ * The play controls send `"heartbeat"`, `"playControls"`, `"logRelay"` and `"queryRuntime"`, plus
188
+ * `"screenshot"` when the game has a canvas and `"sendInput"` when it has `app.input`. The scene
189
+ * host sends `"heartbeat"` and whichever of `"gizmos"`, `"screenshot"`, `"viewMode2d"` and
190
+ * `"pick2d"` it supports; every `SceneMethod` not tied to one of them is required of a 0.3 scene
191
+ * host.
177
192
  *
178
193
  * @public
179
194
  */
@@ -187,7 +202,11 @@ const HostCapability = {
187
202
  * `transformDragging` and `transformDragged`.
188
203
  */
189
204
  gizmos: "gizmos",
190
- /** The scene host answers `screenshot`. */
205
+ /**
206
+ * The host answers `screenshot`: the scene host captures its view, the play controls the game's
207
+ * canvas. The play controls list it from engine ask E47 (additive in 0.3); without it, the play
208
+ * view answers `screenshot` with `RpcErrorCode.methodNotFound`.
209
+ */
191
210
  screenshot: "screenshot",
192
211
  /** The scene host accepts `setViewMode` with `"2d"`: a 2D editor camera and planar gizmos. */
193
212
  viewMode2d: "viewMode2d",
@@ -210,7 +229,20 @@ const HostCapability = {
210
229
  * overrides). A value the document sets is kept. An editor need not reopen the scene for changed
211
230
  * defaults. Additive in 0.3.
212
231
  */
213
- hotReloadDefaults: "hotReloadDefaults"
232
+ hotReloadDefaults: "hotReloadDefaults",
233
+ /**
234
+ * The play controls answer `queryRuntime`: an entity's live state in the scene format. From engine
235
+ * ask E48 (additive in 0.3); without it, the play view answers `queryRuntime` with
236
+ * `RpcErrorCode.methodNotFound`.
237
+ */
238
+ queryRuntime: "queryRuntime",
239
+ /**
240
+ * The play controls answer `sendInput`: synthetic key and pointer events queued into the game's
241
+ * own input system (`app.input` from `@ignifx/input`), never into the editor's window. Listed only
242
+ * when the game has `app.input`. From engine ask E49 (additive in 0.3); without it, the play view
243
+ * answers `sendInput` with `RpcErrorCode.methodNotFound`.
244
+ */
245
+ sendInput: "sendInput"
214
246
  };
215
247
  /**
216
248
  * The longest string, in UTF-16 code units, the editor accepts from a host in `ready` (the engine
@@ -331,140 +363,6 @@ heartbeat: "heartbeat" };
331
363
  */
332
364
  const DEFAULT_HEARTBEAT_INTERVAL_MS = 1e3;
333
365
  //#endregion
334
- //#region src/protocol/play.ts
335
- /**
336
- * The play view's controls: the methods the editor calls on the project's own game page after the
337
- * handshake, through `attachEditorPlayControls(app)` from `virtual:ignifx/editor`. Plan §3.6.
338
- */
339
- /**
340
- * The methods the play view answers after `ready`. `play`, `pause`, `step` and `stop` answer with a
341
- * {@link PlayState}; `playState` answers with a {@link PlayStateReport}; `playStats` answers with
342
- * {@link PlayStats}.
343
- *
344
- * @remarks
345
- * A host that answers them lists `HostCapability.playControls` in `ready`. Sent before `ready`, they
346
- * fail with `RpcErrorCode.notReady`; sent to a host without them, with `RpcErrorCode.methodNotFound`.
347
- * `playState` and `playStats` are additive 0.3 methods: a host from before one answers it with
348
- * `RpcErrorCode.methodNotFound`.
349
- *
350
- * @public
351
- */
352
- const PlayMethod = {
353
- /** Clears `app.time.paused` and starts the frame loop if it is stopped. */
354
- play: "play",
355
- /** Sets `app.time.paused`; scripts marked `updateWhenPaused` keep running. */
356
- pause: "pause",
357
- /** Stops the frame loop, then advances exactly one frame with `app.step()` and leaves the game paused. */
358
- step: "step",
359
- /** Stops the frame loop with `app.stop()`. The editor reloads the view to reset the game. */
360
- stop: "stop",
361
- /** Reads the game's state without changing it. Takes no parameters. */
362
- playState: "playState",
363
- /**
364
- * Reads the game's frame rate, frame time, entity count and frame count without changing
365
- * anything. Takes no parameters. The editor polls it; no notification carries it.
366
- */
367
- playStats: "playStats"
368
- };
369
- /**
370
- * The notifications the play view sends after `ready`.
371
- *
372
- * @remarks
373
- * Additive in 0.3: a host from before them sends none, and answers `playState` with
374
- * `RpcErrorCode.methodNotFound`. `log`, `hostError` and `hotReloaded` came later still: only a host
375
- * that lists `HostCapability.logRelay` in `ready` sends them.
376
- *
377
- * @public
378
- */
379
- const PlayNotification = {
380
- /**
381
- * After the game's {@link PlayStateReport.state} changed. A change a `PlayMethod` makes is sent
382
- * right after that method's answer; one the game makes itself, such as setting
383
- * `app.time.paused`, within one heartbeat interval.
384
- */
385
- playStateChanged: "playStateChanged",
386
- /**
387
- * One line from the game's logger, with the same `LogParams` as the scene view's `log`. Sent by a
388
- * host that lists `HostCapability.logRelay`; lines logged before the handshake are kept (the
389
- * newest few hundred) and sent right after `ready`.
390
- */
391
- log: "log",
392
- /**
393
- * An error the game's app reported through `app.onError`: the same `HostErrorParams` as the scene
394
- * view's `hostError`, with `AppErrorData` as its `data`. Sent by a host that lists
395
- * `HostCapability.logRelay`, kept before the handshake as `log` is.
396
- */
397
- hostError: "hostError",
398
- /**
399
- * After every `app.hotReload` operation in the game: the same `HotReloadedParams` as the scene
400
- * view's `hotReloaded`. Sent by a host that lists `HostCapability.logRelay`.
401
- */
402
- hotReloaded: "hotReloaded"
403
- };
404
- /**
405
- * Whether the game plays, is paused, or is stopped, as {@link PlayStateReport.state} reports it.
406
- *
407
- * @public
408
- */
409
- const PlayPhase = {
410
- /** The frame loop runs (`app.isRunning`) and game time is not paused. */
411
- playing: "playing",
412
- /**
413
- * Game time is paused (`app.time.paused`): after `pause`, or after `step`, which leaves the frame
414
- * loop stopped on the stepped frame.
415
- */
416
- paused: "paused",
417
- /** The frame loop does not run: before the game starts it, or after `stop`. */
418
- stopped: "stopped"
419
- };
420
- /**
421
- * Checks the `result` of a play method's response.
422
- *
423
- * @param value - The received `result`.
424
- * @returns True when `value` has boolean `isRunning` and `isPaused` and a non-negative integer
425
- * `frameCount`.
426
- *
427
- * @public
428
- */
429
- function isPlayState(value) {
430
- if (!isRecord(value)) return false;
431
- const frameCount = value["frameCount"];
432
- return typeof value["isRunning"] === "boolean" && typeof value["isPaused"] === "boolean" && typeof frameCount === "number" && Number.isSafeInteger(frameCount) && frameCount >= 0;
433
- }
434
- /**
435
- * Checks the `result` of `playState` and the `params` of `playStateChanged`.
436
- *
437
- * @param value - The received value.
438
- * @returns True when `value` has a `state` that is a `PlayPhase`, a non-negative integer
439
- * `frameCount`, and a non-negative finite `time`.
440
- *
441
- * @public
442
- */
443
- function isPlayStateReport(value) {
444
- if (!isRecord(value)) return false;
445
- const state = value["state"];
446
- const frameCount = value["frameCount"];
447
- const time = value["time"];
448
- return typeof state === "string" && Object.values(PlayPhase).includes(state) && typeof frameCount === "number" && Number.isSafeInteger(frameCount) && frameCount >= 0 && typeof time === "number" && Number.isFinite(time) && time >= 0;
449
- }
450
- /**
451
- * Checks the `result` of `playStats`.
452
- *
453
- * @param value - The received `result`.
454
- * @returns True when `value` has non-negative finite `fps` and `frameTimeMs` and non-negative
455
- * integer `entityCount` and `frameCount`.
456
- *
457
- * @public
458
- */
459
- function isPlayStats(value) {
460
- if (!isRecord(value)) return false;
461
- const fps = value["fps"];
462
- const frameTimeMs = value["frameTimeMs"];
463
- const entityCount = value["entityCount"];
464
- const frameCount = value["frameCount"];
465
- return typeof fps === "number" && Number.isFinite(fps) && fps >= 0 && typeof frameTimeMs === "number" && Number.isFinite(frameTimeMs) && frameTimeMs >= 0 && typeof entityCount === "number" && Number.isSafeInteger(entityCount) && entityCount >= 0 && typeof frameCount === "number" && Number.isSafeInteger(frameCount) && frameCount >= 0;
466
- }
467
- //#endregion
468
366
  //#region src/protocol/scene-file.ts
469
367
  /**
470
368
  * The engine's scene file format as it travels on the wire: the same object `@ignifx/core`'s
@@ -479,7 +377,7 @@ function isPlayStats(value) {
479
377
  * file with the engine's `validateSceneFile`.
480
378
  */
481
379
  /** How deep a JSON value may nest before {@link isJsonValue} refuses it, as a guard against cycles. */
482
- const MAX_JSON_DEPTH = 256;
380
+ const MAX_JSON_DEPTH$1 = 256;
483
381
  /**
484
382
  * Tells whether a value is JSON: `null`, a boolean, a string, a finite number, or an array or
485
383
  * plain object of JSON values, nested at most 256 levels deep.
@@ -500,7 +398,7 @@ function isJsonValue(value) {
500
398
  * @returns True for a JSON value no deeper than the limit.
501
399
  */
502
400
  function isJsonValueAt(value, depth) {
503
- if (depth > MAX_JSON_DEPTH) return false;
401
+ if (depth > MAX_JSON_DEPTH$1) return false;
504
402
  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
505
403
  if (typeof value === "number") return Number.isFinite(value);
506
404
  if (Array.isArray(value)) return value.every((item) => isJsonValueAt(item, depth + 1));
@@ -694,6 +592,296 @@ function isSceneFile(value) {
694
592
  return isRecord(value) && isString(value["format"]) && Number.isSafeInteger(value["formatVersion"]) && optionalField(value, "engineVersion", isString) && isString(value["name"]) && optionalField(value, "settings", isJsonObject) && isArrayOf(value["entities"], isSceneFileEntity);
695
593
  }
696
594
  //#endregion
595
+ //#region src/protocol/play.ts
596
+ /**
597
+ * The play view's controls: the methods the editor calls on the project's own game page after the
598
+ * handshake, through `attachEditorPlayControls(app)` from `virtual:ignifx/editor`. Plan §3.6.
599
+ */
600
+ /**
601
+ * The methods the play view answers after `ready`. `play`, `pause`, `step` and `stop` answer with a
602
+ * {@link PlayState}; `playState` answers with a {@link PlayStateReport}; `playStats` answers with
603
+ * {@link PlayStats}; `screenshot` answers with a `ScreenshotResult`; `queryRuntime` answers with a
604
+ * {@link QueryRuntimeResult}; `sendInput` answers with a {@link SendInputResult}.
605
+ *
606
+ * @remarks
607
+ * A host that answers them lists `HostCapability.playControls` in `ready`. Sent before `ready`, they
608
+ * fail with `RpcErrorCode.notReady`; sent to a host without them, with `RpcErrorCode.methodNotFound`.
609
+ * `playState`, `playStats`, `screenshot`, `queryRuntime` and `sendInput` are additive 0.3 methods:
610
+ * a host from before one answers it with `RpcErrorCode.methodNotFound`. `screenshot`, `queryRuntime`
611
+ * and `sendInput` also need the `HostCapability` of the same name in the play view's `ready`.
612
+ *
613
+ * @public
614
+ */
615
+ const PlayMethod = {
616
+ /** Clears `app.time.paused` and starts the frame loop if it is stopped. */
617
+ play: "play",
618
+ /** Sets `app.time.paused`; scripts marked `updateWhenPaused` keep running. */
619
+ pause: "pause",
620
+ /** Stops the frame loop, then advances exactly one frame with `app.step()` and leaves the game paused. */
621
+ step: "step",
622
+ /** Stops the frame loop with `app.stop()`. The editor reloads the view to reset the game. */
623
+ stop: "stop",
624
+ /** Reads the game's state without changing it. Takes no parameters. */
625
+ playState: "playState",
626
+ /**
627
+ * Reads the game's frame rate, frame time, entity count and frame count without changing
628
+ * anything. Takes no parameters. The editor polls it; no notification carries it.
629
+ */
630
+ playStats: "playStats",
631
+ /**
632
+ * Captures the game's canvas as an image, with the scene view's `screenshot` parameters, caps and
633
+ * answer (`ScreenshotParams`, `ScreenshotResult`). Changes nothing: a paused game is captured
634
+ * paused. Needs `HostCapability.screenshot`. Fails with `RpcErrorCode.notPlaying` while the frame
635
+ * loop does not run (before the game starts it, after `stop` or `step`), and with
636
+ * `RpcErrorCode.notReady` before the game's first frame.
637
+ */
638
+ screenshot: "screenshot",
639
+ /**
640
+ * Reads one entity of the running game as the scene format writes it ({@link QueryRuntimeParams},
641
+ * {@link QueryRuntimeResult}): its live transform, flags and component props, never anything a
642
+ * component does not serialize, and no expressions. Each value is capped and the whole answer kept
643
+ * within {@link QUERY_RUNTIME_MAX_JSON_LENGTH}. Changes nothing. Needs
644
+ * `HostCapability.queryRuntime`. Fails with `RpcErrorCode.notPlaying` while the game is stopped
645
+ * (before it starts, after `stop`; a stepped game is paused and answers), and with
646
+ * `RpcErrorCode.unknownEntity` when no entity of the game has the uid.
647
+ */
648
+ queryRuntime: "queryRuntime",
649
+ /**
650
+ * Queues synthetic key and pointer events into the game's own input system, as if the game's page
651
+ * had received them ({@link SendInputParams}, {@link SendInputResult}). Nothing reaches the
652
+ * editor's window or the operating system. Needs `HostCapability.sendInput`, which a game lists
653
+ * only when it has `app.input` (`@ignifx/input`). Fails with `RpcErrorCode.notPlaying` while the
654
+ * game is stopped; a paused or stepped game takes the events and resolves them on its next frame,
655
+ * which for a stepped game is the next `step`.
656
+ */
657
+ sendInput: "sendInput"
658
+ };
659
+ /**
660
+ * The most components a `queryRuntime` answer holds, and the most type ids its `components` filter
661
+ * may name. Components past it are counted in {@link QueryRuntimeResult.omittedComponents}.
662
+ *
663
+ * @public
664
+ */
665
+ const QUERY_RUNTIME_MAX_COMPONENTS = 64;
666
+ /**
667
+ * The longest a `queryRuntime` answer may be: its `result` as JSON text, in UTF-16 code units
668
+ * (`JSON.stringify(result).length`), 256 Ki. Components that would pass it are left out, in order,
669
+ * and counted in {@link QueryRuntimeResult.omittedComponents}.
670
+ *
671
+ * @public
672
+ */
673
+ const QUERY_RUNTIME_MAX_JSON_LENGTH = 262144;
674
+ /**
675
+ * In a `queryRuntime` answer, the most keys one object keeps and the longest a key may be; also the
676
+ * longest the entity's `name`, `layer`, each tag and each component `type` may be, and the most
677
+ * tags kept. Keys left out are counted in {@link QueryRuntimeResult.omittedEntries}.
678
+ *
679
+ * @public
680
+ */
681
+ const QUERY_RUNTIME_MAX_KEYS = 256;
682
+ /**
683
+ * In a `queryRuntime` answer, the longest a prop string may be, `… [clipped]` included: 64 Ki, a
684
+ * quarter of {@link QUERY_RUNTIME_MAX_JSON_LENGTH}, so one long string does not cost its component
685
+ * its place.
686
+ *
687
+ * @public
688
+ */
689
+ const QUERY_RUNTIME_MAX_STRING_LENGTH = 65536;
690
+ /**
691
+ * The most events one `sendInput` request may carry.
692
+ *
693
+ * @public
694
+ */
695
+ const SEND_INPUT_MAX_EVENTS = 64;
696
+ /**
697
+ * The notifications the play view sends after `ready`.
698
+ *
699
+ * @remarks
700
+ * Additive in 0.3: a host from before them sends none, and answers `playState` with
701
+ * `RpcErrorCode.methodNotFound`. `log`, `hostError` and `hotReloaded` came later still: only a host
702
+ * that lists `HostCapability.logRelay` in `ready` sends them.
703
+ *
704
+ * @public
705
+ */
706
+ const PlayNotification = {
707
+ /**
708
+ * After the game's {@link PlayStateReport.state} changed. A change a `PlayMethod` makes is sent
709
+ * right after that method's answer; one the game makes itself, such as setting
710
+ * `app.time.paused`, within one heartbeat interval.
711
+ */
712
+ playStateChanged: "playStateChanged",
713
+ /**
714
+ * One line from the game's logger, with the same `LogParams` as the scene view's `log`. Sent by a
715
+ * host that lists `HostCapability.logRelay`; lines logged before the handshake are kept (the
716
+ * newest few hundred) and sent right after `ready`.
717
+ */
718
+ log: "log",
719
+ /**
720
+ * An error the game's app reported through `app.onError`: the same `HostErrorParams` as the scene
721
+ * view's `hostError`, with `AppErrorData` as its `data`. Sent by a host that lists
722
+ * `HostCapability.logRelay`, kept before the handshake as `log` is.
723
+ */
724
+ hostError: "hostError",
725
+ /**
726
+ * After every `app.hotReload` operation in the game: the same `HotReloadedParams` as the scene
727
+ * view's `hotReloaded`. Sent by a host that lists `HostCapability.logRelay`.
728
+ */
729
+ hotReloaded: "hotReloaded"
730
+ };
731
+ /**
732
+ * Whether the game plays, is paused, or is stopped, as {@link PlayStateReport.state} reports it.
733
+ *
734
+ * @public
735
+ */
736
+ const PlayPhase = {
737
+ /** The frame loop runs (`app.isRunning`) and game time is not paused. */
738
+ playing: "playing",
739
+ /**
740
+ * Game time is paused (`app.time.paused`): after `pause`, or after `step`, which leaves the frame
741
+ * loop stopped on the stepped frame.
742
+ */
743
+ paused: "paused",
744
+ /** The frame loop does not run: before the game starts it, or after `stop`. */
745
+ stopped: "stopped"
746
+ };
747
+ /**
748
+ * Checks the `result` of a play method's response.
749
+ *
750
+ * @param value - The received `result`.
751
+ * @returns True when `value` has boolean `isRunning` and `isPaused` and a non-negative integer
752
+ * `frameCount`.
753
+ *
754
+ * @public
755
+ */
756
+ function isPlayState(value) {
757
+ if (!isRecord(value)) return false;
758
+ const frameCount = value["frameCount"];
759
+ return typeof value["isRunning"] === "boolean" && typeof value["isPaused"] === "boolean" && typeof frameCount === "number" && Number.isSafeInteger(frameCount) && frameCount >= 0;
760
+ }
761
+ /**
762
+ * Checks the `result` of `playState` and the `params` of `playStateChanged`.
763
+ *
764
+ * @param value - The received value.
765
+ * @returns True when `value` has a `state` that is a `PlayPhase`, a non-negative integer
766
+ * `frameCount`, and a non-negative finite `time`.
767
+ *
768
+ * @public
769
+ */
770
+ function isPlayStateReport(value) {
771
+ if (!isRecord(value)) return false;
772
+ const state = value["state"];
773
+ const frameCount = value["frameCount"];
774
+ const time = value["time"];
775
+ return typeof state === "string" && Object.values(PlayPhase).includes(state) && typeof frameCount === "number" && Number.isSafeInteger(frameCount) && frameCount >= 0 && typeof time === "number" && Number.isFinite(time) && time >= 0;
776
+ }
777
+ /**
778
+ * Checks the `result` of `playStats`.
779
+ *
780
+ * @param value - The received `result`.
781
+ * @returns True when `value` has non-negative finite `fps` and `frameTimeMs` and non-negative
782
+ * integer `entityCount` and `frameCount`.
783
+ *
784
+ * @public
785
+ */
786
+ function isPlayStats(value) {
787
+ if (!isRecord(value)) return false;
788
+ const fps = value["fps"];
789
+ const frameTimeMs = value["frameTimeMs"];
790
+ const entityCount = value["entityCount"];
791
+ const frameCount = value["frameCount"];
792
+ return typeof fps === "number" && Number.isFinite(fps) && fps >= 0 && typeof frameTimeMs === "number" && Number.isFinite(frameTimeMs) && frameTimeMs >= 0 && typeof entityCount === "number" && Number.isSafeInteger(entityCount) && entityCount >= 0 && typeof frameCount === "number" && Number.isSafeInteger(frameCount) && frameCount >= 0;
793
+ }
794
+ /**
795
+ * Checks the `params` of `queryRuntime`.
796
+ *
797
+ * @param value - The received `params`.
798
+ * @returns True for a non-empty `entity` uid and, when present, a `components` list of at most
799
+ * {@link QUERY_RUNTIME_MAX_COMPONENTS} non-empty strings.
800
+ *
801
+ * @public
802
+ */
803
+ function isQueryRuntimeParams(value) {
804
+ if (!isRecord(value) || !isUidString(value["entity"])) return false;
805
+ const components = value["components"];
806
+ return components === void 0 || Array.isArray(components) && components.length <= 64 && components.every((typeId) => typeof typeId === "string" && typeId.length > 0);
807
+ }
808
+ /**
809
+ * Checks the `result` of `queryRuntime`.
810
+ *
811
+ * @param value - The received `result`.
812
+ * @returns True for an entity record with at most {@link QUERY_RUNTIME_MAX_COMPONENTS} components,
813
+ * non-negative integer `omittedComponents`, `omittedEntries` and `frameCount`, and a non-negative
814
+ * finite `time`, no longer than {@link QUERY_RUNTIME_MAX_JSON_LENGTH} as JSON.
815
+ *
816
+ * @public
817
+ */
818
+ function isQueryRuntimeResult(value) {
819
+ if (!isRecord(value)) return false;
820
+ const entity = value["entity"];
821
+ const omitted = value["omittedComponents"];
822
+ const omittedEntries = value["omittedEntries"];
823
+ const frameCount = value["frameCount"];
824
+ const time = value["time"];
825
+ return isSceneFileEntity(entity) && (entity.components ?? []).length <= 64 && typeof omitted === "number" && Number.isSafeInteger(omitted) && omitted >= 0 && typeof omittedEntries === "number" && Number.isSafeInteger(omittedEntries) && omittedEntries >= 0 && typeof frameCount === "number" && Number.isSafeInteger(frameCount) && frameCount >= 0 && typeof time === "number" && Number.isFinite(time) && time >= 0 && JSON.stringify(value).length <= 262144;
826
+ }
827
+ /** A `<Keyboard>` control name as `sendInput` accepts it. */
828
+ const KEY_CONTROL_PATTERN = /^[A-Za-z0-9]{1,64}$/u;
829
+ /**
830
+ * Tells whether a value is a fraction from 0 to 1.
831
+ *
832
+ * @param value - The value to test.
833
+ * @returns True for a finite number from 0 to 1.
834
+ */
835
+ function isFraction(value) {
836
+ return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
837
+ }
838
+ /**
839
+ * Checks one event of a `sendInput` request.
840
+ *
841
+ * @param value - The value to test.
842
+ * @returns True for a key event with a well-formed `control`, or a pointer event with `x` and `y`
843
+ * from 0 to 1 and, when present, an integer `button` from 0 to 4.
844
+ *
845
+ * @public
846
+ */
847
+ function isSendInputEvent(value) {
848
+ if (!isRecord(value)) return false;
849
+ const type = value["type"];
850
+ if (type === "keydown" || type === "keyup") {
851
+ const control = value["control"];
852
+ return typeof control === "string" && KEY_CONTROL_PATTERN.test(control);
853
+ }
854
+ if (type !== "pointermove" && type !== "pointerdown" && type !== "pointerup") return false;
855
+ const button = value["button"];
856
+ return isFraction(value["x"]) && isFraction(value["y"]) && (button === void 0 || typeof button === "number" && Number.isInteger(button) && button >= 0 && button <= 4);
857
+ }
858
+ /**
859
+ * Checks the `params` of `sendInput`.
860
+ *
861
+ * @param value - The received `params`.
862
+ * @returns True for an `events` list of 1 to {@link SEND_INPUT_MAX_EVENTS} well-formed events.
863
+ *
864
+ * @public
865
+ */
866
+ function isSendInputParams(value) {
867
+ if (!isRecord(value)) return false;
868
+ const events = value["events"];
869
+ return Array.isArray(events) && events.length > 0 && events.length <= 64 && events.every((event) => isSendInputEvent(event));
870
+ }
871
+ /**
872
+ * Checks the `result` of `sendInput`.
873
+ *
874
+ * @param value - The received `result`.
875
+ * @returns True for an integer `queued` from 0 to {@link SEND_INPUT_MAX_EVENTS}.
876
+ *
877
+ * @public
878
+ */
879
+ function isSendInputResult(value) {
880
+ if (!isRecord(value)) return false;
881
+ const queued = value["queued"];
882
+ return typeof queued === "number" && Number.isSafeInteger(queued) && queued >= 0 && queued <= 64;
883
+ }
884
+ //#endregion
697
885
  //#region src/protocol/scene-ops.ts
698
886
  /**
699
887
  * The scene op vocabulary on the wire: the thirteen ops of plan §3.4, exactly as
@@ -5707,8 +5895,11 @@ const COMPONENTS_FORMAT = "components";
5707
5895
  * @remarks
5708
5896
  * Each field carries its inspector options (`step`, `hidden`, `readonly`, `group`, an asset's
5709
5897
  * `assetType`, a `componentRef`'s `componentType`), and each component its `allowMultiple` and the
5710
- * `package` that registered it, all optional members of protocol 0.3. A component core describes
5711
- * keeps core's title and summary; any other is titled from its type id. The host's own classes are left out: they are not the
5898
+ * `package` that registered it, all optional members of protocol 0.3. Each component's title and
5899
+ * summary are its class's own `static title` and `static description`, which every package
5900
+ * declares on its components, so an extension's curated names arrive without the host importing
5901
+ * the extension; core's `describeSchemas()` still overrides core's entries, and a component with
5902
+ * neither is titled from its type id. The host's own classes are left out: they are not the
5712
5903
  * document's. `ignifx/Transform` is described with core's `transformSchema()` and carries
5713
5904
  * `builtIn`: its fields are each entity's `transform` block, edited with `setTransform`, and it is
5714
5905
  * never added or removed. Each component also carries `extends` (engine ask E44): the registered
@@ -5763,6 +5954,13 @@ function registeredAncestors(registry, type) {
5763
5954
  }
5764
5955
  //#endregion
5765
5956
  //#region src/scene/screenshot.ts
5957
+ /**
5958
+ * `screenshot`, shared by the scene view and the play view: the parameter check, and a captured
5959
+ * frame scaled to the requested size and written as a PNG or JPEG data URL. Encoding needs a
5960
+ * browser's `OffscreenCanvas`, as the capture needs a GPU.
5961
+ */
5962
+ /** The JPEG quality when the request gives none. */
5963
+ const DEFAULT_JPEG_QUALITY = .9;
5766
5964
  /** Bytes encoded per `String.fromCharCode` call, to stay under engines' argument limits. */
5767
5965
  const BASE64_CHUNK = 32768;
5768
5966
  /**
@@ -5802,6 +6000,39 @@ async function encodeCapture(capture, size, format, quality) {
5802
6000
  });
5803
6001
  return `data:${type};base64,${toBase64(new Uint8Array(await blob.arrayBuffer()))}`;
5804
6002
  }
6003
+ /**
6004
+ * Checks `screenshot`'s parameters.
6005
+ *
6006
+ * @param params - The received `params`.
6007
+ * @returns The parameters.
6008
+ * @throws InvalidParamsError for a side outside 1 to {@link SCREENSHOT_MAX_SIZE}, an unknown format, or
6009
+ * a quality outside 0 to 1.
6010
+ */
6011
+ function checkScreenshotParams(params) {
6012
+ if (typeof params === "object" && params !== null) for (const side of ["width", "height"]) {
6013
+ const value = Reflect.get(params, side);
6014
+ if (value !== void 0 && (!Number.isSafeInteger(value) || Number(value) < 1 || Number(value) > 2048)) throw new InvalidParamsError(`screenshot takes a width and height from 1 to ${String(SCREENSHOT_MAX_SIZE)} pixels.`);
6015
+ }
6016
+ if (!isScreenshotParams(params)) throw new InvalidParamsError("screenshot takes { width?, height?, format: \"png\" | \"jpeg\", quality? }.");
6017
+ return params;
6018
+ }
6019
+ /**
6020
+ * Captures the app's next presented frame and encodes it as `screenshot` answers.
6021
+ *
6022
+ * @param app - The app whose canvas is captured.
6023
+ * @param params - Checked parameters.
6024
+ * @returns The data URL and its size.
6025
+ * @throws IgnifxError `IGX-0707` when the app's render loop does not run.
6026
+ */
6027
+ async function takeScreenshot(app, params) {
6028
+ const capture = await app.renderer.captureScreenshot();
6029
+ const size = screenshotSize(params, capture);
6030
+ return {
6031
+ dataUrl: await encodeCapture(capture, size, params.format, params.quality ?? DEFAULT_JPEG_QUALITY),
6032
+ width: size.width,
6033
+ height: size.height
6034
+ };
6035
+ }
5805
6036
  //#endregion
5806
6037
  //#region src/scene/settings.ts
5807
6038
  /**
@@ -6319,20 +6550,10 @@ var SceneHost = class {
6319
6550
  async #screenshot(params) {
6320
6551
  const app = this.#requireApp();
6321
6552
  this.#requireMirror(SceneMethod.screenshot);
6322
- if (typeof params === "object" && params !== null) for (const side of ["width", "height"]) {
6323
- const value = Reflect.get(params, side);
6324
- if (value !== void 0 && (!Number.isSafeInteger(value) || Number(value) < 1 || Number(value) > 2048)) throw new InvalidParamsError(`screenshot takes a width and height from 1 to ${String(SCREENSHOT_MAX_SIZE)} pixels.`);
6325
- }
6326
- if (!isScreenshotParams(params)) throw new InvalidParamsError("screenshot takes { width?, height?, format: \"png\" | \"jpeg\", quality? }.");
6553
+ const checked = checkScreenshotParams(params);
6327
6554
  this.#view?.setVisible(false);
6328
6555
  try {
6329
- const capture = await app.renderer.captureScreenshot();
6330
- const size = screenshotSize(params, capture);
6331
- return {
6332
- dataUrl: await encodeCapture(capture, size, params.format, params.quality ?? .9),
6333
- width: size.width,
6334
- height: size.height
6335
- };
6556
+ return await takeScreenshot(app, checked);
6336
6557
  } finally {
6337
6558
  this.#view?.setVisible(true);
6338
6559
  }
@@ -6908,6 +7129,348 @@ function appOptions(options) {
6908
7129
  };
6909
7130
  }
6910
7131
  //#endregion
7132
+ //#region src/play-input.ts
7133
+ /**
7134
+ * The play view's `sendInput` (engine ask E49): synthetic key and pointer events queued into the
7135
+ * game's own `app.input`, the way headless tests drive the engine. The host does not depend on
7136
+ * `@ignifx/input`: it finds `app.input` by name and calls `simulateEvent` by shape, as it reaches
7137
+ * `app.twoD` (`./scene/view-2d.ts`). Nothing here dispatches a DOM event or touches the editor.
7138
+ */
7139
+ /**
7140
+ * The game's input service, when the project registers `@ignifx/input`.
7141
+ *
7142
+ * @param app - The game's app.
7143
+ * @returns `app.input`, or `null` when it has no `simulateEvent`.
7144
+ */
7145
+ function inputServiceOf(app) {
7146
+ const service = Reflect.get(app, "input");
7147
+ if (typeof service !== "object" || service === null) return null;
7148
+ const simulateEvent = Reflect.get(service, "simulateEvent");
7149
+ if (typeof simulateEvent !== "function") return null;
7150
+ const resolveControl = Reflect.get(service, "resolveControl");
7151
+ return {
7152
+ simulateEvent: (event) => {
7153
+ Reflect.apply(simulateEvent, service, [event]);
7154
+ },
7155
+ hasControl: (path) => {
7156
+ if (typeof resolveControl !== "function") return true;
7157
+ try {
7158
+ Reflect.apply(resolveControl, service, [path]);
7159
+ return true;
7160
+ } catch {
7161
+ return false;
7162
+ }
7163
+ }
7164
+ };
7165
+ }
7166
+ /**
7167
+ * Splits a `sendInput` event into a key event or a pointer one.
7168
+ *
7169
+ * @param event - The event.
7170
+ * @returns True for `keydown` and `keyup`.
7171
+ */
7172
+ function isKeyEvent(event) {
7173
+ return event.type === "keydown" || event.type === "keyup";
7174
+ }
7175
+ /**
7176
+ * Measures the game's canvas.
7177
+ *
7178
+ * @param app - The game's app.
7179
+ * @returns Its size and pixel ratio.
7180
+ */
7181
+ function canvasMetrics(app) {
7182
+ const surface = app.renderer.surface;
7183
+ const width = surface !== null && surface.width > 0 ? surface.width : 1;
7184
+ const height = surface !== null && surface.height > 0 ? surface.height : 1;
7185
+ const clientWidth = surface === null ? void 0 : Reflect.get(surface, "clientWidth");
7186
+ return {
7187
+ width,
7188
+ height,
7189
+ cssPerPixel: typeof clientWidth === "number" && clientWidth > 0 ? clientWidth / width : 1
7190
+ };
7191
+ }
7192
+ /**
7193
+ * Queues `sendInput`'s events into one game's input service. Keeps the last pointer position it
7194
+ * sent, so a move reports the motion since it, as a real pointer does.
7195
+ */
7196
+ var PlayInput = class {
7197
+ #app;
7198
+ #input;
7199
+ #last = null;
7200
+ /**
7201
+ * Creates the queue for one game.
7202
+ *
7203
+ * @param app - The game's app.
7204
+ * @param input - Its input service.
7205
+ */
7206
+ constructor(app, input) {
7207
+ this.#app = app;
7208
+ this.#input = input;
7209
+ }
7210
+ /**
7211
+ * `sendInput`: checks every event, then queues them all in order. The game resolves them on its
7212
+ * next frame, as it does events from the page.
7213
+ *
7214
+ * @param params - The received `params`.
7215
+ * @returns How many events were queued.
7216
+ * @throws InvalidParamsError for malformed parameters or a key the game's keyboard does not have;
7217
+ * nothing is queued then. If `simulateEvent` itself throws partway, the events before it stay
7218
+ * queued: the input service has no way to take them back.
7219
+ */
7220
+ send(params) {
7221
+ if (!isSendInputParams(params)) throw new InvalidParamsError(`sendInput needs 1 to ${String(64)} events: { type: "keydown" | "keyup", control } or { type: "pointermove" | "pointerdown" | "pointerup", x, y (0 to 1), button? (0 to 4) }.`);
7222
+ for (const event of params.events) if (isKeyEvent(event) && !this.#input.hasControl(`<Keyboard>/${event.control}`)) throw new InvalidParamsError(`sendInput: the game's keyboard has no key "${event.control}". Use the <Keyboard> control name, such as w, space or arrowUp.`);
7223
+ const metrics = canvasMetrics(this.#app);
7224
+ for (const event of params.events) this.#input.simulateEvent(this.#simulated(event, metrics));
7225
+ return { queued: params.events.length };
7226
+ }
7227
+ /**
7228
+ * Builds the raw event for one request event.
7229
+ *
7230
+ * @param event - The request's event.
7231
+ * @param metrics - The canvas's size and pixel ratio.
7232
+ * @returns The event `simulateEvent` takes.
7233
+ */
7234
+ #simulated(event, metrics) {
7235
+ if (isKeyEvent(event)) return {
7236
+ type: event.type,
7237
+ code: event.control
7238
+ };
7239
+ const x = event.x * metrics.width;
7240
+ const y = event.y * metrics.height;
7241
+ const last = this.#last;
7242
+ this.#last = {
7243
+ x,
7244
+ y
7245
+ };
7246
+ const moves = event.type !== "pointerdown" && last !== null;
7247
+ return {
7248
+ type: event.type,
7249
+ x,
7250
+ y,
7251
+ deltaX: moves ? (x - last.x) * metrics.cssPerPixel : 0,
7252
+ deltaY: moves ? (y - last.y) * metrics.cssPerPixel : 0,
7253
+ button: event.button ?? 0
7254
+ };
7255
+ }
7256
+ };
7257
+ //#endregion
7258
+ //#region src/play-query.ts
7259
+ /**
7260
+ * The play view's `queryRuntime` (engine ask E48): one entity of the running game, as the scene
7261
+ * format writes it, read through core's `serializeEntity`, each value capped and the whole answer
7262
+ * kept within `QUERY_RUNTIME_MAX_JSON_LENGTH`.
7263
+ */
7264
+ /** How deep a capped JSON value may nest; deeper values become `null`, as `isJsonValue` allows 256. */
7265
+ const MAX_JSON_DEPTH = 256;
7266
+ /**
7267
+ * What `"components":[],` and the final counts can add to an answer's JSON beyond the skeleton the
7268
+ * budget measures first: the counts there are written with no more digits than they end with,
7269
+ * except `omittedEntries`, which may grow to a safe integer's 16.
7270
+ */
7271
+ const COMPONENTS_OVERHEAD = 64;
7272
+ /** Thrown out of a copy once it is sure to pass its budget. */
7273
+ var OverBudget = class extends Error {};
7274
+ /**
7275
+ * Counts, while a component is copied, a lower bound of its JSON length, so a copy that cannot fit
7276
+ * stops early instead of building the whole oversized value.
7277
+ */
7278
+ var Meter = class {
7279
+ /** How many object keys and list items the caps left out of the copy. */
7280
+ omitted = 0;
7281
+ #used = 0;
7282
+ #limit;
7283
+ /**
7284
+ * Creates the meter.
7285
+ *
7286
+ * @param limit - The JSON length the copy may take.
7287
+ */
7288
+ constructor(limit) {
7289
+ this.#limit = limit;
7290
+ }
7291
+ /**
7292
+ * Counts part of the copy.
7293
+ *
7294
+ * @param length - At most as many UTF-16 code units as that part takes as JSON.
7295
+ * @throws OverBudget once the count passes the limit.
7296
+ */
7297
+ charge(length) {
7298
+ this.#used += length;
7299
+ if (this.#used > this.#limit) throw new OverBudget();
7300
+ }
7301
+ };
7302
+ /**
7303
+ * Clips a string to a length, never splitting a surrogate pair.
7304
+ *
7305
+ * @param text - The string.
7306
+ * @param max - The longest it may be.
7307
+ * @returns It, or its start.
7308
+ */
7309
+ function clipTo(text, max) {
7310
+ if (text.length <= max) return text;
7311
+ const last = text.charCodeAt(max - 1);
7312
+ return text.slice(0, last >= 55296 && last <= 56319 ? max - 1 : max);
7313
+ }
7314
+ /**
7315
+ * Copies a value within the caps of `QueryRuntimeResult.entity`, counting it on the meter.
7316
+ *
7317
+ * @param value - The value, which a custom codec may have made something other than JSON.
7318
+ * @param depth - How deep it sits.
7319
+ * @param meter - The component's budget.
7320
+ * @returns The capped copy; `null` for anything that is not JSON or sits too deep.
7321
+ * @throws OverBudget when the copy cannot fit.
7322
+ */
7323
+ function capJson(value, depth, meter) {
7324
+ if (typeof value === "string") {
7325
+ const clipped = clipWithMarker(value, QUERY_RUNTIME_MAX_STRING_LENGTH);
7326
+ meter.charge(clipped.length + 2);
7327
+ return clipped;
7328
+ }
7329
+ meter.charge(1);
7330
+ if (typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) return value;
7331
+ if (typeof value !== "object" || value === null || depth >= MAX_JSON_DEPTH) return null;
7332
+ if (Array.isArray(value)) {
7333
+ meter.omitted += Math.max(0, value.length - HOST_LIST_MAX_LENGTH);
7334
+ return value.slice(0, HOST_LIST_MAX_LENGTH).map((item) => capJson(item, depth + 1, meter));
7335
+ }
7336
+ return capJsonObject(value, depth, meter);
7337
+ }
7338
+ /**
7339
+ * {@link capJson} for an object: its first `QUERY_RUNTIME_MAX_KEYS` keys, each clipped as long.
7340
+ * A key that clips to one already kept is left out, so the first keeps its value. Every key left
7341
+ * out is counted on the meter.
7342
+ *
7343
+ * @param value - The object.
7344
+ * @param depth - How deep it sits.
7345
+ * @param meter - The component's budget.
7346
+ * @returns The capped copy, keys in the same order.
7347
+ * @throws OverBudget when the copy cannot fit.
7348
+ */
7349
+ function capJsonObject(value, depth, meter) {
7350
+ const out = {};
7351
+ const entries = Object.entries(value);
7352
+ let kept = 0;
7353
+ for (const [index, [key, item]] of entries.entries()) {
7354
+ if (kept === 256) {
7355
+ meter.omitted += entries.length - index;
7356
+ break;
7357
+ }
7358
+ const clipped = clipTo(key, 256);
7359
+ if (Object.hasOwn(out, clipped)) {
7360
+ meter.omitted += 1;
7361
+ continue;
7362
+ }
7363
+ meter.charge(clipped.length + 3);
7364
+ Object.defineProperty(out, clipped, {
7365
+ value: capJson(item, depth + 1, meter),
7366
+ enumerable: true,
7367
+ writable: true,
7368
+ configurable: true
7369
+ });
7370
+ kept += 1;
7371
+ }
7372
+ return out;
7373
+ }
7374
+ /**
7375
+ * Clips a string as the reports do, ending it with {@link CLIPPED_MARKER}.
7376
+ *
7377
+ * @param text - The string.
7378
+ * @param max - The longest it may be, marker included.
7379
+ * @returns It, or its start and the marker.
7380
+ */
7381
+ function clipWithMarker(text, max) {
7382
+ return text.length <= max ? text : `${clipTo(text, max - 11)}${CLIPPED_MARKER}`;
7383
+ }
7384
+ /**
7385
+ * Copies one component record within the caps, if it fits.
7386
+ *
7387
+ * @param component - The record `serializeEntity` wrote.
7388
+ * @param room - The JSON length still free in the answer.
7389
+ * @returns The capped record and its JSON length, or `null` when it does not fit.
7390
+ */
7391
+ function fitComponent(component, room) {
7392
+ try {
7393
+ const meter = new Meter(room);
7394
+ const record = {
7395
+ ...component,
7396
+ type: clipTo(component.type, 256),
7397
+ ...component.props === void 0 ? {} : { props: capJsonObject(component.props, 0, meter) }
7398
+ };
7399
+ const length = JSON.stringify(record).length + 1;
7400
+ return length <= room ? {
7401
+ record,
7402
+ length,
7403
+ omitted: meter.omitted
7404
+ } : null;
7405
+ } catch (error) {
7406
+ if (error instanceof OverBudget) return null;
7407
+ throw error;
7408
+ }
7409
+ }
7410
+ /**
7411
+ * Reads the type ids a `queryRuntime` keeps.
7412
+ *
7413
+ * @param params - The received `params`.
7414
+ * @returns The entity's uid and the type-id filter, or `null` for every component.
7415
+ * @throws InvalidParamsError when the parameters are not a uid and at most 64 type ids.
7416
+ */
7417
+ function checkQueryRuntimeParams(params) {
7418
+ if (!isQueryRuntimeParams(params)) throw new InvalidParamsError(`queryRuntime needs { entity: uid, components?: typeId[] } with at most ${String(64)} type ids.`);
7419
+ return {
7420
+ uid: params.entity,
7421
+ filter: params.components === void 0 ? null : new Set(params.components)
7422
+ };
7423
+ }
7424
+ /**
7425
+ * `queryRuntime`: one entity of the game as `serializeEntity` writes it from the live world, capped.
7426
+ * Changes nothing.
7427
+ *
7428
+ * @param app - The game's app.
7429
+ * @param params - The received `params`.
7430
+ * @returns The entity record, how many components did not fit, and when it was read.
7431
+ * @throws InvalidParamsError for malformed parameters, and RpcFailure `unknownEntity` when no live
7432
+ * entity of the game has the uid.
7433
+ */
7434
+ function queryRuntime(app, params) {
7435
+ const { uid, filter } = checkQueryRuntimeParams(params);
7436
+ const entity = app.world.getEntity(uid);
7437
+ if (entity === null || entity.isDestroyed) throw new RpcFailure(RpcErrorCode.unknownEntity, "No entity of the running game has that uid. Entities a script or a prefab spawns get new uids on every run.");
7438
+ const { components, ...fields } = serializeEntity(entity);
7439
+ const matching = (components ?? []).filter((component) => filter?.has(component.type) ?? true);
7440
+ const tagsOmitted = Math.max(0, (fields.tags?.length ?? 0) - 256);
7441
+ const answer = {
7442
+ entity: {
7443
+ ...fields,
7444
+ name: clipTo(fields.name, 256),
7445
+ ...fields.layer === void 0 ? {} : { layer: clipTo(fields.layer, 256) },
7446
+ ...fields.tags === void 0 ? {} : { tags: fields.tags.slice(0, 256).map((tag) => clipTo(tag, 256)) }
7447
+ },
7448
+ omittedComponents: matching.length,
7449
+ omittedEntries: tagsOmitted,
7450
+ frameCount: app.time.frameCount,
7451
+ time: app.time.time
7452
+ };
7453
+ let room = QUERY_RUNTIME_MAX_JSON_LENGTH - JSON.stringify(answer).length - COMPONENTS_OVERHEAD;
7454
+ const kept = [];
7455
+ let omittedEntries = tagsOmitted;
7456
+ for (const component of matching.slice(0, 64)) {
7457
+ const fitted = fitComponent(component, room);
7458
+ if (fitted === null) break;
7459
+ kept.push(fitted.record);
7460
+ room -= fitted.length;
7461
+ omittedEntries += fitted.omitted;
7462
+ }
7463
+ return {
7464
+ ...answer,
7465
+ entity: {
7466
+ ...answer.entity,
7467
+ ...kept.length === 0 ? {} : { components: kept }
7468
+ },
7469
+ omittedComponents: matching.length - kept.length,
7470
+ omittedEntries
7471
+ };
7472
+ }
7473
+ //#endregion
6911
7474
  //#region src/play-controls.ts
6912
7475
  /**
6913
7476
  * The play view's controls: the project's own game page, reached by the editor through the app the
@@ -6997,6 +7560,53 @@ function stepDelta(app, params) {
6997
7560
  if (typeof delta !== "number" || !Number.isFinite(delta) || delta <= 0) throw new InvalidParamsError("step needs deltaSeconds to be a positive number of seconds.");
6998
7561
  return delta;
6999
7562
  }
7563
+ /** How often a capture that waits for its frame checks that the game's loop still runs, in ms. */
7564
+ const CAPTURE_STOP_POLL_MS = 50;
7565
+ /**
7566
+ * The refusal of a `screenshot` while the game's frame loop does not run.
7567
+ *
7568
+ * @returns The failure, with code `notPlaying`.
7569
+ */
7570
+ function notPlaying() {
7571
+ return new RpcFailure(RpcErrorCode.notPlaying, "The game is not running, so there is no frame to capture. Press Play first; after Step or Stop the game renders no frames.");
7572
+ }
7573
+ /**
7574
+ * Refuses a method that needs a game that plays or is paused, while the game is stopped.
7575
+ *
7576
+ * @param tracker - Reads the game's phase.
7577
+ * @param what - What the method would have done, for the message.
7578
+ * @throws RpcFailure `notPlaying` while the game is stopped: before it starts, or after `stop`.
7579
+ */
7580
+ function requireStarted(tracker, what) {
7581
+ if (tracker.read().state === PlayPhase.stopped) throw new RpcFailure(RpcErrorCode.notPlaying, `The game is stopped, so there is no running game to ${what}. Press Play first; a paused or stepped game answers.`);
7582
+ }
7583
+ /**
7584
+ * `screenshot`: the game's canvas as an image, as the scene view's `screenshot` answers. Changes
7585
+ * nothing about the game.
7586
+ *
7587
+ * @param app - The game's app.
7588
+ * @param params - The received `params`.
7589
+ * @returns The data URL and its size.
7590
+ * @throws RpcFailure `notPlaying` while the frame loop does not run or when it stops before the
7591
+ * frame arrives, `notReady` before the first frame, and `invalidParams` for parameters the scene
7592
+ * view would refuse.
7593
+ */
7594
+ async function playScreenshot(app, params) {
7595
+ if (!app.isRunning) throw notPlaying();
7596
+ if (app.time.frameCount === 0) throw new RpcFailure(RpcErrorCode.notReady, "The game has not rendered its first frame yet.");
7597
+ const checked = checkScreenshotParams(params);
7598
+ let poll;
7599
+ const stopped = new Promise((_resolve, reject) => {
7600
+ poll = setInterval(() => {
7601
+ if (!app.isRunning) reject(notPlaying());
7602
+ }, CAPTURE_STOP_POLL_MS);
7603
+ });
7604
+ try {
7605
+ return await Promise.race([takeScreenshot(app, checked), stopped]);
7606
+ } finally {
7607
+ clearInterval(poll);
7608
+ }
7609
+ }
7000
7610
  /**
7001
7611
  * Builds the play methods for one app.
7002
7612
  *
@@ -7007,7 +7617,7 @@ function stepDelta(app, params) {
7007
7617
  function playMethods(app, tracker) {
7008
7618
  const answer = () => new Reply(playState(app), tracker.report);
7009
7619
  const stats = new PlayStatsReader(app);
7010
- return /* @__PURE__ */ new Map([
7620
+ const methods = /* @__PURE__ */ new Map([
7011
7621
  [PlayMethod.play, async () => {
7012
7622
  tracker.isStopped = false;
7013
7623
  app.time.paused = false;
@@ -7033,8 +7643,22 @@ function playMethods(app, tracker) {
7033
7643
  return answer();
7034
7644
  }],
7035
7645
  [PlayMethod.playState, () => tracker.read()],
7036
- [PlayMethod.playStats, () => stats.read()]
7646
+ [PlayMethod.playStats, () => stats.read()],
7647
+ [PlayMethod.queryRuntime, (params) => {
7648
+ requireStarted(tracker, "read");
7649
+ return queryRuntime(app, params);
7650
+ }]
7037
7651
  ]);
7652
+ if (!app.isHeadless) methods.set(PlayMethod.screenshot, async (params) => playScreenshot(app, params));
7653
+ const input = inputServiceOf(app);
7654
+ if (input !== null) {
7655
+ const queue = new PlayInput(app, input);
7656
+ methods.set(PlayMethod.sendInput, (params) => {
7657
+ requireStarted(tracker, "send input to");
7658
+ return queue.send(params);
7659
+ });
7660
+ }
7661
+ return methods;
7038
7662
  }
7039
7663
  /**
7040
7664
  * The options every play view checks before it opens a channel.
@@ -7089,7 +7713,10 @@ function openPlayControls(app, options, target, heartbeatIntervalMs, port) {
7089
7713
  capabilities: [
7090
7714
  HostCapability.heartbeat,
7091
7715
  HostCapability.playControls,
7092
- HostCapability.logRelay
7716
+ HostCapability.logRelay,
7717
+ HostCapability.queryRuntime,
7718
+ ...app.isHeadless ? [] : [HostCapability.screenshot],
7719
+ ...inputServiceOf(app) === null ? [] : [HostCapability.sendInput]
7093
7720
  ],
7094
7721
  hostKind: HostKind.play
7095
7722
  },
@@ -7118,7 +7745,7 @@ function openPlayControls(app, options, target, heartbeatIntervalMs, port) {
7118
7745
  }
7119
7746
  /**
7120
7747
  * Lets the editor drive a running game: answers the handshake with `hostKind: "play"`, then `play`,
7121
- * `pause`, `step`, `stop`, `playState` and `playStats`, and sends `playStateChanged` when the game's phase
7748
+ * `pause`, `step`, `stop`, `playState`, `playStats`, `queryRuntime`, (with a canvas) `screenshot` and (with `app.input`) `sendInput`, and sends `playStateChanged` when the game's phase
7122
7749
  * changes, and `log`, `hostError` and `hotReloaded` for the game's log lines, `app.onError` reports
7123
7750
  * and hot reloads (the newest 256 from before the handshake right after it).
7124
7751
  *
@@ -7217,6 +7844,6 @@ function listenForEditorPlayControls(options) {
7217
7844
  };
7218
7845
  }
7219
7846
  //#endregion
7220
- export { ApplyOpFailureCode, COLLIDER_OUTLINES_MAX_ENTITIES, COLLIDER_OUTLINES_MAX_NUMBERS, DEFAULT_HEARTBEAT_INTERVAL_MS, EDITOR_CONNECT_MESSAGE_TYPE, EditorHostErrorCode, GizmoMode, GizmoSpace, HOST_LIST_MAX_LENGTH, HOST_TEXT_MAX_LENGTH, HandshakeMethod, HostCapability, HostKind, HostNotification, JSON_RPC_VERSION, PROTOCOL_VERSION, PickUnit, PlayMethod, PlayNotification, PlayPhase, RpcErrorCode, SAMPLE_ANIMATION_MAX_NAME_LENGTH, SAMPLE_ANIMATION_MAX_PARAMETERS, SCREENSHOT_MAX_SIZE, SceneMethod, SceneNotification, SceneOpKind, ScreenshotFormat, TRANSFORM_DRAGGING_INTERVAL_MS, ViewMode, isAppErrorData, isApplyOpsParams, isApplyOpsResult, isAssetReloadedParams, isColliderOutlineRecord, isColliderOutlineSet, isEditorConnectMessage, isEditorOrigin, isEntitySelection, isFrameParams, isHostErrorParams, isHotReloadedParams, isIncompatibleProtocolData, isInvalidSceneFileData, isJsonObject, isJsonValue, isLogParams, isOpenSceneParams, isOpenSceneResult, isPickParams, isPickResult, isPlayState, isPlayStateReport, isPlayStats, isProtocolVersion, isReadBackParams, isReadBackResult, isReadyResult, isRpcMessage, isSampleAnimationParams, isSampleAnimationResult, isSceneFile, isSceneFileAssetRef, isSceneFileComponent, isSceneFileEntity, isSceneFileInstance, isSceneFileOverride, isSceneFileTransform, isSceneIssue, isSceneOp, isSceneOpenedParams, isSchemaSet, isScreenshotParams, isScreenshotResult, isSetAnimateMaterialsParams, isSetGizmoParams, isSetViewModeParams, isSettingsSet, isTransformDraggedParams, isTransformDraggingParams, listenForEditorPlayControls, protocolVersionIsCompatible, startEditorHost, startEditorPlayControls };
7847
+ export { ApplyOpFailureCode, COLLIDER_OUTLINES_MAX_ENTITIES, COLLIDER_OUTLINES_MAX_NUMBERS, DEFAULT_HEARTBEAT_INTERVAL_MS, EDITOR_CONNECT_MESSAGE_TYPE, EditorHostErrorCode, GizmoMode, GizmoSpace, HOST_LIST_MAX_LENGTH, HOST_TEXT_MAX_LENGTH, HandshakeMethod, HostCapability, HostKind, HostNotification, JSON_RPC_VERSION, PROTOCOL_VERSION, PickUnit, PlayMethod, PlayNotification, PlayPhase, QUERY_RUNTIME_MAX_COMPONENTS, QUERY_RUNTIME_MAX_JSON_LENGTH, QUERY_RUNTIME_MAX_KEYS, QUERY_RUNTIME_MAX_STRING_LENGTH, RpcErrorCode, SAMPLE_ANIMATION_MAX_NAME_LENGTH, SAMPLE_ANIMATION_MAX_PARAMETERS, SCREENSHOT_MAX_SIZE, SEND_INPUT_MAX_EVENTS, SceneMethod, SceneNotification, SceneOpKind, ScreenshotFormat, TRANSFORM_DRAGGING_INTERVAL_MS, ViewMode, isAppErrorData, isApplyOpsParams, isApplyOpsResult, isAssetReloadedParams, isColliderOutlineRecord, isColliderOutlineSet, isEditorConnectMessage, isEditorOrigin, isEntitySelection, isFrameParams, isHostErrorParams, isHotReloadedParams, isIncompatibleProtocolData, isInvalidSceneFileData, isJsonObject, isJsonValue, isLogParams, isOpenSceneParams, isOpenSceneResult, isPickParams, isPickResult, isPlayState, isPlayStateReport, isPlayStats, isProtocolVersion, isQueryRuntimeParams, isQueryRuntimeResult, isReadBackParams, isReadBackResult, isReadyResult, isRpcMessage, isSampleAnimationParams, isSampleAnimationResult, isSceneFile, isSceneFileAssetRef, isSceneFileComponent, isSceneFileEntity, isSceneFileInstance, isSceneFileOverride, isSceneFileTransform, isSceneIssue, isSceneOp, isSceneOpenedParams, isSchemaSet, isScreenshotParams, isScreenshotResult, isSendInputEvent, isSendInputParams, isSendInputResult, isSetAnimateMaterialsParams, isSetGizmoParams, isSetViewModeParams, isSettingsSet, isTransformDraggedParams, isTransformDraggingParams, listenForEditorPlayControls, protocolVersionIsCompatible, startEditorHost, startEditorPlayControls };
7221
7848
 
7222
7849
  //# sourceMappingURL=index.js.map