@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.
- package/dist/error-codes.d.ts +3 -3
- package/dist/error-codes.js +3 -3
- package/dist/error-codes.js.map +1 -1
- package/dist/index.d.ts +62 -10
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1317 -675
- package/dist/index.js.map +1 -1
- package/dist/vite.d.ts +6 -4
- package/dist/vite.d.ts.map +1 -1
- package/dist/vite.js +86 -15
- package/dist/vite.js.map +1 -1
- package/package.json +10 -8
- package/skills/editor-host/SKILL.md +33 -15
|
@@ -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.
|
|
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.
|
|
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`.
|
|
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.
|
|
352
|
-
|
|
353
|
-
|
|
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
|
|