Shin (Fork)

This is an unofficial re-implementation of the game engine used by some visual novels released by Entergram on Nintendo Switch, PS4 and PS Vita.

Currently known games using the engine on Switch and PS Vita are listed in this spreadsheet. PS4 was not researched yet.

The intent is to follow the original engine as closely as possible, so that it can run the original games' data unchanged.

Supported games

This version runs the Switch releases of the Entergram-published 07th Expansion games. Select one with --game:

--game	Game
umineko (default)	Umineko no Naku Koro ni Saku ~Nekobako to Musou no Koukyoukyoku~, original release or with the 1.03 update
higurashi	Higurashi no Naku Koro ni Hō (the updated release, including the Origin content)
gerokasu	幻想牢獄のカレイドスコープ (Gensou Rougoku no Kaleidoscope)
gerokasu2	幻想牢獄のカレイドスコープ 2 (Gensou Rougoku no Kaleidoscope 2)

Story playback, title menus, saving and loading, the backlog, settings, the in-game menus and "special" gameplay segments are implemented for each game, along with any other features and extras: Umineko's character screen, Tips and galleries, Higurashi's Chart, TIPS, Kakera and Quiz screens and galleries, and the Gerokasu card selection minigame and galleries.

Some details might differ from the original games. I tested Umineko and Higurashi pretty extensively and the Gerokasu games to a lesser extent. If you find a problem, please open an issue.

Running a game

You need the game's romfs, which you can dump from your Switch with nxdumptool. With hactoolnet you can extract the romfs from a dumped .nsp file as follows:

hactoolnet -t pfs0 "Umineko no Naku Koro ni Saku ~Nekobako to Musou no Koukyoukyoku~ [01006A300BA2C000].nsp" --romfs=assets

The resulting folder contains data.rom. For Umineko 1.03 and Higurashi, also place the patch.rom from the update's romfs (and, for Higurashi, optionally the append.rom from the Origin DLC's romfs) in the same folder.

By default, the engine reads the assets folder next to the executable. Inside a macOS app bundle, Contents/Resources/assets is also accepted. Use --assets-dir to read another folder:

shin --game higurashi --assets-dir /path/to/higurashi

Movies are decoded by the system: VideoToolbox on macOS and Media Foundation on Windows (Windows N editions need the Media Feature Pack). On Linux, install GStreamer with an H.264 decoder plugin, such as gst-libav or OpenH264. If the system decoder is unavailable, the engine falls back to an ffmpeg executable on PATH or next to the engine.

Command line options

Option	Description
-g, --game <GAME>	The game to run: umineko (default), higurashi, gerokasu or gerokasu2.
-a, --assets-dir <DIR>	Folder containing data.rom (or a data folder). Defaults to assets next to the executable.
-s, --save-file <FILE>	Save file. Defaults to shin/<game>/SAVEDATA in the system application data folder.
-t, --text-websocket <HOST:PORT>	Serve the displayed text over WebSocket, for example to a text hooker or translation tool.
-f, --fullscreen	Start in fullscreen.

The default save file is in:

• macOS: ~/Library/Application Support/shin/<game>/SAVEDATA
• Windows: %APPDATA%\shin\<game>\SAVEDATA
• Linux: ~/.local/share/shin/<game>/SAVEDATA

Progress, settings, gallery unlocks and save slots are all stored in this one file.

shin.ini

A shin.ini file next to the executable (or in Contents/Resources inside a macOS app bundle) can set any of the options above, one per line, using the long option name without --:

game = higurashi
assets-dir = higurashi
text-websocket = 127.0.0.1:9001

Lines starting with ; or # are comments, an empty value leaves an option unset, on/off options such as fullscreen take true or false, and relative paths are resolved from the folder containing shin.ini. Options given on the command line take precedence. See shin.ini.example.

Mods and translations

Every game loads an optional mod.rom from the assets folder before all other archives, so a mod only needs to contain the files it replaces.

Every game also reads an optional UTF-8 localized.toml from the assets folder to translate the engine's own UI text (dialogs, menus, labels). Each entry maps an original string to its replacement:

"確認" = "Confirm"
"達成率:{percent}％" = "Completion: {percent}%"

The localization folder has the full list of strings for Umineko, Higurashi, Gerokasu and Gerokasu2.

It also includes English translations converted from the fan translation projects umineko-catbox-english and HigurashiENX. To use them together with those projects' patches:

• Higurashi: copy higurashi.en.toml to localized.toml in the assets folder. Download and extract HigurashiENX.zip from the HigurashiENX releases, then move atmosphere/contents/0100F6A00A684000/romfs/patch.rmm to mod.rom in the assets folder.
• Umineko: copy umineko.en.toml to localized.toml in the assets folder. Download and extract patch_atmos.zip from the umineko-catbox-english releases, then move contents/01006a300ba2c000/romfs/patch.rom to mod.rom in the assets folder.

Text WebSocket

With --text-websocket 127.0.0.1:9001, every connected client receives each displayed message as plain text. For Umineko, character, Tips and other important text is sent as well. A client that connects later first receives the most recent text.

Controls

The games are played like on the Switch, with a controller, the mouse or trackpad (taps, drags and swipes act as touch input), or the keyboard. The keyboard maps to controller buttons the same way on every screen:

Key	Controller
Arrow keys	D-pad / left stick
Enter	A (confirm, advance text)
Escape	B (cancel, back)
B	X
M	Y
H / J	L / R
K / L	Right stick up / down (scroll)
U / I	Minus / Plus
F	Toggle fullscreen
Left Ctrl (hold)	Skip text while held

A right click acts as B on every screen. The mouse wheel and trackpad scroll wherever the right stick does.

What else is in the box

Aside from the game engine, this repo also includes shin-core, a library for working with the game data, and sdu, a command line interface to it. sdu can extract game data and convert it to more conventional formats:

• .rom - Game data archive
• .bup - Character sprites
• .pic - Backgrounds & CGs
• .nxa - Game audio
• .snr - Game scenario (execution tracing, no decompilation)
• .fnt - Font data
• .txa - Texture archives (used mostly for UI)

Documentation of the engine's formats is collected in this spreadsheet. The autogenerated API docs can be found here.

Building from source

Install Rust; the toolchain version is pinned in rust-toolchain.toml. On Linux, also install the ALSA, udev and GStreamer development packages (on Debian and Ubuntu: libasound2-dev libudev-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev). Then build and run the engine with:

cargo build --release -p shin
cargo run --release -p shin -- --game umineko --assets-dir /path/to/assets

Thanks

Huge thanks to DCNick3 for the original version and for all their work on documenting the engine and its file formats, without which none of this would have been possible!

Disclaimer

This project is not affiliated with Entergram or 07th Expansion. It is an unofficial fan project.

It does not contain copyrighted game data, so you can't play the games if you didn't buy them.