A toolset for Vagrant Story (2000, Square), authored in TypeScript with Three.js. Contains a mostly working model viewer.

Use Bun for local development:

• bun install
• bun run build
• bun run typecheck
• bun run test
• bun run serve

To run parser tests against extracted game files, create a .env file in this folder and set VSTOOLS_GAME_DATA_DIR to your game data root (the folder containing OBJ, MAP, EFFECT, etc.).

Example:

VSTOOLS_GAME_DATA_DIR=C:\path\to\game-data

Run in Browser

Runs in browsers supporting WebGL, like Firefox. The viewer opens individual files obtained from a CD image which have to be extracted first from your copy of Vagrant Story.

The toolset is developed for the US Version of Vagrant Story but should work with any.

• WEP (weapons)
• SHP (characters)
• SEQ (animations)
• ZUD (basically SHP + SEQ + WEP)
• ZND (zone data)
• MPD (map)
• ARM (minimap)

To open an MPD file, you'll need the correct ZND file. You can find the Zone/Map list here.

When serving the local repo copy, the viewer can auto-load files from query parameters:

• file1: primary file path relative to _refs/vstools/
• file2: optional secondary file path, usually a SEQ or MPD
• seq: auto, battle, or common when file1 is a ZUD
• anim: initial animation index

Examples:

• index.html?file1=data/launches/Z001U00/Z001U00.ZUD&seq=battle
• index.html?file1=data/launches/Z001U00/Z001U00.SHP&file2=data/launches/Z001U00/Z001U00_Common.SEQ&anim=3

The helper script tools/export_zud_for_vstools.py writes launcher pages into _refs/vstools/data/launches/<ZUD>/ that use this format.

Reverse engineering is very rewarding. You get to know assembly, debuggers, system architecture, hacking live programs and much more. Making sense of undocumented file formats is great, kind of archeological fun.

Vagrant Story itself is a unique piece of art, featuring an outstanding character and level design.

• Tremendous work in deciphering Vagrant Story by Michael Collins
• WEP textures fixed by Oliver Barraza
• SHP with vertex colors found and reversed by korobetski

A lot of information on Vagrant Story hacking can be found here: http://datacrystal.romhacking.net/wiki/Vagrant_Story

A prior version was written in Java, which can be found here.