Editor
The editor is one window in which a creator draws maps, places events, writes
scripts, edits the creature database and plays the game, on Windows, macOS and Linux.
It does not replace the project folder: it edits the same files ploom builds, so
everything on this site stays true with or without it.
Purpose
Section titled “Purpose”A PokeLoom game is a folder of ordinary files: Tiled maps, TOML settings, PBS text, scripts and PNG pictures. That is good for version control and for checking, but a creator moves between four programs and a terminal, and Tiled shows a map as tiles, not as the game will draw it. Plan 26 names this as one of the engine’s five largest gaps: tooling stops at Tiled and the terminal.
The editor closes that gap without giving up the files. Its first job is the part Tiled covers worst for PokeLoom: a map with the engine’s own view of it beside the grid, with zones and 3D pieces, updated as you paint.
Design goals
Section titled “Design goals”Plan 38 read about two hundred posts and comments where creators of fan games discuss their tools (RPG Maker, Essentials, Tiled, LDtk, ROM-hacking editors) and counted the complaints by theme. The counts rank the themes; they do not measure them. The five most common, and how the design answers each:
| Complaint | What goes wrong today | The design’s answer |
|---|---|---|
| Platforms | RPG Maker and Essentials are Windows programs; on Linux and Mac they crash or need a virtual machine | One native program for Windows, macOS and Linux from the first release; nothing through Wine |
| Editing the database | Creature and move data in many text files, or in fixed forms that cannot be sorted, searched or edited in bulk, with caps on how many entries | Tables with sort, filter, multi-select and fill-down, a “used by” list for every row, no maximum count; the data stays in PBS text |
| Awkward, dated interface | Fixed-size dialogs, tiny viewports, no search | Every pane resizable and dockable, a command palette, “go to anything”, zoom on every canvas |
| Event and script editing | Long command lists built from nested dialogs; switches and variables known by number | A real code editor for scripts with completion and errors, and a visual list of the same script, editable either way; flags and variables by name, with every use listed and rename everywhere |
| Speed and stability | Editors that lag opening their database or a big map, or crash on large projects | A native toolkit; nothing the creator types waits for the build |
Creators also say what they value: RPG Maker’s approachability (paint a map, click a cell, place an event) and tools that edit the same files, put the maps and the data in one window, and show the result without a round trip. The design keeps all of that.
Principles
Section titled “Principles”- The project folder is the source of truth. The editor reads and writes the
files
ploombuilds. There is no project database and no binary save format. A file changed outside the editor (in a text editor, by Tiled, by a version control pull) is read again at once. Writes keep formatting and comments, so a one-field change is a one-line difference. - Instant. An edit applies to the editor’s model at once. Conversion runs in the
background with the same incremental build
ploom builduses, and the game view takes the result the way live reload does. - One undo for everything. Painting a map, a database field, a script edit and an art import are steps on one undo stack, across files.
- Approachable like RPG Maker, honest like a programmer’s tool. Keep the map painter, the database tabs and click-to-place events; drop fixed limits, binary files and patch-style plugins.
- Keyboard first, mouse friendly. Every action has a name in the command palette and a shortcut, and every action can also be done with the mouse.
- Errors where they are.
ploom check’s problems appear as a live list and as marks on the map, row or line they concern, with the DS’s budgets as a meter that is always shown. - Both platforms in view. The DS’s two screens, exact to the pixel, are one click away, and the DS’s limits are checked while you edit, not only at build time.
Window
Section titled “Window”One window with docking panes. A rail on the left picks the workspace:
| Workspace | What it shows |
|---|---|
| World | All maps on the world grid, zones coloured, warps drawn, from the whole region down to one cell |
| Map | One map: paint tiles or metatiles, or place 3D cells and pieces from above, with layers, collision, encounter areas and camera zones; the engine’s view from the cursor beside it |
| Events | Actors, signs, warps and triggers on the map; each one’s script in the code editor and as a visual list |
| Database | Creatures, forms, moves, items, abilities, types, trainers, encounters and shops as tables, over the PBS files |
| Scripts | The code editor, an outline, and a browser of flags and variables with every use |
| Art | Pictures and sheets with the art check before they are accepted; asset roles and art sets, swapped live |
| Battle | Battle settings, the game’s own mechanics and their tests, and a sandbox that runs the real battle engine turn by turn |
| Play | The game running inside the editor, desktop or DS view, with a debug pane: warp, flags and variables, give, start a battle |
| Project | game.toml as a form, builds for desktop and DS, and “new project from…” for imports |
Playing is not a separate program to wait for. The engine view in the World, Map and Events workspaces is a running game paused at the spot being edited; one key plays from there, another returns to editing.
The game view shows exactly what the desktop build shows. The desktop program draws both screens in software into two small pictures, so the editor runs the same game and shows those pictures as a texture. No toolkit has to understand the engine’s renderer, and the pixels cannot differ.
Toolkit
Section titled “Toolkit”The editor is written in Rust in the same workspace as the engine, so it links the
same readers and checks as ploom instead of reading the files a second way. Which
Rust interface toolkit draws it is the open question.
What it must draw decides the choice: the game view (a texture updated every frame); a map canvas with tens of thousands of tiles, panned and zoomed at the display’s rate; and forms, large virtual tables, trees and a code editor.
| Toolkit | For | Against |
|---|---|---|
| GPUI with gpui-component (recommended) | The toolkit of the Zed editor, which its users choose for speed; docking, virtual tables and a code editor with syntax trees already exist; Apache-2.0 | Before version 1.0, with frequent breaking changes and thin documentation; must be pinned to one revision |
| egui (the fallback) | Simple, widely used, proven for showing an emulator’s picture every frame; MIT or Apache-2.0 | Weaker text editing and polish; large lists laid out again every frame |
| iced | Fast, retained, used by a desktop environment | Fewer ready parts for an editor; no code editor of the same class |
| Slint | Stable | Its free licences need the GPL or a visible attribution in creators’ tool |
| A web interface (Tauri, Electron) | Any web component | The class of tool creators call slow; game frames sent between processes |
| Bevy | A game renderer | Heavy to build and start; the engine has its own renderer |
State of the question. The recommendation is GPUI with gpui-component, behind an editor core that holds no toolkit code: the project model, commands, undo, file writing and the index of uses. If GPUI fails its test, egui takes its place over the same core. No toolkit has been run on the project’s machines yet, so every speed figure behind the recommendation is cited, not measured. The first task decides: a throwaway window with the real game running in a pane, a 512 × 512-tile map canvas, a 10,000-row table and a script in the code editor, in GPUI and in egui, measured on Windows, macOS and Linux for start time, frame time, idle CPU and memory, with the game pane’s pixels compared to the desktop build’s.
Order of work
Section titled “Order of work”Each milestone is usable on its own.
- The toolkit test above, and its decision recorded.
- The editor core: the project model, commands, one undo stack, writes that keep formatting, a watcher for outside changes. Tested on the host like the engine’s logic: every edit round-trips, undo restores the files byte for byte.
- The map editor with the live engine view (the first milestone a creator uses):
the World and Map workspaces for both field styles, saving
map.tmjfiles Tiled still opens. Done when a build of a map edited here equals a build of the same edit made in Tiled. - Events and scripts, with errors and completion from the script compiler, also offered to other code editors.
- The visual script list, converting both ways with no loss.
- The database over PBS, with rename everywhere in one undo step.
- Play in the editor, with the debug pane and the DS view.
- Art, Battle and Project workspaces.
- Version control: changed files, map and data differences drawn as maps and fields, conflicts resolved cell by cell.
- Releases for Windows, macOS and Linux that need no Rust.
Plan 45 adds a pane for menu screens: the parts of a screen as boxes over the two screens, dragged into place, writing the same layout files.
Until then
Section titled “Until then”Everything the editor will do can be done today with the files and the command:
| Task | Today |
|---|---|
| Draw a map | Tiled, with the tilesets ploom tiles writes (Maps) |
| See the map in the engine | ploom run: save in Tiled and the running game shows the change around the player |
| Settings, text, scripts, data | Any text editor; every file is plain text (Files a project holds) |
| Find mistakes | ploom check converts everything, writes nothing and lists every problem with its file and place; ploom check --art checks pictures |
| Learn every key | ploom schema and the generated references, such as game.toml |
| Test at an hour | ploom run -- --hour 19:30 |
| Keep history and work together | Version control: the files are text and diff cleanly |
Live reload is what makes this workable: a script is replaced in the running game, a map arrives again around the player, and a file that does not convert is reported while the game carries on. See The ploom command and The project folder.