/silent-hill-museum

A museum of Silent Hill models

Primary LanguageTypeScriptMIT LicenseMIT

Silent Hill Museum

CinderellaLittle MermaidSnow White ClockPianoMusic Box

Build status Test status Version License

kaitai Three.js TypeScript JavaScript Python

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

  1. In public, make a new folder called mdl and copy data/chr and data/chr2 from Silent Hill 2 into it.

  2. Install the dependencies.

npm install
  1. Run the setup script.
npm run setup
  1. Start the development server.
npm run 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 npm run ksy-all in the root directory of this folder.

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

  2. 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 npm run ksy-museum in the root folder of this repository.

Now whenever changes are made to the ksy file, run npm run ksy-museum before committing.