# @yagejs-tools/editor Development-only. A browser level editor for `*.yage-level.json` files: open a level, build it up, and save it back. The game loads the same file through `@yagejs/level`, which is the package a game depends on — never this one. ```bash npm install -D @yagejs-tools/editor npx yage-editor init # write the config, the harness, the level project, the script npm run editor # start it npx yage-editor validate # check every level file against the project, for CI ``` `yage-editor` starts a Vite dev server on `127.0.0.1:5211` built from the project's own Vite config, so aliases, WASM, and decorators work as they do in the game. The editor is served at the project's Vite `base` — `/` unless the project set one — and at the `index.html` there; every other path is the project's. Commands: `init` (`--force`), `validate` (`--config`), and `dev`, the default. Flags: `--port `, `--no-open`, `--config `, `-h`, `-v`. A flag outside its command's set is an error. ## `yage-editor init` Writes, under the project's Vite root, and adds `"editor": "yage-editor"` to the project's `scripts`: | File | Contents | | --------------------- | ----------------------------------------------------------------- | | `editor/config.ts` | `defineEditorConfig`, prefilled from the project | | `editor/harness.ts` | a plain `{ engine, plugins }` object, or a re-export of the lab's | | `src/levelProject.ts` | `defineLevelProject({ entities: [] })` | Prefilled: the harness carries a plugin for each `@yagejs/*` package the project declares in any dependency field, apart from `save`, `level`, `pathfinding` and `effects`, which contribute none. `levels` names each directory already holding `*.yage-level.json` files (`levels/*.yage-level.json` when there are none), `layers` is `../src/layers.ts` when that file exists **and default-exports** — the same name holds a physics `CollisionLayers` module in some projects, and the report says when one was passed over — and `assets` is `public/**/*.png` when `public/` exists. `entities` and `gamePage` are never guessed: nothing in a project says which classes are placeable, and a `gamePage` naming a page that does not exist is refused at startup. `@yagejs/core` and `@yagejs/renderer` must be declared, or the command refuses. An undeclared `@yagejs/level` is a note rather than a refusal, since installing the editor pulls its peers in without declaring them. A file that is already there is kept and named in the output; `--force` rewrites it. That covers `editor/config.ts` under any of the four extensions the CLI probes, and a `scripts.editor` the project already declares. A kept config names the harness the editor loads, so none is written beside it. When the project has a scenario lab harness — `lab/harness.ts`, `.mts`, `.js` or `.mjs` — `editor/harness.ts` is written as `export { default } from "../lab/harness.js"` instead of a second plugin list. The two tools have no dependency on each other: they accept the same object, and the link is a line of the project's own code. ## `yage-editor validate` Checks every level file against the project's declarations, headless. Reads the config, imports `modules.project` through the project's own Vite config with Vite's SSR loader, builds the catalog, and runs `readLevel` + `validateLevel` over every file the level globs match. Nothing renders and no `setup()` runs. Problems print grouped by file — placement id, parameter path, diagnostic code, message — then a count line. Exit 1 on any catalog problem, structural error, import failure or diagnostic; exit 0 when every level is clean, and 0 with a line when the globs match no file. A catalog problem is reported against the project module and stops the run, since there is no catalog to check against. The `@yagejs/*` packages the modules import are transformed by Vite as well, rather than loaded by Node, so a module that imports `@yagejs/physics` (whose `@dimforge/rapier2d` Node cannot resolve) or `@yagejs/audio` is checked like any other. A module that reads `window` or `document` at import time fails: the error names the module, and says to move that import out of the entity modules or into the code that uses it. ``` yage-editor validate levels/forest.yage-level.json 01J000000000000000000STALE - migration-failed Parameters were authored against type version 2, and "game.crate" declares version 1. This level is newer than the game. 01J0000000000000000SLIME01 speed parameter-invalid Parameter "speed" must be at most 200. 2 problems in 1 of 3 level files. ``` The same check as a test, for a project that wants it in its own test run — the calls are `@yagejs/level` public API. The entity modules load through the test runner rather than through the editor's server, in Node, with no browser, so one that touches `window` at import time fails: ```ts yage-check="syntax" yage-reason="Imports the project's own src/levelProject.ts, a module this page does not show." import { readdirSync, readFileSync } from "node:fs"; import path from "node:path"; import { buildLevelCatalog, validateLevel } from "@yagejs/level"; import { readLevel } from "@yagejs/level/document"; import { expect, it } from "vitest"; import project from "./levelProject.js"; const built = buildLevelCatalog(project); if (!built.ok) throw new Error(built.errors[0]?.message); const levels = readdirSync("levels").filter((name) => name.endsWith(".yage-level.json"), ); it.each(levels)("%s matches the catalog", (name) => { const read = readLevel(readFileSync(path.join("levels", name), "utf8")); if (!read.ok) throw new Error(read.errors[0]?.message); expect(validateLevel(read.document, built.catalog)).toEqual([]); }); ``` A project whose entities import `@yagejs/physics` also needs this config, because Vitest cannot otherwise resolve `@dimforge/rapier2d`: ```ts yage-check="syntax" yage-reason="Merges the project's own vite.config.ts, a module this page does not show." // vitest.config.ts import { defineConfig, mergeConfig } from "vitest/config"; import viteConfig from "./vite.config.js"; export default mergeConfig( viteConfig, defineConfig({ environments: { ssr: { resolve: { mainFields: ["module", "main"] } } }, test: { server: { deps: { inline: ["@yagejs/physics", "@dimforge/rapier2d"] } }, }, }), ); ``` ## Configuration `editor/config.ts`, read in Node: ```ts import { defineEditorConfig } from "@yagejs-tools/editor"; export default defineEditorConfig({ modules: { project: "../src/levelProject.ts", // default-exports the LevelProject a game also uses harness: "./harness.ts", // engine + plugin factories, the scenario lab's shape }, levels: [ // a glob, or a glob plus the layers its levels are authored against { glob: "src/levels/forest/*.yage-level.json", layers: "../src/forestLayers.ts", }, "src/levels/menu/*.yage-level.json", ], assets: ["public/sprites/**/*.png"], // optional: what the asset picker lists gamePage: "/game.html", // optional: what the Run control opens }); ``` `assets` globs are the whole filter the picker applies. The editor cannot tell which files a given parameter would accept, so what these patterns match is what the list offers; narrow them to narrow the list. A project without them keeps a typed asset field and the picker says nothing matched. The globs match a file where it sits on disk; the picker offers the path the browser fetches, which is what a level stores. Vite serves the contents of `publicDir` at the server root, so the glob above lists `sprites/hero.png` — one segment shorter than the glob that matched it. A `levels` entry's `layers` is the path of a module default-exporting the `LayerDef[]` the game's own scene spreads into its `layers` — one array, exported once, imported by both. It is a path rather than the array because this file is read in Node before the server starts. The editor page imports it, so a `sort` in it stays the function the game runs. Layers are per entry rather than per project because a scene declares its own set, and they are out of the level document because which scene a level loads into is a project concern. A level whose glob names no layers keeps every placement on `"default"`. Without a declared set the editor's preview flattens the level: nothing has provisioned the project's layers, so every visual falls back to `"default"` in add order while the running game has them on distinct, ordered, sometimes sorted layers. Module paths are relative to the config file and must resolve inside the Vite root. The file carries paths and globs, never imported game objects: the server reads it in Node, and a config that imported an entity class would evaluate Pixi and WASM before the server started. `gamePage` is a root-relative URL naming a page this server serves, written the way the project's own source names it — the editor resolves it under whatever Vite `base` the project set. It needs a page of its own: the editor answers `/`, `/index.html`, `/play` and `/play.html`, so naming any of them — or a form that resolves onto one, such as `/play` for `/play.html` — is refused at startup. Without a `gamePage` there is no Run control; Play needs none. The harness has the same shape the scenario lab uses, so one file can serve both tools: ```ts import { Engine } from "@yagejs/core"; import { RendererPlugin } from "@yagejs/renderer"; export default { engine: () => new Engine({ debug: true }), plugins: ({ container }: { container: HTMLElement }) => [ new RendererPlugin({ width: 960, height: 600, container }), ], }; ``` The preview installs an Inspector before the harness's plugins, so selection boxes built from the render and collider facets work whether or not the harness includes `DebugPlugin`. Play runs the harness as written: add `InspectorPlugin` or `DebugPlugin` to it to reach `window.__yage__.inspector` while playing. ## Editing a tilemap in Tiled Select a placement whose asset parameter points to a local Tiled JSON map, then click **Open in Tiled** beside that parameter. Install Tiled on the same machine that runs `yage-editor`. Include the map JSON, external tileset JSON and tileset images in `assets`: ```ts import { defineEditorConfig } from "@yagejs-tools/editor"; export default defineEditorConfig({ modules: { project: "../src/levelProject.ts", harness: "./harness.ts" }, levels: ["src/levels/*.yage-level.json"], assets: ["public/maps/**/*.json", "public/tiles/**/*"], }); ``` Saving a matching asset refreshes the preview automatically. Level edits, selection, camera and undo history stay in place. A refresh waits for an active viewport drag or stepped transform edit to finish. If a changed asset cannot load, the Problems panel reports it; saving a corrected file retries it. JSON maps open directly. If your game loads a JSON export of a `.tmx` or `.tmj` source, declare which source to open in `editor/config.ts`: ```ts import { defineEditorConfig } from "@yagejs-tools/editor"; export default defineEditorConfig({ modules: { project: "../src/levelProject.ts", harness: "./harness.ts" }, levels: ["src/levels/*.yage-level.json"], assets: ["public/maps/**/*.json", "public/tiles/**/*"], tiled: { sources: { "maps/forest.json": "art/forest.tmx" }, }, }); ``` The key is the path the level stores. The source is relative to the Vite root and must be inside that root. Export the source to the runtime JSON once in Tiled, then enable [Repeat last export on save](https://doc.mapeditor.org/en/stable/manual/preferences/#saving-and-loading). Saving the source then updates the JSON that YAGE reloads. Tiled owns the map contents and their undo history; YAGE keeps the asset reference and placement. On macOS, the editor opens the installed Tiled application through Launch Services. On Windows, it checks the standard Program Files directories, then looks for `tiled.exe` on `PATH`. On Linux, it runs `tiled` from `PATH`. Set `YAGE_TILED_PATH` before starting the editor to use another executable, such as an AppImage or a portable Windows installation. Give the executable path alone, without arguments or surrounding quotes in the value. The application opens on the server's machine. For a remote workspace, run Tiled in that desktop session. Under WSL, use a Linux Tiled installation with a working graphical desktop, or run both Tiled and the editor server on Windows. ## What the editor edits Three bars run across the top. The **file bar** owns which level is open; the **toolbar** owns the tool, the pivot, the grid, the edit actions and the eight arrange actions; the **control bar** under them holds the selected placement's name and its five transform numbers. Below them the **hierarchy** is the left column, the viewport takes the middle, the **inspector** is the right column, and two bands sit under the viewport in its own column: the **Actors** strip, and the **Problems** band under it. The strip starts closed and its header opens it; open, its entries wrap into rows under their group headings, and past a few rows it scrolls down — never sideways, which on a trackpad or touchscreen is the browser's back gesture. The Problems band appears with the first finding and leaves with the last, capped at a fifth of the window, and its header collapses the list while keeping the count. Both take their height from the viewport rather than covering it, so nothing the viewport draws ends up behind a panel and a finding arriving never resizes the hierarchy or the inspector. Panels are not resizable and none of these positions is configurable. The file bar's first control is a `select` listing every level the `levels` globs matched, as project-relative paths in alphabetical order. Choosing one opens it. Beside it sit **New**, **Duplicate** and **Delete**, then the unsaved badge, Save, Play, and Run. **New** and **Duplicate** ask for a name, which becomes the level's id, and a path, which follows the name until it is typed over. New writes an empty level there. Duplicate writes a copy of the open level's file on disk, without its unsaved edits. Either one opens the level it wrote. The server refuses a path the `levels` globs do not cover and a path a file already holds. **Delete** asks first, then removes the open level's file with its draft and undo history, and opens the level that takes its place in the list. Undo does not bring the file back. The placeable types are whatever `defineLevelProject({ entities: [...] })` lists, plus the level contributions of the project's direct dependencies. See `packages/level.md` for the declarations. The viewport draws the level as a real engine scene, with every placement inactive — constructors, `setup()`, and `onAdd()` run, nothing else does. A placement the preview cannot build is left out and reported as `placement-excluded`, carrying the reason the load gave — the asset lease's where an asset failed, else the strict load's own message — and the rest of the level still draws. A placement left out only because it hangs off an excluded one names that placement instead, which carries the real reason in the same report. The only assets loaded are the ones the level names through `param.asset`. There is no scene to run a `preload`, so an entity that builds a visual from a handle its game scene loads throws on a texture that is not in the cache and its placement is excluded. The zoom is the developer's alone: it is canvas pixels per world unit, so the size the level is drawn at is the same in a narrow pane and a wide one. A band opening, a panel closing, or a window drag changes how much of the level is on screen and never how large it is drawn or where it sits under the pointer — the world at the viewport's top-left corner stays put. A level with no remembered view opens at the origin, zoomed so the whole design rectangle fits the pane, which is what `Shift`-`F` goes back to. The editor sets its preview's fit itself, so a `fit` a harness declares governs the game page and the play page and not the editor's viewport. The view moves: pan, zoom around the pointer, frame the selection, reset. The pointer shows which of the three a press would start — `grab` over empty space and while Space is held, `grabbing` while panning, `move` over a placement. The view is browser-local state, stored per project and level path — it never enters a command, the draft, or the document, never marks the level dirty, and produces no undo entry. Zoom is clamped to 0.05–20. Whether the reference guides show, whether gestures snap, and how wide the lattice is are part of that stored view, so all three survive a reload; a view reset leaves them alone. The step starts at 32 and takes a number from 1 to 10000 world units; the field refuses one outside that rather than moving it inside. `ArrowUp` and `ArrowDown`, and dragging the label, double and halve it inside those bounds — the sizes art comes in — and each press takes effect at once, since the lattice takes no undo entry. A snapped move puts the active placement's world position on the nearest lattice point — a placement at 14 on a lattice of 10 lands on 10, rather than moving in ten-unit steps and staying off the grid. Everything else the gesture carries takes the same correction, so an arrangement keeps its spacing and only the active placement lands on a line. A snapped scale puts the side the box handle holds on the nearest lattice point, per axis the handle holds, leaving the factor itself unrounded; a turned placement's side lands as near that point as its own axis reaches, since a `LevelTransform` holds no shear. A side landing on the point the gesture scales about is a scale of zero, and one landing behind it is the placement mirrored at that size; both are values, so both are written. Under the `Each` pivot the side that lands is the covering box's, not any one placement's edge. Creating, pasting, and duplicating land on the lattice too. Snapping does not touch a turn: 15° steps are `Shift`'s, held during the drag, and rounding the resulting world angle rather than the amount turned by. The controls: | Control | What it does | | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Problems header | Collapses and opens the list of findings, keeping the count on screen. Nothing remembers it across a reload | | Actors header | Opens and closes the strip under the viewport. It starts closed, and nothing remembers it across a reload | | Actors entry | Creates that type at the middle of the view, on the grid, and selects it. Grouped by source, the project's first. Shows the default path of the type's first `"texture"`-kind asset parameter as a thumbnail, an empty frame when there is none or the file is missing. A sheet shows one frame, from the first of: the grid the parameter declared through `param.asset(descriptor, path, frames)`, the first frame of a sibling `.json` atlas when the `assets` globs match that atlas, otherwise the whole image, fitted. Proportions are never used to guess a frame, and a declared grid that runs off the loaded image is refused | | Click a placement | Selects it; drag to move it. Ctrl/Cmd-click toggles it in the selection and starts no drag | | Hierarchy row | Click selects; Ctrl/Cmd-click toggles; drag before/after a row, onto a row, or onto the root area | | Hierarchy drag of a selected row | Moves the whole selection, in one command; a row outside the selection moves alone | | Hierarchy row eye | Hides that placement and everything under it, or shows it again. Selects nothing | | Inspector asset field | Text path; Enter or blur commits, Escape restores; **Reset** puts the declared default back | | Inspector reference field | A list of the level's placements of the types the parameter accepts — the holder among them when the slot accepts its own type — by `name` / `key` / `id`; picking one commits at once. **Clear** beside an optional field empties it. A held id the document cannot account for stays as the first row, `Missing: ` or `Wrong type: