GIT Format (Game Instance Template)
Description: The Game Instance Template (.git) orchestrates the exact placement of every single entity within an environment. If the .are file is the underlying “stage”, the .git file acts as the blueprint for its “actors”–defining exactly where creatures initially spawn, where placeables sit, the physical rotation of doors, and the bounds of any active sound emitters.
At a Glance
| Property | Value |
|---|---|
| Extension(s) | .git |
| Magic Signature | GIT / V3.2 |
| Type | Instance Blueprint |
| Rust Reference | View rakata_generics::Git in Rustdocs |
Data Model Structure
Rakata parses the raw GFF structure into the rakata_generics::Git struct.
- Typestate Extraction: By extracting the loosely-typed GFF binary into a strict Rust struct, Rakata inherently standardizes all 13 object sub-lists, creating deterministic representations of
GitCreature,GitDoor,GitPlaceable, etc.
Engine Audits & Decompilation
The following documents the engine’s exact load sequence and field requirements for .git files mapped from swkotor.exe.
(Decompilation logic for this section was entirely audited and verified via native Ghidra pipeline against swkotor.exe, explicitly pulling from CSWSArea::LoadGIT at 0x0050dd80.)
The LoadGIT subroutine is a massive dispatcher. It evaluates 3 immediate root scalars before handing off evaluation to 13 distinct object-list loaders mapping entities. Crucially, the flag UseTemplates dominates this process by dictating whether these lists refer to external files or contain fully inline entity data.
Root Behavior Properties
| Field | Type | Engine Evaluation |
|---|---|---|
UseTemplates | BYTE | Controls whether object arrays read TemplateResRef to construct entities, or fall back to inline evaluation. |
CurrentWeather | BYTE | Standard BYTE. Zeroed to 0xFF on Interior Areas. |
WeatherStarted | BYTE | Standard BYTE. Zeroed to 0 on Interior Areas. |
(The engine validates weather fields against the .are properties immediately during load).
Field Naming Inconsistencies
Due to legacy asset sprawl, the engine evaluates vectors explicitly according to vastly different naming conventions depending entirely on the entity class. This is hardcoded into swkotor.exe.
| Target Lists | Position Paradigm | Orientation Paradigm |
|---|---|---|
| Creatures, Items, Waypoints, Stores | XPosition, YPosition, ZPosition | XOrientation, YOrientation, ZOrientation |
| Doors, Placeables | X, Y, Z | Bearing (Float angle) |
| Area Effects | PositionX, PositionY, PositionZ | OrientationX, OrientationY, OrientationZ |
Warning
Orientation Normalization The engine strictly evaluates 3D orientation logic. If a normalized orientation vector (like in
StoreListorAreaEffectList) inadvertently resolves to0.0unconditionally, the engine catches the math fault and applies a hard fallback vector to(0, 1, 0).
Standard Instance Arrays
Standard loaders evaluate the generic ObjectId, process the localized position/orientation floats, and dispatch behavior mapping logic.
| List Name | Struct Target | Engine Triggers & Fallbacks |
|---|---|---|
| Creature List | LoadCreatures | Positions are explicitly validated defensively through ComputeSafeLocation bounds. |
| Door List | LoadDoors | Save states trigger LoadObjectState. External templates dynamically route to LoadDoorExternal. |
| WaypointList | LoadWaypoints | Completely ignores UseTemplates–it solely relies on inline data! Z-height is shifted dynamically via ComputeHeight. |
| TriggerList | LoadTriggers | Geometry properties reuse native UTT formatting. Contains unique linkage arrays: LinkedToModule, TransitionDestination, LinkedTo. |
Specialized Struct Parsings
| Engine Dispatch Target | Description & Findings |
|---|---|
LoadSounds (0x00505560) | Discard logic: Translates GeneratedType via DWord, but physically truncates it to an 8-bit byte on save, silently discarding the upper 24 bits! |
LoadEncounters (0x00505060) | Highly nested structural array reusing both Geometry and SpawnPointList formats natively built for UTE boundaries. |
LoadPlaceableCameras (0x00505eb0) | Client-side only struct that reads composite GFF spatial types correctly natively! Camera Limit: If it hits 51 camera entries, the loader formally rejects it. |
“List” (Items) (0x00504de0) | Bizarrely, the generic parent entity list List is used specifically to orchestrate Item instances! |
Singular Structs
- AreaProperties: Orchestrates stealth behavior state tracking and dynamic audio states. It physically reads
AmbientSndDayVol/AmbientSndNitVoland explicitly truncates theirINTdeclarations into a single native runtime byte value. - AreaMap: Strict binary blobs evaluating rendering properties (
AreaMapData). It is absolutely bypassed during fresh loads, only executed conditionally during save-game states.
Implemented Linter Rules (Rakata-Lint)
Phase 1 (intra-resource, no context)
Implemented under rakata_lint::rules::git.
- GIT-001 (Weather Zeroing): Informs when
CurrentWeather != 0xFForWeatherStarted=trueis configured; if the area is an interior, the engine forcibly zeros these on load. - GIT-002 (Camera Array Bounds): Errors when
CameraListcontains 51 or more entries; triggers an immediate engine-level loader failure. - GIT-003 (Stealth Clamping): Warns when
StealthXPCurrent > StealthXPMax; the engine clamps on evaluation. - GIT-004 (Ambient Volume Truncation): Warns when
AmbientSndDayVolorAmbientSndNitVolare outside0..=255; the engine truncates to an 8-bit byte. - GIT-005 (Sound GeneratedType Truncation): Warns when any sound’s
GeneratedTypeexceeds 255; the engine truncates to an 8-bit byte on save.
Phase 2 (resource existence, requires LintContext)
Implemented under rakata_lint::rules::git_range.
- GIT-006 (Template Resref Existence): Warns when any per-instance
TemplateResRefdoes not resolve to its expected typed template file:CreatureList[].TemplateResRef(.utc),List[].TemplateResRef(.uti, item instances),Placeable List[].TemplateResRef(.utp),SoundList[].TemplateResRef(.uts),TriggerList[].TemplateResRef(.utt),StoreList[].ResRef(.utm), andEncounter List[].TemplateResRef(.ute). Door and Waypoint instances are inlined and have no template; triggerLinkedToModuleis deferred to Phase 3 cross-resource checks.