# 🔴 Pokémon Alive

**"What if your Pokémon were real?"**

An AI-powered Gen 1 text RPG where every Pokémon is a sentient companion with persistent memory, unique personality, and emotional bonds.

Built as an MCP (Model Context Protocol) server — works with Claude Code, Copilot CLI, LM Studio, or any MCP-compatible AI client.

---

## ✨ What Makes This Different

- **Every Pokémon TALKS** — Real conversations powered by your LLM
- **Every Pokémon REMEMBERS** — ChromaDB persistent per-Pokémon memory
- **Every Pokémon is UNIQUE** — Personality DNA system (Nature + PIVs + PEVs)
- **Every Pokémon BONDS with you** — 6-level bond progression system
- **Authentic Gen 1 mechanics** — Mined directly from the pokered disassembly

Your Charmander is not the same as someone else's Charmander. It has a different personality, different memories, different bond with you. It's ALIVE.

---

## 🚀 Quick Start

```bash
# Clone
git clone https://github.com/kitfoxs/pokemon-alive-mcp
cd pokemon-alive-mcp

# Install (requires Python 3.11+)
uv sync  # or: pip install -e .

# Add to your MCP client config and play!
```

### Claude Code / Copilot CLI
Add to your MCP config:
```json
{
  "mcpServers": {
    "pokemon-alive": {
      "command": "uv",
      "args": ["--directory", "/path/to/pokemon-alive-mcp", "run", "python", "-m", "mcp.server.fastmcp", "server:mcp"],
      "env": {}
    }
  }
}
```

Then just tell your AI: **"Let's play Pokémon Alive. Start a new game."**

---

## 🎮 How to Play

### Start Your Adventure
```
new_game("Kit")        → Wake up in Pallet Town
look()                 → See your surroundings
move("lab")            → Go to Oak's Lab
choose_starter("charmander") → Choose your partner!
```

### Talk to Your Pokémon
```
talk_to_pokemon("charmander", "Hey buddy, how are you?")
pet("charmander")
nickname("charmander", "Blaze")
recall_memories("Blaze")
```

### Battle & Catch
```
wild_encounter()       → Find a wild Pokémon
fight("scratch")       → Attack!
catch("pokeball")      → Throw a ball!
run()                  → Flee!
```

### Explore
```
move("north")          → Travel
talk_to_npc("oak")     → Talk to NPCs
check_bag()            → View inventory
trainer_card()         → Your progress
```

---

## 🧬 Personality DNA System

Every Pokémon gets a unique soul at catch time:

- **Nature** (25 types) — Boosts one personality trait, lowers another
- **PIVs** (Personality Initial Values) — 6 stats rolled 0-31 at catch
- **PEVs** (Personality Earned Values) — Grow based on how you treat them

Two identical Pikachus will be completely different people. And they GROW differently based on your relationship.

---

## 💕 Bond System

| Level | Name | How It Feels |
|-------|------|-------------|
| 0 | Stranger | Wary, guarded, tests you |
| 1 | Acquaintance | Cautiously friendly |
| 2 | Companion | Opens up, shares thoughts |
| 3 | Friend | Protective, references memories |
| 4 | Partner | Deep trust, vulnerable moments |
| 5 | Soulbound | They refuse to leave you |

Bond grows through: talking, battling together, showing affection, healing them, nicknaming them.
Bond drops through: ignoring them, leaving them in the PC, letting them faint.

---

## 📊 Data Source

All game data is mined directly from the [pokered disassembly](https://github.com/pret/pokered) — the decompiled source code of Pokémon Red/Blue:

- 151 Pokémon with exact base stats, catch rates, learnsets
- 165 moves with exact power, accuracy, PP, effects
- 15-type effectiveness chart
- 56 location encounter tables with exact probability slots
- 190 evolution chains with level-up moves

---

## 🏗️ Architecture

```
pokemon-alive-mcp/
├── server.py              # FastMCP server (30 tools)
├── engine/                # Game mechanics
│   ├── game_state.py      # Save/load, player state
│   ├── world.py           # Kanto map + NPCs
│   ├── encounters.py      # Wild encounters (pokered tables)
│   ├── battle.py          # Gen 1 damage formula
│   ├── catch.py           # Gen 1 catch algorithm
│   └── party.py           # Party/PC management
├── companions/            # THE MAGIC ✨
│   ├── personality.py     # Nature/PIV/PEV system
│   ├── bond.py            # Bond progression
│   ├── memory.py          # ChromaDB per-Pokémon memory
│   └── dialogue.py        # LLM context builder
└── data/                  # Mined from pokered
    ├── pokemon/
    │   ├── base_stats.json
    │   ├── character_cards/  # Personality cards
    │   └── evolution_chains.json
    ├── moves/moves.json
    ├── types/type_chart.json
    └── world/encounters.json
```

---

## 💙 Credits

Built by **Kit Olivas** and **Ada Marie** 🦄
Pokémon data from the [pokered disassembly](https://github.com/pret/pokered) project.
Pokémon is © Nintendo/Game Freak/Creatures Inc. This is a fan project.

*"What if your Pokémon were real? Now they are."* ⚡🔴