@ignifx/editor-host 0.11.0 → 0.12.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.
@@ -3,7 +3,7 @@ name: editor-host
3
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.
4
4
  license: Apache-2.0
5
5
  metadata:
6
- ignifx-version: "0.11.0"
6
+ ignifx-version: "0.12.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.12.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"
@@ -86,7 +86,8 @@ carry `Content-Security-Policy: frame-ancestors <editorOrigin>`.
86
86
  The editor owns the scene document; the scene view mirrors it. `openScene` sends the whole file
87
87
  object (it may hold unsaved edits) and the host builds it with `world.loadSceneFile`, keeping the
88
88
  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
89
+ same ops; any failure means the mirror drifted, and the editor resends `openScene`. The answer's
90
+ `warnings` lists what building the command's entities reported, as `openScene`'s does. What the user
90
91
  does in the view comes back as notifications (`selectionChanged`, `transformDragged`) that the
91
92
  editor turns into commands. The host never edits the document. When a script's hot reload changes a
92
93
  field's default, the host gives the field its new default wherever the document leaves it out, and
@@ -102,14 +103,14 @@ A headless scene-view host and the editor's side of the handshake, in one Node p
102
103
  import { EDITOR_CONNECT_MESSAGE_TYPE, PROTOCOL_VERSION, startEditorHost } from "@ignifx/editor-host";
103
104
 
104
105
  const frameWindow = new EventTarget();
105
- const host = await startEditorHost({ editorOrigin: "ignifx://app", headless: true, messageTarget: frameWindow });
106
+ const host = await startEditorHost({ editorOrigin: "ignifx-editor://app", headless: true, messageTarget: frameWindow });
106
107
 
107
108
  // The editor's side: a fresh channel, with one end posted to the view's window.
108
109
  const channel = new MessageChannel();
109
110
  frameWindow.dispatchEvent(
110
111
  new MessageEvent("message", {
111
112
  data: { type: EDITOR_CONNECT_MESSAGE_TYPE },
112
- origin: "ignifx://app",
113
+ origin: "ignifx-editor://app",
113
114
  ports: [channel.port2],
114
115
  }),
115
116
  );
@@ -152,6 +153,7 @@ host.dispose();
152
153
  | `PlayStats`, `isPlayStats` | `playStats`'s `{ fps, frameTimeMs, entityCount, frameCount }`: the newest second of `app.diagnostics` frames, the world's entities |
153
154
  | `HostCapability.hotReloadDefaults` | The scene view gives fields the document leaves out their new default after a script's hot reload |
154
155
  | `HostCapability.logRelay`, `isAppErrorData`, `LoggedError` | Both views relay `log` (with the first `Error` a line carries), `hostError` (entity, component, phase, stack) and `hotReloaded` |
156
+ | `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
157
  | `EditorHostErrorCode` | `IGX-1801` bad origin, `IGX-1802` no window, `IGX-1803` bad option |
156
158
 
157
159
  ## Recipes
@@ -188,13 +190,13 @@ import { EDITOR_CONNECT_MESSAGE_TYPE, PROTOCOL_VERSION, startEditorPlayControls
188
190
 
189
191
  const app = await createApp({ headless: true });
190
192
  const pageWindow = new EventTarget();
191
- const controls = startEditorPlayControls(app, { editorOrigin: "ignifx://app", messageTarget: pageWindow });
193
+ const controls = startEditorPlayControls(app, { editorOrigin: "ignifx-editor://app", messageTarget: pageWindow });
192
194
 
193
195
  const channel = new MessageChannel();
194
196
  pageWindow.dispatchEvent(
195
197
  new MessageEvent("message", {
196
198
  data: { type: EDITOR_CONNECT_MESSAGE_TYPE },
197
- origin: "ignifx://app",
199
+ origin: "ignifx-editor://app",
198
200
  ports: [channel.port2],
199
201
  }),
200
202
  );
@@ -232,12 +234,12 @@ app.dispose();
232
234
  import { EDITOR_CONNECT_MESSAGE_TYPE, PROTOCOL_VERSION, startEditorHost } from "@ignifx/editor-host";
233
235
 
234
236
  const frameWindow = new EventTarget();
235
- const host = await startEditorHost({ editorOrigin: "ignifx://app", headless: true, messageTarget: frameWindow });
237
+ const host = await startEditorHost({ editorOrigin: "ignifx-editor://app", headless: true, messageTarget: frameWindow });
236
238
  const channel = new MessageChannel();
237
239
  frameWindow.dispatchEvent(
238
240
  new MessageEvent("message", {
239
241
  data: { type: EDITOR_CONNECT_MESSAGE_TYPE },
240
- origin: "ignifx://app",
242
+ origin: "ignifx-editor://app",
241
243
  ports: [channel.port2],
242
244
  }),
243
245
  );
@@ -291,7 +293,7 @@ object `openScene` sends, through `world.loadSceneFile`; `readBack` answers with
291
293
  the build half is what turns it into an empty function. Without the plugin the import does not
292
294
  resolve.
293
295
  - **`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
296
+ trailing slash: `ignifx-editor://app` for the packaged editor, `http://localhost:<port>` for the editor's
295
297
  own dev server. A mismatch is silent by design: the host just never connects.
296
298
  - **Every view reload needs a new port.** A transferred `MessagePort` cannot be posted twice; the
297
299
  editor makes a fresh `MessageChannel` on each `load`, and the host closes the previous port.
@@ -305,6 +307,17 @@ object `openScene` sends, through `world.loadSceneFile`; `readBack` answers with
305
307
  - **Script edits reload both views** while `main.ts` imports `src/scripts/**` statically: Vite's one
306
308
  module graph sends a full reload to every page when an update reaches a module that does not
307
309
  accept it.
310
+ - **An op's build problems come back with its command.** `applyOps` answers
311
+ `{ applied, failures, warnings }`. `warnings` holds `{ code, message }` issues, as `openScene`'s
312
+ does, for everything the subtrees its ops built or rebuilt reported: an override that names
313
+ nothing in the prefab, or a reference that resolves nowhere in the document. The op still
314
+ applies. Each issue is also a `log` warning for the Console. The answer is the record tied to the
315
+ command. A host from before this field sends no `warnings`.
316
+ - **A schema says what its class requires and what it extends.** A component's `getSchemas` entry
317
+ carries `requires` (the type ids `addComponent` adds when missing) and `extends` (the registered
318
+ classes its class derives from, nearest first; `[]` when none). The engine counts a component
319
+ whose class extends a required one as present, so a required id is present on an entity when a
320
+ component has that id or lists it in `extends`. A host from before `extends` sends no such member.
308
321
  - **Scene methods answer `notReady` until the app has started.** The host answers `hello` at once;
309
322
  its first `schemasChanged` is the cue that `openScene` and the rest are accepted. `applyOps`,
310
323
  `readBack` and `frame` answer `noScene` while no scene is open.
@@ -348,9 +361,14 @@ object `openScene` sends, through `world.loadSceneFile`; `readBack` answers with
348
361
  asset the app has loaded, of type `scene` (a scene or prefab), `model`, `mesh`, `material`,
349
362
  `spriteatlas` or `shader`. A changed prefab rebuilds the document's instances of it, directly or
350
363
  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.
364
+ then writes the new prefab's hash. An override the new prefab no longer has, like any problem
365
+ building an op's subtree, is a `log` warning worded as a reopen's (an op's problems also come back
366
+ in `applyOps`' `warnings`). A rebuilt subtree resolves its
367
+ references, the ones its overrides hold included, against the whole document, as a reopen does,
368
+ and so do the references into it from the rest of the document, other instances' overrides
369
+ included. The host sends `assetReloaded { address, type, entities }` (the rebuilt instance
370
+ roots) once the new value is in. A texture, a removed file and the open document's own file are
371
+ left alone and send nothing.
354
372
  - **Document uids only.** Members of an instanced prefab and the editor's own entities never appear
355
373
  in a selection, a pick or `readBack`; a pick on a prefab member resolves to its instance root.
356
374