@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.d.ts CHANGED
@@ -87,6 +87,19 @@ export declare const RpcErrorCode: {
87
87
  readonly notReady: -32_001;
88
88
  /** A scene method that needs an open scene was called while none is open (`SceneMethod`). */
89
89
  readonly noScene: -32_002;
90
+ /**
91
+ * A play method that needs a running game was called while it does not run. `PlayMethod.screenshot`
92
+ * needs the frame loop: it fails before the game starts it, after `stop`, and after `step`.
93
+ * `PlayMethod.queryRuntime` and `PlayMethod.sendInput` need a game that plays or is paused (a
94
+ * stepped game is paused): they fail before the game starts and after `stop`. Additive in 0.3:
95
+ * only a host that answers one of those methods in the play view sends it.
96
+ */
97
+ readonly notPlaying: -32_003;
98
+ /**
99
+ * A play method named an entity uid the game's world does not hold (`PlayMethod.queryRuntime`).
100
+ * Additive in 0.3: only a host that answers `queryRuntime` sends it.
101
+ */
102
+ readonly unknownEntity: -32_004;
90
103
  };
91
104
  /**
92
105
  * The union of the codes in `RpcErrorCode`.
@@ -285,9 +298,11 @@ export type HostKind = (typeof HostKind)[keyof typeof HostKind];
285
298
  * The optional features a host lists in its `ready` result.
286
299
  *
287
300
  * @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.
301
+ * The play controls send `"heartbeat"`, `"playControls"`, `"logRelay"` and `"queryRuntime"`, plus
302
+ * `"screenshot"` when the game has a canvas and `"sendInput"` when it has `app.input`. The scene
303
+ * host sends `"heartbeat"` and whichever of `"gizmos"`, `"screenshot"`, `"viewMode2d"` and
304
+ * `"pick2d"` it supports; every `SceneMethod` not tied to one of them is required of a 0.3 scene
305
+ * host.
291
306
  *
292
307
  * @public
293
308
  */
@@ -301,7 +316,11 @@ export declare const HostCapability: {
301
316
  * `transformDragging` and `transformDragged`.
302
317
  */
303
318
  readonly gizmos: "gizmos";
304
- /** The scene host answers `screenshot`. */
319
+ /**
320
+ * The host answers `screenshot`: the scene host captures its view, the play controls the game's
321
+ * canvas. The play controls list it from engine ask E47 (additive in 0.3); without it, the play
322
+ * view answers `screenshot` with `RpcErrorCode.methodNotFound`.
323
+ */
305
324
  readonly screenshot: "screenshot";
306
325
  /** The scene host accepts `setViewMode` with `"2d"`: a 2D editor camera and planar gizmos. */
307
326
  readonly viewMode2d: "viewMode2d";
@@ -325,6 +344,19 @@ export declare const HostCapability: {
325
344
  * defaults. Additive in 0.3.
326
345
  */
327
346
  readonly hotReloadDefaults: "hotReloadDefaults";
347
+ /**
348
+ * The play controls answer `queryRuntime`: an entity's live state in the scene format. From engine
349
+ * ask E48 (additive in 0.3); without it, the play view answers `queryRuntime` with
350
+ * `RpcErrorCode.methodNotFound`.
351
+ */
352
+ readonly queryRuntime: "queryRuntime";
353
+ /**
354
+ * The play controls answer `sendInput`: synthetic key and pointer events queued into the game's
355
+ * own input system (`app.input` from `@ignifx/input`), never into the editor's window. Listed only
356
+ * when the game has `app.input`. From engine ask E49 (additive in 0.3); without it, the play view
357
+ * answers `sendInput` with `RpcErrorCode.methodNotFound`.
358
+ */
359
+ readonly sendInput: "sendInput";
328
360
  };
329
361
  /**
330
362
  * The union of the names in `HostCapability`.
@@ -489,230 +521,6 @@ export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 1e3;
489
521
  */
490
522
  type HeartbeatNotification = RpcNotification<typeof HostNotification.heartbeat, never>;
491
523
  //#endregion
492
- //#region src/protocol/play.d.ts
493
- /**
494
- * The methods the play view answers after `ready`. `play`, `pause`, `step` and `stop` answer with a
495
- * {@link PlayState}; `playState` answers with a {@link PlayStateReport}; `playStats` answers with
496
- * {@link PlayStats}.
497
- *
498
- * @remarks
499
- * A host that answers them lists `HostCapability.playControls` in `ready`. Sent before `ready`, they
500
- * fail with `RpcErrorCode.notReady`; sent to a host without them, with `RpcErrorCode.methodNotFound`.
501
- * `playState` and `playStats` are additive 0.3 methods: a host from before one answers it with
502
- * `RpcErrorCode.methodNotFound`.
503
- *
504
- * @public
505
- */
506
- export declare const PlayMethod: {
507
- /** Clears `app.time.paused` and starts the frame loop if it is stopped. */
508
- readonly play: "play";
509
- /** Sets `app.time.paused`; scripts marked `updateWhenPaused` keep running. */
510
- readonly pause: "pause";
511
- /** Stops the frame loop, then advances exactly one frame with `app.step()` and leaves the game paused. */
512
- readonly step: "step";
513
- /** Stops the frame loop with `app.stop()`. The editor reloads the view to reset the game. */
514
- readonly stop: "stop";
515
- /** Reads the game's state without changing it. Takes no parameters. */
516
- readonly playState: "playState";
517
- /**
518
- * Reads the game's frame rate, frame time, entity count and frame count without changing
519
- * anything. Takes no parameters. The editor polls it; no notification carries it.
520
- */
521
- readonly playStats: "playStats";
522
- };
523
- /**
524
- * The union of the names in `PlayMethod`.
525
- *
526
- * @public
527
- */
528
- export type PlayMethod = (typeof PlayMethod)[keyof typeof PlayMethod];
529
- /**
530
- * The parameters of the `step` method.
531
- *
532
- * @public
533
- */
534
- interface StepParams {
535
- /**
536
- * The frame delta in seconds, a positive finite number. Defaults to `app.time.fixedDeltaTime`;
537
- * any other value fails with `RpcErrorCode.invalidParams`.
538
- */
539
- readonly deltaSeconds?: number;
540
- }
541
- /**
542
- * Editor → play view: one of the `PlayMethod`s. Only `step` takes parameters.
543
- *
544
- * @public
545
- */
546
- 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>;
547
- /**
548
- * What the play view reports after every `PlayMethod`.
549
- *
550
- * @public
551
- */
552
- interface PlayState {
553
- /** Whether the frame loop runs (`app.isRunning`). */
554
- readonly isRunning: boolean;
555
- /** Whether game time is paused (`app.time.paused`). */
556
- readonly isPaused: boolean;
557
- /** How many frames have started (`app.time.frameCount`). */
558
- readonly frameCount: number;
559
- }
560
- /**
561
- * Play view → editor: the answer to `play`, `pause`, `step` or `stop`.
562
- *
563
- * @public
564
- */
565
- type PlayResponse = RpcSuccessResponse<PlayState>;
566
- /**
567
- * The notifications the play view sends after `ready`.
568
- *
569
- * @remarks
570
- * Additive in 0.3: a host from before them sends none, and answers `playState` with
571
- * `RpcErrorCode.methodNotFound`. `log`, `hostError` and `hotReloaded` came later still: only a host
572
- * that lists `HostCapability.logRelay` in `ready` sends them.
573
- *
574
- * @public
575
- */
576
- export declare const PlayNotification: {
577
- /**
578
- * After the game's {@link PlayStateReport.state} changed. A change a `PlayMethod` makes is sent
579
- * right after that method's answer; one the game makes itself, such as setting
580
- * `app.time.paused`, within one heartbeat interval.
581
- */
582
- readonly playStateChanged: "playStateChanged";
583
- /**
584
- * One line from the game's logger, with the same `LogParams` as the scene view's `log`. Sent by a
585
- * host that lists `HostCapability.logRelay`; lines logged before the handshake are kept (the
586
- * newest few hundred) and sent right after `ready`.
587
- */
588
- readonly log: "log";
589
- /**
590
- * An error the game's app reported through `app.onError`: the same `HostErrorParams` as the scene
591
- * view's `hostError`, with `AppErrorData` as its `data`. Sent by a host that lists
592
- * `HostCapability.logRelay`, kept before the handshake as `log` is.
593
- */
594
- readonly hostError: "hostError";
595
- /**
596
- * After every `app.hotReload` operation in the game: the same `HotReloadedParams` as the scene
597
- * view's `hotReloaded`. Sent by a host that lists `HostCapability.logRelay`.
598
- */
599
- readonly hotReloaded: "hotReloaded";
600
- };
601
- /**
602
- * The union of the names in `PlayNotification`.
603
- *
604
- * @public
605
- */
606
- export type PlayNotification = (typeof PlayNotification)[keyof typeof PlayNotification];
607
- /**
608
- * Whether the game plays, is paused, or is stopped, as {@link PlayStateReport.state} reports it.
609
- *
610
- * @public
611
- */
612
- export declare const PlayPhase: {
613
- /** The frame loop runs (`app.isRunning`) and game time is not paused. */
614
- readonly playing: "playing";
615
- /**
616
- * Game time is paused (`app.time.paused`): after `pause`, or after `step`, which leaves the frame
617
- * loop stopped on the stepped frame.
618
- */
619
- readonly paused: "paused";
620
- /** The frame loop does not run: before the game starts it, or after `stop`. */
621
- readonly stopped: "stopped";
622
- };
623
- /**
624
- * The union of the names in `PlayPhase`.
625
- *
626
- * @public
627
- */
628
- export type PlayPhase = (typeof PlayPhase)[keyof typeof PlayPhase];
629
- /**
630
- * The game's state as `playState` answers it and `playStateChanged` reports it.
631
- *
632
- * @public
633
- */
634
- interface PlayStateReport {
635
- /** Whether the game plays, is paused, or is stopped. */
636
- readonly state: PlayPhase;
637
- /** How many frames have started (`app.time.frameCount`). */
638
- readonly frameCount: number;
639
- /** Scaled seconds of game time since the app started running frames (`app.time.time`). */
640
- readonly time: number;
641
- }
642
- /**
643
- * Play view → editor: the answer to `playState`.
644
- *
645
- * @public
646
- */
647
- type PlayStateResponse = RpcSuccessResponse<PlayStateReport>;
648
- /**
649
- * The game's performance as `playStats` answers it.
650
- *
651
- * @public
652
- */
653
- interface PlayStats {
654
- /**
655
- * Frames per second: `1000 / frameTimeMs`, or `0` when `frameTimeMs` is `0`. Rendered frames
656
- * count whether or not game time is paused.
657
- */
658
- readonly fps: number;
659
- /**
660
- * The mean wall-clock time between the frames of the last second, in milliseconds, from the
661
- * frame history in `app.diagnostics` (each frame's `rawDeltaMs`); `0` while the frame loop does
662
- * not run (stopped, or stepped and paused on a frame) or before its first frame.
663
- */
664
- readonly frameTimeMs: number;
665
- /** How many entities the game's world holds, in every scene instance, persistent ones included. */
666
- readonly entityCount: number;
667
- /** How many frames have started (`app.time.frameCount`). */
668
- readonly frameCount: number;
669
- }
670
- /**
671
- * Play view → editor: the answer to `playStats`.
672
- *
673
- * @public
674
- */
675
- type PlayStatsResponse = RpcSuccessResponse<PlayStats>;
676
- /**
677
- * Play view → editor: the game's state changed.
678
- *
679
- * @public
680
- */
681
- interface PlayStateChangedNotification extends RpcNotification<typeof PlayNotification.playStateChanged, PlayStateReport> {
682
- /** The game's state after the change. */
683
- readonly params: PlayStateReport;
684
- }
685
- /**
686
- * Checks the `result` of a play method's response.
687
- *
688
- * @param value - The received `result`.
689
- * @returns True when `value` has boolean `isRunning` and `isPaused` and a non-negative integer
690
- * `frameCount`.
691
- *
692
- * @public
693
- */
694
- export declare function isPlayState(value: unknown): value is PlayState;
695
- /**
696
- * Checks the `result` of `playState` and the `params` of `playStateChanged`.
697
- *
698
- * @param value - The received value.
699
- * @returns True when `value` has a `state` that is a `PlayPhase`, a non-negative integer
700
- * `frameCount`, and a non-negative finite `time`.
701
- *
702
- * @public
703
- */
704
- export declare function isPlayStateReport(value: unknown): value is PlayStateReport;
705
- /**
706
- * Checks the `result` of `playStats`.
707
- *
708
- * @param value - The received `result`.
709
- * @returns True when `value` has non-negative finite `fps` and `frameTimeMs` and non-negative
710
- * integer `entityCount` and `frameCount`.
711
- *
712
- * @public
713
- */
714
- export declare function isPlayStats(value: unknown): value is PlayStats;
715
- //#endregion
716
524
  //#region src/protocol/scene-file.d.ts
717
525
  /**
718
526
  * Any JSON value. The engine's `JsonValue`.
@@ -2601,6 +2409,465 @@ export declare function isAppErrorData(value: unknown): value is AppErrorData;
2601
2409
  */
2602
2410
  export declare function isLogParams(value: unknown): value is LogParams;
2603
2411
  //#endregion
2412
+ //#region src/protocol/play.d.ts
2413
+ /**
2414
+ * The methods the play view answers after `ready`. `play`, `pause`, `step` and `stop` answer with a
2415
+ * {@link PlayState}; `playState` answers with a {@link PlayStateReport}; `playStats` answers with
2416
+ * {@link PlayStats}; `screenshot` answers with a `ScreenshotResult`; `queryRuntime` answers with a
2417
+ * {@link QueryRuntimeResult}; `sendInput` answers with a {@link SendInputResult}.
2418
+ *
2419
+ * @remarks
2420
+ * A host that answers them lists `HostCapability.playControls` in `ready`. Sent before `ready`, they
2421
+ * fail with `RpcErrorCode.notReady`; sent to a host without them, with `RpcErrorCode.methodNotFound`.
2422
+ * `playState`, `playStats`, `screenshot`, `queryRuntime` and `sendInput` are additive 0.3 methods:
2423
+ * a host from before one answers it with `RpcErrorCode.methodNotFound`. `screenshot`, `queryRuntime`
2424
+ * and `sendInput` also need the `HostCapability` of the same name in the play view's `ready`.
2425
+ *
2426
+ * @public
2427
+ */
2428
+ export declare const PlayMethod: {
2429
+ /** Clears `app.time.paused` and starts the frame loop if it is stopped. */
2430
+ readonly play: "play";
2431
+ /** Sets `app.time.paused`; scripts marked `updateWhenPaused` keep running. */
2432
+ readonly pause: "pause";
2433
+ /** Stops the frame loop, then advances exactly one frame with `app.step()` and leaves the game paused. */
2434
+ readonly step: "step";
2435
+ /** Stops the frame loop with `app.stop()`. The editor reloads the view to reset the game. */
2436
+ readonly stop: "stop";
2437
+ /** Reads the game's state without changing it. Takes no parameters. */
2438
+ readonly playState: "playState";
2439
+ /**
2440
+ * Reads the game's frame rate, frame time, entity count and frame count without changing
2441
+ * anything. Takes no parameters. The editor polls it; no notification carries it.
2442
+ */
2443
+ readonly playStats: "playStats";
2444
+ /**
2445
+ * Captures the game's canvas as an image, with the scene view's `screenshot` parameters, caps and
2446
+ * answer (`ScreenshotParams`, `ScreenshotResult`). Changes nothing: a paused game is captured
2447
+ * paused. Needs `HostCapability.screenshot`. Fails with `RpcErrorCode.notPlaying` while the frame
2448
+ * loop does not run (before the game starts it, after `stop` or `step`), and with
2449
+ * `RpcErrorCode.notReady` before the game's first frame.
2450
+ */
2451
+ readonly screenshot: "screenshot";
2452
+ /**
2453
+ * Reads one entity of the running game as the scene format writes it ({@link QueryRuntimeParams},
2454
+ * {@link QueryRuntimeResult}): its live transform, flags and component props, never anything a
2455
+ * component does not serialize, and no expressions. Each value is capped and the whole answer kept
2456
+ * within {@link QUERY_RUNTIME_MAX_JSON_LENGTH}. Changes nothing. Needs
2457
+ * `HostCapability.queryRuntime`. Fails with `RpcErrorCode.notPlaying` while the game is stopped
2458
+ * (before it starts, after `stop`; a stepped game is paused and answers), and with
2459
+ * `RpcErrorCode.unknownEntity` when no entity of the game has the uid.
2460
+ */
2461
+ readonly queryRuntime: "queryRuntime";
2462
+ /**
2463
+ * Queues synthetic key and pointer events into the game's own input system, as if the game's page
2464
+ * had received them ({@link SendInputParams}, {@link SendInputResult}). Nothing reaches the
2465
+ * editor's window or the operating system. Needs `HostCapability.sendInput`, which a game lists
2466
+ * only when it has `app.input` (`@ignifx/input`). Fails with `RpcErrorCode.notPlaying` while the
2467
+ * game is stopped; a paused or stepped game takes the events and resolves them on its next frame,
2468
+ * which for a stepped game is the next `step`.
2469
+ */
2470
+ readonly sendInput: "sendInput";
2471
+ };
2472
+ /**
2473
+ * The union of the names in `PlayMethod`.
2474
+ *
2475
+ * @public
2476
+ */
2477
+ export type PlayMethod = (typeof PlayMethod)[keyof typeof PlayMethod];
2478
+ /**
2479
+ * The parameters of the `step` method.
2480
+ *
2481
+ * @public
2482
+ */
2483
+ interface StepParams {
2484
+ /**
2485
+ * The frame delta in seconds, a positive finite number. Defaults to `app.time.fixedDeltaTime`;
2486
+ * any other value fails with `RpcErrorCode.invalidParams`.
2487
+ */
2488
+ readonly deltaSeconds?: number;
2489
+ }
2490
+ /**
2491
+ * The most components a `queryRuntime` answer holds, and the most type ids its `components` filter
2492
+ * may name. Components past it are counted in {@link QueryRuntimeResult.omittedComponents}.
2493
+ *
2494
+ * @public
2495
+ */
2496
+ export declare const QUERY_RUNTIME_MAX_COMPONENTS = 64;
2497
+ /**
2498
+ * The longest a `queryRuntime` answer may be: its `result` as JSON text, in UTF-16 code units
2499
+ * (`JSON.stringify(result).length`), 256 Ki. Components that would pass it are left out, in order,
2500
+ * and counted in {@link QueryRuntimeResult.omittedComponents}.
2501
+ *
2502
+ * @public
2503
+ */
2504
+ export declare const QUERY_RUNTIME_MAX_JSON_LENGTH = 262144;
2505
+ /**
2506
+ * In a `queryRuntime` answer, the most keys one object keeps and the longest a key may be; also the
2507
+ * longest the entity's `name`, `layer`, each tag and each component `type` may be, and the most
2508
+ * tags kept. Keys left out are counted in {@link QueryRuntimeResult.omittedEntries}.
2509
+ *
2510
+ * @public
2511
+ */
2512
+ export declare const QUERY_RUNTIME_MAX_KEYS = 256;
2513
+ /**
2514
+ * In a `queryRuntime` answer, the longest a prop string may be, `… [clipped]` included: 64 Ki, a
2515
+ * quarter of {@link QUERY_RUNTIME_MAX_JSON_LENGTH}, so one long string does not cost its component
2516
+ * its place.
2517
+ *
2518
+ * @public
2519
+ */
2520
+ export declare const QUERY_RUNTIME_MAX_STRING_LENGTH = 65536;
2521
+ /**
2522
+ * The parameters of the `queryRuntime` method.
2523
+ *
2524
+ * @public
2525
+ */
2526
+ interface QueryRuntimeParams {
2527
+ /** The entity's uid. A scene's own entities keep their file uids at run time. */
2528
+ readonly entity: string;
2529
+ /**
2530
+ * Only the components of these type ids, at most {@link QUERY_RUNTIME_MAX_COMPONENTS}; absent for
2531
+ * all of them. A type id the entity does not carry matches nothing.
2532
+ */
2533
+ readonly components?: readonly string[];
2534
+ }
2535
+ /**
2536
+ * Play view → editor: the answer to `queryRuntime`.
2537
+ *
2538
+ * @public
2539
+ */
2540
+ interface QueryRuntimeResult {
2541
+ /**
2542
+ * The entity as `serializeEntity` writes it from the live world, with at most
2543
+ * {@link QUERY_RUNTIME_MAX_COMPONENTS} components (only the filtered ones when `components` was
2544
+ * given), in the entity's order, as many as fit in {@link QUERY_RUNTIME_MAX_JSON_LENGTH}.
2545
+ *
2546
+ * @remarks
2547
+ * Each value is capped too: a prop string is clipped to {@link QUERY_RUNTIME_MAX_STRING_LENGTH}
2548
+ * (ending `… [clipped]`), a list cut to `HOST_LIST_MAX_LENGTH` items, an object to its first
2549
+ * {@link QUERY_RUNTIME_MAX_KEYS} keys, and each key, the `name`, the `layer`, each component
2550
+ * `type` and each of at most {@link QUERY_RUNTIME_MAX_KEYS} tags clipped to
2551
+ * {@link QUERY_RUNTIME_MAX_KEYS} characters. When two keys clip to the same one, the first keeps
2552
+ * it. No marker is written into a value (a map's keys can be any string, so none would be safe):
2553
+ * what was left out is counted in {@link QueryRuntimeResult.omittedEntries}. A value that is not JSON (a non-finite number, a function a custom codec returned)
2554
+ * becomes `null`, and so does anything nested deeper than 256 levels.
2555
+ */
2556
+ readonly entity: SceneFileEntity;
2557
+ /**
2558
+ * How many matching components were left out: past {@link QUERY_RUNTIME_MAX_COMPONENTS}, or past
2559
+ * the first that did not fit in {@link QUERY_RUNTIME_MAX_JSON_LENGTH}.
2560
+ */
2561
+ readonly omittedComponents: number;
2562
+ /**
2563
+ * How many object keys, list items and tags the caps left out of the answered entity: past
2564
+ * {@link QUERY_RUNTIME_MAX_KEYS} keys or tags, past `HOST_LIST_MAX_LENGTH` items, or a key that
2565
+ * clipped to one already kept. `0` when every kept component is whole.
2566
+ */
2567
+ readonly omittedEntries: number;
2568
+ /** How many frames had started when it was read (`app.time.frameCount`). */
2569
+ readonly frameCount: number;
2570
+ /** Scaled seconds of game time when it was read (`app.time.time`). */
2571
+ readonly time: number;
2572
+ }
2573
+ /**
2574
+ * Play view → editor: the answer to `queryRuntime`.
2575
+ *
2576
+ * @public
2577
+ */
2578
+ type QueryRuntimeResponse = RpcSuccessResponse<QueryRuntimeResult>;
2579
+ /**
2580
+ * The most events one `sendInput` request may carry.
2581
+ *
2582
+ * @public
2583
+ */
2584
+ export declare const SEND_INPUT_MAX_EVENTS = 64;
2585
+ /**
2586
+ * A key press or release in a `sendInput` request.
2587
+ *
2588
+ * @public
2589
+ */
2590
+ interface SendInputKeyEvent {
2591
+ /** `"keydown"` presses the key and holds it until a `"keyup"`; `"keyup"` releases it. */
2592
+ readonly type: "keydown" | "keyup";
2593
+ /**
2594
+ * The `<Keyboard>` control name: the physical key's `KeyboardEvent.code` in camelCase without its
2595
+ * `Key` or `Digit` prefix, such as `w`, `1`, `space`, `arrowUp` or `shiftLeft`. Letters and digits
2596
+ * only, at most 64 of them; a name the game's keyboard does not have fails with
2597
+ * `RpcErrorCode.invalidParams`.
2598
+ */
2599
+ readonly control: string;
2600
+ }
2601
+ /**
2602
+ * A pointer move, press or release in a `sendInput` request.
2603
+ *
2604
+ * @public
2605
+ */
2606
+ interface SendInputPointerEvent {
2607
+ /** Which pointer event it is. */
2608
+ readonly type: "pointermove" | "pointerdown" | "pointerup";
2609
+ /** The pointer's x as a fraction of the game's canvas width, from `0` (left) to `1` (right). */
2610
+ readonly x: number;
2611
+ /** The pointer's y as a fraction of the game's canvas height, from `0` (top) to `1` (bottom). */
2612
+ readonly y: number;
2613
+ /** The `PointerEvent.button`, an integer from `0` (main) to `4`. Defaults to `0`. */
2614
+ readonly button?: number;
2615
+ }
2616
+ /**
2617
+ * One event of a `sendInput` request.
2618
+ *
2619
+ * @public
2620
+ */
2621
+ type SendInputEvent = SendInputKeyEvent | SendInputPointerEvent;
2622
+ /**
2623
+ * The parameters of the `sendInput` method.
2624
+ *
2625
+ * @public
2626
+ */
2627
+ interface SendInputParams {
2628
+ /** The events, in order: from 1 to {@link SEND_INPUT_MAX_EVENTS} of them. */
2629
+ readonly events: readonly SendInputEvent[];
2630
+ }
2631
+ /**
2632
+ * Play view → editor: what `sendInput` queued.
2633
+ *
2634
+ * @public
2635
+ */
2636
+ interface SendInputResult {
2637
+ /** How many events were queued: all of the request's. */
2638
+ readonly queued: number;
2639
+ }
2640
+ /**
2641
+ * Play view → editor: the answer to `sendInput`.
2642
+ *
2643
+ * @public
2644
+ */
2645
+ type SendInputResponse = RpcSuccessResponse<SendInputResult>;
2646
+ /**
2647
+ * Editor → play view: one of the `PlayMethod`s. Only `step`, `screenshot`, `queryRuntime` and
2648
+ * `sendInput` take parameters.
2649
+ *
2650
+ * @public
2651
+ */
2652
+ 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> | RpcRequestWithParams<typeof PlayMethod.screenshot, ScreenshotParams> | RpcRequestWithParams<typeof PlayMethod.queryRuntime, QueryRuntimeParams> | RpcRequestWithParams<typeof PlayMethod.sendInput, SendInputParams>;
2653
+ /**
2654
+ * What the play view reports after every `PlayMethod`.
2655
+ *
2656
+ * @public
2657
+ */
2658
+ interface PlayState {
2659
+ /** Whether the frame loop runs (`app.isRunning`). */
2660
+ readonly isRunning: boolean;
2661
+ /** Whether game time is paused (`app.time.paused`). */
2662
+ readonly isPaused: boolean;
2663
+ /** How many frames have started (`app.time.frameCount`). */
2664
+ readonly frameCount: number;
2665
+ }
2666
+ /**
2667
+ * Play view → editor: the answer to `play`, `pause`, `step` or `stop`.
2668
+ *
2669
+ * @public
2670
+ */
2671
+ type PlayResponse = RpcSuccessResponse<PlayState>;
2672
+ /**
2673
+ * The notifications the play view sends after `ready`.
2674
+ *
2675
+ * @remarks
2676
+ * Additive in 0.3: a host from before them sends none, and answers `playState` with
2677
+ * `RpcErrorCode.methodNotFound`. `log`, `hostError` and `hotReloaded` came later still: only a host
2678
+ * that lists `HostCapability.logRelay` in `ready` sends them.
2679
+ *
2680
+ * @public
2681
+ */
2682
+ export declare const PlayNotification: {
2683
+ /**
2684
+ * After the game's {@link PlayStateReport.state} changed. A change a `PlayMethod` makes is sent
2685
+ * right after that method's answer; one the game makes itself, such as setting
2686
+ * `app.time.paused`, within one heartbeat interval.
2687
+ */
2688
+ readonly playStateChanged: "playStateChanged";
2689
+ /**
2690
+ * One line from the game's logger, with the same `LogParams` as the scene view's `log`. Sent by a
2691
+ * host that lists `HostCapability.logRelay`; lines logged before the handshake are kept (the
2692
+ * newest few hundred) and sent right after `ready`.
2693
+ */
2694
+ readonly log: "log";
2695
+ /**
2696
+ * An error the game's app reported through `app.onError`: the same `HostErrorParams` as the scene
2697
+ * view's `hostError`, with `AppErrorData` as its `data`. Sent by a host that lists
2698
+ * `HostCapability.logRelay`, kept before the handshake as `log` is.
2699
+ */
2700
+ readonly hostError: "hostError";
2701
+ /**
2702
+ * After every `app.hotReload` operation in the game: the same `HotReloadedParams` as the scene
2703
+ * view's `hotReloaded`. Sent by a host that lists `HostCapability.logRelay`.
2704
+ */
2705
+ readonly hotReloaded: "hotReloaded";
2706
+ };
2707
+ /**
2708
+ * The union of the names in `PlayNotification`.
2709
+ *
2710
+ * @public
2711
+ */
2712
+ export type PlayNotification = (typeof PlayNotification)[keyof typeof PlayNotification];
2713
+ /**
2714
+ * Whether the game plays, is paused, or is stopped, as {@link PlayStateReport.state} reports it.
2715
+ *
2716
+ * @public
2717
+ */
2718
+ export declare const PlayPhase: {
2719
+ /** The frame loop runs (`app.isRunning`) and game time is not paused. */
2720
+ readonly playing: "playing";
2721
+ /**
2722
+ * Game time is paused (`app.time.paused`): after `pause`, or after `step`, which leaves the frame
2723
+ * loop stopped on the stepped frame.
2724
+ */
2725
+ readonly paused: "paused";
2726
+ /** The frame loop does not run: before the game starts it, or after `stop`. */
2727
+ readonly stopped: "stopped";
2728
+ };
2729
+ /**
2730
+ * The union of the names in `PlayPhase`.
2731
+ *
2732
+ * @public
2733
+ */
2734
+ export type PlayPhase = (typeof PlayPhase)[keyof typeof PlayPhase];
2735
+ /**
2736
+ * The game's state as `playState` answers it and `playStateChanged` reports it.
2737
+ *
2738
+ * @public
2739
+ */
2740
+ interface PlayStateReport {
2741
+ /** Whether the game plays, is paused, or is stopped. */
2742
+ readonly state: PlayPhase;
2743
+ /** How many frames have started (`app.time.frameCount`). */
2744
+ readonly frameCount: number;
2745
+ /** Scaled seconds of game time since the app started running frames (`app.time.time`). */
2746
+ readonly time: number;
2747
+ }
2748
+ /**
2749
+ * Play view → editor: the answer to `playState`.
2750
+ *
2751
+ * @public
2752
+ */
2753
+ type PlayStateResponse = RpcSuccessResponse<PlayStateReport>;
2754
+ /**
2755
+ * The game's performance as `playStats` answers it.
2756
+ *
2757
+ * @public
2758
+ */
2759
+ interface PlayStats {
2760
+ /**
2761
+ * Frames per second: `1000 / frameTimeMs`, or `0` when `frameTimeMs` is `0`. Rendered frames
2762
+ * count whether or not game time is paused.
2763
+ */
2764
+ readonly fps: number;
2765
+ /**
2766
+ * The mean wall-clock time between the frames of the last second, in milliseconds, from the
2767
+ * frame history in `app.diagnostics` (each frame's `rawDeltaMs`); `0` while the frame loop does
2768
+ * not run (stopped, or stepped and paused on a frame) or before its first frame.
2769
+ */
2770
+ readonly frameTimeMs: number;
2771
+ /** How many entities the game's world holds, in every scene instance, persistent ones included. */
2772
+ readonly entityCount: number;
2773
+ /** How many frames have started (`app.time.frameCount`). */
2774
+ readonly frameCount: number;
2775
+ }
2776
+ /**
2777
+ * Play view → editor: the answer to `playStats`.
2778
+ *
2779
+ * @public
2780
+ */
2781
+ type PlayStatsResponse = RpcSuccessResponse<PlayStats>;
2782
+ /**
2783
+ * Play view → editor: the game's state changed.
2784
+ *
2785
+ * @public
2786
+ */
2787
+ interface PlayStateChangedNotification extends RpcNotification<typeof PlayNotification.playStateChanged, PlayStateReport> {
2788
+ /** The game's state after the change. */
2789
+ readonly params: PlayStateReport;
2790
+ }
2791
+ /**
2792
+ * Checks the `result` of a play method's response.
2793
+ *
2794
+ * @param value - The received `result`.
2795
+ * @returns True when `value` has boolean `isRunning` and `isPaused` and a non-negative integer
2796
+ * `frameCount`.
2797
+ *
2798
+ * @public
2799
+ */
2800
+ export declare function isPlayState(value: unknown): value is PlayState;
2801
+ /**
2802
+ * Checks the `result` of `playState` and the `params` of `playStateChanged`.
2803
+ *
2804
+ * @param value - The received value.
2805
+ * @returns True when `value` has a `state` that is a `PlayPhase`, a non-negative integer
2806
+ * `frameCount`, and a non-negative finite `time`.
2807
+ *
2808
+ * @public
2809
+ */
2810
+ export declare function isPlayStateReport(value: unknown): value is PlayStateReport;
2811
+ /**
2812
+ * Checks the `result` of `playStats`.
2813
+ *
2814
+ * @param value - The received `result`.
2815
+ * @returns True when `value` has non-negative finite `fps` and `frameTimeMs` and non-negative
2816
+ * integer `entityCount` and `frameCount`.
2817
+ *
2818
+ * @public
2819
+ */
2820
+ export declare function isPlayStats(value: unknown): value is PlayStats;
2821
+ /**
2822
+ * Checks the `params` of `queryRuntime`.
2823
+ *
2824
+ * @param value - The received `params`.
2825
+ * @returns True for a non-empty `entity` uid and, when present, a `components` list of at most
2826
+ * {@link QUERY_RUNTIME_MAX_COMPONENTS} non-empty strings.
2827
+ *
2828
+ * @public
2829
+ */
2830
+ export declare function isQueryRuntimeParams(value: unknown): value is QueryRuntimeParams;
2831
+ /**
2832
+ * Checks the `result` of `queryRuntime`.
2833
+ *
2834
+ * @param value - The received `result`.
2835
+ * @returns True for an entity record with at most {@link QUERY_RUNTIME_MAX_COMPONENTS} components,
2836
+ * non-negative integer `omittedComponents`, `omittedEntries` and `frameCount`, and a non-negative
2837
+ * finite `time`, no longer than {@link QUERY_RUNTIME_MAX_JSON_LENGTH} as JSON.
2838
+ *
2839
+ * @public
2840
+ */
2841
+ export declare function isQueryRuntimeResult(value: unknown): value is QueryRuntimeResult;
2842
+ /**
2843
+ * Checks one event of a `sendInput` request.
2844
+ *
2845
+ * @param value - The value to test.
2846
+ * @returns True for a key event with a well-formed `control`, or a pointer event with `x` and `y`
2847
+ * from 0 to 1 and, when present, an integer `button` from 0 to 4.
2848
+ *
2849
+ * @public
2850
+ */
2851
+ export declare function isSendInputEvent(value: unknown): value is SendInputEvent;
2852
+ /**
2853
+ * Checks the `params` of `sendInput`.
2854
+ *
2855
+ * @param value - The received `params`.
2856
+ * @returns True for an `events` list of 1 to {@link SEND_INPUT_MAX_EVENTS} well-formed events.
2857
+ *
2858
+ * @public
2859
+ */
2860
+ export declare function isSendInputParams(value: unknown): value is SendInputParams;
2861
+ /**
2862
+ * Checks the `result` of `sendInput`.
2863
+ *
2864
+ * @param value - The received `result`.
2865
+ * @returns True for an integer `queued` from 0 to {@link SEND_INPUT_MAX_EVENTS}.
2866
+ *
2867
+ * @public
2868
+ */
2869
+ export declare function isSendInputResult(value: unknown): value is SendInputResult;
2870
+ //#endregion
2604
2871
  //#region src/channel.d.ts
2605
2872
  /**
2606
2873
  * Where a host listens for the editor's connect message: the view's `window` in a browser, or any
@@ -2818,7 +3085,7 @@ interface EditorPlayConnector {
2818
3085
  }
2819
3086
  /**
2820
3087
  * Lets the editor drive a running game: answers the handshake with `hostKind: "play"`, then `play`,
2821
- * `pause`, `step`, `stop`, `playState` and `playStats`, and sends `playStateChanged` when the game's phase
3088
+ * `pause`, `step`, `stop`, `playState`, `playStats`, `queryRuntime`, (with a canvas) `screenshot` and (with `app.input`) `sendInput`, and sends `playStateChanged` when the game's phase
2822
3089
  * changes, and `log`, `hostError` and `hotReloaded` for the game's log lines, `app.onError` reports
2823
3090
  * and hot reloads (the newest 256 from before the handshake right after it).
2824
3091
  *
@@ -2871,5 +3138,5 @@ export declare function startEditorPlayControls(app: App, options: EditorPlayCon
2871
3138
  */
2872
3139
  export declare function listenForEditorPlayControls(options: EditorPlayControlsOptions): EditorPlayConnector;
2873
3140
  //#endregion
2874
- export { type AddComponentOp, type AppErrorData, type ApplyOpFailure, type ApplyOpsParams, type ApplyOpsResponse, type ApplyOpsResult, type AssetReloadedParams, type ColliderOutlineRecord, type ColliderOutlineSet, type ColliderOutlinesResponse, 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 SampleAnimationParams, type SampleAnimationResponse, type SampleAnimationResult, 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 SetAnimateMaterialsParams, 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 };
3141
+ export { type AddComponentOp, type AppErrorData, type ApplyOpFailure, type ApplyOpsParams, type ApplyOpsResponse, type ApplyOpsResult, type AssetReloadedParams, type ColliderOutlineRecord, type ColliderOutlineSet, type ColliderOutlinesResponse, 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 QueryRuntimeParams, type QueryRuntimeResponse, type QueryRuntimeResult, 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 SampleAnimationParams, type SampleAnimationResponse, type SampleAnimationResult, 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 SendInputEvent, type SendInputKeyEvent, type SendInputParams, type SendInputPointerEvent, type SendInputResponse, type SendInputResult, type SetAnimateMaterialsParams, 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 };
2875
3142
  //# sourceMappingURL=index.d.ts.map