Silent Hill Museum

Live Website: silenthillmuseum.org

The Silent Hill Museum is a digital archive of Silent Hill assets.

The museum reads the original binary files directly in your browser and delivers them to you in an interactive exhibit.

How does it work?

The binary format is documented in Kaitai Struct, a powerful declarative binary parsing language. This serves as both a human-readable outline and also a rigorous specification that can be compiled to a parser in many different languages. See the ksy file for the Silent Hill 2 mdl format.

In particular, the ksy files are compiled to a JavaScript parser, which allows the JavaScript Kaitai Struct runtime to facilitate the parsing of assets in their original form. Additionally, we emit TypeScript .d.ts type definitions from the Kaitai source, allowing this project to be written in TypeScript. The beauty of this is that it enables an IDE to know the structure of the binary files.

Once everything is parsed, we use Three.js to draw assets to the screen.

Installation

To get started locally, you'll need a working installation of pnpm. To view assets, you also need to have Silent Hill 2 Restless Dreams (PC) fully extracted.

1. Clone the repository and enter the folder.

git clone https://github.com/laura-a-n-n/silent-hill-museum.git
cd silent-hill-museum

2. Copy the data folder from Silent Hill 2 into the public directory of this repository.

3. Install the dependencies.

pnpm install

4. Run the setup script.

pnpm setup

5. Start the development server.

pnpm dev

This should be enough to get started. See the package.json for more scripts.

Advanced setup

If you'd like to edit the Kaitai Struct (ksy) files, you need a copy of the Kaitai Struct compiler.

In order to emit TypeScript .d.ts files from the ksy source, this repository relies on a fork of the Kaitai Struct compiler that has not been merged to main. Huge thanks to aquach for making this project possible.

1. Install the Kaitai Struct compiler. It should be globally available as the kaitai-struct-compiler command.

To make sure this step worked, try pnpm kaitai all in the root directory of this folder.

2. Clone this fork of aquach's TypeScript compiler for Kaitai Struct, as a sub-directory of this repository. It is the same feature, I just merged it with latest.

3. Follow these instructions for building Kaitai Struct from source in the newly cloned folder, except checkout feature/typescript, not the serialization branch.

To test that everything worked, try pnpm kaitai js in the root folder of this repository.

Now whenever changes are made to the ksy file, run pnpm kaitai js && kaitai ts before committing.