{"id":50371330,"url":"https://github.com/logdog2325/pokebridge","last_synced_at":"2026-05-30T07:03:08.637Z","repository":{"id":360524434,"uuid":"1250540918","full_name":"logdog2325/pokebridge","owner":"logdog2325","description":"GameCube homebrew for reading, editing, and exporting Pokemon Gen 3 saves (Ruby/Sapphire/Emerald/FireRed/LeafGreen + ROM hacks + XD + Colosseum) with a Pokemon Box-inspired graphics UI","archived":false,"fork":false,"pushed_at":"2026-05-26T18:51:46.000Z","size":1443,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T20:22:06.083Z","etag":null,"topics":["devkitpro","gamecube","homebrew","pkhex","pokemon","rom-hack","save-editor"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/logdog2325.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-26T18:26:14.000Z","updated_at":"2026-05-26T20:07:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/logdog2325/pokebridge","commit_stats":null,"previous_names":["logdog2325/pokebridge"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/logdog2325/pokebridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logdog2325%2Fpokebridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logdog2325%2Fpokebridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logdog2325%2Fpokebridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logdog2325%2Fpokebridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/logdog2325","download_url":"https://codeload.github.com/logdog2325/pokebridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logdog2325%2Fpokebridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33682998,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["devkitpro","gamecube","homebrew","pkhex","pokemon","rom-hack","save-editor"],"created_at":"2026-05-30T07:03:08.055Z","updated_at":"2026-05-30T07:03:08.631Z","avatar_url":"https://github.com/logdog2325.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PokéBridge\n\nA **GameCube homebrew app** for reading, editing, and exporting Pokémon Gen 3 saves — covering Ruby, Sapphire, Emerald, FireRed, LeafGreen, **all pokeemerald-expansion ROM hacks** (Seaglass, Lazarus, etc.), and the two Gen 3 GameCube titles **Pokémon XD: Gale of Darkness** and **Pokémon Colosseum**.\n\nThe interface is fully graphical with a Pokémon Box: Ruby \u0026 Sapphire aesthetic — pastel-blue gradient backgrounds, rounded translucent panels, real Gen 3-style sprites for **all 1025 species + shiny variants**, and box-art previews for every mainstream Gen 3-era game.\n\n\u003e ## ⚠️ Back up your saves first\n\u003e\n\u003e PokéBridge writes directly to physical GameCube memory cards. **Always back up your `.gci` files with [GCMM](https://github.com/suloku/gcmm) before using the \"Save to memory card\" feature.**\n\u003e\n\u003e v0.5 includes a self-verify step that re-parses our own re-encrypted output before touching the card, but the algorithm-level test suite is small and a future bug could still produce a save the game refuses to load. The bytes you write replace what's on the card with no undo.\n\u003e\n\u003e A v0.5 prerelease build *did* corrupt a tester's real XD save during development — the bug is fixed, but please don't be the person who finds the next one without a backup. GCMM is small, fast, and handles all three Gen 3 GameCube games cleanly.\n\n## What it does\n\n- **Read** Gen 3 GBA `.sav` files (128 KB) directly from SD card via Swiss\n- **Read** Pokémon XD `.gci` files (encrypted with GeniusCrypto)\n- **Read** Pokémon Colosseum `.gci` files (encrypted with SHA-1 chain XOR)\n- **Scan a physical GameCube memory card** for XD / Colosseum / Pokémon Box saves and load them directly (no need to extract to SD first)\n- **Edit** any Pokémon: IVs, EVs, moves, nature, shiny toggle, friendship, held item\n  - Shiny toggle preserves nature via PID re-rolling; nature edit preserves shiny status\n  - Sprites swap to the shiny variant live in the preview\n- **Write** edited saves back to SD with correct checksums + encryption for the source format\n- **Legalize** ROM-hack Pokémon into Gen 3-compatible `.pk3` files for the Pokémon HOME transfer chain (species/move remap for the standard pokeemerald-expansion enum)\n- **Read GBA cart saves over the link cable** by multiboot-loading FIX94's dumper onto a connected GBA (untested — needs hardware verification)\n\n## Screenshots\n\n### Main menu — game-themed box art previews\n\n![Main menu with FireRed box art preview](docs/screenshots/main_menu.png)\n\n### XD party browser — MARK's iconic team, with detail panel\n\n![Pokemon XD party screen — MARK's team](docs/screenshots/xd_party.png)\n\n### Editor — live shiny sprite swap\n\n![Editor: Charizard with shiny toggled — sprite swaps to the black/silver variant in real time](docs/screenshots/edit_shiny.png)\n\n### Move picker — full 354 Gen 3 moves, paged\n\n![Move picker, paged through all 354 Gen 3 moves](docs/screenshots/moves_picker.png)\n\n### Game Art Gallery — every mainstream Gen 3-era title\n\n![Game Art Gallery with Pokemon Emerald / Rayquaza featured](docs/screenshots/game_art_gallery.png)\n\n## Quick start\n\n### Build prerequisites\n\n- **devkitPPC** with libogc, libfat-ogc, SDL2, SDL2_test\n- **devkitARM** (to build the GBA-side dumper ROM)\n- **Python 3** with Pillow (`pip install pillow`) for sprite conversion\n- macOS, Linux, or WSL\n\nInstall via `dkp-pacman`:\n\n```bash\nsudo dkp-pacman -S --needed gamecube-dev gamecube-sdl2 gba-dev\n```\n\n### Clone + set up assets\n\n```bash\ngit clone https://github.com/\u003cyou\u003e/pokebridge.git\ncd pokebridge\n./scripts/setup_assets.sh\n```\n\nThe setup script:\n1. Sparse-clones `pokeemerald-expansion` (for the 1025-species sprite set)\n2. Clones `FIX94/gba-link-cable-dumper`, builds the GBA-side multiboot ROM\n3. Generates `include/embedded_sprites.h` (~2 MB, 4bpp + palette) covering all 1025 species + shiny\n4. Generates `include/embedded_gba_mb.h` (60 KB) from the dumper ROM\n5. Creates stub `embedded_*save.h` files (empty placeholders for the optional demo saves)\n\n### Build\n\n```bash\nmake\n```\n\nProduces `pokebridge.dol` (~3 MB without demo saves, larger if you embed your own).\n\n### Install on GameCube\n\nCopy to your Swiss-formatted SD card:\n\n```\nsd:/apps/pokebridge/boot.dol     ← rename pokebridge.dol to boot.dol\nsd:/pokebridge/saves/            ← drop your .sav / .gci / .gcs files here\nsd:/pokebridge/export/           ← legalized .pk3 files land here\n```\n\nBoot via Swiss → `sd:/apps/pokebridge/boot.dol`. The graphics menu loads directly.\n\n### Wii / Wii U compatibility\n\nWorks on a **homebrew-enabled Wii running in GameCube mode** (Nintendont, Swiss-r, or the disc-channel GameCube backwards-compat on the original Wii). The Wii's two GameCube memory card slots are exposed as slot A / slot B just like on a real GameCube, so the \"Scan GameCube memory card\" feature picks up XD / Colosseum / Pokémon Box saves there too.\n\nWhat does **not** work:\n- Wii U vWii (no native GameCube hardware exposed)\n- Wii in Wii-mode SD slot for GC memcards (PokéBridge runs as a GC homebrew, so it sees GC slots only)\n- Wii without GameCube ports (the family-edition / later \"Wii Mini\" hardware revisions)\n\n## Optional: embed your own demo saves\n\nIf you want save files baked into the `.dol` (so they work without an SD card — handy for Dolphin testing), drop them into the `data/` folder and run:\n\n```bash\npython3 tools/embed_save.py firered  data/my_firered.sav\npython3 tools/embed_save.py emerald  data/my_emerald.sav\npython3 tools/embed_save.py xd       data/my_pokemon_xd.gci\npython3 tools/embed_save.py colo     data/my_pokemon_colosseum.gcs\nmake\n```\n\nEach command writes `include/embedded_\u003ckind\u003e_save.h` which the build picks up automatically.\n\n**Note:** the `embedded_*save.h` files are gitignored — don't commit them. They contain user save data which is technically copyrighted.\n\n## Optional: embed background music\n\nA WAV dropped into `data/` and embedded via `embed_audio.py` will loop in the background while the app runs (uses libaesnd, gapless via `AESND_SetVoiceLoop`).\n\n```bash\npython3 tools/embed_audio.py title data/your_song.wav\nmake\n```\n\nRequirements:\n- 16-bit PCM WAV (mono preferred, smaller .dol; stereo works too — change the format constant in `pb_audio.c`)\n- The tool byte-swaps to BE at embed time (GameCube DSP is BE-native)\n- Anything up to a few MB is fine — bigger samples make the `.dol` bigger, that's all\n\n`include/embedded_title_audio.h` is gitignored. Without it, `setup_assets.sh` writes a silent stub and the app boots without music.\n\n## How it works\n\nPokéBridge is several modular pieces:\n\n### Save parsers\n\n- **`source/save.c`** — Gen 3 GBA save: 14 sections of 4096 bytes per slot, latest-slot detection by save_index, full Trainer Info + Team/Items + PC Storage layout. Little-endian throughout.\n- **`source/pokemon.c`** — Gen 3 Pokémon: 80-byte boxed format with PID/OT-XOR encryption and 24-permutation substructure shuffle. Verified byte-for-byte against PKHeX's `BlockPosition` table.\n- **`source/pb_xd.c`** + **`source/genius_crypto.c`** — Pokémon XD: `SAV3XD` slot layout + GeniusCrypto stream cipher (4 BE u16 keys, additive). Dynamic sub-offset resolution. CK3 / XK3 (196-byte XD Pokémon).\n- **`source/pb_colo.c`** + **`source/sha1.c`** — Pokémon Colosseum: 3-slot save container, SHA-1 chain XOR encryption (digest = inverted at-rest hash, then XOR + re-hash per 20-byte block). CK3 (312-byte Colosseum Pokémon).\n\nAll four formats expose a common edit surface via `pb_pkm_t`. Edits write back through format-specific apply functions (`pb_pkm_encode`, `pb_xk3_apply_pkm_edits`, `pb_ck3_apply_pkm_edits`) with checksum recomputation + re-encryption as appropriate.\n\n### Legalizer\n\nROM-hack Pokémon (species ID \u003e 386) are mapped to nearest Gen 3 analogues via a hand-curated table (`include/rom_hack_species_map.h`) — pseudos map to Bagon line, regional starters to Gen 3 starters of matching type, etc. Output is a PKHeX-compatible 80-byte `.pk3` file that rides the legitimate Gen 3 → Pal Park → Gen 4 → Bank → HOME chain (see [docs/HOME_TRANSFER.md](docs/HOME_TRANSFER.md)).\n\n### Graphics\n\n- **SDL2** on devkitPPC's GameCube target. 640×480 framebuffer.\n- **Sprite cache** is 2-bank (normal + shiny) keyed by species ID. Sprites are stored 4bpp indexed (16-color palette) and decoded to RGBA on first use, then cached as `SDL_Texture`.\n- **Box art** is procedural — gradient panel + cover-species sprite + game name. Eight games: Ruby/Sapphire/Emerald/FireRed/LeafGreen + Colosseum/XD/Pokémon Box: R\u0026S.\n- **Editor** is graphics-mode throughout with sub-screens for each field. Shiny re-rolls PID under a nature-preserving constraint; nature edit preserves shiny status.\n\n### GBA link cable\n\nMirror of FIX94's `gba-link-cable-dumper`. Detects a GBA on a controller port, runs the Nintendo multiboot handshake to upload a 60 KB dumper ROM, then the dumper streams the cart's SRAM back.\n\n**Known issue: internal SI-bus controller mods (BlueRetro, etc.) interfere with the multiboot upload.** Detection works intermittently because the GBA wins some SI probes against the mod's controller emulation, but the sustained ~60 KB multiboot transfer needs every SI exchange to land cleanly, and the mod answering any of them corrupts the CRC and aborts the upload. The GBA ends up sitting on the GAME BOY splash forever (which is actually the correct multiboot-wait state — the bug is upstream).\n\nIf you have a BlueRetro or similar internal SI-bus mod:\n- The graphics-mode \"Joybus debug\" screen (hold Z while entering the link-cable menu) will show the response flapping between \"device not ready\" and \"GBA detected!\" — that's the smoking gun\n- Workaround: swap back to a stock controller board for the dump, or check if your mod's firmware supports a per-port disable\n- The Gen 3 / XD / Colosseum SD-card paths are not affected; only the GBA link cable dump is\n\n## Status\n\n| Format | Read | Edit | Write |\n|--------|------|------|-------|\n| Gen 3 GBA (Ruby/Sapphire/Emerald/FireRed/LeafGreen) | ✅ | ✅ | ✅ |\n| pokeemerald-expansion ROM hacks (Seaglass, Lazarus, etc.) | ✅ | ✅ | ✅ |\n| Pokémon XD: Gale of Darkness (SD + memcard) | ✅ | ✅ | ✅ |\n| Pokémon Colosseum (SD + memcard) | ✅ | ✅ | ✅ |\n| GBA cart over link cable | 🟡 ported, blocked by SI-mod hardware | n/a | n/a |\n| Pokémon Box: Ruby \u0026 Sapphire | 🟡 memcard detection only | ❌ | ❌ |\n\n## Credits\n\nSee [CREDITS.md](CREDITS.md). Standing on the shoulders of:\n- **PKHeX** by kwsch — save format documentation and algorithm references\n- **FIX94's gba-link-cable-dumper** — GBA multiboot + save dump protocol\n- **pokeemerald-expansion** by rh-hideout — Gen 3-style sprites for 1025 species\n- **devkitPro** — toolchain + libogc + SDL2 port\n\n## License\n\nGPL-3.0. See [LICENSE](LICENSE).\n\nThe \"Pokémon\" name and all species names are trademarks of Nintendo / Game Freak / The Pokémon Company. Nominative use only.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flogdog2325%2Fpokebridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flogdog2325%2Fpokebridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flogdog2325%2Fpokebridge/lists"}