UTT Format (Trigger Blueprint)
Description: The Trigger (.utt) blueprint defines invisible zones placed across level maps. While encounters spawn creatures, triggers operate as tripwires – firing scripts, acting as loading zones to new areas, or springing mechanical traps when a character crosses them.
At a Glance
| Property | Value |
|---|---|
| Extension(s) | .utt |
| Magic Signature | UTT / V3.2 |
| Type | Trigger Blueprint |
| Rust Reference | View rakata_generics::Utt in Rustdocs |
Data Model Structure
Rakata maps the Trigger definition directly into the rakata_generics::Utt struct. To view the exhaustive binary schema and strict GFF field mappings, please refer to the Rustdocs for this struct, where each field is explicitly documented.
A Trigger breaks down into four main categories:
- Core Identity & Geometry: The basic identifiers and coordinate boundaries that define what the trigger is and where it sits on the ground (e.g.,
Tag,Geometry). - Interactive State & Sub-types: Settings that determine if the trigger acts as a loading zone, a trap, or just a generic scripting boundary (e.g.,
Type,Cursor,HighlightHeight). - Trap Mechanics: The parameters defining rules for trap visibility and skill checks required to disarm them (e.g.,
TrapType,TrapOneShot). - Transition & Behavioral Hooks (
Scripts): The event scripts that fire when a character enters, clicks, leaves, or disarms the trigger, as well as the destination area if the trigger acts as a loading zone (e.g.,ScriptOnEnter,LinkedTo).
- State Validation:
rakata-lintchecks the GFF structure directly against the constraints the engine expects.
Engine Audits & Decompilation
(Decompilation logic for this section was entirely audited and verified via native Ghidra pipeline against swkotor.exe, explicitly pulling from CSWSTrigger::LoadTrigger at 0x0058da80.)
Structural Load Phasing
| Function | Size | Behavior |
|---|---|---|
LoadTrigger | 3381 B | The main constructor. It reads the trigger’s properties, scripts, and trap rules. |
LoadTriggerGeometry | 743 B | Reads the X, Y, and Z coordinates that draw the trigger’s boundary on the floor. |
Core Structural Findings
| Engine Rule | Runtime Behavior |
|---|---|
| Behavior Derived from Type | The engine determines the trigger’s behavior and UI cursor based on the Type field. Type 1 makes it a map transition zone. Type 2 makes it a trap. |
| OnClick Duplication Bug | The engine has a known bug where it copies the ScriptOnEnter value and uses it to overwrite the OnClick listener by default, unless explicitly overridden. |
| Trap Hook Fallback | If the OnTrapTriggered script is left empty, set to null, or named "default", the engine ignores it and pulls the default script from traps.2da based on the TrapType. |
| Highlight Clamping | The trigger’s HighlightHeight is ignored by the engine unless it is greater than 0.0. If it is exactly zero or negative, the engine falls back to a default rendering height of 0.1. |
| Contextual Loading | Fields like LinkedTo, LinkedToModule, AutoRemoveKey, Tag, and Faction are only loaded into memory when the Trigger is processed from a .git area layout file. |
| Dual-Path Portraits | If PortraitId is < 0xFFFE, the engine treats it as an ID to resolve the 2DA map icon. If it is >= 0xFFFE, the engine ignores the integer and uses the explicit Portrait string instead. |
Legacy & Ignored Data
| Finding Type | Explanation |
|---|---|
| Legacy Engine Artifacts | As with other templates, older asset revisions include TemplateResRef, Comment, PaletteID, and PartyRequired. The engine completely ignores these. |
| Superseded Legacy Fields | Older asset revisions typically map TrapDetectDC and DisarmDC in the .utt file itself, but the engine ignores them – it calculates DCs dynamically using the rules in the .2da files instead. |
Implemented Linter Rules (Rakata-Lint)
These static constraints are targets for implementation under rakata_lint::rules::utt.
- Trap Type Verification: (Pending) Warns if a trigger has its
TrapFlagset but itsTypeis not equal to2. The engine will ignore its trap settings in this state. - Transition Enforcement: (Pending) Flags triggers where
Type==1is set but noLinkedToorTransitionDestinationis defined. - Height Bounding: (Pending) Detects configuration patterns where
HighlightHeightis≤ 0.0, triggering the mandatory engine fallback to0.1. - Default Script Identification: (Pending) Identifies empty or
"default"OnTrapTriggeredentries to explicitly document which default script the engine will pull fromtraps.2da. - Geometry Safety: (Pending) Ensures that the trigger’s geometry contains at least 3 vertices to form a valid map boundary.