@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.
- 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 +559 -240
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2207 -938
- 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 +58 -17
|
@@ -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
|
|
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.
|
|
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.
|
|
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`.
|
|
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.
|
|
352
|
-
|
|
353
|
-
|
|
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
|
|