mirror of https://github.com/isledecomp/isle.git synced 2026-02-02 18:38:57 +00:00

Files

Christian Semmler e63449fd91 Fix polygon and texture indices documentation in wdb.ksy (#1736 )

Correct the bit layout for polygon_indices to use bits 0-15 (16 bits)
for vertex index instead of incorrectly claiming bits 0-14 with bit 15
unused. Add separate texture_indices type since these are simple U32
values, not packed like polygon_indices. Clarify num_texture_indices
should equal num_polygons * 3 when textured.

2026-01-31 22:12:53 +01:00

samples

Add Kaitai Struct definition for animation files (.ani) (#1734 )

2026-01-30 18:05:48 -08:00

animation.ksy

Add Kaitai Struct definition for animation files (.ani) (#1734 )

2026-01-30 18:05:48 -08:00

history.ksy

Add initial Kaitai formats to document LEGO Island file formats (#1712 )

2026-01-10 21:52:53 +01:00

players.ksy

Add initial Kaitai formats to document LEGO Island file formats (#1712 )

2026-01-10 21:52:53 +01:00

README.md

Add Kaitai Struct definition for world database files (.wdb) (#1735 )

2026-01-31 21:01:38 +01:00

savegame.ksy

Savegame: kaitai format (#1713 )

2026-01-11 00:27:44 +01:00

wdb.ksy

Fix polygon and texture indices documentation in wdb.ksy (#1736 )

2026-01-31 22:12:53 +01:00

README.md

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
`animation.ksy`	`.ani`	Animation data (keyframes, actor references, camera animation)
`wdb.ksy`	`.wdb`	World database (textures, parts, models, ROI hierarchies, LODs)

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

# View an animation file
ksv samples/pns065rd.ani animation.ksy

# View the world database (from game installation)
ksv /path/to/lego/data/world.wdb wdb.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

# Dump an animation file to JSON
ksdump --format json samples/pns065rd.ani animation.ksy

# Dump world database to YAML (from game installation)
ksdump --format yaml /path/to/lego/data/world.wdb wdb.ksy

Sample Files

The samples/ directory contains example files for testing:

G0.GS, G1.GS, G2.GS - Sample main game save files (slots 0, 1, 2)
Players.gsi - Sample player profile data
History.gsi - Sample score history data
pns065rd.ani - Sample animation file

Note: The world database (world.wdb) can be found in your LEGO Island installation at lego/data/world.wdb.