# Crystal

A native web port of Pokémon Crystal, translated from [PRET's Game Boy disassembly](https://github.com/pret/pokecrystal). The game runs in TypeScript and reads graphics, maps, sprites and dialogue from the user's own ROM. No original game assets are included.

**Current milestone: New Bark Town exploration.** Walk around your room, downstairs, town and its buildings. Read signs, use the bedroom radio, try supported conversations, and save your progress. Opening scenes, story progression, battles, NPC movement, decorations, audio and the rest of the world are still being ported.

## Run

Requires Node.js 22.12 or newer.

```sh
npm ci
npm run dev
```

Open the printed local URL, choose a name/character and select your uncompressed **English US/Europe revision 1.1** ROM (`.gbc`, 2 MiB). Its checksum is verified locally. ROMs are never uploaded or stored in browser storage; select yours again after reloading to resume.

Use onscreen controls, or focus the game screen and use arrows to move, **X** to interact and **X / Z** to continue dialogue. Sessions save every 10 seconds and when paused. Switching apps pauses play. Download a backup before clearing browser data.

Native saves are separate from emulator snapshots and cartridge `.sav` files. Time-of-day colors follow the device clock. The tile counter measures in-game movement, not real-world steps.

## Reference emulator

During development, open **`/reference.html`** to run the original game for comparison. It has separate saves and does not run inside the native player. Reference tools and the emulator are excluded from the default build.

```sh
npm run build             # Native application in dist/
npm run check:release     # Check the native distribution
npm run build:reference   # Optional reference in dist-reference/
```

Serve `dist/` through an HTTPS static host, or use `npm run preview` locally. Subdirectory hosting is supported with `npm run build -- --base=/Crystal/`. Use HTTPS from another device; ROM verification and save locking require a secure context.

## Development

```sh
npm test
npx playwright install chromium webkit
npm run test:e2e
npm run check:vendor
```

Local-ROM tests use `Pokemon - Crystal Version (UE) (V1.1) [C][!].gbc` at the root, or `CRYSTAL_ROM_PATH`. They skip when absent; no test downloads a ROM. Game files, private reference builds and gameplay screenshots must remain ignored.

The [full port plan](docs/PLAN.md) covers remaining game systems, mobile UI, internet Link and walking. See the [architecture](docs/ARCHITECTURE.md) and [routine map and verification](docs/NATIVE_PORT.md) for module boundaries and reference checks.

References: PRET [documentation](https://pret.github.io/pokecrystal/), [wiki](https://github.com/pret/pokecrystal/wiki) and [source](https://github.com/pret/pokecrystal). The development reference uses [binjgb](https://github.com/binji/binjgb) under its [MIT license](reference/public/vendor/binjgb/LICENSE); see [provenance](reference/public/vendor/binjgb/PROVENANCE.md).

Independent project. Not affiliated with Nintendo or Game Freak.