mirror of
https://github.com/isledecomp/isle.git
synced 2026-01-12 11:11:16 +00:00
4998bdaf65
Some checks are pending
Analyze / ${{ matrix.who }} annotations (CONFIG) (push) Waiting to run
Analyze / ${{ matrix.who }} annotations (ISLE) (push) Waiting to run
Analyze / ${{ matrix.who }} annotations (LEGO1) (push) Waiting to run
Build / Download original binaries (push) Waiting to run
Build / Current ${{ matrix.toolchain.name }} (map[clang-tidy:true msys-env:mingw-w64-i686 msystem:mingw32 name:msys2 mingw32 shell:msys2 {0} werror:true]) (push) Waiting to run
Build / Current ${{ matrix.toolchain.name }} (map[name:MSVC setup-cmake:true setup-msvc:true setup-ninja:true shell:sh]) (push) Waiting to run
Build / MSVC 4.20 (push) Waiting to run
Build / MSVC 4.20 (BETA10) (push) Waiting to run
Build / Verify decomp (push) Blocked by required conditions
Build / Upload artifacts (push) Blocked by required conditions
Format / C++ (push) Waiting to run
Naming / C++ (push) Waiting to run
* Add savegame.ksy * Updates * Updates
2.3 KiB
2.3 KiB
LEGO Island File Format Documentation
This folder contains documentation for LEGO Island's custom binary file formats using Kaitai Struct, a declarative language for describing binary data structures.
What is Kaitai Struct?
Kaitai Struct allows you to define binary formats in a YAML-based .ksy file, which can then be:
- Compiled into parser libraries for many programming languages (C++, Python, JavaScript, etc.)
- Visualized interactively using the Kaitai Struct Visualizer
- Dumped to human-readable formats using
ksdump
Documented Formats
| File | Extension | Description |
|---|---|---|
savegame.ksy |
.GS |
Main game save data (game state, progress, customizations) |
players.ksy |
.gsi |
Player profile save data (usernames) |
history.ksy |
.gsi |
Score history and high scores |
Using the Tools
Installation
See the Kaitai Struct Visualizer installation instructions for setup details.
Kaitai Struct Visualizer (ksv)
The Kaitai Struct Visualizer (ksv) provides an interactive terminal UI for exploring binary files.
# View a save game file
ksv samples/G0.GS savegame.ksy
# View a Players.gsi file
ksv samples/Players.gsi players.ksy
# View a History.gsi file
ksv samples/History.gsi history.ksy
Kaitai Struct Dump (ksdump)
ksdump outputs the parsed structure as JSON or YAML for scripting and inspection.
# Dump a save game to JSON
ksdump --format json samples/G0.GS savegame.ksy
# Dump Players.gsi to JSON
ksdump --format json samples/Players.gsi players.ksy
# Dump History.gsi to YAML
ksdump --format yaml samples/History.gsi history.ksy
Sample Files
The samples/ directory contains example save files for testing:
G0.GS,G1.GS,G2.GS- Sample main game save files (slots 0, 1, 2)Players.gsi- Sample player profile dataHistory.gsi- Sample score history data