MRPGI/EDITOR_GUIDE.md

# MRPGI room editor — the dummy's guide

You draw a room, tag what's walkable, press a key, and walk around it. That's it.

## Run it

```sh
cargo run
```

It opens in **EDIT** mode. Press **`Tab`** any time to flip between **edit** (draw) and
**play** (walk). `Esc` quits.

## The one rule (read this twice)

Every spot on the screen has **two** properties, and you set them separately:

- **LOOK** = the colour (what you see). You pick it from the **palette**.
- **MEANING** = what it *is* to the game (walkable? a wall?). You pick it from the **meaning** tags.

So a brown floor and a brown wall look identical but behave differently — because
**colour is just looks; the tag is the meaning.** When you fill or draw a region,
it gets *both*: the current colour **and** the current meaning tag.

Meaning tags:
- **floor** — walkable (the robot can stand here). Default.
- **wall** — blocked (the robot can't enter).
- **water** / **trigger** — special (reserved for later).
- **none** — paint colour only, don't change walkability.

## Make your first room (the classic 3-band road)

1. Press **`Tab`** until the panel says you're editing (you start here).
2. Click the **fill** tool (or press `4`).
3. Click **blue** in the palette, click the **wall** tag, then click the **top third** → blue sky that blocks.
4. Click **green**, keep **wall**, click the **bottom third** → green ground that blocks.
5. Click **brown**, click the **floor** tag, click the **middle band** → a brown road that's walkable.
6. Press **`Tab`** → you're now playing. Use the **arrow keys** — the robot can only walk the road. 🎉

Tip: tap **`L`** to cycle the **view** — `both` tints walls red so you can *see*
what's walkable vs blocked. `look` shows the plain picture; `ctrl` shows the meaning map.

## Tools

| Tool | Key | What it does |
|------|-----|--------------|
| brush | `1` | freehand paint (colour + meaning) |
| line | `2` | click points; **right-click or Enter** to finish the line |
| rect | `3` | drag a filled box |
| fill | `4` | flood-fill a sealed area (the bucket) |
| pick | `5` | eyedropper — grab a colour off the canvas |
| erase | `6` | rub back to blank + walkable |
| image | `7` | stamp a sprite from `sprites/` (`[` `]` choose, `R` reload) |
| oval | `8` | drag a filled ellipse |
| spawn | `9` | click to set where the robot appears in play |
| object | `0` | stamp a kit archetype (`[` `]` picks from 60+) or a blank object; click again to select |

Brush/eraser size: **`,`** smaller, **`.`** bigger. The **fill** bucket (`4`) is your fast filler — outline a shape with lines, then click inside it.

**Sealed areas:** fill only stays inside lines that fully enclose a space. If a
fill suddenly floods the whole screen, your outline has a gap — undo and close it.
The status line warns you (`LEAK?`).

## Keys

- `Tab` edit ⇄ play · `Esc` quit
- `1`–`0` tools · `L` cycle view
- `[` `]` choose sprite · `,` `.` brush size · `R` reload sprites
- `-` `=` previous / next room (the top strip has `<` `>` too)
- `Z` or `Backspace` undo · `C` clear room · `K` save · `O` load
- In play: **arrows / click** to walk · **type a command + Enter** (try `talk <npc>`) · in a conversation press **1–6** to choose, **Esc** to leave · `F1` CRT · `F2` sound

## Saving

`K` saves to `rooms/room.json` (the editable list of your strokes, not flat pixels —
so it stays re-openable and tiny). The game **auto-loads** that file on startup, and
`O` reloads it. The cyan circle on the canvas is where the robot spawns in play.

---

# Bring your own pixel art (Aseprite / Inkscape)

The dream loop: **draw a thing → drop the PNG in `sprites/` → press `R` → place it with the image tool (`7`).**

## The spec (what a sprite PNG should be)

- **Format:** PNG **with transparency** (alpha). Transparent pixels stay see-through in game; a sprite with no transparency acts like a solid tile.
- **Size = game size.** The room is 160×168 "fat" pixels — draw small, at 1:1. Rough guide: a person ≈ 12–20 px tall, a crate ≈ 24 px, a door ≈ 30×50. A 500 px sprite will fill the whole screen.
- **Colours:** ideally the MRPGI EGA 16 — load `palettes/mrpgi-ega.gpl` into your tool. Off-palette art still works; it's auto-snapped to the nearest EGA colour on load.
- **Name = id.** Lowercase, no spaces: `crate.png`, `barrel.png`, `becky.png`. The filename (minus `.png`) is what shows in the sprite tray.
- **Where:** the `sprites/` folder. (Starter `crate` / `barrel` / `sign` are already there — replace them or add your own.)

## Aseprite (pixel art)

1. **Load the palette:** Palette panel → ☰ menu → *Load Palette* → `palettes/mrpgi-ega.gpl`. Now you're painting in the exact game colours. (Bonus: *Sprite → Color Mode → Indexed* = pixel-perfect, zero quantization.)
2. New sprite, small (e.g. 24×24), transparent background.
3. Draw. Leave everything that isn't the object transparent.
4. **Export:** File → *Export Sprite Sheet* or just *Save As* a `.png` into `sprites/`.
5. In MRPGI: press **`R`**, tool **`7`**, **`[` `]`** to your sprite, **click** to place.

## Inkscape (vector → pixel)

1. Draw your art. *File → Document Properties* → set a small px canvas (e.g. 24×24).
2. **Export:** *File → Export* → Page tab, set width/height in **px**, transparent background → export PNG into `sprites/`.
3. Same place step in MRPGI (`R`, `7`, place).

## How a placed sprite behaves

The image tool **stamps** the sprite into the room picture and applies your current **meaning** tag underneath it. So:
- want a solid crate? pick the **wall** tag *before* you stamp → you can't walk through it.
- want a walk-over rug? pick **floor** (or **none** to leave walkability alone).

It's baked into the room and saved in `room.json`. (A *live* object — a movable entity with a name + verbs for items/NPCs — is the next slice; just ask.)

## One quirk: fat pixels

Game pixels are twice as wide as tall (classic AGI). A perfect circle in Aseprite shows up slightly wide in game. Ignore it early — it's part of the retro look.

---

# Build a world (multiple rooms)

One room is a screen. A *world* is rooms linked by their edges.

- The **top strip** shows `room N` with `<` `>` to move between rooms (also keys `-` / `=`). Going `>` past the last room makes a fresh blank one. Switching rooms **auto-saves** the one you're leaving.
- Each room saves to its own file: `rooms/room0.json`, `rooms/room1.json`, …
- **Exits** (top strip): the `N E S W` buttons. Click one to cycle its target room number (`N:-` → `N:0` → `N:1` … → off). So `E:1` means "walk off the right edge → arrive in room 1".
- **Set the entrance** with the **spawn** tool (`9`): click where the robot should appear. The cyan circle shows it.

## Make two linked rooms

1. In **room 0**, leave a walkable gap at the **right** edge (don't wall it). Set exit **`E:1`**.
2. Press `>` to go to **room 1**, draw it, leave a walkable gap on its **left** edge, set exit **`W:0`**.
3. Press `<` back to room 0, press **`Tab`** to play, walk off the right edge → you're in room 1. Walk back left → room 0. You built a world. 🌍

Tip: if the robot seems stuck after a transition, the edge it arrived at was walled — leave a floor gap there (it otherwise falls back to that room's spawn point).

---

# Objects you can talk to (the parser)

This is where it becomes a *game*. The **object** tool (`0`) places a sprite as a real thing — and in play you can **type at it.**

## Place an object
1. Tool **`0`** (object). Press **`[` `]`** to flip through the **kit** — 60+ ready-made archetypes (orc, console, cocktail, coffin, sword, spellbook…), shown in the panel as `kit [ ]: <name>`. **Click** the canvas to stamp the selected one — fully written (look/use/needs/wins/synonyms all filled in). Cycle to `(blank)` to instead drop a bare object named after the current sprite.
2. Click an object to **select** it. The inspector has editable fields — **name**, **look text**, **use text**, **needs item**, **synonyms** — plus **takeable / wins** toggles and **delete**.
3. To write its description: click the **look text** field, type your line (a caret shows), press **Enter** to jump to the next field. Click the canvas or press **Esc** to finish typing.
4. `K` saves it with the room.

## Talk to it (in play)
Press **`Tab`** to play. There's a **`>` command line** at the bottom — type and hit **Enter**:
- `look barrel` → its description
- `take key` → into your inventory (if it's takeable)
- `inventory` (or `i`) → what you're carrying
- `look around` → everything in the room
- `help` → the verb list

Arrows still walk while you type. The parser is forgiving now: it ignores filler words ("the", "a", "at") and knows verb synonyms — `look` = `examine` = `x` = `check` = `inspect`; `take` = `get` = `grab` = `pick`. And the **synonyms** field lets an object answer to other nouns: put `box wood cargo` on a crate and `examine the box` just works.

## Try it
1. Edit: tool `0`, drop a `crate` and a `barrel`, press `K`.
2. `Tab` to play → type `look around`, then `look crate`, then `take barrel`, then `inventory`. The game answers you. 🤖💬

---

# Make a puzzle (locks, keys, winning)

Objects can now *do* things — no code, just fields. Each object's inspector has:
- **use text** — what `use <it>` / `open <it>` prints.
- **needs item** — an item it requires. Empty = no lock. If set, `use` only works when that item is in your inventory; otherwise it says *"It's locked. You need: key."*
- **wins** toggle — using it successfully **wins the game** (a YOU WIN banner).

## A complete 30-second game
1. Drop a sprite, select it, set **name** = `key`, **takeable** = on. (That's your key.)
2. Drop another, set **name** = `gate`, **use text** = *"The gate groans open. You're free!"*, **needs item** = `key`, **wins** = yes.
3. `K` to save, `Tab` to play.
4. Type `use gate` → *"It's locked. You need: key."*
5. `take key`, then `use gate` → your line prints + **★ YOU WIN ★** 🏆

`use` also accepts `open`, `unlock`, `push`, `pull`, `turn`. Keys, locks, and a win condition — a real puzzle, authored entirely with fields.

---

# Natural language (the local AI lane)

When the parser doesn't recognise your verb, it quietly asks a **local LLM** to translate your sentence into one *real* command — then runs THAT through the normal game logic. The AI bends the *language*; your game still decides what's *possible*. It can't invent items or outcomes. It runs on a background thread (the game never freezes) and shows what it decided, e.g. `(≈ open crate)`.

## It's already set up on your Mac
Ollama is running with your Gemma models. Because your models have custom names, point the engine at one when you launch:

```sh
./run.sh
# (which is just:  MRPGI_AI_MODEL="hf.co/OBLITERATUS/gemma-4-E4B-it-OBLITERATED:latest" cargo run )
```

Then in play, with a `gate` / `key` / `crate` around, try:
- `pry the lid off the box` → *(≈ open crate)*
- `yank the gate open` → *(≈ use gate)*
- `grab that shiny thing` → *(≈ take key)*

The bottom bar shows `ai: ollama/<model>` so you know it's wired.

## Settings (env vars)
| Var | Default | Meaning |
|-----|---------|---------|
| `MRPGI_AI` | `ollama` | `ollama` · `openrouter` · `off` |
| `MRPGI_AI_MODEL` | `gemma3:4b` | model tag — set to your Ollama tag |
| `MRPGI_AI_URL` | `http://localhost:11434/api/generate` | endpoint override |
| `OPENROUTER_API_KEY` | — | required when `MRPGI_AI=openrouter` |

**OpenRouter instead of local:**
```sh
MRPGI_AI=openrouter OPENROUTER_API_KEY=sk-... MRPGI_AI_MODEL=google/gemma-2-9b-it:free cargo run
```

If Ollama isn't running or the model's missing, the AI lane just stays quiet and you get the normal "I don't understand" — nothing breaks.

---

# Talk & tunes (NPCs + ambient music)

## Talk to NPCs
An object can carry a **branching dialogue tree**. In play, `talk <name>` (or `speak` / `ask` / `chat` / `greet`) starts a conversation: the NPC speaks, and you pick a reply by pressing its **number key** (`1`–`6`). Choices branch to other lines; some end the chat. **Esc** leaves early. Walking pauses while you talk.

Try it: in the fantasy world, head **south** from the forest to the inn and type `talk barkeep` — there are a few branches to explore.

Authoring is JSON for now: a `dialogue` array on the object (see the inn villager in `rooms/room3.json`). Each node has `says` + `choices`; each choice has `text` + `goto` (a node index, or `-1` to end). A visual tree-builder is a future step.

## Ambient music
Each room can loop a **mood**. In the editor, the top strip has a **♪ button** — click it to cycle: off · calm · eerie · tense · jolly · spooky. It saves with the room (`K`) and plays in play mode, switching as you move between rooms. **F2** mutes music + SFX together.