Add Kaitai Struct definition for animation data files (.dta) (#1740)

docs/README.md

@@ -20,6 +20,7 @@ Kaitai Struct allows you to define binary formats in a YAML-based `.ksy` file, w
 | [`history.ksy`](/docs/history.ksy) | `.gsi` | Score history and high scores |
 | [`animation.ksy`](/docs/animation.ksy) | `.ani` | Animation data (keyframes, actor references, camera animation) |
 | [`wdb.ksy`](/docs/wdb.ksy) | `.wdb` | World database (textures, parts, models, ROI hierarchies, LODs) |
+| [`dta.ksy`](/docs/dta.ksy) | `.dta` | Animation data (world animation info, model placement) |
 
 ## Using the Tools
 
@@ -46,6 +47,9 @@ ksv samples/pns065rd.ani animation.ksy
 
 # View the world database (from game installation)
 ksv /path/to/lego/data/world.wdb wdb.ksy
+
+# View an animation data file
+ksv samples/BLDRINF.DTA dta.ksy
 ```
 
 ### Kaitai Struct Dump (ksdump)
@@ -67,6 +71,9 @@ 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
+
+# Dump an animation data file to JSON
+ksdump --format json samples/BLDRINF.DTA dta.ksy
 ```
 
 ## Sample Files
@@ -76,5 +83,6 @@ The [`samples/`](/docs/samples/) directory contains example files for testing:
 - `Players.gsi` - Sample player profile data
 - `History.gsi` - Sample score history data
 - `pns065rd.ani` - Sample animation file
+- `BLDRINF.DTA` - Sample animation data file
 
 Note: The world database (`world.wdb`) can be found in your LEGO Island installation at `lego/data/world.wdb`.

docs/dta.ksy

@@ -0,0 +1,135 @@
+meta:
+  id: dta
+  title: Animation Data File
+  application: LEGO Island
+  file-extension: dta
+  license: CC0-1.0
+  endian: le
+
+doc: |
+  Animation data file format for LEGO Island (1997). Contains animation
+  information for world objects including their positions, orientations,
+  and associated models.
+
+  DTA files are located at `<install_path>/lego/data/<world>inf.dta` where
+  <world> is the world name (e.g., "isle", "act1", "act2m", etc.). They are
+  loaded by LegoAnimationManager::LoadWorldInfo() to populate animation
+  information for the current world.
+
+  File structure:
+  1. Header - version (must be 3) and animation count
+  2. AnimInfo entries - animation references with nested model placement data
+
+seq:
+  - id: version
+    type: u4
+    doc: |
+      File format version. Must be 3 for valid files.
+      The game rejects files with mismatched versions.
+  - id: num_anims
+    type: u2
+    doc: Number of animation info entries in this file.
+  - id: anims
+    type: anim_info
+    repeat: expr
+    repeat-expr: num_anims
+    doc: Animation information entries.
+
+types:
+  anim_info:
+    doc: |
+      Animation information for a single animation (AnimInfo struct).
+      Contains metadata about the animation and a list of models involved.
+      Parsed by LegoAnimationManager::ReadAnimInfo().
+    seq:
+      - id: name_length
+        type: u1
+        doc: Length of the animation name in bytes.
+      - id: name
+        type: str
+        size: name_length
+        encoding: ASCII
+        doc: |
+          Animation name identifier. The last two characters are used
+          to look up a character index via GetCharacterIndex().
+      - id: object_id
+        type: u4
+        doc: Object ID used to identify this animation in the game.
+      - id: location
+        type: s2
+        doc: |
+          Location index referencing a LegoLocation. A value of -1
+          indicates no specific location is assigned.
+      - id: unk_0x0a
+        type: u1
+        doc: Boolean flag (MxBool). Purpose unknown.
+      - id: unk_0x0b
+        type: u1
+        doc: Unknown byte field.
+      - id: unk_0x0c
+        type: u1
+        doc: Unknown byte field.
+      - id: unk_0x0d
+        type: u1
+        doc: Unknown byte field.
+      - id: unk_0x10
+        type: f4
+        repeat: expr
+        repeat-expr: 4
+        doc: Array of 4 unknown float values (16 bytes total).
+      - id: model_count
+        type: u1
+        doc: Number of model entries that follow.
+      - id: models
+        type: model_info
+        repeat: expr
+        repeat-expr: model_count
+        doc: Model information for each model in this animation.
+
+  model_info:
+    doc: |
+      Model information defining position and orientation for a single
+      model within an animation (ModelInfo struct). Used to place characters
+      and objects in the world during animation playback.
+      Parsed by LegoAnimationManager::ReadModelInfo().
+    seq:
+      - id: name_length
+        type: u1
+        doc: Length of the model name in bytes.
+      - id: name
+        type: str
+        size: name_length
+        encoding: ASCII
+        doc: |
+          Model name used to look up the character or vehicle.
+          Examples: "caprc01" (race car), "irt001d1" (character).
+      - id: unk_0x04
+        type: u1
+        doc: Unknown byte field.
+      - id: position
+        type: vertex3
+        doc: World position (X, Y, Z) of the model.
+      - id: direction
+        type: vertex3
+        doc: Forward direction vector of the model.
+      - id: up
+        type: vertex3
+        doc: Up direction vector of the model.
+      - id: unk_0x2c
+        type: u1
+        doc: |
+          Boolean flag. When non-zero, this model is considered a vehicle
+          and tracked in the animation's vehicle list (m_unk0x2a).
+
+  vertex3:
+    doc: A 3D point or vector with X, Y, Z components.
+    seq:
+      - id: x
+        type: f4
+        doc: X component.
+      - id: y
+        type: f4
+        doc: Y component.
+      - id: z
+        type: f4
+        doc: Z component.