@ignifx/editor-host 0.9.0 → 0.10.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 +44 -0
- package/dist/error-codes.d.ts.map +1 -0
- package/dist/error-codes.js +46 -0
- package/dist/error-codes.js.map +1 -0
- package/dist/index.d.ts +2628 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +6236 -0
- package/dist/index.js.map +1 -0
- package/dist/vite.d.ts +245 -0
- package/dist/vite.d.ts.map +1 -0
- package/dist/vite.js +432 -0
- package/dist/vite.js.map +1 -0
- package/package.json +8 -5
- package/skills/editor-host/SKILL.md +142 -21
package/dist/vite.d.ts
ADDED
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
import { n as isEditorOrigin, t as EditorHostErrorCode } from "./error-codes.js";
|
|
2
|
+
import { Plugin } from "vite";
|
|
3
|
+
//#region src/vite/errors.d.ts
|
|
4
|
+
/**
|
|
5
|
+
* The error every `@ignifx/editor-host/vite` API throws for a misconfiguration
|
|
6
|
+
* (`CONSTITUTION.md` §3.9).
|
|
7
|
+
*
|
|
8
|
+
* @beta
|
|
9
|
+
*/
|
|
10
|
+
export declare class EditorHostPluginError extends Error {
|
|
11
|
+
/** The stable diagnostic code for this failure. */
|
|
12
|
+
readonly code: EditorHostErrorCode;
|
|
13
|
+
/**
|
|
14
|
+
* Creates a plugin error.
|
|
15
|
+
*
|
|
16
|
+
* @param code - The stable `IGX-####` code for the failure.
|
|
17
|
+
* @param message - An actionable description of what went wrong and how to fix it.
|
|
18
|
+
*/
|
|
19
|
+
constructor(code: EditorHostErrorCode, message: string);
|
|
20
|
+
}
|
|
21
|
+
//#endregion
|
|
22
|
+
//#region src/vite/modules.d.ts
|
|
23
|
+
/**
|
|
24
|
+
* The path the scene view is served at, below the dev server's `base`.
|
|
25
|
+
*
|
|
26
|
+
* @beta
|
|
27
|
+
*/
|
|
28
|
+
export declare const EDITOR_PAGE_PATH = "/__ignifx_editor__/";
|
|
29
|
+
/**
|
|
30
|
+
* The module a game imports to hand its app to the editor's play controls.
|
|
31
|
+
*
|
|
32
|
+
* @example
|
|
33
|
+
* ```ts
|
|
34
|
+
* import { attachEditorPlayControls } from "virtual:ignifx/editor";
|
|
35
|
+
*
|
|
36
|
+
* attachEditorPlayControls(app);
|
|
37
|
+
* ```
|
|
38
|
+
*
|
|
39
|
+
* @beta
|
|
40
|
+
*/
|
|
41
|
+
export declare const EDITOR_MODULE_ID = "virtual:ignifx/editor";
|
|
42
|
+
/**
|
|
43
|
+
* The resolved id of {@link EDITOR_MODULE_ID}. The `\0` prefix marks it as owned by a plugin.
|
|
44
|
+
*
|
|
45
|
+
* @beta
|
|
46
|
+
*/
|
|
47
|
+
export declare const RESOLVED_EDITOR_MODULE_ID: string;
|
|
48
|
+
/**
|
|
49
|
+
* The module the scene view's page runs. Only the generated page imports it.
|
|
50
|
+
*
|
|
51
|
+
* @beta
|
|
52
|
+
*/
|
|
53
|
+
export declare const EDITOR_ENTRY_MODULE_ID = "virtual:ignifx/editor-host-entry";
|
|
54
|
+
/**
|
|
55
|
+
* The resolved id of {@link EDITOR_ENTRY_MODULE_ID}.
|
|
56
|
+
*
|
|
57
|
+
* @beta
|
|
58
|
+
*/
|
|
59
|
+
export declare const RESOLVED_EDITOR_ENTRY_MODULE_ID: string;
|
|
60
|
+
/**
|
|
61
|
+
* The function `virtual:ignifx/editor` exports. It takes the game's app and returns a function that
|
|
62
|
+
* detaches the controls; in a production build it does nothing.
|
|
63
|
+
*
|
|
64
|
+
* @beta
|
|
65
|
+
*/
|
|
66
|
+
export declare const EDITOR_PLAY_CONTROLS_EXPORT = "attachEditorPlayControls";
|
|
67
|
+
/**
|
|
68
|
+
* The module the scene view imports the project's extensions from, unless the plugin is told
|
|
69
|
+
* otherwise. It exports `extensions()`, which returns the list `main.ts` passes to `createApp`.
|
|
70
|
+
*
|
|
71
|
+
* @beta
|
|
72
|
+
*/
|
|
73
|
+
export declare const DEFAULT_EXTENSIONS_MODULE = "/src/extensions.ts";
|
|
74
|
+
/**
|
|
75
|
+
* The `id` of the scene view's canvas.
|
|
76
|
+
*
|
|
77
|
+
* @beta
|
|
78
|
+
*/
|
|
79
|
+
export declare const EDITOR_CANVAS_ID = "ignifx-editor-view";
|
|
80
|
+
/**
|
|
81
|
+
* Options accepted by {@link editorEntryModuleSource}.
|
|
82
|
+
*
|
|
83
|
+
* @beta
|
|
84
|
+
*/
|
|
85
|
+
interface EditorEntryModuleOptions {
|
|
86
|
+
/** The origin the editor is served from. */
|
|
87
|
+
readonly editorOrigin: string;
|
|
88
|
+
/** The root-absolute path of the project's extensions module, or `null` when it has none. */
|
|
89
|
+
readonly extensionsModule: string | null;
|
|
90
|
+
/** A scene address to load before the app starts, or `null`. */
|
|
91
|
+
readonly bootScene: string | null;
|
|
92
|
+
/** The project's `@ignifx/core` version, or `null` when it could not be read. */
|
|
93
|
+
readonly engineVersion: string | null;
|
|
94
|
+
/** Milliseconds between heartbeats, or `null` for the host's default. */
|
|
95
|
+
readonly heartbeatIntervalMs: number | null;
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* Options accepted by {@link playControlsModuleSource}.
|
|
99
|
+
*
|
|
100
|
+
* @beta
|
|
101
|
+
*/
|
|
102
|
+
interface PlayControlsModuleOptions {
|
|
103
|
+
/** The origin the editor is served from. */
|
|
104
|
+
readonly editorOrigin: string;
|
|
105
|
+
/** The project's `@ignifx/core` version, or `null` when it could not be read. */
|
|
106
|
+
readonly engineVersion: string | null;
|
|
107
|
+
/** Milliseconds between heartbeats, or `null` for the host's default. */
|
|
108
|
+
readonly heartbeatIntervalMs: number | null;
|
|
109
|
+
/**
|
|
110
|
+
* Emit the development module. `false` emits the production no-op, which imports nothing and has
|
|
111
|
+
* no `import.meta.hot` reference.
|
|
112
|
+
*/
|
|
113
|
+
readonly hot: boolean;
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Turns the `extensions` option into the root-absolute path the generated module imports.
|
|
117
|
+
*
|
|
118
|
+
* @param path - The path as configured, relative to the Vite root or already root-absolute.
|
|
119
|
+
* @returns The root-absolute path, for example `"/src/extensions.ts"`.
|
|
120
|
+
* @throws EditorHostPluginError `IGX-1803` when the path is empty or leaves the root with `..`.
|
|
121
|
+
*
|
|
122
|
+
* @beta
|
|
123
|
+
*/
|
|
124
|
+
export declare function normalizeExtensionsModule(path: string): string;
|
|
125
|
+
/**
|
|
126
|
+
* Generates the module the scene view's page runs.
|
|
127
|
+
*
|
|
128
|
+
* @remarks
|
|
129
|
+
* The module is the only code with an import-time effect: it creates the host. The package itself
|
|
130
|
+
* creates nothing when imported (`CONSTITUTION.md` §3.5). Every import is resolved from the
|
|
131
|
+
* project's root, so the host, the scripts, and the extensions share the project's one copy of
|
|
132
|
+
* `@ignifx/core`. It hands every `ignifx:asset-changed` event to `host.assetChanged`, which
|
|
133
|
+
* reloads the asset in place; the `import.meta.hot` calls are written out literally, because Vite
|
|
134
|
+
* finds them by reading the source.
|
|
135
|
+
*
|
|
136
|
+
* @param options - The editor origin, the project's extensions module, and the reporting options.
|
|
137
|
+
* @returns The ES module source.
|
|
138
|
+
*
|
|
139
|
+
* @beta
|
|
140
|
+
*/
|
|
141
|
+
export declare function editorEntryModuleSource(options: EditorEntryModuleOptions): string;
|
|
142
|
+
/**
|
|
143
|
+
* Generates the scene view's HTML page, before Vite's own `transformIndexHtml` adds its client.
|
|
144
|
+
*
|
|
145
|
+
* @returns The HTML document.
|
|
146
|
+
*
|
|
147
|
+
* @beta
|
|
148
|
+
*/
|
|
149
|
+
export declare function editorPageHtml(): string;
|
|
150
|
+
/**
|
|
151
|
+
* Generates `virtual:ignifx/editor`.
|
|
152
|
+
*
|
|
153
|
+
* @remarks
|
|
154
|
+
* In development, the module listens for the editor's connect message as soon as it is evaluated,
|
|
155
|
+
* which is before the game's `main.ts` runs, and keeps the port
|
|
156
|
+
* (`listenForEditorPlayControls`); `attachEditorPlayControls(app)` then starts the play controls on
|
|
157
|
+
* it, so the editor's first connect message is never lost to `await createApp(...)`. Vite replacing
|
|
158
|
+
* the module stops both. The `import.meta.hot` calls are written out literally because Vite
|
|
159
|
+
* finds them by reading the source, not by running it. In a production build the export is an empty
|
|
160
|
+
* function, the same shape as `acceptHotReload` from `virtual:ignifx/scripts`, so the game's
|
|
161
|
+
* `main.ts` builds either way and ships no editor code.
|
|
162
|
+
*
|
|
163
|
+
* @param options - The editor origin, the reporting options, and whether to emit the development module.
|
|
164
|
+
* @returns The ES module source.
|
|
165
|
+
*
|
|
166
|
+
* @beta
|
|
167
|
+
*/
|
|
168
|
+
export declare function playControlsModuleSource(options: PlayControlsModuleOptions): string;
|
|
169
|
+
//#endregion
|
|
170
|
+
//#region src/vite/plugin.d.ts
|
|
171
|
+
/**
|
|
172
|
+
* Options accepted by {@link editorHostPlugin}.
|
|
173
|
+
*
|
|
174
|
+
* @beta
|
|
175
|
+
*/
|
|
176
|
+
interface EditorHostPluginOptions {
|
|
177
|
+
/**
|
|
178
|
+
* The origin the editor is served from, for example `"ignifx://app"` when packaged or
|
|
179
|
+
* `"http://localhost:5173"` while the editor itself runs from a dev server. Only this origin may
|
|
180
|
+
* frame either view in `vite dev`, and only it can hand either view a port.
|
|
181
|
+
*/
|
|
182
|
+
readonly editorOrigin: string;
|
|
183
|
+
/**
|
|
184
|
+
* The project's extensions module, relative to the Vite root. It exports `extensions()`, which
|
|
185
|
+
* returns the list `main.ts` passes to `createApp`. When the file does not exist the scene view
|
|
186
|
+
* runs with no extensions. Defaults to `"/src/extensions.ts"`.
|
|
187
|
+
*/
|
|
188
|
+
readonly extensions?: string;
|
|
189
|
+
/** A scene address the scene view loads before it starts. Defaults to none. */
|
|
190
|
+
readonly bootScene?: string | null;
|
|
191
|
+
/** Milliseconds between heartbeats in both views. Defaults to the host's `1000`. */
|
|
192
|
+
readonly heartbeatIntervalMs?: number;
|
|
193
|
+
}
|
|
194
|
+
/**
|
|
195
|
+
* Reads the version of the project's own `@ignifx/core`.
|
|
196
|
+
*
|
|
197
|
+
* @param root - The Vite root.
|
|
198
|
+
* @returns The version, or `null` when the project does not resolve `@ignifx/core`.
|
|
199
|
+
*
|
|
200
|
+
* @beta
|
|
201
|
+
*/
|
|
202
|
+
export declare function readProjectEngineVersion(root: string): string | null;
|
|
203
|
+
/**
|
|
204
|
+
* The editor host's Vite plugin.
|
|
205
|
+
*
|
|
206
|
+
* @remarks
|
|
207
|
+
* It is two plugins, because the two halves run under different commands:
|
|
208
|
+
*
|
|
209
|
+
* - `ignifx-editor-host` (`vite dev` only) serves the scene view at `/__ignifx_editor__/` with
|
|
210
|
+
* `Content-Security-Policy: frame-ancestors <editorOrigin>`, and adds the same header to every
|
|
211
|
+
* page a browser navigates to, so the game's own `index.html` (the play view) can be framed by the
|
|
212
|
+
* editor and by nothing else. A `Content-Security-Policy` in `server.headers` replaces it. The page's module imports the host,
|
|
213
|
+
* `virtual:ignifx/scripts`, `virtual:ignifx/manifest` and the project's extensions module from
|
|
214
|
+
* the project's own graph, and calls `startEditorHost`. It adds the extensions module to
|
|
215
|
+
* `optimizeDeps.entries` (keeping Vite's default crawl) and keeps `@ignifx/editor-host` out of
|
|
216
|
+
* pre-bundling, so the host reaches the same pre-bundled `@ignifx/core` as the game.
|
|
217
|
+
* - `ignifx-editor-host:play-controls` (every command) serves `virtual:ignifx/editor`: the play
|
|
218
|
+
* controls under `vite dev`, an empty function under `vite build`.
|
|
219
|
+
*
|
|
220
|
+
* List it after `ignifx()` from `@ignifx/vite-plugin`, which serves the two modules the scene
|
|
221
|
+
* view imports.
|
|
222
|
+
*
|
|
223
|
+
* @param options - The editor's origin and the scene view's options.
|
|
224
|
+
* @returns The plugins, to be listed in `vite.config.ts`.
|
|
225
|
+
* @throws EditorHostPluginError `IGX-1801` for a malformed `editorOrigin`, `IGX-1803` for a bad
|
|
226
|
+
* `extensions` path or `heartbeatIntervalMs`.
|
|
227
|
+
*
|
|
228
|
+
* @example
|
|
229
|
+
* ```ts
|
|
230
|
+
* // vite.config.ts
|
|
231
|
+
* import { ignifx } from "@ignifx/vite-plugin";
|
|
232
|
+
* import { editorHostPlugin } from "@ignifx/editor-host/vite";
|
|
233
|
+
* import { defineConfig } from "vite";
|
|
234
|
+
*
|
|
235
|
+
* export default defineConfig({
|
|
236
|
+
* plugins: [ignifx(), editorHostPlugin({ editorOrigin: "ignifx://app" })],
|
|
237
|
+
* });
|
|
238
|
+
* ```
|
|
239
|
+
*
|
|
240
|
+
* @beta
|
|
241
|
+
*/
|
|
242
|
+
export declare function editorHostPlugin(options: EditorHostPluginOptions): Plugin[];
|
|
243
|
+
//#endregion
|
|
244
|
+
export { type EditorEntryModuleOptions, EditorHostErrorCode, type EditorHostPluginOptions, type PlayControlsModuleOptions, isEditorOrigin };
|
|
245
|
+
//# sourceMappingURL=vite.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"vite.d.ts","names":[],"sources":["../src/vite/errors.ts","../src/vite/modules.ts","../src/vite/plugin.ts"],"mappings":";;;;;;;;;qBAiBa,8BAA8B;;WAEhC,MAAM;;;;;;;EAQf,YAAY,MAAM,qBAAqB;;;;;;;;;qBCR5B;;;;;;;;;;;;;qBAcA;;;;;;qBAOA;;;;;;qBAOA;;;;;;qBAOA;;;;;;;qBAQA;;;;;;;qBAQA;;;;;;qBAOA;;;;;;UAUI;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;;;;;;UAQM;;WAEN;;WAEA;;WAEA;;;;;WAKA;;;;;;;;;;;wBAYK,0BAA0B;;;;;;;;;;;;;;;;;wBAyC1B,wBAAwB,SAAS;;;;;;;;wBAoCjC;;;;;;;;;;;;;;;;;;;wBAwCA,yBAAyB,SAAS;;;;;;;;UCxNjC;;;;;;WAMN;;;;;;WAMA;;WAEA;;WAEA;;;;;;;;;;wBAkBK,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAgFzB,iBAAiB,SAAS,0BAA0B"}
|
package/dist/vite.js
ADDED
|
@@ -0,0 +1,432 @@
|
|
|
1
|
+
import { n as isEditorOrigin, t as EditorHostErrorCode } from "./error-codes.js";
|
|
2
|
+
import { ASSET_CHANGED_EVENT, IGNIFX_CONFIG_DEFINE_KEY, MANIFEST_MODULE_ID, SCRIPTS_MODULE_ID } from "@ignifx/vite-plugin";
|
|
3
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
4
|
+
import { createRequire } from "node:module";
|
|
5
|
+
import { join, resolve } from "node:path";
|
|
6
|
+
//#region src/vite/errors.ts
|
|
7
|
+
/**
|
|
8
|
+
* The error every `@ignifx/editor-host/vite` API throws for a misconfiguration
|
|
9
|
+
* (`CONSTITUTION.md` §3.9).
|
|
10
|
+
*
|
|
11
|
+
* @beta
|
|
12
|
+
*/
|
|
13
|
+
var EditorHostPluginError = class extends Error {
|
|
14
|
+
/** The stable diagnostic code for this failure. */
|
|
15
|
+
code;
|
|
16
|
+
/**
|
|
17
|
+
* Creates a plugin error.
|
|
18
|
+
*
|
|
19
|
+
* @param code - The stable `IGX-####` code for the failure.
|
|
20
|
+
* @param message - An actionable description of what went wrong and how to fix it.
|
|
21
|
+
*/
|
|
22
|
+
constructor(code, message) {
|
|
23
|
+
super(message);
|
|
24
|
+
this.name = "EditorHostPluginError";
|
|
25
|
+
this.code = code;
|
|
26
|
+
}
|
|
27
|
+
};
|
|
28
|
+
//#endregion
|
|
29
|
+
//#region src/vite/modules.ts
|
|
30
|
+
/**
|
|
31
|
+
* The page and the two modules the plugin generates: the scene view's HTML entry, the module that
|
|
32
|
+
* page runs, and `virtual:ignifx/editor`, the play view's controls.
|
|
33
|
+
*/
|
|
34
|
+
/**
|
|
35
|
+
* The path the scene view is served at, below the dev server's `base`.
|
|
36
|
+
*
|
|
37
|
+
* @beta
|
|
38
|
+
*/
|
|
39
|
+
const EDITOR_PAGE_PATH = "/__ignifx_editor__/";
|
|
40
|
+
/**
|
|
41
|
+
* The module a game imports to hand its app to the editor's play controls.
|
|
42
|
+
*
|
|
43
|
+
* @example
|
|
44
|
+
* ```ts
|
|
45
|
+
* import { attachEditorPlayControls } from "virtual:ignifx/editor";
|
|
46
|
+
*
|
|
47
|
+
* attachEditorPlayControls(app);
|
|
48
|
+
* ```
|
|
49
|
+
*
|
|
50
|
+
* @beta
|
|
51
|
+
*/
|
|
52
|
+
const EDITOR_MODULE_ID = "virtual:ignifx/editor";
|
|
53
|
+
/**
|
|
54
|
+
* The resolved id of {@link EDITOR_MODULE_ID}. The `\0` prefix marks it as owned by a plugin.
|
|
55
|
+
*
|
|
56
|
+
* @beta
|
|
57
|
+
*/
|
|
58
|
+
const RESOLVED_EDITOR_MODULE_ID = `\0${EDITOR_MODULE_ID}`;
|
|
59
|
+
/**
|
|
60
|
+
* The module the scene view's page runs. Only the generated page imports it.
|
|
61
|
+
*
|
|
62
|
+
* @beta
|
|
63
|
+
*/
|
|
64
|
+
const EDITOR_ENTRY_MODULE_ID = "virtual:ignifx/editor-host-entry";
|
|
65
|
+
/**
|
|
66
|
+
* The resolved id of {@link EDITOR_ENTRY_MODULE_ID}.
|
|
67
|
+
*
|
|
68
|
+
* @beta
|
|
69
|
+
*/
|
|
70
|
+
const RESOLVED_EDITOR_ENTRY_MODULE_ID = `\0${EDITOR_ENTRY_MODULE_ID}`;
|
|
71
|
+
/**
|
|
72
|
+
* The function `virtual:ignifx/editor` exports. It takes the game's app and returns a function that
|
|
73
|
+
* detaches the controls; in a production build it does nothing.
|
|
74
|
+
*
|
|
75
|
+
* @beta
|
|
76
|
+
*/
|
|
77
|
+
const EDITOR_PLAY_CONTROLS_EXPORT = "attachEditorPlayControls";
|
|
78
|
+
/**
|
|
79
|
+
* The module the scene view imports the project's extensions from, unless the plugin is told
|
|
80
|
+
* otherwise. It exports `extensions()`, which returns the list `main.ts` passes to `createApp`.
|
|
81
|
+
*
|
|
82
|
+
* @beta
|
|
83
|
+
*/
|
|
84
|
+
const DEFAULT_EXTENSIONS_MODULE = "/src/extensions.ts";
|
|
85
|
+
/**
|
|
86
|
+
* The `id` of the scene view's canvas.
|
|
87
|
+
*
|
|
88
|
+
* @beta
|
|
89
|
+
*/
|
|
90
|
+
const EDITOR_CANVAS_ID = "ignifx-editor-view";
|
|
91
|
+
/** The package the generated modules import the host from, resolved from the project's root. */
|
|
92
|
+
const HOST_PACKAGE = "@ignifx/editor-host";
|
|
93
|
+
/**
|
|
94
|
+
* Turns the `extensions` option into the root-absolute path the generated module imports.
|
|
95
|
+
*
|
|
96
|
+
* @param path - The path as configured, relative to the Vite root or already root-absolute.
|
|
97
|
+
* @returns The root-absolute path, for example `"/src/extensions.ts"`.
|
|
98
|
+
* @throws EditorHostPluginError `IGX-1803` when the path is empty or leaves the root with `..`.
|
|
99
|
+
*
|
|
100
|
+
* @beta
|
|
101
|
+
*/
|
|
102
|
+
function normalizeExtensionsModule(path) {
|
|
103
|
+
const trimmed = path.startsWith("./") ? path.slice(2) : path;
|
|
104
|
+
if (trimmed === "" || trimmed === "/" || trimmed.split("/").some((segment) => segment === "..")) throw new EditorHostPluginError(EditorHostErrorCode.invalidOption, `The "extensions" option must name a module inside the Vite root, for example "src/extensions.ts"; got "${path}".`);
|
|
105
|
+
return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* The fields shared by both generated calls, as source text.
|
|
109
|
+
*
|
|
110
|
+
* @param engineVersion - The version to report, or `null`.
|
|
111
|
+
* @param heartbeatIntervalMs - The heartbeat period, or `null`.
|
|
112
|
+
* @returns Zero, one, or two `key: value,` lines.
|
|
113
|
+
*/
|
|
114
|
+
function reportingLines(engineVersion, heartbeatIntervalMs) {
|
|
115
|
+
return [...engineVersion === null ? [] : [` engineVersion: ${JSON.stringify(engineVersion)},`], ...heartbeatIntervalMs === null ? [] : [` heartbeatIntervalMs: ${JSON.stringify(heartbeatIntervalMs)},`]];
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* Generates the module the scene view's page runs.
|
|
119
|
+
*
|
|
120
|
+
* @remarks
|
|
121
|
+
* The module is the only code with an import-time effect: it creates the host. The package itself
|
|
122
|
+
* creates nothing when imported (`CONSTITUTION.md` §3.5). Every import is resolved from the
|
|
123
|
+
* project's root, so the host, the scripts, and the extensions share the project's one copy of
|
|
124
|
+
* `@ignifx/core`. It hands every `ignifx:asset-changed` event to `host.assetChanged`, which
|
|
125
|
+
* reloads the asset in place; the `import.meta.hot` calls are written out literally, because Vite
|
|
126
|
+
* finds them by reading the source.
|
|
127
|
+
*
|
|
128
|
+
* @param options - The editor origin, the project's extensions module, and the reporting options.
|
|
129
|
+
* @returns The ES module source.
|
|
130
|
+
*
|
|
131
|
+
* @beta
|
|
132
|
+
*/
|
|
133
|
+
function editorEntryModuleSource(options) {
|
|
134
|
+
const { extensionsModule } = options;
|
|
135
|
+
return [
|
|
136
|
+
`import { startEditorHost } from ${JSON.stringify(HOST_PACKAGE)};`,
|
|
137
|
+
`import { manifest } from ${JSON.stringify(MANIFEST_MODULE_ID)};`,
|
|
138
|
+
`import { acceptHotReload, scripts } from ${JSON.stringify(SCRIPTS_MODULE_ID)};`,
|
|
139
|
+
...extensionsModule === null ? [] : [`import { extensions } from ${JSON.stringify(extensionsModule)};`],
|
|
140
|
+
"",
|
|
141
|
+
"const host = await startEditorHost({",
|
|
142
|
+
` editorOrigin: ${JSON.stringify(options.editorOrigin)},`,
|
|
143
|
+
" hostKind: \"scene\",",
|
|
144
|
+
` canvas: document.getElementById(${JSON.stringify(EDITOR_CANVAS_ID)}),`,
|
|
145
|
+
` settings: ${IGNIFX_CONFIG_DEFINE_KEY},`,
|
|
146
|
+
" assets: { manifest },",
|
|
147
|
+
` extensions: ${extensionsModule === null ? "[]" : "extensions()"},`,
|
|
148
|
+
" scripts,",
|
|
149
|
+
` bootScene: ${JSON.stringify(options.bootScene)},`,
|
|
150
|
+
...reportingLines(options.engineVersion, options.heartbeatIntervalMs),
|
|
151
|
+
"});",
|
|
152
|
+
"acceptHotReload(host.app);",
|
|
153
|
+
"if (import.meta.hot) {",
|
|
154
|
+
` import.meta.hot.on(${JSON.stringify(ASSET_CHANGED_EVENT)}, (change) => {`,
|
|
155
|
+
" void host.assetChanged(change);",
|
|
156
|
+
" });",
|
|
157
|
+
"}",
|
|
158
|
+
""
|
|
159
|
+
].join("\n");
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* Generates the scene view's HTML page, before Vite's own `transformIndexHtml` adds its client.
|
|
163
|
+
*
|
|
164
|
+
* @returns The HTML document.
|
|
165
|
+
*
|
|
166
|
+
* @beta
|
|
167
|
+
*/
|
|
168
|
+
function editorPageHtml() {
|
|
169
|
+
return [
|
|
170
|
+
"<!doctype html>",
|
|
171
|
+
"<html lang=\"en\">",
|
|
172
|
+
" <head>",
|
|
173
|
+
" <meta charset=\"utf-8\" />",
|
|
174
|
+
" <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />",
|
|
175
|
+
" <title>ignifx editor host</title>",
|
|
176
|
+
" <style>",
|
|
177
|
+
" html, body { margin: 0; height: 100%; overflow: hidden; background: #000; }",
|
|
178
|
+
` #${EDITOR_CANVAS_ID} { display: block; width: 100%; height: 100%; }`,
|
|
179
|
+
" </style>",
|
|
180
|
+
" </head>",
|
|
181
|
+
" <body>",
|
|
182
|
+
` <canvas id="${EDITOR_CANVAS_ID}"></canvas>`,
|
|
183
|
+
` <script type="module" src="/@id/${EDITOR_ENTRY_MODULE_ID}"><\/script>`,
|
|
184
|
+
" </body>",
|
|
185
|
+
"</html>",
|
|
186
|
+
""
|
|
187
|
+
].join("\n");
|
|
188
|
+
}
|
|
189
|
+
/**
|
|
190
|
+
* Generates `virtual:ignifx/editor`.
|
|
191
|
+
*
|
|
192
|
+
* @remarks
|
|
193
|
+
* In development, the module listens for the editor's connect message as soon as it is evaluated,
|
|
194
|
+
* which is before the game's `main.ts` runs, and keeps the port
|
|
195
|
+
* (`listenForEditorPlayControls`); `attachEditorPlayControls(app)` then starts the play controls on
|
|
196
|
+
* it, so the editor's first connect message is never lost to `await createApp(...)`. Vite replacing
|
|
197
|
+
* the module stops both. The `import.meta.hot` calls are written out literally because Vite
|
|
198
|
+
* finds them by reading the source, not by running it. In a production build the export is an empty
|
|
199
|
+
* function, the same shape as `acceptHotReload` from `virtual:ignifx/scripts`, so the game's
|
|
200
|
+
* `main.ts` builds either way and ships no editor code.
|
|
201
|
+
*
|
|
202
|
+
* @param options - The editor origin, the reporting options, and whether to emit the development module.
|
|
203
|
+
* @returns The ES module source.
|
|
204
|
+
*
|
|
205
|
+
* @beta
|
|
206
|
+
*/
|
|
207
|
+
function playControlsModuleSource(options) {
|
|
208
|
+
if (!options.hot) return [
|
|
209
|
+
`export function ${EDITOR_PLAY_CONTROLS_EXPORT}() {`,
|
|
210
|
+
" return () => {};",
|
|
211
|
+
"}",
|
|
212
|
+
""
|
|
213
|
+
].join("\n");
|
|
214
|
+
return [
|
|
215
|
+
`import { listenForEditorPlayControls } from ${JSON.stringify(HOST_PACKAGE)};`,
|
|
216
|
+
"",
|
|
217
|
+
"// Listens now, before main.ts awaits createApp, so the editor's first port is kept.",
|
|
218
|
+
"const connector = listenForEditorPlayControls({",
|
|
219
|
+
` editorOrigin: ${JSON.stringify(options.editorOrigin)},`,
|
|
220
|
+
...reportingLines(options.engineVersion, options.heartbeatIntervalMs),
|
|
221
|
+
"});",
|
|
222
|
+
"if (import.meta.hot) {",
|
|
223
|
+
" import.meta.hot.dispose(() => {",
|
|
224
|
+
" connector.dispose();",
|
|
225
|
+
" });",
|
|
226
|
+
"}",
|
|
227
|
+
"",
|
|
228
|
+
`export function ${EDITOR_PLAY_CONTROLS_EXPORT}(app) {`,
|
|
229
|
+
" const controls = connector.attach(app);",
|
|
230
|
+
" return () => {",
|
|
231
|
+
" controls.dispose();",
|
|
232
|
+
" };",
|
|
233
|
+
"}",
|
|
234
|
+
""
|
|
235
|
+
].join("\n");
|
|
236
|
+
}
|
|
237
|
+
//#endregion
|
|
238
|
+
//#region src/vite/plugin.ts
|
|
239
|
+
/**
|
|
240
|
+
* The editor host's Vite plugin: the scene view's page on the project's own dev server, and
|
|
241
|
+
* `virtual:ignifx/editor` for the play view (`docs/architecture/17-editor-host.md` §3).
|
|
242
|
+
*/
|
|
243
|
+
/** The plugin names, as they appear in Vite's logs. */
|
|
244
|
+
const PAGE_PLUGIN_NAME = "ignifx-editor-host";
|
|
245
|
+
const PLAY_PLUGIN_NAME = "ignifx-editor-host:play-controls";
|
|
246
|
+
/** What Vite crawls for dependencies when `optimizeDeps.entries` is not set. */
|
|
247
|
+
const DEFAULT_OPTIMIZE_ENTRIES = "**/*.html";
|
|
248
|
+
/**
|
|
249
|
+
* Reads the version of the project's own `@ignifx/core`.
|
|
250
|
+
*
|
|
251
|
+
* @param root - The Vite root.
|
|
252
|
+
* @returns The version, or `null` when the project does not resolve `@ignifx/core`.
|
|
253
|
+
*
|
|
254
|
+
* @beta
|
|
255
|
+
*/
|
|
256
|
+
function readProjectEngineVersion(root) {
|
|
257
|
+
try {
|
|
258
|
+
const requireFromProject = createRequire(join(root, "package.json"));
|
|
259
|
+
const manifest = JSON.parse(readFileSync(requireFromProject.resolve("@ignifx/core/package.json"), "utf8"));
|
|
260
|
+
if (typeof manifest === "object" && manifest !== null && "version" in manifest) return typeof manifest.version === "string" ? manifest.version : null;
|
|
261
|
+
return null;
|
|
262
|
+
} catch {
|
|
263
|
+
return null;
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
/**
|
|
267
|
+
* Checks the options and applies their defaults.
|
|
268
|
+
*
|
|
269
|
+
* @param options - The options as given.
|
|
270
|
+
* @returns The extensions module path and the heartbeat period.
|
|
271
|
+
* @throws EditorHostPluginError `IGX-1801` for a malformed origin, `IGX-1803` for a bad option.
|
|
272
|
+
*/
|
|
273
|
+
function checkOptions(options) {
|
|
274
|
+
if (!isEditorOrigin(options.editorOrigin)) throw new EditorHostPluginError(EditorHostErrorCode.invalidEditorOrigin, `editorOrigin "${options.editorOrigin}" is not an origin; pass one such as "ignifx://app" or "http://localhost:5173".`);
|
|
275
|
+
const interval = options.heartbeatIntervalMs;
|
|
276
|
+
if (interval !== void 0 && (!Number.isFinite(interval) || interval <= 0)) throw new EditorHostPluginError(EditorHostErrorCode.invalidOption, `heartbeatIntervalMs must be a positive number of milliseconds; got ${String(interval)}.`);
|
|
277
|
+
return {
|
|
278
|
+
extensions: normalizeExtensionsModule(options.extensions ?? "/src/extensions.ts"),
|
|
279
|
+
heartbeatIntervalMs: interval ?? null
|
|
280
|
+
};
|
|
281
|
+
}
|
|
282
|
+
/**
|
|
283
|
+
* The editor host's Vite plugin.
|
|
284
|
+
*
|
|
285
|
+
* @remarks
|
|
286
|
+
* It is two plugins, because the two halves run under different commands:
|
|
287
|
+
*
|
|
288
|
+
* - `ignifx-editor-host` (`vite dev` only) serves the scene view at `/__ignifx_editor__/` with
|
|
289
|
+
* `Content-Security-Policy: frame-ancestors <editorOrigin>`, and adds the same header to every
|
|
290
|
+
* page a browser navigates to, so the game's own `index.html` (the play view) can be framed by the
|
|
291
|
+
* editor and by nothing else. A `Content-Security-Policy` in `server.headers` replaces it. The page's module imports the host,
|
|
292
|
+
* `virtual:ignifx/scripts`, `virtual:ignifx/manifest` and the project's extensions module from
|
|
293
|
+
* the project's own graph, and calls `startEditorHost`. It adds the extensions module to
|
|
294
|
+
* `optimizeDeps.entries` (keeping Vite's default crawl) and keeps `@ignifx/editor-host` out of
|
|
295
|
+
* pre-bundling, so the host reaches the same pre-bundled `@ignifx/core` as the game.
|
|
296
|
+
* - `ignifx-editor-host:play-controls` (every command) serves `virtual:ignifx/editor`: the play
|
|
297
|
+
* controls under `vite dev`, an empty function under `vite build`.
|
|
298
|
+
*
|
|
299
|
+
* List it after `ignifx()` from `@ignifx/vite-plugin`, which serves the two modules the scene
|
|
300
|
+
* view imports.
|
|
301
|
+
*
|
|
302
|
+
* @param options - The editor's origin and the scene view's options.
|
|
303
|
+
* @returns The plugins, to be listed in `vite.config.ts`.
|
|
304
|
+
* @throws EditorHostPluginError `IGX-1801` for a malformed `editorOrigin`, `IGX-1803` for a bad
|
|
305
|
+
* `extensions` path or `heartbeatIntervalMs`.
|
|
306
|
+
*
|
|
307
|
+
* @example
|
|
308
|
+
* ```ts
|
|
309
|
+
* // vite.config.ts
|
|
310
|
+
* import { ignifx } from "@ignifx/vite-plugin";
|
|
311
|
+
* import { editorHostPlugin } from "@ignifx/editor-host/vite";
|
|
312
|
+
* import { defineConfig } from "vite";
|
|
313
|
+
*
|
|
314
|
+
* export default defineConfig({
|
|
315
|
+
* plugins: [ignifx(), editorHostPlugin({ editorOrigin: "ignifx://app" })],
|
|
316
|
+
* });
|
|
317
|
+
* ```
|
|
318
|
+
*
|
|
319
|
+
* @beta
|
|
320
|
+
*/
|
|
321
|
+
function editorHostPlugin(options) {
|
|
322
|
+
const { extensions, heartbeatIntervalMs } = checkOptions(options);
|
|
323
|
+
const { editorOrigin } = options;
|
|
324
|
+
let root = process.cwd();
|
|
325
|
+
let base = "/";
|
|
326
|
+
let command = "serve";
|
|
327
|
+
let engineVersion = null;
|
|
328
|
+
const extensionsFile = () => resolve(root, `.${extensions}`);
|
|
329
|
+
const framePolicy = `frame-ancestors ${editorOrigin}`;
|
|
330
|
+
/**
|
|
331
|
+
* Sends the frame policy with every page a browser navigates to, the game's `index.html` (the
|
|
332
|
+
* play view) included. Navigations and frames ask for `text/html`; module and asset requests do
|
|
333
|
+
* not, and a policy on them would do nothing anyway.
|
|
334
|
+
*
|
|
335
|
+
* @param server - The dev server.
|
|
336
|
+
*/
|
|
337
|
+
const installPlayViewPolicy = (server) => {
|
|
338
|
+
server.middlewares.use((request, response, next) => {
|
|
339
|
+
if ((request.method === "GET" || request.method === "HEAD") && (request.headers.accept ?? "").includes("text/html")) response.setHeader("Content-Security-Policy", framePolicy);
|
|
340
|
+
next();
|
|
341
|
+
});
|
|
342
|
+
};
|
|
343
|
+
/**
|
|
344
|
+
* Serves the scene view's page and redirects the path without its trailing slash.
|
|
345
|
+
*
|
|
346
|
+
* @param server - The dev server.
|
|
347
|
+
*/
|
|
348
|
+
const installPage = (server) => {
|
|
349
|
+
const pagePath = `${base.endsWith("/") ? base.slice(0, -1) : base}${EDITOR_PAGE_PATH}`;
|
|
350
|
+
server.middlewares.use((request, response, next) => {
|
|
351
|
+
const url = request.url ?? "";
|
|
352
|
+
const path = url.split("?")[0] ?? "";
|
|
353
|
+
if (path === pagePath.slice(0, -1)) {
|
|
354
|
+
response.statusCode = 302;
|
|
355
|
+
response.setHeader("Location", `${pagePath}${url.slice(path.length)}`);
|
|
356
|
+
response.end();
|
|
357
|
+
return;
|
|
358
|
+
}
|
|
359
|
+
if (path !== pagePath && path !== `${pagePath}index.html`) {
|
|
360
|
+
next();
|
|
361
|
+
return;
|
|
362
|
+
}
|
|
363
|
+
server.transformIndexHtml(EDITOR_PAGE_PATH, editorPageHtml(), request.originalUrl).then((html) => {
|
|
364
|
+
response.statusCode = 200;
|
|
365
|
+
response.setHeader("Content-Type", "text/html; charset=utf-8");
|
|
366
|
+
response.setHeader("Cache-Control", "no-store");
|
|
367
|
+
response.setHeader("Content-Security-Policy", framePolicy);
|
|
368
|
+
response.end(html);
|
|
369
|
+
}, (error) => {
|
|
370
|
+
next(error);
|
|
371
|
+
});
|
|
372
|
+
});
|
|
373
|
+
};
|
|
374
|
+
return [{
|
|
375
|
+
name: PAGE_PLUGIN_NAME,
|
|
376
|
+
apply: "serve",
|
|
377
|
+
config(userConfig) {
|
|
378
|
+
const projectRoot = resolve(process.cwd(), userConfig.root ?? ".");
|
|
379
|
+
const scanExtensions = existsSync(resolve(projectRoot, `.${extensions}`));
|
|
380
|
+
const entries = userConfig.optimizeDeps?.entries === void 0 ? [DEFAULT_OPTIMIZE_ENTRIES, extensions.slice(1)] : [extensions.slice(1)];
|
|
381
|
+
return { optimizeDeps: {
|
|
382
|
+
...scanExtensions ? { entries } : {},
|
|
383
|
+
exclude: ["@ignifx/editor-host"]
|
|
384
|
+
} };
|
|
385
|
+
},
|
|
386
|
+
configResolved(resolvedConfig) {
|
|
387
|
+
root = resolvedConfig.root;
|
|
388
|
+
base = resolvedConfig.base;
|
|
389
|
+
engineVersion = readProjectEngineVersion(root);
|
|
390
|
+
},
|
|
391
|
+
configureServer(server) {
|
|
392
|
+
installPlayViewPolicy(server);
|
|
393
|
+
installPage(server);
|
|
394
|
+
},
|
|
395
|
+
resolveId(id) {
|
|
396
|
+
return id === "virtual:ignifx/editor-host-entry" ? RESOLVED_EDITOR_ENTRY_MODULE_ID : null;
|
|
397
|
+
},
|
|
398
|
+
load(id) {
|
|
399
|
+
if (id !== RESOLVED_EDITOR_ENTRY_MODULE_ID) return null;
|
|
400
|
+
return editorEntryModuleSource({
|
|
401
|
+
editorOrigin,
|
|
402
|
+
extensionsModule: existsSync(extensionsFile()) ? extensions : null,
|
|
403
|
+
bootScene: options.bootScene ?? null,
|
|
404
|
+
engineVersion,
|
|
405
|
+
heartbeatIntervalMs
|
|
406
|
+
});
|
|
407
|
+
}
|
|
408
|
+
}, {
|
|
409
|
+
name: PLAY_PLUGIN_NAME,
|
|
410
|
+
configResolved(resolvedConfig) {
|
|
411
|
+
root = resolvedConfig.root;
|
|
412
|
+
command = resolvedConfig.command;
|
|
413
|
+
engineVersion = readProjectEngineVersion(root);
|
|
414
|
+
},
|
|
415
|
+
resolveId(id) {
|
|
416
|
+
return id === "virtual:ignifx/editor" ? RESOLVED_EDITOR_MODULE_ID : null;
|
|
417
|
+
},
|
|
418
|
+
load(id) {
|
|
419
|
+
if (id !== RESOLVED_EDITOR_MODULE_ID) return null;
|
|
420
|
+
return playControlsModuleSource({
|
|
421
|
+
editorOrigin,
|
|
422
|
+
engineVersion,
|
|
423
|
+
heartbeatIntervalMs,
|
|
424
|
+
hot: command === "serve"
|
|
425
|
+
});
|
|
426
|
+
}
|
|
427
|
+
}];
|
|
428
|
+
}
|
|
429
|
+
//#endregion
|
|
430
|
+
export { DEFAULT_EXTENSIONS_MODULE, EDITOR_CANVAS_ID, EDITOR_ENTRY_MODULE_ID, EDITOR_MODULE_ID, EDITOR_PAGE_PATH, EDITOR_PLAY_CONTROLS_EXPORT, EditorHostErrorCode, EditorHostPluginError, RESOLVED_EDITOR_ENTRY_MODULE_ID, RESOLVED_EDITOR_MODULE_ID, editorEntryModuleSource, editorHostPlugin, editorPageHtml, isEditorOrigin, normalizeExtensionsModule, playControlsModuleSource, readProjectEngineVersion };
|
|
431
|
+
|
|
432
|
+
//# sourceMappingURL=vite.js.map
|