Skip to content

Setup

Jump to bottom
IWILLCRAFT-M0d edited this page Nov 10, 2025 · 5 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.

At the moment of writing this setup guide, the project only supports the NTSC-U 1.1 release. The project intends to add support to other retail releases, however.

Setup - Linux/Windows (WSL2) (Makefile & Ninja)

Install build dependencies

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

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:

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`.

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.

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.
  • compilation-test: Runs both progress and matching build processes and checks if any of them fails.

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)
  • 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)

By default the Makefile will consider the variables BUILD_* variables in Additionally the Makefile handles variables that allows to compile specific overlays or set of them:

  • 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)
  • 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).

Note

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

Note

GAME_VERSION Doesn't have any other option available as required configuration files for other versions are still not available.

Build the code - Ninja

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 Objdiff.
  • -nall/--ninja_all: Builds setup for both matching build and Objdiff. Use ninja -f matching.ninja to build the matching files.
  • -ver/--game_version: Specify the version of the game that is being work on.

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)
  • 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).

In case of working regenerating the game's assembly or looking for add multiple overlays to the workflow add an r at the ending of the input value (For example: -set M00 will always generate a new build.ninja file, then in case of then using -set M01 will generate a new file without MAP0_S00, but in case of using -set M00 and then -set M01R the ninja.build will now include both overlays.

Note

-ver/--game_version will not work as this argument requires configuration files for other versions which are still not available.

Setup - Windows (Ninja)

Install build dependencies

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

You can set up an environment in the repository folder with the following:

python -m venv venv                       # Creates `.venv` folder with environment.
venv\Scripts\activate.bat                 # Activates environment (must be run in every new terminal session).
python -m pip install -r requirements.txt # Installs project requirements from `requirements.txt`.

Build the code

Run python ninja_config.py -iso_e to extract needed assets and code from the binary. If the extraction was successful, run python 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 Objdiff.
  • -nall/--ninja_all: Builds setup for both matching build and Objdiff. Use ninja -f matching.ninja to build the matching files.
  • -ver/--game_version: Specify the version of the game that is being work on.

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)
  • 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).

In case of working regenerating the game's assembly or looking for add multiple overlays to the workflow add an r at the ending of the input value (For example: -set M00 will always generate a new build.ninja file, then in case of then using -set M01 will generate a new file without MAP0_S00, but in case of using -set M00 and then -set M01R the ninja.build will now include both overlays.

Note

-ver/--game_version will not work as this argument requires configuration files for other versions which are still not available.

Clone this wiki locally