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

UTS Format (Sound Object Blueprint)

Description: The Sound Object (.uts) blueprint defines dynamic, positional, and ambient audio emitters placed throughout a game map. Ranging from environmental hums and randomized crowd chatter to highly localized looping sound effects, .uts files act as physical sound nodes combining strict spatial coordinates with randomized pitch, interval, and varying volume matrices.

At a Glance

PropertyValue
Extension(s).uts
Magic SignatureUTS / V3.2
TypeSound Object Blueprint
Rust ReferenceView rakata_generics::Uts in Rustdocs

Data Model Structure

Rakata maps the Sound Object definition directly into the rakata_generics::Uts 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 Sound Object breaks down into five main categories:

  1. Audio Emitters (Sounds List): An array containing the audio files (.wav files) the engine will sequence or shuffle through.
  2. Spatial Geometry: Distance boundaries determining exactly where the sound is audible in the map (MinDistance, MaxDistance).
  3. Playback Automation: Rules for how the sound loops and strings together (Continuous, Random, Active, Looping).
  4. Algorithmic Variations: Modifiers that dynamically distort the audio file’s pitch and volume at runtime (PitchVariation, FixedVariance, VolumeVrtn).
  5. Procedural Generators: Identifiers that tell the engine if the sound represents specific background noise like crowd chatter or combat ambiance (GeneratedType).
  • State Validation: rakata-lint checks the data against engine constraints to prevent runtime bugs.

Engine Audits & Decompilation

(Decompilation logic for this section was entirely audited and verified via native Ghidra pipeline against swkotor.exe, explicitly pulling from CSWSSoundObject::Load at 0x005c9040.)

Sound Objects represent one of the most streamlined parsers in the engine. They completely lack script triggers and rely almost entirely on mathematically calculating randomized positional matrices and variations natively.

Structural Load Phasing

FunctionSizeBehavior
Load1345 BThe primary physical parser evaluating 24 core audio metric bounds, defining spatial positioning, volume variation, pitch scales, and active looping capabilities.
Sounds List–Iterates through the list of associated audio clips, actively loading sound resrefs into memory sequentially for playback.

Core Structural Findings

Engine RuleRuntime Behavior
Generated Type TruncationThe engine reads GeneratedType as a massive 32-bit integer from the file, but forcefully truncates it and stores only the bottom single byte in memory. Setting this number astronomically high physically corrupts the expected generator type.
Constructor DefaultsIf fields are missing from the .uts binary, the engine physically relies on its internal C++ constructor to populate default values, completely avoiding hardcoded literal checks during parse time.
Spatial Loading ContextWhen loaded globally via a static map (CSWSArea::LoadSounds), the engine skips reading positional coordinates from the .uts file entirely and strictly enforces the X, Y, and Z vectors defined practically in the area’s .git file.
Silent Sound ListsWhen pulling the list of sounds, the engine actively ignores missing entries. It only pushes a sound struct into playable memory if the file actually provided a valid Sound reference string.

Legacy & Ignored Data

Finding TypeExplanation
Legacy Engine ArtifactsSome older tools and legacy file revisions include values like TemplateResRef, LocName, Comment, Elevation, Priority, and PaletteID. These are artifacts from other Odyssey Engine branches (like Neverwinter Nights) and the KOTOR engine never evaluates them natively.

Implemented Linter Rules (Rakata-Lint)

Phase 1 (intra-resource, no context)

Implemented under rakata_lint::rules::uts.

  1. UTS-001 (Volume Ceiling): Warns when Volume > 127; values outside the engine’s byte threshold cause distortion or clipping.
  2. UTS-002 (Audio Integrity): Warns when the Sounds list contains blank entries; the engine skips them silently.
  3. UTS-003 (Emitter Verification): Errors when the Sounds list is empty; the object loads as a dead audio node.
  4. UTS-004 (GeneratedType Truncation): Errors when GeneratedType > 255; the engine truncates to a single byte and corrupts intended behavior.
  5. UTS-005 (Legacy Engine Artifacts): Informs when TemplateResRef, Elevation, Priority, or PaletteID are populated; never natively evaluated by the K1 engine.

Phase 2 (resource existence, requires LintContext)

Implemented under rakata_lint::rules::uts_range.

  1. UTS-006 (Sound Resref Existence): Warns when any non-blank Sounds[i].Sound does not resolve to a .wav resource in the configured sources. Blank entries are skipped (UTS-002 already covers them).