$ show Xeeynamo/sotn-decomp
This repository is a multi-platform decompilation of **Castlevania: Symphony of the Night**, targeting the original PlayStation (PSX), PSP, Sega Saturn, and a modern PC port. It reconstructs the game's source code from original binaries to produce byte-identical builds, while also providing a full reimplementation with a cross-platform port. The codebase is organized into per-stage, per-boss, and per-weapon overlay modules, each defining entity update tables, initialization data, and asset references. A central entity system with step-based state machines drives all game objects, and a shared `g_api` function table enables cross-overlay communication. The project includes extensive tooling for asset extraction/rebuilding (Go), automated code linting and transformation (Rust), binary diffing (Python), and duplicate function detection (Rust). While the decompilation is largely complete for the US PSX version, many PSP and Saturn functions remain as `INCLUDE_ASM` stubs, and the PC port contains several `UnsupportedEntity` placeholders. The architecture demonstrates high craftsmanship in its overlay system, entity dispatch patterns, and modular toolchain, though platform-specific `#ifdef` branching and code duplication across overlays introduce maintenance complexity.
The LLM identified 6 files worth highlighting for reuse:
A complete asset extraction and rebuilding pipeline in Go that reads original game binaries (PSX, PSP, Saturn) and outputs structured C arrays, PNGs, and YAML configs. Handles sprite banks, tilemaps, layers, palettes, and graphics data with atomic file writes to preserve build caching. The pipeline is modular with version-specific configurations and can be adapted to other games with similar binary data formats.
A set of Rust-based lint tools that automatically transform hardcoded hexadecimal constants into named symbolic constants (e.g., player status flags, item drop IDs, draw flags, fixed-point macros). Uses regular expressions and AST analysis to apply changes across the C source tree. This pattern is directly reusable for any decompilation project to systematically clean up magic numbers.
A shared header for breakable entity logic that is `#include`d by multiple stage overlays with per-stage `#define` macros to customize behavior (break sound, debris type, prize drops). Demonstrates a clean way to avoid code duplication while maintaining stage-specific variations. The pattern of shared entity headers (like `e_room_bg.h`, `e_explosion_puff_opaque.h`) can be extracted and applied to other entity-driven games.
Defines the interface for all weapons via a struct of function pointers (`func_ptr_80170004`, `GetWeaponId`, `EntityWeaponShieldSpell`, etc.). Each weapon (e.g., `w_018.c`) implements these callbacks, enabling a plugin-like dispatch system. This design cleanly separates weapon-specific logic from the core engine and is reusable as a generic attack/spell system pattern.
A Rust tool that finds duplicate functions across game overlays using Levenshtein distance on decompiled C code and assembly. Useful for identifying copy-pasted code that should be refactored into shared libraries. The algorithm is generic and could be applied to any large codebase to locate near-duplicate implementations.
A header defining the `PfnEntityUpdate` dispatch table that maps entity IDs to their update functions. Each stage overlay sets up its own table, and the core engine calls into it at runtime. This pattern provides a clean, extensible way to add new entity types without modifying the engine loop, and it's easily reusable for any entity-component or command-dispatch system.