isledecomp/isle-portable
1
0
Fork 0
mirror of https://github.com/isledecomp/isle-portable.git synced 2026-05-02 10:33:57 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
9eb5dbd664
isle-portable/docs
History
Christian Semmler 9eb5dbd664
Update Phase 1 plan: configurable rooms, animation research, INI config 
- Configurable room size with relay-enforced ceiling (MAX_PLAYERS_CEILING)
- Room config written to isle.ini via OPFS (same pattern as existing settings)
- Multiplayer extension disabled in INI for solo play (zero overhead)
- Hash-based routing (#r/name) consistent with existing isle.pizza navigation
- Three-word Lego Island-themed room names (brave-red-brick style)
- Collapsible in-game overlay
- Animation research: identified CNs###xx generic animations, click body flip,
  disassemble/reassemble, and procedural flip; documented playback mechanisms
  and which are portable to remote players
- Animations broadcast-only (not played on local player)
- String-based animation names in protocol (matches internal lookup)
- Room full: game exits, frontend shows error modal on reload
- Removed future layers reference
2026-03-01 11:44:24 -08:00
..
samples Savegame: kaitai format (#1713) 2026-01-11 00:27:44 +01:00
history.ksy Add initial Kaitai formats to document LEGO Island file formats (#1712) 2026-01-10 21:52:53 +01:00
multiplayer-mvp-assessment.md Implement multiplayer MVP: WebSocket networking, remote player rendering, vehicle support 2026-02-28 12:00:01 -08:00
multiplayer-rooms-and-animations.md Update Phase 1 plan: configurable rooms, animation research, INI config 2026-03-01 11:44:24 -08:00
multiplayer-world-state-assessment.md Update world state assessment: mark Tier 1 done, reassess Tiers 2 and 4 2026-03-01 10:50:43 -08:00
players.ksy Add initial Kaitai formats to document LEGO Island file formats (#1712) 2026-01-10 21:52:53 +01:00
README.md Savegame: kaitai format (#1713) 2026-01-11 00:27:44 +01:00
savegame.ksy Savegame: kaitai format (#1713) 2026-01-11 00:27:44 +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:

image

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 data
  • History.gsi - Sample score history data