mirror of
https://github.com/isledecomp/isle.git
synced 2026-02-02 18:38:57 +00:00
Add initial Kaitai formats to document LEGO Island file formats (#1712)
* Add initial Kaitai formats * Update README with installation and command examples Added installation instructions for Kaitai Struct Visualizer and updated ksdump command examples. * Update README.md * Update link to Kaitai Struct documentation * Update installation link for Kaitai Struct Visualizer
This commit is contained in:
committed by
GitHub
parent
4bcc2b964b
commit
f52b275130
55
docs/README.md
Normal file
55
docs/README.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# LEGO Island File Format Documentation
|
||||
|
||||
This folder contains documentation for LEGO Island's custom binary file formats using [Kaitai Struct](https://kaitai.io/), 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](https://kaitai.io/#quick-start) (C++, Python, JavaScript, etc.)
|
||||
- Visualized interactively using the [Kaitai Struct Visualizer](https://github.com/kaitai-io/kaitai_struct_visualizer)
|
||||
- Dumped to human-readable formats using `ksdump`
|
||||
|
||||
<img width="1877" height="706" alt="image" src="https://github.com/user-attachments/assets/0d124219-1208-48ce-83bb-f433d9bb84b1" />
|
||||
|
||||
## Documented Formats
|
||||
|
||||
| File | Extension | Description |
|
||||
|------|-----------|-------------|
|
||||
| [`players.ksy`](/docs/players.ksy) | `.gsi` | Player profile save data (usernames) |
|
||||
| [`history.ksy`](/docs/history.ksy) | `.gsi` | Score history and high scores |
|
||||
|
||||
## Using the Tools
|
||||
|
||||
### Installation
|
||||
|
||||
See the [Kaitai Struct Visualizer installation instructions](https://github.com/kaitai-io/kaitai_struct_visualizer?tab=readme-ov-file#downloading-and-installing) for setup details.
|
||||
|
||||
### Kaitai Struct Visualizer (ksv)
|
||||
|
||||
The [Kaitai Struct Visualizer](https://github.com/kaitai-io/kaitai_struct_visualizer) (`ksv`) provides an interactive terminal UI for exploring binary files.
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
|
||||
```bash
|
||||
# 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/`](/docs/samples/) directory contains example save files for testing:
|
||||
- `Players.gsi` - Sample player profile data
|
||||
- `History.gsi` - Sample score history data
|
||||
Reference in New Issue
Block a user