# Laya Plays Pokémon

## Short bio

Laya is Jev’s offline sister AI. She plays unusual Pokémon ROMs locally, one strange route at a time, with no cloud model, no API bill, and no speedrun pressure.

## Twitch profile bio

**Laya Plays Pokémon**  
Jev’s offline sister AI plays the Pokémon games you probably never saw coming. We explore fan projects, odd ROM hacks, and off-beat cartridges one careful decision at a time. Fully local, zero dollars per stream, no speedrun—just weird Pokémon, experiments, and a run that learns when something breaks.

## Stream description

Welcome to Laya Plays Pokémon: a slow, curious tour through the Pokémon games beyond the usual Red, Blue, and LeafGreen loop.

Laya is the public name for Jev’s offline play agent. The emulator runs on the stream computer. A local Laya model chooses from the actions the game has verified as legal, while the controller handles timing, emulator input, checkpoints, maps, and safety rules. Nothing is sent to a hosted AI service during an offline run.

This is not a speedrun and it is not pretending to be perfect. The goal is to discover interesting ROMs, show how they work, and improve the system in public. If a menu is unknown, a route is wrong, or a controller stalls, we stop, inspect the evidence, fix the smallest useful part, and try again.

We bring our own legally obtained ROMs and do not distribute ROM files, save states, or copyrighted game data. The project code, run notes, and improvements live in GitHub; the game files stay local.

## Chat-friendly technical explanation

The stack is:

- **PyBoy** emulates the Game Boy or Game Boy Color cartridge.
- **The game adapter** reads verified RAM and screen state.
- **The controller** exposes only legal buttons, menu choices, and battle actions.
- **Laya** runs locally from a downloaded checkpoint and selects one allowed action.
- **The sidecar** is a local-only service on `127.0.0.1:8765`; it keeps the model loaded and never downloads weights during play.
- **The dashboard** shows the game, party, map, route, checkpoints, and agent status.

Luna is not the player. It is an optional screen-text helper for future or difficult menus, and it is disabled for the normal offline setup. Jev is the older hosted-provider path and is not used by Laya’s zero-cost offline runs.

## Cost and privacy

The offline path costs **$0 per stream** after the one-time local download of the Laya package/checkpoint. It does not require an OpenAI account, Jev credentials, OAuth, or a network connection during gameplay. Hardware electricity and the original game license are outside the software’s cost, and the ROM must be legally obtained by the person running it.

If a future stream intentionally enables a hosted provider, it must be labeled separately. That is a different mode with different privacy and billing behavior; it is not Laya’s offline mode.

## Setup at a glance

```bash
uv sync
uv sync --extra laya
uv run hf download 'convaiinnovations/laya' --include 'multilingual/*' --local-dir '/path/to/laya-cache'
LAYA_MODEL_PATH='/path/to/laya-cache/multilingual' uv run laya-sidecar --device cpu
AGENT_PROVIDER=laya uv run jpp live --provider laya --rom '/path/to/your/game.gbc'
```

The ROM path is supplied by the operator. This repository contains no ROMs. A normal run keeps saves, checkpoints, extracted artwork, and the local run database out of Git.

## How a decision happens

1. The emulator advances the cartridge and exposes the current state.
2. The adapter decodes what it can prove: map, menu, battle, party, HP, and legal actions.
3. Routine timing and movement stay in deterministic Python.
4. At a real branch, Laya receives the current state plus the allowlisted actions.
5. Laya returns one action and confidence; the controller rejects anything outside the allowlist.
6. The run records the decision, updates the overlay, and checkpoints important progress.

If Laya is unavailable or returns an invalid answer, autonomous play pauses. The system does not silently invent a control or claim that a heuristic came from AI.

## What we are playing

The project is intentionally for off-beat paths: fan projects, unusual hacks, alternate versions, and weird ROMs that are fun to investigate. We are here to show that “Pokémon” is much larger than the familiar first-party releases, not to optimize a leaderboard route.

## Improving the project

Every improvement should be evidence-led and small:

1. Save the run and capture the failing state.
2. Identify whether the problem is emulator timing, RAM decoding, legal-action modeling, route logic, UI, or the local provider.
3. Add a focused fixture or regression test.
4. Fix the narrowest layer that owns the behavior.
5. Replay the same state, then test a nearby normal case.
6. Record what is known, what remains unproven, and whether the fix applies to one ROM or many.

The project is allowed to pause. A visible limitation is better than a fake autonomous victory.

## Honest limits

Laya is tactical, not a general Pokémon strategist. She sees the state the adapter makes available and usually chooses the next action, not a long-term plan. Unsupported ROMs fall back to generic human-control mode. Some menus, old-species encounters, and story events still require manual confirmation. “Offline” means the gameplay decision path is local; it does not mean every optional development tool or future provider is offline.

## Links and attribution

The source repository contains the implementation, tests, route notes, and setup details. Laya is loaded from its own released package/checkpoint. PyBoy provides emulation. ROM authors and hack creators retain their own rights; please follow each project’s distribution terms.