{"id":13715633,"url":"https://github.com/pret/pokemon-reverse-engineering-tools","last_synced_at":"2025-05-07T04:30:57.781Z","repository":{"id":9868575,"uuid":"11867626","full_name":"pret/pokemon-reverse-engineering-tools","owner":"pret","description":"Tools for building and disassembling Pokémon Red and Pokémon Crystal","archived":true,"fork":false,"pushed_at":"2022-12-16T23:41:38.000Z","size":2374,"stargazers_count":337,"open_issues_count":22,"forks_count":57,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-15T16:25:39.256Z","etag":null,"topics":["disassembly","pokemon","python","reverse-engineering"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pret.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-08-03T18:29:09.000Z","updated_at":"2025-04-07T21:28:48.000Z","dependencies_parsed_at":"2023-01-13T15:36:32.151Z","dependency_job_id":null,"html_url":"https://github.com/pret/pokemon-reverse-engineering-tools","commit_stats":null,"previous_names":["kanzure/pokemon-reverse-engineering-tools"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pret%2Fpokemon-reverse-engineering-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pret%2Fpokemon-reverse-engineering-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pret%2Fpokemon-reverse-engineering-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pret%2Fpokemon-reverse-engineering-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pret","download_url":"https://codeload.github.com/pret/pokemon-reverse-engineering-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252813720,"owners_count":21808374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["disassembly","pokemon","python","reverse-engineering"],"created_at":"2024-08-03T00:01:01.351Z","updated_at":"2025-05-07T04:30:56.921Z","avatar_url":"https://github.com/pret.png","language":"Python","readme":"pokemontools\n==============================\n\n# 2022 Note\nThis repository was a collection of tools for reverse engineering the Generation 1 and 2 Pokémon games in the early days of disassembling. The scripts here range from repository build tools to programs of varying complexity to extract ROM data. None of the tools here are maintained anymore and were written in python2, and some don't run at all because [the port to python3](https://github.com/pret/pokemon-reverse-engineering-tools/commits?author=eevee) was done rather lazily. The two main tools of interest, [gbz80disasm.py](pokemontools/gbz80disasm.py) and [gfx.py](pokemontools/gfx.py) are no longer used and have modern, updated tooling (see [mgbdis](https://github.com/mattcurrie/mgbdis) for a replacement for `gbz80disasm.py` and the various programs in [pokecrystal/tools](https://github.com/pret/pokecrystal/tree/master/tools) for a replacement for `gfx.py`).\n\nAs a result, this repository has been archived and is available only for historical purposes. You are on your own if you choose to use any scripts here as a base for tooling. Only a few of the tools here were released under an open source license if that is of concern for you.\n\n# Original README below\n\n``pokemontools`` is a python module that provides various reverse engineering\ncomponents for various Pokémon games. This includes:\n\n* a utility to disassemble bytes from games into asm\n* map editor\n* python bindings for Pokémon games running in the vba-linux emulator\n* in-game graphics converter (png, lz, 2bpp)\n* preprocessor that dumps out rgbds-compatible asm\n* stuff that parses and dumps data from ROMs\n\n# installing\n\nTo install this python library in ``site-packages``:\n\n```\npip install --upgrade pokemontools\n```\n\nAnd for local development work:\n\n```\npython setup.py develop\n```\n\nAnd of course local installation:\n\n```\npython setup.py install\n```\n\n# testing\n\nRun the tests with:\n\n```\nnosetests-2.7\n```\n\nThere might be a great deal of spammy output. Drop some of the spam with:\n\n```\nnosetests-2.7 tests.integration.tests --nocapture --nologcapture\n```\n\n# see also\n\n* [Pokémon Crystal source code](https://github.com/kanzure/pokecrystal)\n* [Pokémon Red source code](https://github.com/iimarckus/pokered)\n\nPokémon Crystal utilities and extras\n==============================\n\n`crystal.py` parses the ROM and provides convenient classes to dump human-readable ASM with the global `to_asm()` method. This ASM can then be compiled back into the original ROM. Currently it parses map headers, \"second\" map headers, map event headers, map script headers, map triggers, map \"callbacks\", map blockdata, xy triggers, warps, people-events, texts and scripts.\n\n#### Simple ASM generation example\n\nNote: throughout these examples it is possible to use `reload(crystal)` instead of `import pokemontools.crystal`. Once the module is loaded a first time, it must be reloaded if the file changes and the updates are desired.\n\n```python\nimport pokemontools.crystal as crystal\n\n# parse the ROM\ncrystal.run_main()\n\n# create a new dump\nasm = crystal.Asm()\n\n# insert the first 10 maps\nx = 10\nasm.insert_with_dependencies(crystal.all_map_headers[:x])\n\n# dump to extras/output.txt\nasm.dump()\n```\n\nAfter running those lines, `cp extras/output.txt main.asm` and run `git diff main.asm` to confirm that changes to `main.asm` have occurred. To test whether or not the newly inserted ASM compiles into the same ROM, use: `make clean \u0026\u0026 make`. This will complain very loudly if something is broken.\n\n#### Testing\n\nUnit tests cover most of the classes.\n\n```bash\npython tests.py\n```\n\n#### Parsing a script at a known address\n\nHere is a demo of how to investigate a particular script, starting with only an address to a known script (0x58043). In this case, the script calls the `2writetext` command to show some dialog. This dialog will be shown at the end of the example.\n\n```python\nimport pokemontools.crystal as crystal\n\n# parse the script at 0x58043 from the map event header at 0x584c3\n# from the second map header at 0x958b8\n# from the map header at 0x941ae\n# for \"Ruins of Alph Outside\" (map_group=3 map_id=0x16)\nscript = Script(0x58043)\n\n# show the script\nprint script.to_asm()\n\n# what labels does it point to in the to_asm output?\n# these must be present in the final asm file for rgbasm to compile the file\nobjdeps = script.get_dependencies()\nprint str(objdeps)\n\n# the individual commands that make up the script\ncommands = script.commands\nprint str(commands)\n\n# the 3rd command is 2writetext and points to a text\nthirdcommand = script.commands[2]\nprint thirdcommand\n# \u003ccrystal.2writetextCommand instance at 0x8ad4c0c\u003e\n\n# look at the command parameters\nparams = thirdcommand.params\nprint params\n# {0: \u003ccrystal.RawTextPointerLabelParam instance at 0x8ad4b0c\u003e}\n\n# 2writetext always has a single parameter\ndefinition_param_count = len(getattr(crystal, \"2writetextCommand\").param_types.keys())\ncurrent_param_count    = len(params.keys())\nassert definition_param_count == current_param_count, \"this should never \" + \\\n       \"happen: instance of a command has more parameters than the \" + \\\n       \"definition of the command allows\"\n\n# get the first parameter (the text pointer)\nparam = params[0]\nprint param\n# \u003ccrystal.RawTextPointerLabelParam instance at 0x8ad4b0c\u003e\n\n# RawTextPointerLabelParam instances point to their text\ntext = param.text\nprint text\n# \u003ccrystal.TextScript instance at 0x8ad47ec\u003e\n\n# now investigate this text appearing in this script in \"Ruins of Alph Outside\"\nprint text.to_asm()\n```\n\nThe final output will be the following text.\n\n```asm\ndb $0, \"Hm? That's a #-\", $4f\ndb \"DEX, isn't it?\", $55\n; ...\n```\n\nHowever, this is not how that `TextScript` object would appear in the final ASM. To see how it would appear in `main.asm` once inserted, you would run `print crystal.to_asm(text)` to get the following.\n\n```asm\nUnknownText_0x580c7: ; 0x580c7\n    db $0, \"Hm? That's a #-\", $4f\n    db \"DEX, isn't it?\", $55\n    db \"May I see it?\", $51\n    db \"There are so many\", $4f\n    db \"kinds of #MON.\", $51\n    db \"Hm? What's this?\", $51\n    db \"What is this\", $4f\n    db \"#MON?\", $51\n    db \"It looks like the\", $4f\n    db \"strange writing on\", $51\n    db \"the walls of the\", $4f\n    db \"RUINS.\", $51\n    db \"If those drawings\", $4f\n    db \"are really #-\", $55\n    db \"MON, there should\", $55\n    db \"be many more.\", $51\n    db \"I know! Let me up-\", $4f\n    db \"grade your #-\", $55\n    db \"DEX. Follow me.\", $57\n; 0x581e5\n```\n\n#### Figuring out where a script appears based on a known address\n\nAnother approach is to parse the entire ROM, then check a script at a particular address. This has the advantage that the script object will have the `map_group` and `map_id` variables set.\n\n```python\nimport pokemontools.crystal as crystal\n\n# parse the ROM\ncrystal.run_main()\n\n# get the parsed script\nscript = crystal.script_parse_table[0x58043]\n\n# read its attributes to figure out map group / map id\nmap_group = script.map_group\nmap_id = script.map_id\n\n# MapHeader is not given all the info yet\n# in the mean time \"map_names\" contains some metadata\nmap_dict = crystal.map_names[map_group][map_id]\nmap_header = map_dict[\"header_new\"]\n\nprint map_dict[\"name\"]\n# Ruins of Alph Outside\n```\n\nWhile the above doesn't show this, it turns out that the script at 0x58043 is referenced in the `MapEventHeader` as a person-event.\n\n```python\nprint map_header.second_map_header.event_header.to_asm()\n```\n\nThis will show a structure roughly like:\n\n```asm\nperson_event $3c, 19, 15, $7, $0, 255, 255, $0, 0, UnknownScript_0x58043, $0703\n```\n\nwithin this:\n\n```asm\nMapEventHeader_0x584c3: ; 0x584c3\n    ; filler\n    db 0, 0\n\n    ; warps\n    db 11\n    warp_def $11, $2, 1, GROUP_RUINS_OF_ALPH_HO_OH_CHAMBER, MAP_RUINS_OF_ALPH_HO_OH_CHAMBER\n    warp_def $7, $e, 1, GROUP_RUINS_OF_ALPH_KABUTO_CHAMBER, MAP_RUINS_OF_ALPH_KABUTO_CHAMBER\n    warp_def $1d, $2, 1, GROUP_RUINS_OF_ALPH_OMANYTE_CHAMBER, MAP_RUINS_OF_ALPH_OMANYTE_CHAMBER\n    warp_def $21, $10, 1, GROUP_RUINS_OF_ALPH_AERODACTYL_CHAMBER, MAP_RUINS_OF_ALPH_AERODACTYL_CHAMBER\n    warp_def $d, $a, 1, GROUP_RUINS_OF_ALPH_INNER_CHAMBER, MAP_RUINS_OF_ALPH_INNER_CHAMBER\n    warp_def $b, $11, 1, GROUP_RUINS_OF_ALPH_RESEARCH_CENTER, MAP_RUINS_OF_ALPH_RESEARCH_CENTER\n    warp_def $13, $6, 1, GROUP_UNION_CAVE_B1F, MAP_UNION_CAVE_B1F\n    warp_def $1b, $6, 2, GROUP_UNION_CAVE_B1F, MAP_UNION_CAVE_B1F\n    warp_def $5, $7, 3, GROUP_ROUTE_36_RUINS_OF_ALPH_GATE, MAP_ROUTE_36_RUINS_OF_ALPH_GATE\n    warp_def $14, $d, 1, GROUP_ROUTE_32_RUINS_OF_ALPH_GATE, MAP_ROUTE_32_RUINS_OF_ALPH_GATE\n    warp_def $15, $d, 2, GROUP_ROUTE_32_RUINS_OF_ALPH_GATE, MAP_ROUTE_32_RUINS_OF_ALPH_GATE\n\n    ; xy triggers\n    db 2\n    xy_trigger 1, $e, $b, $0, UnknownScript_0x58031, $0, $0\n    xy_trigger 1, $f, $a, $0, UnknownScript_0x5803a, $0, $0\n\n    ; signposts\n    db 3\n    signpost 8, 16, $0, UnknownScript_0x580b1\n    signpost 16, 12, $0, UnknownScript_0x580b4\n    signpost 12, 18, $0, UnknownScript_0x580b7\n\n    ; people-events\n    db 5\n    person_event $27, 24, 8, $6, $0, 255, 255, $2, 1, Trainer_0x58089, $ffff\n    person_event $3c, 19, 15, $7, $0, 255, 255, $0, 0, UnknownScript_0x58043, $0703\n    person_event $3a, 21, 17, $3, $0, 255, 255, $a0, 0, UnknownScript_0x58061, $078e\n    person_event $27, 15, 18, $2, $11, 255, 255, $b0, 0, UnknownScript_0x58076, $078f\n    person_event $27, 12, 16, $7, $0, 255, 255, $80, 0, UnknownScript_0x5807e, $078f\n; 0x58560\n```\n\n#### Helpful ROM investigation tools\n\n```python\nimport pokemontools.crystal as crystal\n\n# load the bytes\ncrystal.load_rom()\n\n# get a sequence of bytes\ncrystal.rom_interval(0x112116, 10)\n# ['0x48', '0x54', '0x54', '0x50', '0x2f', '0x31', '0x2e', '0x30', '0xd', '0xa']\ncrystal.rom_interval(0x112116, 10, strings=False)\n# [72, 84, 84, 80, 47, 49, 46, 48, 13, 10]\n\n# get bytes until a certain byte\ncrystal.rom_until(0x112116, 0x50, strings=False)\n# ['0x48', '0x54', '0x54']\n# [72, 84, 84]\n\n# or just look at the encoded characters directly\ncrystal.rom[0x112116:0x112116+10]\n# 'HTTP/1.0\\r\\n'\n\n# look at a text at 0x197186\ntext = crystal.parse_text_at2(0x197186, 601, debug=False)\nprint text\n```\n\nThat last text at 0x197186 will look like:\n\n```python\n\"\"\"\nOAK: Aha! So\nyou're !\nI'm OAK! A #MON\nresearcher.\nI was just visit-\ning my old friend\nMR.#MON.\nI heard you were\nrunning an errand\nfor PROF.ELM, so I\nwaited here.\nOh! What's this?\nA rare #MON!\n...\n\"\"\"\n```\n\n","funding_links":[],"categories":["Reverse Engineering","逆向工程","Development Projects"],"sub_categories":["Demos","民众"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpret%2Fpokemon-reverse-engineering-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpret%2Fpokemon-reverse-engineering-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpret%2Fpokemon-reverse-engineering-tools/lists"}