Skip to content

Setup

Jump to bottom
IWILLCRAFT edited this page Apr 30, 2026 · 10 revisions

The project building can be handled in two ways: through Makefile (recommended) or Ninja. Both can be compiled in Linux and Windows, however, Makefile requires some Unix handler in order to work on Windows, for this project we use WSL2, and Ninja can be built natively in both Windows and Linux.

Important

Project's setup is still rough for modding purposes.

  • Shiftable build is not currently available yet and file insertion/replacement has not been properly implemented.
  • This setup supports all retail releases; however, at the moment the project is mainly focused on the NTSC-U 1.1 release.
  • Most of the event code and some extensive game core and graphic functionality remain unrecognized.
  • Native Windows build is still under a rough state. The game is currently able to build, but runs into mismatches due to some different compiler behaviour.

Prerequisites

Linux/Windows (WSL2) (Makefile & Ninja)

The build process has the following package requirements:

  • git
  • build-essential
  • binutils-mips-linux-gnu
  • cpp-mips-linux-gnu
  • python3
  • python3-venv
  • bchunk
  • 7z

Under a Debian-based distribution (or Windows with a Debian-based WSL2 setup), you can install these with the following commands:

sudo apt update && \
sudo apt install git build-essential binutils-mips-linux-gnu cpp-mips-linux-gnu python3 python3-venv bchunk p7zip-full

Windows (Ninja)

The build process has the following requirements:

Note

Run python -m ensurepip after installing Python in order to get pip

Clone the repository

Clone https://github.com/Vatuu/silent-hill-decomp to your desired directory. Make sure to clone recursively!

git clone --recursive https://github.com/Vatuu/silent-hill-decomp.git && cd silent-hill-decomp

Place the ROM

You will need to provide your own ROM dump of the NTSC-U 1.1 version of the game. If dumped correctly, you will have a .BIN file with the SHA1 hash 34278D31D9B9B12B3B5DB5E45BCBE548991ECBC7 (616,494,480 Bytes / 587 MiB).

After dumping, the .BIN file must be placed as rom/image/SLUS-00707.bin in the repo.

Setup Python virtual environment and requirements

Modern Linux distros require a virtual environment to be set up before installing requirements with pip.

You can set up an environment in the repository folder with the following on Linux/WSL2:

python3 -m venv .venv                      # Creates `.venv` folder with environment.
source .venv/bin/activate                  # Activates environment (must be run in every new terminal session).
python3 -m pip install -r requirements.txt # Installs project requirements from `requirements.txt`.

For Windows:

:: Creates `.venv` folder with environment.
python -m venv .venv

:: Activates environment (must be run in every new terminal session).
.venv\Scripts\activate.bat

:: Installs project requirements from `requirements.txt`.
python -m pip install -r requirements.txt

Build the code

Makefile

Run make setup to extract needed assets and code from the binary. If the setup was successful, run make to build. Once the build has finished, a folder named build will be generated and a checksum check will be displayed in the command prompt.

Note

clean-build/clean-progress is obligatory if the decompilation configuration files inside the configs folder or the Makefile have been modified when intending to work on different overlays.

Make rules available:

  • build: Builds the executable and overlays. After compilation, it compares checksums with the original files.
    • reset-build: Forcely rebuilds all the C code of the executable and overlays. After compilation, it compares checksums with the original files.
    • clean-build: Renegerates the project configuration and builds the executable and overlays. After compilation, it compares checksums with the original files.
  • progress: Builds the code of the executable and overlays without producing a complete final binary. This command is intended to be use alongisde Objdiff workflow.
    • reset-progress: Forcely rebuilds all the C code of the executable and overlays without producing a complete final binary. This command is intended to be use alongisde Objdiff workflow.
    • clean-progress: Renegerates and builds the project configuration and builds the executable and overlays without producing a complete final binary. This command is intended to be use alongisde Objdiff workflow. This command doesn't affect previously generated Objdiff target files.
  • objdiff-config: Generates project configuration for Objdiff.
  • objdiff-config-all: Generates project configuration of all supported version for Objdiff.

The Makefile includes 8 variables that disables specific aspect of compilation:

  • BUILD_EXE - Build the executable (1 = Enabled; 0 = Disabled)
  • BUILD_ENGINE - Build the engine overlay (1 = Enabled; 0 = Disabled)
  • BUILD_SCREENS - Build the screen overlays (1 = Enabled; 0 = Disabled)
  • BUILD_MAPS - Build the map overlays (1 = Enabled; 0 = Disabled)
  • BUILD_ITEMS - Build the item strings overlays (Only available for the PAL 1.0 release. 1 = Enabled; 0 = Disabled)
  • CHECKSUM - Runs checksum check after compilation (1 = Enabled; 0 = Disabled)
  • NON_MATCHING - Build the game overlays and executable with inserted non-matching code (1 = Enabled; 0 = Disabled)
  • SKIP_ASM - Build all game code excluding any assembly code. This option doesn't generate a binary file as most overlays and the executable still have many pieces of non-decompiled code. (1 = Enabled; 0 = Disabled)
  • GAME_VERSION - Specify the version to be work on. (USA = NTSC 1.1 Release, EUR = PAL 1.0 Release, JAP0 = NTSC-J 1.0 Release, JAP1 = NTSC-J 1.1 Release, JAP2 = NTSC-J 1.2 Release)

By default the Makefile will consider the variables BUILD_* variables, however, the Makefile handles variables that allows to specify what overlays or set of them will be only compiled:

  • EXE - Build the executable
  • ENG - Build the engine (BODYPROG.BIN)
  • SCR - Build all screens overlays
  • STR/FMV - Build the FMV logic overlay (STREAM.BIN)
  • BKO - Build the splash screen overlay (B_KONAMI.BIN)
  • CRE - Build the credits screen overlay (STF_ROLL.BIN)
  • OPT - Build the options screen overlay (OPTIONS.BIN)
  • SAV - Build the save screen overlay (SAVELOAD.BIN)
  • ITM - Build the item strings overlays (Only available for the PAL 1.0 release)
  • MAP - Build all maps overlays
  • MXX - Build an individual or a set of map overlays. For an individual overlay change both XX to the number of the overlay targetting (For example: M00=1 for MAP0_S00.BIN). For a set of map overlays change the second X (For example: M0X=1 for MAP0_S00.BIN, MAP0_S01.BIN and MAP0_S02.BIN).

Multiple overlays can compiled in union, for example by setting: SCR=1 ENG=1 only screen overlays and the engine will be compiled.

Ninja

Note

  • Makefile is mainly used by current decompilation maintainers, therefore, Ninja build may tend to be broken unexpectedly.
  • In case of running into issues related to text read, try adding -X utf8 to the parameters before ninja_config.py.
  • For Windows use python instead of python3.

Run python3 ninja_config.py -iso_e to extract needed assets and code from the binary. If the extraction was successful, run python3 ninja_config.py to generate the build.ninja file and then ninja to build. Once the build has finished, a folder named build will be generated and a checksum check will be displayed in the command prompt.

ninja_config.py arguments available:

  • -c/--clean: Clean build and permuter files.
  • -iso_e/--iso_extract: Extract game files.
  • -sc/--skip_checksum: Skip checksum check.
  • -nm/--non_matching: The generated ninja.build will compiled the game overlays and executable with inserted non-matching code.
  • -obj/--objdiff_config: Generate setup for both matching build and Objdiff. Use ninja -f matching.ninja to build the matching files, otherwise it will use the base build.ninja file which will only compile the working split.
  • -ver/--game_version: Specify the version of the game that is being work on. (USA = NTSC 1.1 Release, EUR = PAL 1.0 Release, JAP0 = NTSC-J 1.0 Release, JAP1 = NTSC-J 1.1 Release, JAP2 = NTSC-J 1.2 Release)

By default the configuration file will build the executable and all overlays, but we have an additional argument that allows to compile a specific overlay or set of them. This argument is -set/--setup which requires any of the 3 letters listed arguments below to work on:

  • EXE - Build the executable
  • ENG - Build the engine (BODYPROG.BIN)
  • SCR - Build all screens overlays
  • STR/FMV - Build the FMV logic overlay (STREAM.BIN)
  • BKO - Build the splash screen overlay (B_KONAMI.BIN)
  • CRE - Build the credits screen overlay (STF_ROLL.BIN)
  • OPT - Build the options screen overlay (OPTIONS.BIN)
  • SAV - Build the save screen overlay (SAVELOAD.BIN)
  • ITM - Build the item strings overlays (Only available for the PAL 1.0 release)
  • MAP - Build all maps overlays
  • MXX - Build an individual or a set of map overlays. For an individual overlay change both XX to the number of the overlay targetting (For example: -set M00 for MAP0_S00.BIN). For a set of map overlays change the second X (For example: -set M0X for MAP0_S00.BIN, MAP0_S01.BIN and MAP0_S02.BIN).

Multiple overlays can compiled in union, for example by setting: -set SCR ENG only screen overlays and the engine will be compiled.

Clone this wiki locally