Skip to content

Project setup

The editor needs three things from a project: a description of how to build its worlds, a page that starts the editor, and a Vite plugin that lets the editor read and write the asset folder. examples/editor in the repository is a complete project set up this way.

To see it running before you set up your own:

Terminal window
pnpm install
cd examples/editor
pnpm dev

Open http://localhost:5180/ for the editor; http://localhost:5180/play is the game itself. Your first scene walks through the editor.

One object tells both the game and the editor how to build a world.

src/project.ts
import { Engine2D } from '@shell/engine-2d';
import { GamePlugin } from './game-plugin';
export const Project = {
name: 'My Game',
/** Folder the editor may read and write, relative to the project root. */
assetRoot: 'public/assets',
/** URL prefix that folder is served from when the game runs. */
assetBaseUrl: '/assets',
/** Asset path of the scene the game loads and the editor opens. */
startScene: 'scenes/main.scene.json',
engine: (canvas: HTMLCanvasElement) => Engine2D({ canvas, resizeTo: canvas, spawnCamera: false }),
plugins: [GamePlugin],
} as const;
FieldMeaning
nameShown in the editor’s toolbar.
assetRootFolder of scenes, prefabs, textures, and other files.
assetBaseUrlWhere the game loads those files from. Component fields store URLs under this prefix.
startSceneAsset path of the first scene: level one.
sharedSceneOptional. Asset path of the shared scene: what every level needs, such as the camera. Loaded first and never unloaded; Play loads it too.
engineThe engine plugins for a canvas. Called once per world.
pluginsThe project’s own plugins: components, systems, resources.
debugOptional. Plugins only the editor’s worlds get, after plugins, such as PhysicsDebugPlugin. The game’s entry does not install them.
prefabsOptional. Code-defined prefabs, by key. The editor lists them and registers them in its worlds; the game’s entry registers them too (see below).

A scene refers to a code-defined prefab by its key, for example in a spawner’s StoreType.Prefab() field. The editor registers prefabs in its own worlds; the game’s entry does the same before it loads a scene:

src/main.ts
for (const [key, prefab] of Object.entries(Project.prefabs)) {
world.get('prefabs').register(key, prefab);
}

The type is ProjectDefinition from @shell/editor. Import it with import type if you annotate the object, so the game carries no editor code.

Two conventions make a project editable:

  • Scene content comes from scene files, not from startup systems. The editor never runs startup schedules.
  • Gameplay systems are not marked .runInEditMode(), so the edit world shows the scene as authored. Systems that only draw, such as the renderer’s, are marked.

The editor gets its own HTML page and entry module, next to the game’s. It is the only source file that imports editor packages.

editor.html
<div id="editor"></div>
<script type="module" src="/src/editor.ts"></script>
src/editor.ts
import { createEditor, RpcAssetSource } from '@shell/editor';
import { EditorViewport2D } from '@shell/editor-viewport-2d';
import { ProjectEditorPackages } from 'virtual:shell/packages/editor';
import { Project } from './project';
await createEditor({
target: document.querySelector<HTMLElement>('#editor')!,
project: Project,
viewport: EditorViewport2D,
packages: ProjectEditorPackages,
assets: import.meta.hot ? new RpcAssetSource(import.meta.hot) : undefined,
// Optional: lets an agent (an MCP client) work on the open editor. See "Agents" below.
hot: import.meta.hot,
});

The target element needs a size; the editor fills it. Give html, body, and the element height: 100%.

createEditor options:

OptionMeaning
targetElement the editor fills.
projectThe project definition.
viewportThe scene view plugin, EditorViewport2D. It draws each camera’s frame: with both sides of the camera’s view set, the area the game always shows; else what a screen of the UI’s reference size shows.
packagesThe tools of the Packages, ProjectEditorPackages (from shellPackages(), step 3): the editor’s own (bones, paths, particles) and those of the project’s Packages. Without it the editor has none of them.
assetsWhere files come from. Without it the editor reads by URL and cannot save.
pluginsFurther plugins for the edit world. See Extending the editor.

It resolves to { world, destroy() }: the edit world, and a function that removes the editor.

Do not list editor.html as a build input. A production build then contains no editor code.

vite.config.ts
import { shellEditor } from '@shell/editor/vite';
import { shellPackages } from '@shell/packages/vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [svelte(), shellEditor({ assetRoot: 'public/assets' }), shellPackages()],
});
  • svelte() compiles the editor’s interface. The project needs svelte and @sveltejs/vite-plugin-svelte as dev dependencies.
  • shellEditor() lets the editor page list, read, and write files under assetRoot, and tells it when they change. Use the same folder as Project.assetRoot.
  • shellPackages() writes virtual:shell/packages/editor, the editor’s tools that packages installs. The project depends on @shell/packages (see Packages for the game’s side) and adds "@shell/packages/client" to the types of tsconfig.json.

Start the dev server and open /editor.html.

To have the editor at the dev server’s root, name its page: shellEditor({ assetRoot: 'public/assets', page: '/editor.html' }). The root then shows the editor and /play the game. Each page stays at its file’s name, and a build is not changed: index.html is still the game.

A script is a system or a component in a file of its own, which no plugin lists.

vite.config.ts
import { shellScripts } from '@shell/scripts/vite';
plugins: [svelte(), shellEditor({ assetRoot: 'public/assets' }), shellScripts()],
src/project.ts
import { ProjectScripts } from 'virtual:shell/scripts';
plugins: [GamePlugin, ProjectScripts],
  • @shell/scripts is a dependency of the game, not a dev dependency: shellScripts() runs in the build too, which is what puts the scripts in the shipped game. Add "@shell/scripts/client" to the types of tsconfig.json.
  • A script is a file in src/scripts (shellScripts({ scriptRoot }) names another folder): spin.system.ts with one export made with Define.system(), or spin.component.ts with one made with Define.component(). Any other .ts file there is a helper that scripts import.
  • A system that reacts to an event says so: Define.system().observes(OnDamage).
  • A changed system is replaced in place, also in a game that is playing, and starts over with new locals. A changed component, resource or plugin builds the editor anew in its page, with no reload.
  • A script that is wrong is left out, or stays as it last worked, and is named in the editor’s console. Vite’s error overlay is off in a project with shellEditor(), unless the project sets server.hmr.overlay.
  • editor.html?scripts=off opens the editor with no script loaded, for a script that hangs the page.
  • In the editor, the Scripts panel, a tab beside Assets, lists the scripts: its buttons make a system, a component, or a folder, and a double click opens a script in the Code panel. Ctrl or Cmd+S there saves the script. The Code panel underlines type errors, lists what can follow a dot, and shows a declaration under the pointer; the dev server’s TypeScript answers that from the project’s own tsconfig.json. A type error does not stop a script from running.
  • A script renamed or moved in the Scripts panel takes the import lines that name it along, in scripts and in the project’s other code.
  • A script made in the editor imports from the project’s engine package: the first of @shell/engine-2d, @shell/engine-3d, and @shell/engine-minimal that its package.json lists, else @shell/ecs. The engine package has every name of @shell/ecs, @shell/transform, and the rest, so the one import line of a script reaches all of them, and the Code panel lists them inside its braces.

A Package is what a project adds beyond its engine, such as @shell/spatial. Its ECS plugin is installed with no code listing it.

vite.config.ts
import { shellPackages } from '@shell/packages/vite';
plugins: [svelte(), shellEditor({ assetRoot: 'public/assets' }), shellScripts(), shellPackages()],
src/project.ts
import { ProjectPackages } from 'virtual:shell/packages';
plugins: [GamePlugin, ProjectScripts, ProjectPackages],
  • @shell/packages is a dependency of the game, not a dev dependency: shellPackages() runs in the build too. Add "@shell/packages/client" to the types of tsconfig.json. The project depends on @shell/ecs itself.

  • The project’s package.json is the list. Every one of its dependencies that is a Package has its plugin installed in the game’s world, the editor’s, and each play world. Nothing else names them.

  • A Package is an npm package whose own package.json has a shell field: title, description, plugin (the name its ECS plugin is exported under), and optionally skill (a skill an agent loads to use it) and editor (its editor plugin, from its ./editor entry). A Package for the editor alone, such as the editor’s own bone tools, has an editor and no plugin; File, Packages… does not offer it, since every editor has it. What File, Packages… shows of it besides is optional: summary (one short line for its list), features (a few lines of what it gives, shown before it is added) and partOf (the name of the Package it is shown inside, as @shell/editor-tilemap is inside @shell/tilemap-2d).

    {
    "name": "@shell/spatial",
    "shell": { "title": "Spatial", "description": "…", "plugin": "SpatialPlugin" }
    }
  • In the editor, File, Packages… lists the Packages of the workspace the project is in, and adds or removes one: the dev server writes the dependency as workspace:*, runs pnpm install --filter . --prefer-offline in the project’s folder, and has the pages load anew. An agent does the same with add_package and remove_package.

  • A dependency added by hand (pnpm add) works the same. It is seen when the dev server next starts.

  • A Package’s plugin is installed after the project’s own plugins. A project that installs it itself, with a configuration, keeps its own: a plugin installed twice is installed once.

  • A Package’s numbers are its settings, of a settings type it declares and set in Project Settings, not a configuration in code.

  • Removing a Package loses nothing: scenes keep its components, and a script that imports it is left out and named.

What a player sees before the game’s code has arrived: splash.html of the asset folder, put into the game’s page.

vite.config.ts
import { shellEditor, shellSplash } from '@shell/editor/vite';
plugins: [svelte(), shellEditor({ assetRoot: 'public/assets' }), shellSplash({ assetRoot: 'public/assets' })],
  • shellSplash() runs in the dev server and in the build. It puts the splash last in index.html’s body, so an edit that is broken spoils only the splash. With no splash.html, the page has the default.
  • {{background}}, {{logo}}, {{title}}, {{text}} and {{atLeast}} are filled from the project’s settings file of the Splash type (settings/engine.splash.settings.json), where the settings index lists it, as the game reads it. A name it does not have is left out, with a warning.
  • splash.html is only markup and CSS, with id="shell-splash" on its root. The engine’s PageSplashPlugin (in BrowserPlugin) sets --shell-progress (0 to 1) on it while the first scene loads, and fades it out once the game shows its first scene or its Loading cover, after atLeast ms; before a splash scene, as soon as that shows. A game that starts no Scene loses it 4 s after its code began. All of the file is in one element, #shell-splash-file, which goes with it; a file with no #shell-splash is taken out at once, unfaded, with a warning.
  • In the editor, splash.html opens from the Assets panel in the Code panel.

shellEditor() writes to your disk on behalf of a web page, so it is deliberately narrow:

  • Dev server only, but for two things, both in what vite build built and never in your folder: it writes the asset folder’s settings.index.json and tilesets.index.json again, from the folder, so a game built after a file was moved outside the editor lists it where it is; and where a scene, prefab, settings, clip, effect or tileset file names a file that has moved, it writes the new path, found by what the editor remembered of that file. It does nothing in vite preview.
  • Local only. If the dev server is reachable from other machines (--host), the plugin registers nothing and logs why. Set allowRemote: true to accept that risk.
  • One folder. Every path is checked against assetRoot: absolute paths, .., hidden files, and symbolic links leading outside are refused.
  • No half-written files in your folder. A write there goes to a temporary file that is then renamed over the target. The two things a build writes go straight into what it built, and only into its own files, never through a link.
  • No silent overwrite. A save states the file’s modification time as the editor last saw it. If the file changed or vanished since, the save is refused and the editor asks what to do.
  • Nothing is overwritten or destroyed. Creating, importing, and moving refuse a path that is taken. Deleting moves the file into .shell-editor/trash/ in the project, under the time it was deleted; add .shell-editor/ to .gitignore. The trash is never emptied for you.
  • Files over 32 MB are refused.

With hot: import.meta.hot passed to createEditor, shellEditor() also serves an MCP endpoint at /__shell/mcp. An agent (Claude Code, or any MCP client) uses it to read and change the open editor:

Terminal window
claude mcp add --transport http shell-editor http://localhost:5173/__shell/mcp
Agent toolsWhat they do
get_guide, get_skillHow a game is built here and how these tools are used; one of the engine’s skills by its name
world_listComponents, world_listEntities, world_getEntity, world_query, world_snapshot, …Read the open scene, or the running game during play
world_spawn, world_setFields, world_insertComponent, world_despawn, world_reparent, …Change the scene. Each call is one undo step, labelled Agent: …
batchSeveral changes as one undo step: all of them, or none
run_actionAny editor action: file.save, play.start, play.stop, edit.undo, …
play_stepAdvance the game by a count of frames and leave it paused
play_keysPress and release keys of the game as a player would, held over calls, then advance it
read_log, get_selection, set_selection, screenshotThe console, the selection, and a picture of the scene view or the game
move_panelPut a panel of the editor in another place, as dragging its tab does
get_prefab_pictureA prefab’s picture, drawn alone and fitted, to see it before placing it
get_editor_state, open_document, create_scene, set_scene_keyWhich scene is open and whether it is saved; open another, or a new one; a scene’s key
wait_for_reloadAfter a code change: answered once the new code is running, or with what is wrong with it
check_codeThe type errors of the files it names, or of every script, as tsc finds them
list_assets, move_asset, delete_assetThe files of the asset folder, each with the URL a component field stores; move, rename, or delete one
instantiate_prefab, create_prefabAdd an instance of a prefab (a file, or code:<key>) to the scene; make a prefab file from an entity
  • The agent writes components and systems with its own file tools. A code change reaches the page (a system in place, a component, resource or plugin by building the editor anew, other code by a reload); wait_for_reload, given the codeAt read before the change as since, waits up to 15 seconds for it. Unsaved scene changes survive it. The undo history does not.
  • world_listComponents lists the components shown in the editor. keys asks for particular ones, shown or not, and all for every registered one.
  • screenshot answers with the picture, its size in pixels, and the rectangle of the world it shows, so the agent can tell that an entity is outside the picture.
  • move_asset updates every scene, prefab, preset, tileset, clip and effect that refers to the file, and the open scene as one undo step. A file the agent moves with its own file tools is still found by a value that carries its id (a picture or a sound only with its .meta file beside it); a value without one names the old place. delete_asset leaves references as they are, and the dev server keeps the file in .shell-editor/trash.
  • get_editor_state includes codeAt, the time the page last took new code: when it loaded, or when it replaced a system script in place. The agent reads it before a code change and passes it to wait_for_reload after: that call is answered by the page running the new code, however soon it is made. startedAt is the time the page loaded.
  • Code that cannot be built is what the agent’s next call is told (“The editor page failed to start: …”). An error thrown while a project module loads is only in the browser’s console.
  • When it connects, the endpoint tells an agent to call get_guide first, and get_skill for each skill the guide names for its task, so the project needs no instructions of its own. Both answer before any editor page is open. get_skill without a name lists the skills of the project’s .claude/skills.
  • To check a game the same way every time, the agent starts it paused (run_action with play.startPaused) and advances it with play_step. A frame is the fixed timestep, so 60 frames are one second of the game whatever the machine is doing. A screenshot of a paused game shows it as it is.
  • The editor page must be open in a browser. It does not have to be visible: the game keeps running in a hidden tab, and a screenshot is still drawn.
  • The endpoint follows the same rules as the file server: dev server only, localhost only. It also refuses a request that carries another site’s Origin, so a web page you have open cannot edit your scene.
  • With several editor tabs open, the one that loaded last answers.

A plugin adds its own agent tool with world.get('editorAgentTools').register({ name, description, inputSchema, handler }).

  1. /editor.html (or the root, with page) shows the start scene’s entities in the hierarchy.
  2. Change a value in the inspector and press Mod+S. The scene file changes on disk and the page does not reload.
  3. Edit the scene file in a text editor. The editor shows the change.
  4. Press Play. The game runs in the Game view; Stop returns to the scene as authored.

If the Save button is disabled, the editor is running on the read-only fallback: check that shellEditor() is in the Vite config and that assets is passed to createEditor.