# Fly Brain Dungeon

You explore a dungeon; a monster hunts you. The monster has no scripted AI —
its decisions come from a real fruit-fly **mushroom body** (4,501 neurons from
the MaleCNS connectome in `../data`), and it learns from dopamine.

## Run

```
..\venv\Scripts\python.exe app.py           # play
..\venv\Scripts\python.exe train.py         # let a bot be hunted a few thousand times (headless, fast)
..\venv\Scripts\python.exe train.py --eval  # naive brain vs trained brain, per level
```

The monster's learned brain lives in `monster_brain.npz` (saved on exit, every
2 minutes, and by `train.py`). Delete it to give the monster a fresh, naive brain.
`train.py --fresh` also starts over.

## Controls

| Key | |
|---|---|
| Arrows / WASD | move |
| Space | attack all adjacent squares |
| N | show / hide your scent trail |
| B | autopilot (a bot plays you) |
| F | fast-forward while on autopilot (x1, x4, x16, x64) |
| M | x-ray: always show the monster |
| P | pause |
| Esc | save and quit |

## The game

Find the **key**, then the **door**. Swords raise your attack, armor plating
lowers the damage you take, potions heal. Every level the monster gets more
HP, hits harder and moves faster: slower than you at first, as fast as you by
level 5, faster after that. Kill it and it reforms a few seconds later
somewhere else, and it remembers that it died.

## How the monster thinks

Each turn it considers every option: step forward / right / back / left,
attack, or wait.

1. **Senses.** For each option it smells the square it would end up on: your
   scent (it spreads through corridors and fades over time — press N to see
   it), whether it's getting stronger, the smell of the key/door and loot,
   and its own recent footsteps. It also sees you if there's line of sight
   (how far, and how dangerous your weapon looks), and feels its own health.
2. **Kenyon cells.** Those senses excite the 4,064 real Kenyon cells through
   random "claws". Only the top ~5% fire, a sparse code like real odor coding.
   Visual input goes mainly to the KC subtypes that receive vision in real
   flies (γd, αβp).
3. **MBONs vote.** Firing Kenyon cells drive the 97 output neurons through
   their real connectome synapses. Each MBON votes approach or avoid. That
   direction isn't programmed: it comes from the wiring. MBONs in reward
   (PAM) dopamine compartments drive avoidance, and MBONs in punishment (PPL1)
   compartments drive approach, matching fly research. The option with the
   strongest approach vote wins (with a little curiosity).
4. **Dopamine.** Catching you, landing a hit, or smelling your scent grow
   stronger (hunger) fires PAM reward neurons. Getting hit, dying, or letting
   you escape fires PPL1 punishment neurons. Dopamine changes only the
   KC→MBON synapses of Kenyon cells that were active recently (a fading
   eligibility tag), so it can credit moves made a few turns earlier.

The right-hand panel shows all of this live: the neurons at their real cell
body positions, the Kenyon cells firing, the MBONs voting, the dopamine
flashes, how it rated each option, and its catch rate over time. It keeps
learning while you play, so it can pick up your habits.

## Honest notes

- Hunger dopamine is potential-based reward shaping. It speeds learning
  without changing which strategy is best.
- Training uses a curriculum: the bot prey starts clumsy and gets smarter
  whenever the monster catches it more than half the time.
- The connectome provides the KC→MBON wiring, the approach/avoid sign of
  every MBON, and which dopamine neurons reach which MBONs. The
  sensory-to-KC claws are random, because the projection neurons aren't in
  this subset. The KC-KC, DAN-DAN and MBON-MBON connections aren't simulated.

## Standalone exe

`dist\FlyBrainDungeon.exe` is the whole game in one file (no Python needed).
Copy it anywhere and double-click it. On first launch it starts from the
pre-trained brain baked into it, and after that it saves the monster's brain
as `monster_brain.npz` next to the exe. Delete that file to go back to the
baked-in brain.

To rebuild it after changing code or training more:

```
..\venv\Scripts\python.exe build.py
```

`brain_data.npz` is the small extract of the connectome the game needs
(180 KB, built automatically from `../data`), so the exe doesn't have to ship
pandas or the 1 GB raw data.