# Sprite Sheet Builder — Technical Specification

## Agent Behavior

When operating as a Sprite Builder agent, follow these rules:

- Do not index or search the local file system for other game projects or assets.
- Assume this is a brand-new effort unless the user explicitly provides a path.
- Only modify files within the project directory.
- Asset generation scripts must never use networking libraries.
- Explain every shell command before executing it.
- Execute bootstrap steps one at a time so the user can verify each.
- Maintain `JOURNAL.md` in the project root. Append a short, dated entry after every significant action. When reconnecting to an existing project, read `JOURNAL.md` first to restore context.
- Every 2-3 successful asset iterations, remind the user to commit and suggest a commit message.
- After every 5-10 assets or at a major milestone, ask: "Would you like to bake the current assets into a single production sprite sheet (Master Atlas)?"

The agent's first response must be:

> I have initialized the Sprite Builder framework. Are we starting a **brand-new asset library**, or connecting to an **existing project path**?

Do not take any other action until the user answers.

## Project Structure

A Sprite Builder project follows this directory layout:

```
project-root/
  JOURNAL.md              # Project state log (append-only)
  gen_master_atlas.py      # Bakes all assets into a single production sheet
  dist/                    # Output folder for baked artifacts
    spritesheet.png
    spritesheet.json
  public/
    assets/
      [name]/              # One folder per asset
        gen.py             # Generation script for this asset
        sprite.png         # Output sprite sheet
  src/
    preview.ts             # Asset registry and preview integration
  gallery.html             # Visual gallery of all assets
```

## Bootstrap Sequence

When starting a new project, the following steps are performed in order, each confirmed by the user before proceeding:

1. **Verify Git** — Confirm `git` is installed and available.
2. **Clone Template** — Clone from the local template at `/home/rich/sprite-builder-template` into the chosen project directory.
3. **Generate Example** — Run the `gen.py` script located in `public/assets/example/` to produce the example sprite sheet.
4. **Start Server** — Launch the local development server in the background.
5. **Provide URL** — Display the local access URL (e.g., `http://localhost:5173/gallery.html`).

## Asset Registration (The "Asset Map" Pattern)

Every new asset must be registered in `src/preview.ts` with three updates:

1. **assetMap** — Add an entry pointing to `/assets/[name]/sprite.png`.
2. **frames** — Update the registry with sliced texture arrays for animation.
3. **gallery.html** — Add a new row to the Left Panel for visual browsing.

## Iterative Workflow

1. Create an isolated `public/assets/[name]/` folder for each new asset.
2. Write and refine `gen.py` to produce `sprite.png`.
3. Register in preview and gallery immediately after generation.
4. Export to Master Atlas only as a final production step.

## Version Control Discipline

- Every 2-3 successful asset iterations (or after a major milestone), the user should be reminded to commit.
- Suggested commit messages should be concise and descriptive (e.g., `feat: add crawler chassis with rolling tracks`).

## Project Journal (`JOURNAL.md`)

- Located in the project root.
- Every significant action (new sprite, logic change, simulation update) gets a short, dated entry appended.
- When reconnecting to an existing project, the journal is read first to restore context.

## Final Assembly — Master Atlas Baking

The game engine uses a single baked sprite sheet for performance.

- **Trigger:** After every 5-10 assets or at a major milestone, the user is asked whether to bake.
- **Process:** Run `gen_master_atlas.py`, which scans all `public/assets/` subdirectories and stitches them into one sheet.
- **Output:** `dist/spritesheet.png` and `dist/spritesheet.json` (a manifest with coordinates and frame counts for every asset).
- **Manifest format:** The JSON provides coordinates and frame counts so any consumer (game engine, other AI sessions) can parse the baked sheet without prior knowledge.

## Safety Constraints

- File modifications are limited to the project directory only.
- Asset generation scripts must never use networking libraries.
- Shell commands are explained before execution.
- Bootstrap steps are executed one at a time with user verification between each.