Metadata-Version: 2.4
Name: gbc-scene-forge
Version: 0.3.0
Summary: Standalone local scene editor for imported artwork and portable Tiled projects
Project-URL: Repository, https://github.com/cliffom/gbc-scene-forge
Project-URL: Documentation, https://github.com/cliffom/gbc-scene-forge/blob/main/README.md
Project-URL: Issues, https://github.com/cliffom/gbc-scene-forge/issues
License-Expression: MIT
License-File: LICENSE
Keywords: game-boy-color,scene-editor,tilemap
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# GBC Scene Forge

![GBC Scene Forge — Build a world. One tile at a time.](assets/branding/hero.png)

Scene Forge is a local browser editor for building tile-based scenes from imported
[gbc-atlas](https://github.com/cliffom/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:

```sh
python -m pip install gbc-scene-forge==0.3.0
gbc-scene-forge
```

Open **http://127.0.0.1:8765/** in your browser. The terminal prints the address;
you can stop the server with **Ctrl+C**. The installed editor needs no Node or
additional Python runtime dependencies.

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

```sh
make setup PYTHON=python3.12
make run
```

### Create your first project

1. On the project selector, enter **Hello World** and choose **Create project**.
2. Choose **Import atlas**, then **Browse folder…**. Select your atlas folder,
   choose a `*.atlas.json` manifest if needed, and confirm the import. Forge copies
   the artwork into the project, so you can move the original import folder later.
3. Choose **Create scene**. Give it a name, dimensions in cells, and an 8, 16 or
   32 pixel grid.
4. Pick a tile in the asset library and paint. Choose **Save scene** or press
   **Ctrl/⌘ S** to save your work.

To reopen a scene, choose it from the scene list and click **Open scene**.

### Open another project

Choose **Projects…** at the top of the workspace to return to the project selector.
You can open an existing project or create another one 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.

![Choose an existing project or create a new one](docs/screenshots/project-selector.png)

### 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.

```text
.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:

```sh
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.3.0 continues to use manifest format version 1.

### Bring an existing project into 0.3.0

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:

```sh
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:

```sh
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.
- Use named tile and object layers, change their order and visibility, and undo edits.
- 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](docs/STANDALONE.md) for controls, atlas reimport, preview
settings, supported Tiled features and recovery behavior.

## Try the sample

From a development checkout after setup:

```sh
make demo
```

Open the printed address, choose **Riverside** or **Courtyard**, and click
**Open scene**. 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 editable sample project](docs/screenshots/standalone-demo.png)

The sample lives in `.demo/` and preserves saved edits on later runs.
`make demo DEMO_ROOT=/path/to/demo` chooses another sample directory. It opens in
direct mode; you can put it under a project root to find it in the selector later.
The sample artwork is covered by this project's MIT license.

## Development

Install **Python 3.10+**, **Poetry 2.4–2.x**, **Node 24.12+**, **npm**, and **Make**
on your `PATH`. See the [Poetry installation guide](https://python-poetry.org/docs/#installation)
if needed. Run commands from the repository root.

`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.

| Command | What it does |
| --- | --- |
| `make run` | Rebuild the UI and open the project selector for `.forge_project/` |
| `make run PROJECT_ROOT="/path/to/projects"` | Browse projects in another root |
| `make run PROJECT="/path/to/world"` | Open one project directly |
| `make demo [DEMO_ROOT=/path]` | Create or reopen the editable sample |
| `make run PORT=8777` | Use another local port; also works with `make demo` |
| `make check-deps` | Check tools and the Python dependency lock without installing |
| `make frontend` | Type-check and rebuild the browser UI |
| `make lint` / `make format` | Check code style or apply formatting |
| `make typecheck` | Run strict TypeScript checks |
| `make test` | Run Python and TypeScript tests |
| `make test-python` / `make test-frontend` | Run one test suite |
| `make test-browser [CHROME=/path]` | Run Chrome acceptance in disposable directories |
| `make check` | Run lint, tests and Chrome acceptance |
| `make build` | Rebuild the UI, build wheel/source distributions and check metadata |
| `make check-dist` | Install the built wheel in an isolated environment and smoke-test it |
| `make clean` | Remove build outputs and `node_modules`; keep your projects |
| `make clean-demo` | Delete the default `.demo/`, including saved sample edits |

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.

Chrome defaults to its macOS application path; pass `CHROME=/path/to/chrome` on
other systems. 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.

See [the 0.3.0 release notes](docs/RELEASE-0.3.0.md) and
[building and releasing](docs/RELEASING.md) for release validation and publication.

## License

[MIT](LICENSE). Copyright (c) 2026 Michael Clifford.
