@ignifx/editor-host 0.11.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.
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  name: editor-host
3
- description: Connects an ignifx project to the ignifx editor with @ignifx/editor-host: the Vite plugin that serves the editor's scene view from the project's own dev server, the virtual:ignifx/editor play controls a game's main.ts hands its app to (play, pause, step, stop, playState, playStateChanged, playStats), and the host half of the editor protocol 0.3 over a MessagePort (hello/ready, heartbeat, and the scene document methods openScene, applyOps, readBack, select, pick, frame, setGizmo, setViewMode, screenshot, getSchemas, describeSettings, setAnimateMaterials, getColliderOutlines, sampleAnimation), including the 2D view mode (an editor Camera2D and app.twoD.pickAt picking). Use when wiring a project or template for the editor, when the user mentions @ignifx/editor-host, editorHostPlugin, attachEditorPlayControls, virtual:ignifx/editor, startEditorHost or /__ignifx_editor__/, or when debugging why the editor cannot connect to a view or why the scene view disagrees with the editor's document.
3
+ description: Connects an ignifx project to the ignifx editor with @ignifx/editor-host: the Vite plugin that serves the editor's scene view from the project's own dev server, the virtual:ignifx/editor play controls a game's main.ts hands its app to (play, pause, step, stop, playState, playStateChanged, playStats, screenshot, queryRuntime, sendInput), and the host half of the editor protocol 0.3 over a MessagePort (hello/ready, heartbeat, and the scene document methods openScene, applyOps, readBack, select, pick, frame, setGizmo, setViewMode, screenshot, getSchemas, describeSettings, setAnimateMaterials, getColliderOutlines, sampleAnimation), including the 2D view mode. Use when wiring a project or template for the editor, when the user mentions @ignifx/editor-host, editorHostPlugin, attachEditorPlayControls, virtual:ignifx/editor, startEditorHost or /__ignifx_editor__/, or when debugging why the editor cannot connect to a view or why the scene view disagrees with the editor's document.
4
4
  license: Apache-2.0
5
5
  metadata:
6
- ignifx-version: "0.11.0"
6
+ ignifx-version: "0.13.0"
7
7
  ---
8
8
 
9
9
  # @ignifx/editor-host
@@ -25,7 +25,7 @@ editor's, even though its name starts with `editor-`.
25
25
 
26
26
  ## Environment
27
27
 
28
- - Engine: ignifx `0.11.0`; this package targets `@ignifx/core` `>=0.0.0 <1.0.0`.
28
+ - Engine: ignifx `0.13.0`; this package targets `@ignifx/core` `>=0.0.0 <1.0.0`.
29
29
  - Peers: `@ignifx/core` and `@babylonjs/lite` (the scene view's gizmos); for the `./vite` entry,
30
30
  `@ignifx/vite-plugin` and `vite`.
31
31
  - A development dependency of the project, at the same version as its `@ignifx/core`.
@@ -38,7 +38,7 @@ import { editorHostPlugin } from "@ignifx/editor-host/vite";
38
38
  import { defineConfig } from "vite";
39
39
 
40
40
  export default defineConfig({
41
- plugins: [ignifx(), editorHostPlugin({ editorOrigin: process.env.IGNIFX_EDITOR_ORIGIN ?? "ignifx://app" })],
41
+ plugins: [ignifx(), editorHostPlugin({ editorOrigin: process.env.IGNIFX_EDITOR_ORIGIN ?? "ignifx-editor://app" })],
42
42
  });
43
43
  ```
44
44
 
@@ -55,7 +55,7 @@ Add `/// <reference types="@ignifx/editor-host/client" />` beside `@ignifx/vite-
55
55
  ## Mental model
56
56
 
57
57
  ```
58
- editor window (ignifx://app)
58
+ editor window (ignifx-editor://app)
59
59
  ├── <iframe> scene view http://127.0.0.1:<port>/__ignifx_editor__/
60
60
  │ generated module → startEditorHost({ extensions(), scripts, settings, manifest })
61
61
  │ owns its app, in edit mode; hostKind "scene"
@@ -71,7 +71,8 @@ each view ◀── MessagePort ──▶ editor JSON-RPC 2.0, protocol 0.3
71
71
  / setAnimateMaterials / getColliderOutlines / sampleAnimation
72
72
  ← sceneOpened, selectionChanged, transformDragging/Dragged, hotReloaded, assetReloaded,
73
73
  hostError, log
74
- play view: play / pause / step / stop / playState / playStats
74
+ play view: play / pause / step / stop / playState / playStats / screenshot (with a canvas)
75
+ / queryRuntime / sendInput (with app.input)
75
76
  ← playStateChanged, log, hostError, hotReloaded (logRelay; kept from before hello)
76
77
  ```
77
78
 
@@ -86,7 +87,8 @@ carry `Content-Security-Policy: frame-ancestors <editorOrigin>`.
86
87
  The editor owns the scene document; the scene view mirrors it. `openScene` sends the whole file
87
88
  object (it may hold unsaved edits) and the host builds it with `world.loadSceneFile`, keeping the
88
89
  file's uids. Every command the editor applies to its document goes to the host as `applyOps`, the
89
- same ops; any failure means the mirror drifted, and the editor resends `openScene`. What the user
90
+ same ops; any failure means the mirror drifted, and the editor resends `openScene`. The answer's
91
+ `warnings` lists what building the command's entities reported, as `openScene`'s does. What the user
90
92
  does in the view comes back as notifications (`selectionChanged`, `transformDragged`) that the
91
93
  editor turns into commands. The host never edits the document. When a script's hot reload changes a
92
94
  field's default, the host gives the field its new default wherever the document leaves it out, and
@@ -102,14 +104,14 @@ A headless scene-view host and the editor's side of the handshake, in one Node p
102
104
  import { EDITOR_CONNECT_MESSAGE_TYPE, PROTOCOL_VERSION, startEditorHost } from "@ignifx/editor-host";
103
105
 
104
106
  const frameWindow = new EventTarget();
105
- const host = await startEditorHost({ editorOrigin: "ignifx://app", headless: true, messageTarget: frameWindow });
107
+ const host = await startEditorHost({ editorOrigin: "ignifx-editor://app", headless: true, messageTarget: frameWindow });
106
108
 
107
109
  // The editor's side: a fresh channel, with one end posted to the view's window.
108
110
  const channel = new MessageChannel();
109
111
  frameWindow.dispatchEvent(
110
112
  new MessageEvent("message", {
111
113
  data: { type: EDITOR_CONNECT_MESSAGE_TYPE },
112
- origin: "ignifx://app",
114
+ origin: "ignifx-editor://app",
113
115
  ports: [channel.port2],
114
116
  }),
115
117
  );
@@ -152,6 +154,7 @@ host.dispose();
152
154
  | `PlayStats`, `isPlayStats` | `playStats`'s `{ fps, frameTimeMs, entityCount, frameCount }`: the newest second of `app.diagnostics` frames, the world's entities |
153
155
  | `HostCapability.hotReloadDefaults` | The scene view gives fields the document leaves out their new default after a script's hot reload |
154
156
  | `HostCapability.logRelay`, `isAppErrorData`, `LoggedError` | Both views relay `log` (with the first `Error` a line carries), `hostError` (entity, component, phase, stack) and `hotReloaded` |
157
+ | `HOST_TEXT_MAX_LENGTH`, `HOST_LIST_MAX_LENGTH` | The editor's caps on a report's strings (1 MiB) and lists (4096); both views clip to them, a string ending `… [clipped]` |
155
158
  | `EditorHostErrorCode` | `IGX-1801` bad origin, `IGX-1802` no window, `IGX-1803` bad option |
156
159
 
157
160
  ## Recipes
@@ -188,13 +191,13 @@ import { EDITOR_CONNECT_MESSAGE_TYPE, PROTOCOL_VERSION, startEditorPlayControls
188
191
 
189
192
  const app = await createApp({ headless: true });
190
193
  const pageWindow = new EventTarget();
191
- const controls = startEditorPlayControls(app, { editorOrigin: "ignifx://app", messageTarget: pageWindow });
194
+ const controls = startEditorPlayControls(app, { editorOrigin: "ignifx-editor://app", messageTarget: pageWindow });
192
195
 
193
196
  const channel = new MessageChannel();
194
197
  pageWindow.dispatchEvent(
195
198
  new MessageEvent("message", {
196
199
  data: { type: EDITOR_CONNECT_MESSAGE_TYPE },
197
- origin: "ignifx://app",
200
+ origin: "ignifx-editor://app",
198
201
  ports: [channel.port2],
199
202
  }),
200
203
  );
@@ -232,12 +235,12 @@ app.dispose();
232
235
  import { EDITOR_CONNECT_MESSAGE_TYPE, PROTOCOL_VERSION, startEditorHost } from "@ignifx/editor-host";
233
236
 
234
237
  const frameWindow = new EventTarget();
235
- const host = await startEditorHost({ editorOrigin: "ignifx://app", headless: true, messageTarget: frameWindow });
238
+ const host = await startEditorHost({ editorOrigin: "ignifx-editor://app", headless: true, messageTarget: frameWindow });
236
239
  const channel = new MessageChannel();
237
240
  frameWindow.dispatchEvent(
238
241
  new MessageEvent("message", {
239
242
  data: { type: EDITOR_CONNECT_MESSAGE_TYPE },
240
- origin: "ignifx://app",
243
+ origin: "ignifx-editor://app",
241
244
  ports: [channel.port2],
242
245
  }),
243
246
  );
@@ -291,7 +294,7 @@ object `openScene` sends, through `world.loadSceneFile`; `readBack` answers with
291
294
  the build half is what turns it into an empty function. Without the plugin the import does not
292
295
  resolve.
293
296
  - **`editorOrigin` is exact.** It must equal `event.origin` as the browser reports it, with no path or
294
- trailing slash: `ignifx://app` for the packaged editor, `http://localhost:<port>` for the editor's
297
+ trailing slash: `ignifx-editor://app` for the packaged editor, `http://localhost:<port>` for the editor's
295
298
  own dev server. A mismatch is silent by design: the host just never connects.
296
299
  - **Every view reload needs a new port.** A transferred `MessagePort` cannot be posted twice; the
297
300
  editor makes a fresh `MessageChannel` on each `load`, and the host closes the previous port.
@@ -305,9 +308,42 @@ object `openScene` sends, through `world.loadSceneFile`; `readBack` answers with
305
308
  - **Script edits reload both views** while `main.ts` imports `src/scripts/**` statically: Vite's one
306
309
  module graph sends a full reload to every page when an update reaches a module that does not
307
310
  accept it.
311
+ - **An op's build problems come back with its command.** `applyOps` answers
312
+ `{ applied, failures, warnings }`. `warnings` holds `{ code, message }` issues, as `openScene`'s
313
+ does, for everything the subtrees its ops built or rebuilt reported: an override that names
314
+ nothing in the prefab, or a reference that resolves nowhere in the document. The op still
315
+ applies. Each issue is also a `log` warning for the Console. The answer is the record tied to the
316
+ command. A host from before this field sends no `warnings`.
317
+ - **A schema says what its class requires and what it extends.** A component's `getSchemas` entry
318
+ carries `requires` (the type ids `addComponent` adds when missing) and `extends` (the registered
319
+ classes its class derives from, nearest first; `[]` when none). The engine counts a component
320
+ whose class extends a required one as present, so a required id is present on an entity when a
321
+ component has that id or lists it in `extends`. A host from before `extends` sends no such member.
308
322
  - **Scene methods answer `notReady` until the app has started.** The host answers `hello` at once;
309
323
  its first `schemasChanged` is the cue that `openScene` and the rest are accepted. `applyOps`,
310
324
  `readBack` and `frame` answer `noScene` while no scene is open.
325
+ - **The play view's `screenshot` needs a running game.** It takes the scene view's parameters and
326
+ answers the same `{ dataUrl, width, height }` from the game's canvas, paused or not. While the
327
+ frame loop does not run (before Play, after `stop` or `step`) it answers `notPlaying`, and before
328
+ the first frame `notReady`. Only a game with a canvas lists `screenshot` in `ready`; an older or
329
+ headless play view answers `methodNotFound`.
330
+ - **The play view's `queryRuntime` reads one live entity.** `{ entity: uid, components?: typeId[] }`
331
+ answers the entity as `serializeEntity` writes it (serialized props only, no expressions), with at
332
+ most 64 components, prop strings clipped to 64 Ki, objects cut to 256 keys, keys and names
333
+ clipped to 256 characters (`omittedEntries` counts the keys, items and tags left out), and the
334
+ whole answer within 262,144 characters of JSON: components past the budget, in order, are counted
335
+ in `omittedComponents`. An
336
+ unknown uid answers `unknownEntity`; a stopped game `notPlaying`. A paused or stepped game
337
+ answers, so pause, `step`, `queryRuntime` reads a game frame by frame. Spawned entities get new
338
+ uids each run; a scene's own keep their file uids.
339
+ - **The play view's `sendInput` drives the game's own input.** `{ events }` (1 to 64) of
340
+ `{ type: "keydown" | "keyup", control: "w" }` (a `<Keyboard>` control name) and
341
+ `{ type: "pointermove" | "pointerdown" | "pointerup", x, y, button? }` (`x`, `y` as 0–1 fractions of
342
+ the canvas) go to `app.input.simulateEvent` and resolve on the game's next frame; nothing reaches
343
+ the DOM, the editor's window or the OS. A bad event or unknown key answers `invalidParams` and
344
+ queues nothing; a stopped game `notPlaying`. A stepped game resolves the events only on its next
345
+ `step`, so step after sending. A held key stays down until its `keyup`. Only a game
346
+ with `app.input` lists `sendInput`; others answer `methodNotFound`.
311
347
  - **The scene view keeps the project's `rendering.msaaSamples`.** The gizmos and the outline draw in
312
348
  core's render overlay (`app.renderer.openOverlay()`), which works at every MSAA setting.
313
349
  - **A headless host lists only `heartbeat`.** Without a canvas there are no gizmos, no `screenshot`,
@@ -348,9 +384,14 @@ object `openScene` sends, through `world.loadSceneFile`; `readBack` answers with
348
384
  asset the app has loaded, of type `scene` (a scene or prefab), `model`, `mesh`, `material`,
349
385
  `spriteatlas` or `shader`. A changed prefab rebuilds the document's instances of it, directly or
350
386
  through another prefab, with their uids, transforms, overrides and document children; `readBack`
351
- then writes the new prefab's hash. The host sends `assetReloaded { address, type, entities }`
352
- (the rebuilt instance roots) once the new value is in. A texture, a removed file and the open
353
- document's own file are left alone and send nothing.
387
+ then writes the new prefab's hash. An override the new prefab no longer has, like any problem
388
+ building an op's subtree, is a `log` warning worded as a reopen's (an op's problems also come back
389
+ in `applyOps`' `warnings`). A rebuilt subtree resolves its
390
+ references, the ones its overrides hold included, against the whole document, as a reopen does,
391
+ and so do the references into it from the rest of the document, other instances' overrides
392
+ included. The host sends `assetReloaded { address, type, entities }` (the rebuilt instance
393
+ roots) once the new value is in. A texture, a removed file and the open document's own file are
394
+ left alone and send nothing.
354
395
  - **Document uids only.** Members of an instanced prefab and the editor's own entities never appear
355
396
  in a selection, a pick or `readBack`; a pick on a prefab member resolves to its instance root.
356
397