GBC Scene Forge

Scene Forge is a local browser editor for building tile-based scenes from imported gbc-atlas artwork. Organize your work into projects, paint maps, place sprites and markers, and export portable Tiled files. Your projects stay on your computer.

Start editing

Install the release with Python 3.10 or newer:

python -m pip install gbc-scene-forge==0.21.2
gbc-scene-forge

Forge opens your default browser at http://127.0.0.1:8765/. The terminal prints the address; if no browser opens, open that URL manually. Use --no-browser to suppress automatic opening, or --port 0 to select an available port. Keep the terminal running while editing; you can stop the server with Ctrl+C. The installed editor needs no Node or additional Python runtime dependencies.

The console shows server status, the editor URL, the absolute Project Root path, the log location and a live Clients / Failures field. Request and client activity goes to .forge-logs/server-PORT.log under the directory where you launch Forge, keeping the terminal compact. Logs include timestamps, all HTTP requests, failures, and client arrivals and expirations with IP and User-Agent. They append across launches and rotate at 1 MiB, retaining three backups (for example, server-8765.log.1 through server-8765.log.3). A client is one IP address + User-Agent combination, so multiple tabs in the same browser count once; different browsers at the same address count separately. Each HTTP request refreshes that client's activity. After 120 seconds without a request, the client expires, even if its tab is still open; its next request counts it as active again. This is recent activity, not a count of open browser connections. The live failure count points to details in the log. Colors appear only in interactive terminals and can be disabled with NO_COLOR (or TERM=dumb). Redirected output prints only startup and shutdown summaries without ANSI escapes; activity logs always use plain text.

Working from this repository? Install the development tools described below, then run:

make setup PYTHON=python3.13
make run

Create your first project

1. Enter Hello World on the project selector. Choose Sample artwork and scenes to start without preparing artwork. If projects already exist, choose Create a new project first.
2. Optionally enable Continue first-scene guide, then choose Create project. The sample becomes your own editable project; its bundled original stays unchanged.
3. Choose Scene actions → Create scene…, name it First scene, and keep the default dimensions.
4. Choose a tile from the asset library and paint. Choose Save scene or press Ctrl/⌘ S, reload, and select First scene to confirm your tiles survived.
5. Place a sprite on the canvas to try its animation preview, then choose Export… → Whole project → Download ZIP for portable Tiled files and artwork.

First scene guide in the header opens optional instructions covering project creation, artwork import, painting, save/reopen, preview, and export. Close it to edit, then reopen to continue. It remembers your position in this browser and can be restarted. Empty projects support your own gbc-atlas imports through Import atlas → Browse folder…; plain PNG tilesheet import is planned separately.

You only need Python 3.10+ and a current desktop browser (Chrome, Edge, Firefox or Safari). Node, Poetry, Tiled and gbc-atlas are not needed to edit the bundled sample. Installation needs access to the package index or a previously downloaded wheel; editing, the guide and sample work offline. Automated browser acceptance runs in Chrome on macOS and Linux; the package CI checks Python 3.13 and 3.14 on Linux.

Choose a scene from the scene dropdown to open it. If the current scene has unsaved edits, choose whether to save, discard, or keep editing before switching.

Plan before importing artwork

Choose Blockout — no artwork needed when creating a project, or Scene actions → Create blockout scene… in an existing project. Draw labeled ground, platforms, hazards and climb regions; place encounter/progression markers; and review the route through a configurable gameplay camera. The plan stays as native objects when you add artwork or export to Tiled. Follow the blockout tutorial for a complete first session, or see the blockout reference.

Agents can author saved projects through the optional local MCP server, including blockout planning, bounded atlas import/reimport, canonical decoration, and saved artwork camera/overview review. A clean browser automatically refreshes after external saves; checks pause during local edits and interactions. See external refresh for controls and conflict recovery. The ordinary editor needs no MCP dependencies.

Open another project

Use the Project dropdown beside the scene selector to open another project. Choose Choose or create project… to return to the project selector, then open an existing project or choose Create a new project, without restarting Forge. If your scene has unsaved edits, choose Save and switch, Discard and switch, or Keep editing. If saving fails, your edits stay in the current workspace.

Opening a project loads a fresh workspace. Choose a saved scene to continue; brushes, selections, undo history, and running previews start fresh. Separate browser tabs can work on different projects. If two tabs edit the same scene, revision checks protect against overwriting each other's saved work.

Where your projects live

By default, Forge keeps projects in .forge_project/ under the directory where you start it. Each project gets its own folder: Hello World becomes hello-world. Names are normalized to lowercase letters, numbers and hyphens; accents are simplified. Choose another name if its folder already exists.

.forge_project/
├── hello-world/
│   ├── forge.project.json    # Project name, identity and format version
│   ├── assets/               # Imported artwork and generated Tiled tilesets
│   ├── scenes/               # Saved Tiled maps
│   └── .forge/history/       # Recovery records
└── another-world/
    └── …

Asset and scene folders appear when you import artwork or create scenes. Back up or move the entire project folder, including its hidden .forge directory. The project selector finds manifests in the root's immediate child directories; there is no separate project registry to maintain.

Choose a different location for your projects:

gbc-scene-forge --project-root "$HOME/Scene Forge Projects"
# From the repository:
make run PROJECT_ROOT="$HOME/Scene Forge Projects"

Use the same location on later launches to see those projects again. Unsupported or damaged manifests are reported in the selector so you can identify the folder that needs attention. Version 0.21.2 continues to use manifest format version 1.

Bring an existing project into 0.21.2

Existing 0.2.0 projects keep their artwork, scene IDs and manifest format. To add one to the selector, stop Forge and move the whole project folder into your project root. For the old default location, run these commands from the repository:

mkdir -p .forge_project
# Choose a destination name that does not already exist:
mv .forge-project .forge_project/my-world
make run

You can also open a project directly, including an extracted whole-project export:

gbc-scene-forge --project /path/to/my-world
# From the repository:
make run PROJECT=/path/to/my-world

Direct mode opens just that directory; it has no project selector. The old .forge-project/ directory is never moved or deleted automatically. In 0.3.0, a positional directory argument means a project root; use --project for a single project. Passing a project as a root produces instructions instead of silently nesting new projects inside it. The old --create option is replaced by project creation in the browser.

Explore the editor

• Paint tile regions as stamps; place sprites at their native size and atlas origin.
• Rename and duplicate scenes; resize or crop with an anchored preview and undo.
• Use named tile and object layers, change their order and visibility, and undo edits.
• Recover unsaved scene drafts after a browser or server interruption; checkpoints stay inside the project, with explicit restore, download and discard choices.
• Place spawn points and trigger rectangles with names, classes and typed properties.
• Add shared terrain and collision metadata, then inspect it with canvas overlays.
• Select a sprite to try animation and movement previews. Save sequence mappings and preview preferences separately with Save preview settings.
• Choose Export… for a scene or whole-project ZIP. You can include unsaved canvas edits in an export. Open the maps in Tiled, or extract a whole-project export and open it in Forge with --project.

See the editor guide for controls, atlas reimport, preview settings, supported Tiled features and recovery behavior.

Try the sample

In the installed editor, choose Sample artwork and scenes when creating a project. Each copy receives its own project identity and a name you choose. It is never reset automatically. Source-checkout demo commands below remain useful for repeatable development previews.

From a development checkout after setup:

make demo

Open the printed address and select Riverside or Courtyard from the scene dropdown. The sample includes original pixel artwork, layers, markers, collision metadata and an animated character. Select the character on its object layer to try animation and movement previews.

The canonical sample lives in assets/demo/: editable Aseprite artwork, exported PNGs and a gbc-atlas manifest, and the portable Forge project built from that atlas. make demo copies the project into .demo/ and restores its scenes and assets on every launch. No artwork tools are needed to run it. The installed wheel includes the same project.

To keep editing without a reset, use make run PROJECT=.demo or export the project to another folder. make demo DEMO_ROOT=/path/to/demo chooses another working directory with the same reset behavior; unrelated projects are refused. Resets retain transaction recovery history and unrelated files. The sample artwork is covered by this project's MIT license.

Development

See the documentation index and documentation policy. Run make docs-check for every change.

Install Python 3.13, Poetry 2.4–2.x, Node 24 (24.12+), npm, and Make on your PATH. See the Poetry installation guide if needed. Run commands from the repository root.

.python-version selects Python 3.13.13 with pyenv; .nvmrc and .node-version select Node 24 with nvm and nodenv respectively. Run pyenv install -s and nvm install && nvm use when using those managers. .npmrc makes npm reject Node versions outside the supported Node 24 range. After switching Python, rerun make setup PYTHON=python3.13 to select the development interpreter. The installed package continues to support Python 3.10+.

make setup checks tools, creates a Poetry-managed .venv, installs locked dependencies and builds the browser UI. It does not install Poetry itself. make help lists the available commands.

Stop the sample server before make clean-demo. Custom demo directories are never removed by that command. Default project and sample directories are Git-ignored. Override tool paths with PYTHON, POETRY, or NPM when needed.

Install the test browser once with npx playwright install chromium after setup. make test-playwright-browser runs all regular suites under tests/playwright/; npm run test:playwright -- --ui opens their interactive runner. All suites use Playwright Chromium by default; pass CHROME=/path/to/chrome to override it. See browser testing for the domain layout, single-suite selection, readiness, traces, installed-wheel checks and optional MCP runs. Optional official Tiled interoperability checks run with make test-tiled TILED=/path/to/Tiled RASTERIZER=/path/to/tmxrasterizer.

Edit TypeScript in frontend/ and Python in src/gbc_scene_forge/. Generated JavaScript is Git-ignored. After frontend edits, run make frontend and reload the page; launch, demo, browser-test and build commands rebuild it for you. Release packages include the prebuilt UI.

Optional GBC palette checks report scene requirements across atlases, with separate background/window and sprite budgets, explicit runtime reservations and navigable contributors. Generic editing and Tiled export remain available without a target profile.

Reusable object definitions provide typed fields, shared defaults, instance overrides and navigable validation for points, rectangles and sprites.

World view and scene connections let you arrange scenes, author one-way or two-way links between object endpoints, and follow or repair connections with navigable findings.

Project diagnostics reports content errors, unused assets, and movement findings under explicitly selected assumptions.

Choose Review scene in the canvas toolbar for a larger view with the authoring panels hidden. Drag to pan, use zoom or Fit scene, and choose Return to editing when finished. See the review mode guide.

Clipboard editing, duplication, transforms and reusable project stamps are described in the composition guide.

Import ordinary PNG tilesheets or supported external Tiled JSON maps from the Library import dialog. See the import tutorial for slicing previews, reimport and the supported Tiled subset.

Paint connected roads, walls and shorelines with terrain brushes.

Optional GBC target budgets report static source-tile and OAM estimates alongside palette requirements, with explicit runtime limitations.

Author wide and tall scenes, including 480×9 cells at grid 16, within 65,536 cells and 8,192 pixels per axis.

Copy the scene URL to reopen its saved state directly; see scene links.

See the 0.21.2 release notes and building and releasing for release validation and publication.

License

MIT. Copyright (c) 2026 Michael Clifford.

Python contributors: see the backend domain map for service ownership, guarded reads, transaction boundaries and the isolated legacy code.