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

UTW Format (Waypoint Blueprint)

Description: The Waypoint (.utw) blueprint defines static reference coordinates within an area map. Unlike functional triggers or physical placeables, waypoints act exclusively as invisible logic markers. They provide coordinate anchors for creature patrol routes, spawn locations, camera focal points, or visible map pins in the player’s UI.

At a Glance

PropertyValue
Extension(s).utw
Magic SignatureUTW / V3.2
TypeWaypoint Blueprint
Rust ReferenceView rakata_generics::Utw in Rustdocs

Data Model Structure

Rakata maps the Waypoint definition directly into the rakata_generics::Utw 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 Waypoint breaks down into three main categories:

  1. Core Identity: The basic identifiers that define the waypoint’s name and tag used heavily by scripts (e.g., Tag, LocalizedName).
  2. Spatial Geometry: The exact map coordinates and facing orientation that creatures or cameras will reference (e.g., XPosition, XOrientation).
  3. Map Navigation Notes: The text and toggles that dictate whether the waypoint draws a physical pin on the player’s mini-map UI (e.g., HasMapNote, MapNote).
  • State Validation: rakata-lint checks the data against engine constraints to prevent runtime bugs or dead data paths.

Engine Audits & Decompilation

The following documents the engine’s exact load sequence and field requirements for .utw files mapped from swkotor.exe.

(Decompilation logic for this section was audited and verified via native Ghidra pipeline against swkotor.exe, explicitly pulling from CSWSWaypoint::LoadWaypoint at 0x005c7f30.)

Structural Load Phasing

FunctionSizeBehavior
LoadWaypoint682 BThe main constructor. It loads the waypoint’s identity, map geometry, and checks for mini-map pins.
LoadFromTemplate134 BA fallback used when dynamically spawning a waypoint from a script.

Core Structural Findings

Engine RuleRuntime Behavior
Map Note Two-Gate PatternIf HasMapNote is 0 or missing, the engine skips reading the map note entirely. If it is 1, it reads the strings but uses a second gate: if the MapNote string itself is missing, the entire map pin block is discarded silently.
Orientation NormalizationThe engine computes the squared magnitude of the orientation vectors. If it is not exactly 1.0, it automatically calls Vector::Normalize() to fix the math. Non-unit vectors are tolerated but corrected instantly at load.
Position OverrideWhen a waypoint is loaded from a .git area layout via LoadWaypoints, the engine re-reads the X and Y coordinates directly from the .git file, completely overriding the .utw. It also forcefully calculates the Z height based on the terrain collision mesh via ComputeHeight.
Dynamic IdentificationWaypoints never pull an ObjectId from their own .utw file. It is always forcibly assigned by the .git list element (defaulting to 0x7f000000).

Legacy & Ignored Data

Finding TypeExplanation
Superseded Legacy FieldsOlder asset revisions pad the file with fields like TemplateResRef, Appearance, PaletteID, Comment, LinkedTo, and Description. The KOTOR engine completely ignores these.

Implemented Linter Rules (Rakata-Lint)

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

  1. Tag enforcement: (Pending) Flags if Tag is completely empty, as waypoints are primarily targeted by scripts.
  2. Boolean Clamping: (Pending) Ensures HasMapNote acts properly as a BYTE constraint.
  3. Double-Gating Check: (Pending) Detects dead data patterns where MapNote or MapNoteEnabled are defined but HasMapNote is configured to 0.
  4. Orientation Warnings: (Pending) Warns if orientation vectors do not mathematically normalize to ~1.0, documenting the engine’s forced correction.