MioROM¶

> MIOROM // RE_FRAMEWORK_v0.13.1

Modular Low-Level Binary & Assembly Primitives for Console ROM Hacking

NDS ARM9/ARM7 N64 MIPS-VR4300 GBA ARM7TDMI WII BROADWAY PPC PS1 MIPS-R3000A SNES 65C816 SEGA M68000 GB SM83

TESTS: 468 PASSED RUNTIME DEPS: ZERO (STDLIB ONLY) DISASSEMBLER: 6 ARCHITECTURES LICENSE: MIT

MioROM is an advanced Python framework and low-level primitive library designed for ROM hacking, game localization engineering, and binary reverse engineering.

Rather than imposing a monolithic graphical interface or rigid one-click workflows, MioROM delivers foundational programmatic building blocks: declarative struct modeling, progressive streaming scanners, micro-assembly emitters, and multi-architecture SSA IR decompilers. Developers assemble these primitives directly into bespoke, reproducible extraction, translation, and repacking toolchains.

Supported Systems & Targets¶

Architecture / Platform	Binary Formats	Primary Primitives
Nintendo DS	`.nds`, `.srl`, `.narc`, `.nftr`	`NDSRom`, `NARCArchive`, `NFTRFont`, FAT/FNT mapper, CRC16 header recalibration
Nintendo 64	`.z64`, `.n64`, `.v64`, `.m64`	`N64Rom`, `DmaTableArchive`, `Fast3DParser`, `Fast3DBuilder`, `N64TextureDecoder`, IPL3 CIC verification
Game Boy Advance	`.gba`, `.agb`, `.bin`	`GBARom`, `LZ10`, `LZ11`, `ArmSnippet`, complement check validation
Wii / GameCube	`.iso`, `.gcm`, `.u8`, `.arc`, `.tpl`, `.dol`	`GameCubeDisc`, `U8Archive`, `TPLFile`, `DolBinary`, `FstInjector`, 32-byte sector alignment
PlayStation 1	`.bin/.cue`, `.iso`, `.exe`, `.tim`	`ISO9660`, `CueBinDisc`, `TIMImage`, `PSXExe`, `CdXaDecoder` (ADPCM)
Super Nintendo	`.sfc`, `.smc`	`SNESRom`, LoROM / HiROM complement checksum fixer
Sega Genesis / MD	`.md`, `.gen`, `.smd`	`MDRom`, SMD deinterleaving, Motorola 68000 disasm & lifter
Game Boy / GBC	`.gb`, `.gbc`	`GBRom`, `SM83Snippet`, SM83 instruction disassembler & IR lifter

Core Primitives at a Glance¶

1. Declarative Binary Struct Modeling (`BinaryStruct`)¶

Stop writing brittle manual struct.unpack_from("<IIH", data, offset). Define binary structures cleanly with typed fields, dynamic lengths, bitfields, and automated validation:

from miorom.core.schema import BinaryStruct, FixedString, U16, U32, EnumField, ParseError
from enum import IntEnum

class CompressionType(IntEnum):
    NONE = 0x00
    LZ10 = 0x10
    LZ11 = 0x11
    YAZ0 = 0x20

class RomHeader(BinaryStruct):
    _endian = "<"
    magic = FixedString(4, default="ROM1")
    version = U16(default=1, validate=lambda v: v >= 1)
    compression = EnumField(U16(), CompressionType)
    file_count = U32()

# Unpack from raw binary bytes
header = RomHeader.from_bytes(raw_bytes)
print(header.magic)        # "ROM1"
print(header.compression)  # CompressionType.LZ11

# Modify and serialize back
header.version = 2
packed_bytes = header.to_bytes()

2. Multi-Architecture SSA IR Decompilation (`BinaryLifter`)¶

Lift raw machine code from PowerPC, ARM32, MIPS32 (including COP1 floats), SM83, and M68K into an architecture-neutral Static Single Assignment (SSA) Micro-IR, and decompile directly into readable C pseudocode:

from miorom.script.lifter import BinaryLifter

# MIPS machine code snippet (e.g. from N64 or PS1)
mips_bytes = bytes.fromhex("2404002A 8C820000 03E00008 00000000")

# Lift to SSA Intermediate Representation
ir = BinaryLifter.lift(mips_bytes, base_address=0x80001000, arch="mips", endian=">")

# Generate human-readable C pseudocode
c_code = BinaryLifter.decompile_to_c(ir)
print(c_code)
# Output:
# int sub_80001000() {
#     int $a0_1, $v0_1;
# loc_80001000:
#     $a0_1 = 0x2A;
#     $v0_1 = *($a0_1);
#     return $v0_1;
# }

3. Fast3D Texture Codecs & Display List Parsing¶

Extract and inject N64 Fast3D graphics textures (RGBA32, RGBA16, IA16, I8, CI8) directly into transparent PNGs, or parse microcode commands straight from display lists:

from miorom.graphics import N64TextureDecoder, N64TextureEncoder, Fast3DParser

# Decode raw N64 RGBA32 binary bytes to PNG
N64TextureDecoder.to_png(raw_bytes, fmt="rgba32", width=32, height=32, output_path="icon.png")

# Re-encode edited PNG back to native N64 binary bytes
n64_binary = N64TextureEncoder.from_image("icon_edited.png", fmt="rgba32")

# Parse display list microcode stream (G_SETTIMG, G_SETTILE, G_SETTILESIZE)
textures = Fast3DParser.find_textures(display_list_bytes)
for tex in textures:
    print(f"Discovered {tex.format_name} ({tex.width}x{tex.height}) at 0x{tex.image_ptr:08X}")

4. Dialogue Localization & Clean Script Catalogs¶

Extract complex dialogue with variable-width fonts, sanitize pointer artifacts, and export clean human-readable scripts formatted in [id]\ntext:

from miorom.formats.script_catalog import DialogueCleaner, ScriptCatalog

# Strip binary pointer noise, raw hex tags, and format clean newlines
clean_text = DialogueCleaner.clean("<1A><13>-<08>You found the <05>AFairy Bow<05>@!<01>Shoot it with B.")
print(clean_text)
# Output:
# You found the AFairy Bow@!
# Shoot it with B.

# Dump translation rows to plain human-readable [id] script file
ScriptCatalog.dump_script("script.txt", translation_rows, clean=True)

# Synchronize edited script back into CSV translation columns
ScriptCatalog.script_to_csv("script_translated.txt", "base.csv", "updated.csv")

Installation¶

Install MioROM from PyPI:

pip install miorom

Or install the latest development tree directly from GitHub:

pip install git+https://github.com/MiokoTech/miorom

:material-book-open-page-variant: Workflow Guide --- End-to-end tutorial: from untouched ROM to distributed binary patch.
:material-chip: Binary & Assembly Primitives --- Fluent micro-assemblers (MipsSnippet, ArmSnippet), patch writers, and symbol maps.
:material-console: CLI Reference --- Terminal manual for miorom unpack, repack, scan, diff, and more.
:material-gamepad: Platform Specifications --- Technical format breakdown for NDS, Wii, GC, N64, GBA, SNES, and Mega Drive.
:material-puzzle: Plugin Guide --- Register custom console handlers and codecs via RomManager or entry_points.
:material-code-json: API Reference --- Complete programmatic index across all 10 core subpackages.