mirror of https://github.com/bryanthaboi/gen1recomp.git synced 2026-08-25 15:01:11 +02:00

Files

T

bryanthaboi ca4d3d283c Add Pokemon Crystal as a sixth supported version

Crystal boots from a user-supplied ROM, imports a full cache and is playable:
copyright, the Crystal intro movie, the animated title, gender select, Oak,
and out into Johto. 122 of the cart's 169 script specials are implemented.

Import and data
- tools/make_crystal_manifest.py derives the manifest by importing
  make_gold_manifest as a library, with three additive keyword seams. Gold and
  Silver still regenerate byte-identical, which is the standing requirement for
  touching that generator.
- crystal_symbol_deltas.py and crystal_movie_symbols.py carry the symbol delta:
  Crystal renames the credits mons, splits the trainer card, Pokegear and
  pack-pal blocks by gender, and replaces the intro and title outright.
- Crystal-only manifest keys: engineFlagOrder (162 flags to Gold's 93, so the
  badge block sits one higher) and unownCharmap (the main charmap parser stops
  at the first newcharmap so the two cannot contaminate each other).

Extractor
- RomExtractorGen2 becomes three-edition. Crystal corrections: PAL_MAP_BANK
  0x13, a flat PICS_FIX pic bank, audio bank 0x5e, the mapSongs id-100 hole,
  seven NPC trades, a TradeTexts stride of 8, the five Crystal tileset anim
  steps with per-row degrade, and the column-major trainer card portraits.
- New: animated front sprites (frames, bitmasks, play and idle scripts), the
  Battle Tower roster, Kris assets, Mobile System GB art, and the Crystal
  intro and title via src/import/CrystalMovie.lua.

Engine
- GameVersion gains engine(id) and fixes(id). Gold and Silver keep their
  original bugs where the bug is not hardware dependent; Crystal gets the fixes
  Crystal shipped: Lucky Number boxes 10-14, surfing onto an NPC, and the
  Reflect and Light Screen defence overflow.
- Crystal story: Suicune and Eusine, Celebi behind the GS Ball flag, the Ruins
  of Alph chambers, Buena, the Move Tutor, the Poke Seer, and the Battle Tower
  including the wInBattleTowerBattle badge-boost guard.
- Kris and the gender flag, animated fronts in battle and the summary screen,
  and mon caught data.

Verification
- Every extracted asset is pixel-compared against pret's own source PNGs.
- Gold caches are byte-identical before and after, file for file.
- New Crystal suites plus a T2 Gen 2 tier; the full suite passes.

2026-08-23 12:10:28 -04:00

7.3 KiB

Raw Blame History

Switch file transfer (MTP / SD / FTP)

Ways to put Gen1Recomp artifacts and inbox files onto a Nintendo Switch. Any method is valid if the bytes land in the destinations below.

This is the runbook for contributors on macOS, Linux, and Windows. Player install (what to download, title override) stays in switch-install.md. Packaging stays in switch-build.md.

Not supported yet: nxlink / hbmenu netloader automation. Useful later for a fast contrib rebuild loop; deferred (AD-009). Do not treat netloader as the release or ROM/mod install path.

Destinations (shared by every method)

What	Where on the console
SD-ready release zip	Extract at microSD root → `sdmc:/switch/gen1recomp/gen1recomp.nro` plus `pokemon-love2d/` inbox folders. Install and update use the same merge; do not delete `pokemon-love2d/`
Loose iteration pair	`sdmc:/switch/gen1recomp/gen1recomp.nro` and `game.love` beside it
ROM inbox	LÖVE save dir → `imports/` (launcher shows the live `getSaveDirectory()` path; under MTP often `1: SD Card/<save identity>/imports/`)
Mod zip inbox	Same save dir → `imports/mods/` then MODS → Scan again
Save `.sav` inbox	Same save dir → `imports/saves/red\|blue\|yellow\|gold\|silver\|crystal/` then that game's SAVE FILES → Import save (Gen 2 cart `.sav` not supported yet, on Gold, Silver or Crystal)
Save exports	Same save dir → `exports/red\|blue\|yellow\|gold\|silver\|crystal/` (pull after Export save; Gen 2 cart `.sav` not supported yet, on Gold, Silver or Crystal)
Opt-in diagnostics	Empty `switch-debug.txt` in the save dir → `switch.log`
Lua error log	`lua-error.log` in the save dir

Saves persist across zip re-extract / NRO replacements as long as pokemon-love2d/ is left in place. Never commit ROM dumps, .sav files, or third-party mod zips to git.

Transfer methods

1. MTP (DBI responder + host client)

On the Switch: close Gen1Recomp → open DBI → Run MTP responder (often X on the main screen) → keep that screen up → USB-C data cable to the host.

On the host: open one MTP client, navigate to 1: SD Card, then the paths above. Wait for the transfer queue; refresh; exit MTP on the Switch before launching.

macOS (example: OpenMTP)

OpenMTP is a documented example for macOS, not a Mac-only requirement.

Quit other MTP clients.
Open OpenMTP → select the DBI device → 1: SD Card.
Create switch/gen1recomp/ if needed; extract the release zip at SD root (or copy NRO / game.love for loose).
For ROMs/mods/saves, open the save-dir imports/, imports/mods/, imports/saves/<red|blue|yellow|gold|silver|crystal>/, or exports/<red|blue|yellow|gold|silver|crystal>/ path the launcher prints.
Wait for the queue; refresh; exit MTP responder; title-override launch.

macOS clients often create AppleDouble sidecars (._Something.zip, ._cart.gb, ._foo.sav). Those are not real archives or saves. The launcher skips hidden .* names. Delete ._* junk if a zip/ROM/.sav fails to open.

Linux

Install desktop MTP support if needed (e.g. gvfs-mtp on GNOME/GTK desktops, or your distro's KDE MTP stack).
With DBI MTP active, open Files / Dolphin / Thunar and select the Switch / DBI device → 1: SD Card.
Extract the release zip at SD root (merge), or copy into switch/gen1recomp/ and the save-dir inboxes as above.
Use only one MTP accessor at a time. If mtp-tools / mtpfs reports "device is busy", close the file manager's MTP mount (or the CLI mount) and retry with a single client.
Eject/unmount cleanly; exit MTP on the Switch; title-override launch.

If MTP is unavailable or flaky on Linux, use direct SD (Hekate UMS or a card reader) or FTP instead. Same destinations in the table above.

Windows

With DBI MTP active, open This PC / File Explorer and look under Portable Devices for the Switch / DBI MTP volume → 1: SD Card.
Copy / extract into switch\gen1recomp\ and the save-dir inboxes.
Optional: OpenMTP on Windows if Explorer is flaky.
If Windows does not show an MTP device: Device Manager → find DBI / Switch → Update driver → MTP USB Device (or Standard MTP Device). Prefer a data-capable USB-C cable and a direct port.
Safely disconnect; exit MTP on the Switch; title-override launch.

If MTP is unavailable or flaky on Windows, use direct SD (Hekate UMS or a card reader) or FTP instead. Same destinations in the table above.

2. Direct SD (Hekate UMS or card reader)

Same destinations; no MTP client required.

Hekate UMS (preferred when available): expose the microSD to the host while the card stays in the console; mount the volume; copy files; cleanly unmount before leaving UMS.
Physical reader: power off / remove the microSD, copy on the host, eject safely, reinsert, boot CFW, title-override launch.

Do not yank the card or unplug UMS mid-write.

3. FTP (any SD-exposing Switch FTP)

Any homebrew FTP server that can write the microSD is fine. For example DBI's own FTP, sys-ftpd-light, or Sphaira. Names are illustrations only; pick what your CFW setup already uses.

Start the FTP server on the Switch; note IP/port/credentials from that app.
From the host, connect with any FTP client and upload to the same switch/gen1recomp/, imports/, imports/mods/, imports/saves/<game>/, and exports/<game>/ paths.
Stop the FTP server cleanly before launching Gen1Recomp.

If credentials or chroots differ by app, trust the destination paths, not a single vendor tutorial.

After every transfer

Exit MTP / unmount SD / stop FTP cleanly.
Launch via title override (hold R on a title → hbmenu). Applet Mode is not supported (not enough memory).
For ROMs: open the matching game tab → Scan again if the file was added after boot (SHA-1 must match that tab; other dumps in imports/ stay for their own tabs). For mods: MODS → Scan again → enable → Play. For saves: SAVE FILES → Import save (rescans imports/saves/<game>/). Pull exported .sav files from exports/<game>/. Joy-Con display chords (stock engine): switch-install.md.

Optional NRO integrity check

For the first deploy of a given artifact (or after a flaky cable):

shasum -a 256 path/to/gen1recomp.nro   # or sha256sum

Copy the file back from the SD and compare hashes. Round-trip must match.

Failure modes (quick)

Symptom	What to try
Device busy / no MTP volume	One client only; different cable/port; Windows MTP USB Device driver; alternate method (SD or FTP)
Zip/ROM/`.sav` "could not be opened"	Delete `._` sidecars (including `._.sav`); confirm real zip starts with `PK`
Half-copied NRO / crash on boot	Re-copy; verify SHA-256; exit transfer mode before launch
App opens in Applet Mode	Use title override (hold R), not Album

Players: switch-install.md
Builders: switch-build.md

7.3 KiB Raw Blame History