# gameLLM — Game Guide Assistant

A Claude Code knowledge base for video games. Scrapes guides from multiple portals, stores structured game data, and exposes everything through an MCP server and a set of Claude Code skills so you can ask questions in natural language.

Currently supports **Clair Obscur: Expedition 33** out of the box. Structured data (pictos, weapons, bosses, skills, side areas, status effects, etc.) is included in the repository and works immediately without scraping anything.

## Disclaimer

This project is a personal, non-commercial tool for private study and reference.

- **Content ownership:** All scraped content belongs to the respective source sites (Vandal, Eliteguias, Game8, IGN, Mein-MMO, Maxroll, etc.). This repository does not include any scraped data — the `output/<game>/<portal>/` directories are excluded from version control and must be generated locally.
- **Game intellectual property:** Game names, characters, mechanics, and all related assets are the property of their respective owners (e.g. Sandfall Interactive for *Clair Obscur: Expedition 33*). This project is not affiliated with, endorsed by, or connected to any game developer or publisher.
- **No affiliation:** This project has no affiliation with any of the scraped websites or their owners.
- **Terms of Service:** Web scraping may be restricted by the Terms of Service of some sites. Anyone running this tool is solely responsible for ensuring compliance with the terms of any site they scrape.
- **No warranty:** Scraped content may be incomplete, outdated, or inaccurate. This tool is provided as-is, with no guarantees regarding the correctness or completeness of the data it produces.

---

## Quick Start

```bash
git clone <repo>
cd gameLLM
pip install -r requirements.txt
```

Open the project in **Claude Code**. The MCP server (`mcps/ex33mcp/`) starts automatically via `.mcp.json` — no manual setup needed.

---

## Querying Expedition 33

Use the `/ex33-guide` skill in Claude Code to ask anything about the game:

```
/ex33-guide what's the best build for Maelle?
/ex33-guide where do I find the Lost Gestrals?
/ex33-guide what pictos work well with a burn build?
/ex33-guide which bosses are in act II and what level should I be?
/ex33-guide what does the Foretell status effect do?
```

The skill queries the MCP server first for structured data, then falls back to scraped guides if needed.

### What data is available without scraping

The `output/expedition-33/data/` directory is included in the repository and covers:

| File | Content |
|------|---------|
| `pictos.md` | All pictos — names (EN/ES), effect, LP cost, location |
| `weapons.md` | All weapons — stats, scaling, passives, per character |
| `skills.md` | All skills — names (EN/ES), AP cost, character, effect |
| `boss-levels.md` | All bosses — recommended level, location, type |
| `side-areas.md` | Optional areas — act, recommended level, rewards |
| `skill-damage-scaling.md` | Damage scaling numbers per character and skill |
| `monoco-skills.md` | Monoco learnable skills and source enemies |
| `status.md` | Status effects — names (EN/ES) |
| `zone-mapping.md` | Zone name translations EN↔ES |
| `quests.md` | Side quests |
| `expedition-journals.md` | Collectible journals |
| `music-records.md` | Collectible music records |
| `lost-gestrals.md` | Lost Gestral locations |
| `mimes.md` | Mime locations |
| `petanks.md` | Petank locations |
| `paint-cages.md` | Paint cage locations |
| `outfits.md` | Outfits |
| `haircuts.md` | Haircuts |
| `tint-upgrades.md` | Tint upgrades |
| `endless-tower.md` | Endless Tower floors |

### MCP tools

The MCP server exposes these queryable tools (used automatically by `/ex33-guide`):

| Tool | Description |
|------|-------------|
| `search_pictos` | Search pictos by name (EN/ES), effect, or attribute |
| `search_weapons` | Search weapons by name, passive, damage type, or character |
| `search_bosses` | Search bosses by name or location; filter by type and level range |
| `search_side_areas` | Search optional areas by zone name or reward; filter by act |
| `get_skill_scaling` | Damage scaling data for a character's skills |
| `evaluate_picto_lumina` | Recommend whether to use a picto as Picto or Lumina |
| `search_status` | Translate status effect names EN↔ES |

---

## Adding Content

### Scrape more portals for Expedition 33

```bash
python scrape.py <guide_url> --game expedition-33
```

After scraping, run `/ex33-index` in Claude Code to update the portal index.

### Add a new game

```bash
# 1. If the site isn't supported yet, generate a scraper:
/scraper-creator   ← provide the URL in Claude Code

# 2. Scrape the guides:
python scrape.py <url> --game <slug>

# 3. Bootstrap the game (generates _index.json + guide skill):
/game-setup <slug>

# 4. Start querying:
/<slug>-guide
```

---

## Output Structure

```
output/
└── <game-slug>/
    ├── <portal>/
    │   ├── 001-section-title.md
    │   ├── 002-another-section.md
    │   ├── _guide.md         ← all sections concatenated
    │   └── README.md         ← section index
    ├── data/                 ← structured data (included in repo)
    └── _index.json           ← portal index
```

---

## Technical Reference

### Supported scraping sites

| Domain | Scraper | Notes |
|--------|---------|-------|
| `vandal.elespanol.com` | `VandalScraper` | SSR, requests |
| `www.eliteguias.com` | `EliteGuiasScraper` | SSR, requests |
| `game8.co` | `Game8Scraper` | SSR, requests |
| `mein-mmo.de` | `MeinMMOScraper` | SSR, requests |
| `www.ign.com` | `IGNScraper` | **Playwright required** — React-rendered |
| `maxroll.gg` | `MaxRollScraper` | requests |
| Any other URL | `SinglePageScraper` | Use `--single-page`; auto-upgrades to Playwright if JS-rendered |

IGN scraper additionally requires:

```bash
pip install playwright && playwright install chromium
```

### Scraper architecture — `scrapers/base.py`

`GuiaScraper` is an abstract base class. Subclasses implement:

- `extract_guide_links(soup, guide_url) → list[{title, url}]` — discovers all sections
- `extract_content(soup) → Tag` — extracts and cleans article content
- `extract_guide_title(soup) → str` — page title (optional override)
- `output_slug(guide_url) → str` — portal directory name

| Attribute | Default | Description |
|-----------|---------|-------------|
| `REQUEST_DELAY` | `1.5` | Seconds between requests |
| `RECURSIVE_LINKS` | `False` | Enable BFS link discovery |

`run()` fetches the index, iterates sections writing numbered `.md` files, resumes from existing files on re-run, and writes `_guide.md` + `README.md` at the end.

**BFS link discovery (`RECURSIVE_LINKS = True`):** Some sites (IGN) only link sub-pages from category pages, not the index. BFS discovers links as it scrapes. Cached pages are not re-fetched for new links — delete the portal directory to start fresh.

### Scraper notes

**IGN** — React-rendered; uses Playwright. Waits for `.wiki-html`. `RECURSIVE_LINKS = True` because category pages hold the individual boss/quest sub-pages. Known working selector: `.wiki-html` (`.wiki-section` fires too early).

**Game8** — SSR. Content in `.archive-style-wrapper`. Do not use `main` — on game8 it only contains the membership modal.

**SinglePageScraper** — Tries `requests` first; auto-upgrades to Playwright if body < 300 chars. Steam guides work via plain requests (`#profileBlock`).

### Adding a new scraper manually

1. Create `scrapers/<name>.py` subclassing `GuiaScraper`
2. Implement `extract_guide_links`, `extract_content`, `output_slug`
3. Register the domain in `scrape.py`'s `SCRAPERS` dict

Use `/scraper-creator` in Claude Code to automate this — it fetches the target page, analyzes the HTML structure, and generates the scraper class.