Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

UTD Format (Door Blueprint)

Description: The Door (.utd) blueprint defines interactive pathways on a level map. Beyond acting as physical barriers or transitions between areas, doors house lock mechanics, trap configurations, script hooks, and basic visual states (open, destroyed, jammed).

At a Glance

PropertyValue
Extension(s).utd
Magic SignatureUTD / V3.2
TypeDoor Blueprint
Rust ReferenceView rakata_generics::Utd in Rustdocs

Data Model Structure

Rakata maps the Door definition directly into the rakata_generics::Utd 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 Door breaks down into four main categories:

  1. Core Identity & Geometry: The configuration for what the door looks like, its faction, and the text displayed when targeted (e.g., Appearance, TemplateResRef, LocName).
  2. Lock & Trap Mechanics: The parameters defining whether it’s locked, what key is needed, and rules for any attached traps (e.g., Locked, KeyName, TrapType, DisarmDC).
  3. Transition Pathways: The linked destination used when a door acts as a loading zone to another area (e.g., LinkedTo, LinkedToFlags).
  4. Behavioral Hooks (Scripts): The scripts that run when a player opens, destroys, or fails to unlock the door (e.g., OnOpen, OnFailToOpen, OnMeleeAttacked).
  • Active Validation: rakata-lint enforces checks against missing keys or invalid transition references before a module ever reaches the game engine.

Engine Audits & Decompilation

The following information documents the engine’s exact load sequence and field requirements for .utd 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 the primary dispatcher CSWSDoor::LoadDoor at 0x0058a1f0.)

Structural Load Phasing

The engine processes a Door structurally by mapping its sub-fields into distinct operational constraints.

DomainSub-fields EvaluatedPurpose
Scales & State22Reads the physical health, visual appearance, and base traits determining whether the door is locked or indestructible.
Hooks15Attaches custom event scripts that fire when the door is opened, forced, unlocked, or trapped.
Mechanical9Configures the lock difficulty tiers and the specific skill hurdles required to detect and disarm any attached traps.
Transitions4Links the door strictly to another area (.are), turning it into a physical loading screen transition node.

Core Structural Findings

The CSWSDoor parser natively guarantees strict state adjustments upon parsing.

Engine RuleRuntime Behavior
Appearance TruncationThe engine reads Appearance as a 32-bit integer but forcefully truncates it to a single byte ((byte)uVar5). Any ID above 255 automatically wraps to 0 and breaks the physical door model.
Static EnforcementIf the door is marked Static, the engine automatically forces plot = 1. This safely guarantees that static level architecture cannot be destroyed by players.
Portrait FallbacksIf PortraitId is 0, the engine hardcodes it to 0x22E. If it is >= 0xFFFE, the engine ignores the integer and falls back to looking up the string Portrait resref instead.
Trap Hook FallbackIf the OnTrapTriggered script is left empty, set to null, or literally named "default", the engine pulls the default standard script from traps.2da instead.
HP SynchronizationCurrentHP is securely clamped against the door’s maximum HP to prevent overflow bugs.

Legacy & Ignored Data

Finding TypeExplanation
Legacy Engine Artifacts7 explicitly mapped template structures (like AnimationState, NotBlastable, OpenLockDiff) are Neverwinter Nights or KOTOR 2 legacy dependencies inherently ignored by the K1 parser.

Implemented Linter Rules (Rakata-Lint)

These static constraints are targeted for implementation under rakata_lint::rules::utd.

  1. Truncation Faults: (Pending) Flags Appearance values over 255 to prevent the engine from wrapping the 32-bit integer out of bounds.
  2. Static Parity: Asserts that Plot is active if Static is also active.
  3. Invalid Hooks: (Pending) Scans for explicitly empty or "default" OnTrapTriggered references that invoke the traps.2da fallback.
  4. Portrait Anomalies: (Pending) Detects PortraitId mappings equal to 0 or >= 0xFFFE.
  5. HP Bounds: Ensures initialized CurrentHP safely rests at or below the standard HP total.