$ show sonicretro/s2disasm
This repository is a complete, commented disassembly of Sonic the Hedgehog 2 for the Sega Genesis/Mega Drive. It provides the full 68000 assembly source code for the game, including the Z80 sound driver, level data, art mappings, music and sound effect definitions, and a build system that can reassemble a bit-perfect ROM. The project is the result of extensive reverse engineering and documents the game's memory layout, object system, and hardware interactions in detail. The architecture is organized as a collection of assembly source files, with a Lua-based build script (build.lua) that orchestrates assembly via the AS macro assembler, compresses music and sound data using the included Saxman/Kosinski compression tools, and patches the final ROM. Precompiled native binaries for the assembler and compression utilities are provided for Windows, Linux, macOS, and Android, ensuring cross-platform reproducibility. The codebase makes heavy use of macros for code generation, data definition, and hardware abstraction, which improves maintainability and readability. It supports multiple ROM revisions (REV00, REV01, REV02) and includes optional bug fixes and optimizations that can be toggled at build time. The repository also integrates with the SonLVL level editor through INI and XML object definitions. Key reusable components include the ClownLZSS compression library (supporting Kosinski, Saxman, and Kosinski+ algorithms), the SMPS sound conversion macros for music data, and the sprite mapping macro system. These can be extracted and applied to other Sega Genesis projects or any project requiring similar compression or sound driver conversion.
The LLM identified 4 files worth highlighting for reuse:
Implements the Saxman and Kosinski compression algorithms used in Sega Genesis games. Provides a callback-based API (ClownLZSS_Compress, ClownLZSS_Decompress) that can be reused in any project requiring these specific compression formats. The code is self-contained, well-structured, and demonstrates non-obvious skill in handling bit-exact compression for ROM hacking.
A macro library for converting SMPS (Sega Music and Sound Programming System) data between different driver versions. Defines pitch equates, note values, DAC sample IDs, and coordination flags. Can be reused in any Sonic or Sega game modding project that works with SMPS music data, providing a clean abstraction layer over the raw binary format.
Defines macros for sprite and DPLC (Dynamic Pattern Load Cue) mapping tables used in Sonic 2. Macros like spriteHeader, spritePiece, dplcHeader, and dplcEntry abstract away the binary layout and support multiple mapping versions. This pattern is reusable for any game that uses tile-based sprite rendering and simplifies the definition of complex animation frames.
Core Lua module for the build system. Provides functions for locating platform-specific tools, invoking the assembler, compressing music/sound data, patching ROM headers, and verifying output hashes. Implements incremental builds via MD5 caching. While somewhat tailored to this project, the patterns for assembling a Genesis ROM and compressing assets are reusable for other disassembly or modding projects targeting the same platform.