Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/laura-a-n-n/silent-hill-museum
A museum of Silent Hill models
https://github.com/laura-a-n-n/silent-hill-museum
3d kaitai-struct preservation reverse-engineering silent-hill three-js
Last synced: 2 months ago
JSON representation
A museum of Silent Hill models
- Host: GitHub
- URL: https://github.com/laura-a-n-n/silent-hill-museum
- Owner: laura-a-n-n
- License: mit
- Created: 2024-06-29T13:51:55.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2024-09-28T02:27:58.000Z (3 months ago)
- Last Synced: 2024-09-28T05:21:22.888Z (3 months ago)
- Topics: 3d, kaitai-struct, preservation, reverse-engineering, silent-hill, three-js
- Language: TypeScript
- Homepage: https://silenthillmuseum.org
- Size: 2.11 MB
- Stars: 17
- Watchers: 4
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Silent Hill Museum
   
    
**Live Website**: [silenthillmuseum.org](https://silenthillmuseum.org/)
The [_Silent Hill Museum_](https://silenthillmuseum.org/) 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](https://kaitai.io/), 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](https://github.com/laura-a-n-n/silent-hill-museum/blob/main/ksy/mdl.ksy).
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](https://threejs.org/) to draw assets to the screen.
## Installation
To get started locally, you'll need a working installation of [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-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.
```sh
git clone https://github.com/laura-a-n-n/silent-hill-museum.git
cd silent-hill-museum
```
2. In `public`, make a new folder called `mdl` and copy `data/chr` and `data/chr2` from Silent Hill 2 into it.
3. Install the dependencies.
```sh
npm install
```
4. Run the setup script.
```sh
npm run setup
```
5. Start the development server.
```sh
npm run dev
```
This should be enough to get started. See the [package.json](https://github.com/laura-a-n-n/silent-hill-museum/blob/main/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](https://github.com/kaitai-io/kaitai_struct_compiler/pull/233) of the Kaitai Struct compiler that has not been merged to main. Huge thanks to [aquach](https://github.com/aquach) for making this project possible.
1. Install the [Kaitai Struct compiler](https://kaitai.io/#download). It should be globally available as the `kaitai-struct-compiler` command.
To make sure this step worked, try `npm run kaitai all` in the root directory of this folder.
2. Clone [this fork](https://github.com/laura-a-n-n/kaitai_struct_compiler) 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](https://doc.kaitai.io/serialization.html#_building_the_compiler_from_source) 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 kaitai js` in the root folder of this repository.
Now whenever changes are made to the ksy file, run `npm run kaitai js && npm run kaitai ts` before committing.