@ignifx/editor-host 0.10.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.
@@ -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), 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), 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.10.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.10.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"
@@ -68,6 +68,7 @@ each view ◀── MessagePort ──▶ editor JSON-RPC 2.0, protocol 0.3
68
68
  connect (window message, origin-checked) → hello → ready → ping/pong, heartbeat
69
69
  scene view: schemasChanged → openScene → applyOps… / readBack / select / pick / frame / setGizmo / screenshot
70
70
  / setViewMode / getSchemas / describeSettings (on request only)
71
+ / setAnimateMaterials / getColliderOutlines / sampleAnimation
71
72
  ← sceneOpened, selectionChanged, transformDragging/Dragged, hotReloaded, assetReloaded,
72
73
  hostError, log
73
74
  play view: play / pause / step / stop / playState / playStats
@@ -85,7 +86,8 @@ carry `Content-Security-Policy: frame-ancestors <editorOrigin>`.
85
86
  The editor owns the scene document; the scene view mirrors it. `openScene` sends the whole file
86
87
  object (it may hold unsaved edits) and the host builds it with `world.loadSceneFile`, keeping the
87
88
  file's uids. Every command the editor applies to its document goes to the host as `applyOps`, the
88
- 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
89
91
  does in the view comes back as notifications (`selectionChanged`, `transformDragged`) that the
90
92
  editor turns into commands. The host never edits the document. When a script's hot reload changes a
91
93
  field's default, the host gives the field its new default wherever the document leaves it out, and
@@ -101,14 +103,14 @@ A headless scene-view host and the editor's side of the handshake, in one Node p
101
103
  import { EDITOR_CONNECT_MESSAGE_TYPE, PROTOCOL_VERSION, startEditorHost } from "@ignifx/editor-host";
102
104
 
103
105
  const frameWindow = new EventTarget();
104
- const host = await startEditorHost({ editorOrigin: "ignifx://app", headless: true, messageTarget: frameWindow });
106
+ const host = await startEditorHost({ editorOrigin: "ignifx-editor://app", headless: true, messageTarget: frameWindow });
105
107
 
106
108
  // The editor's side: a fresh channel, with one end posted to the view's window.
107
109
  const channel = new MessageChannel();
108
110
  frameWindow.dispatchEvent(
109
111
  new MessageEvent("message", {
110
112
  data: { type: EDITOR_CONNECT_MESSAGE_TYPE },
111
- origin: "ignifx://app",
113
+ origin: "ignifx-editor://app",
112
114
  ports: [channel.port2],
113
115
  }),
114
116
  );
@@ -151,6 +153,7 @@ host.dispose();
151
153
  | `PlayStats`, `isPlayStats` | `playStats`'s `{ fps, frameTimeMs, entityCount, frameCount }`: the newest second of `app.diagnostics` frames, the world's entities |
152
154
  | `HostCapability.hotReloadDefaults` | The scene view gives fields the document leaves out their new default after a script's hot reload |
153
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]` |
154
157
  | `EditorHostErrorCode` | `IGX-1801` bad origin, `IGX-1802` no window, `IGX-1803` bad option |
155
158
 
156
159
  ## Recipes
@@ -187,13 +190,13 @@ import { EDITOR_CONNECT_MESSAGE_TYPE, PROTOCOL_VERSION, startEditorPlayControls
187
190
 
188
191
  const app = await createApp({ headless: true });
189
192
  const pageWindow = new EventTarget();
190
- const controls = startEditorPlayControls(app, { editorOrigin: "ignifx://app", messageTarget: pageWindow });
193
+ const controls = startEditorPlayControls(app, { editorOrigin: "ignifx-editor://app", messageTarget: pageWindow });
191
194
 
192
195
  const channel = new MessageChannel();
193
196
  pageWindow.dispatchEvent(
194
197
  new MessageEvent("message", {
195
198
  data: { type: EDITOR_CONNECT_MESSAGE_TYPE },
196
- origin: "ignifx://app",
199
+ origin: "ignifx-editor://app",
197
200
  ports: [channel.port2],
198
201
  }),
199
202
  );
@@ -231,12 +234,12 @@ app.dispose();
231
234
  import { EDITOR_CONNECT_MESSAGE_TYPE, PROTOCOL_VERSION, startEditorHost } from "@ignifx/editor-host";
232
235
 
233
236
  const frameWindow = new EventTarget();
234
- const host = await startEditorHost({ editorOrigin: "ignifx://app", headless: true, messageTarget: frameWindow });
237
+ const host = await startEditorHost({ editorOrigin: "ignifx-editor://app", headless: true, messageTarget: frameWindow });
235
238
  const channel = new MessageChannel();
236
239
  frameWindow.dispatchEvent(
237
240
  new MessageEvent("message", {
238
241
  data: { type: EDITOR_CONNECT_MESSAGE_TYPE },
239
- origin: "ignifx://app",
242
+ origin: "ignifx-editor://app",
240
243
  ports: [channel.port2],
241
244
  }),
242
245
  );
@@ -290,7 +293,7 @@ object `openScene` sends, through `world.loadSceneFile`; `readBack` answers with
290
293
  the build half is what turns it into an empty function. Without the plugin the import does not
291
294
  resolve.
292
295
  - **`editorOrigin` is exact.** It must equal `event.origin` as the browser reports it, with no path or
293
- 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
294
297
  own dev server. A mismatch is silent by design: the host just never connects.
295
298
  - **Every view reload needs a new port.** A transferred `MessagePort` cannot be posted twice; the
296
299
  editor makes a fresh `MessageChannel` on each `load`, and the host closes the previous port.
@@ -304,6 +307,17 @@ object `openScene` sends, through `world.loadSceneFile`; `readBack` answers with
304
307
  - **Script edits reload both views** while `main.ts` imports `src/scripts/**` statically: Vite's one
305
308
  module graph sends a full reload to every page when an update reaches a module that does not
306
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.
307
321
  - **Scene methods answer `notReady` until the app has started.** The host answers `hello` at once;
308
322
  its first `schemasChanged` is the cue that `openScene` and the rest are accepted. `applyOps`,
309
323
  `readBack` and `frame` answer `noScene` while no scene is open.
@@ -324,18 +338,37 @@ object `openScene` sends, through `world.loadSceneFile`; `readBack` answers with
324
338
  tilemaps, and `pick` and clicks use `app.twoD.pickAt` (unpickable sprites included): a hit's
325
339
  `point` is on `z = 0` and its `distance` is `null`. The host finds `app.twoD` and the 2D classes
326
340
  by name, so a project without `@ignifx/2d` still gets an orthographic 2D view of its meshes.
341
+ - **A pose on demand.** `sampleAnimation { entity, state, normalizedTime, parameters? }` calls
342
+ `Animator.sample` on the entity's `Animator` and answers `{ posed }`; the edit-mode view keeps
343
+ the pose until the next sample. `posed` is `false` while the clips load, when the model lacks a clip the state names, and
344
+ always headless. Names are capped at 256 characters and `parameters` at 64 values. An
345
+ entity without an `Animator`, or an engine refusal such as an unknown state (`data.code`
346
+ `IGX-1202`), is `invalidParams`. The host finds `ignifx/Animator` by type id, so a project
347
+ without `@ignifx/3d` simply has none.
327
348
  - **Settings over the protocol.** `describeSettings` answers `{ sections, values }`: core's
328
349
  `describeSettings(app)` with each section's `settingsJsonSchema` entry as `propsSchema`, and the
329
350
  values the app resolved, in the settings form (`{ x, y, z }`, `{ r, g, b, a }`). No notification
330
351
  announces settings; ask again after the project's settings change.
352
+ - **Materials and collider gizmos.** `setAnimateMaterials { enabled }` sets
353
+ `app.renderer.animateMaterialsInEditMode` (on at every start, so re-send it after `ready`).
354
+ `getColliderOutlines { entities }` answers `{ outlines }`: per enabled collider of each open
355
+ entity, its uid, the component's uid, `isTrigger`, and world-space `lines` (six numbers a
356
+ segment), read from `app.physics` / `app.physics2d` by shape, plus `truncated` when the request
357
+ passed 256 entities or the lines 600 000 numbers. Edit mode keeps physics bodies on the
358
+ transforms the editor moves without stepping, so the outlines and physics queries follow.
331
359
  - **A changed asset reloads in place, not the view.** The scene view's page hands every
332
360
  `ignifx:asset-changed` event to `host.assetChanged`, which calls `app.assets.reload(address)` for an
333
361
  asset the app has loaded, of type `scene` (a scene or prefab), `model`, `mesh`, `material`,
334
362
  `spriteatlas` or `shader`. A changed prefab rebuilds the document's instances of it, directly or
335
363
  through another prefab, with their uids, transforms, overrides and document children; `readBack`
336
- then writes the new prefab's hash. The host sends `assetReloaded { address, type, entities }`
337
- (the rebuilt instance roots) once the new value is in. A texture, a removed file and the open
338
- 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.
339
372
  - **Document uids only.** Members of an instanced prefab and the editor's own entities never appear
340
373
  in a selection, a pick or `readBack`; a pick on a prefab member resolves to its instance root.
341
374