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

UTC Format (Creature Blueprint)

Description: The Creature (.utc) blueprint format defines the attributes, stats, and behavior of all in-scene NPCs and monsters. It covers a creature’s identity, class/level, appearance, equipment, and event scripts. Because they hold so much state, Creatures are one of the most dynamic and memory-heavy templates processed by the Odyssey Engine.

At a Glance

PropertyValue
Extension(s).utc
Magic SignatureUTC / V3.2
TypeCreature Blueprint
Rust ReferenceView rakata_generics::Utc in Rustdocs

Data Model Structure

Rakata maps the Creature definition directly into the rakata_generics::Utc 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 Creature breaks down into six main categories:

  1. Core Statistics: The basic stats that define the creature’s physical capabilities (e.g., Strength, Dexterity, base HitPoints).
  2. Identity & Graphics: Identifiers that define who the creature is and what 3D model they use (e.g., Tag, Appearance_Type, Conversation).
  3. Class & Skill Progression: The mechanics that define their level, classes, and skills (e.g., ClassList, SkillList).
  4. Combat Capabilities: The specific feats and Force powers the creature can use (e.g., FeatList, SpellList).
  5. Inventory & Equipment: The exact items the creature spawns with, including both equipped gear and inventory drops (e.g., Equip_ItemList, ItemList).
  6. Event Hooks (Scripts): The behavior scripts that run when the creature reacts to the world, such as taking damage or noticing an enemy (e.g., OnNotice, OnDamaged).
  • State Validation: rakata-lint checks the data against engine constraints to prevent fatal runtime crashes.

Engine Audits & Decompilation

The following documents the engine’s exact load sequence and field requirements for .utc 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 CSWSCreatureStats::ReadStatsFromGff at 0x005afce0.)

Structural Load Phasing

FunctionSizeBehavior
ReadStatsFromGff7835 BThe massive initial pass that parses 57 basic creature scalars including strength, dexterity, and physical appearance.
LoadCreature–Sets up how the creature physically sits in the world, handling their stealth states, collision size, and idle animations.
ReadScriptsFromGff–Attaches all the custom event scripts that fire when the creature notices an enemy, takes damage, dies, or simply stands around (heartbeat).
ReadItemsFromGff–Pulls all loot into memory, structuring items specifically into equipped slots, the backpack, or dropping them entirely if a creature spawns dead.
ReadSpellsFromGff–Specifically extracts the list of any Force powers or combat feats the creature is allowed to use.

Note

Zeroed Data Elements Legacy structures referencing Tail and Wings are explicitly hardcoded to 0 during parsing and completely bypassed by the binary loader.

Core Structural Findings

The engine strictly validates parameters when loading a .utc file. Improper formatting will trigger some of KOTOR’s most notorious game crashes.

Warning

Understanding Fatal Crash Codes (0x5fX) When the game engine parses a file and hits an invalid stat, it completely aborts loading. Instead of recovering gracefully, the engine deliberately triggers a fatal crash to your desktop and returns a specific hexadecimal error code (e.g., 0x5f7 or 0x5f4). The rules below track the specific scenarios where the game will crash.

Engine RuleRuntime Behavior
Class LimitsThe engine expects a strict limit of 2 discrete class types. Providing duplicate class configuration completely crashes the game (Engine Error 0x5f7).
Race BoundsThe engine compares Race against the compiled row count of racialtypes.2da. Exceeding this boundary fatally crashes the map loader (Engine Error 0x5f4).
Saves CalculationPre-computed saving throws (SaveWill, SaveFortitude) in the .utc file are completely ignored dead data. The engine overrides them exclusively by reading willbonus and fortbonus.
Perception FaultsA non-PC PerceptionRange initiates a read against appearance.2da for PERCEPTIONDIST. Failing to resolve this distance fails the entire creature load (Engine Error 0x5f5).
Movement FallbacksIf a unique MovementRate isn’t declared, the engine logic falls back directly to default WalkRate parameters.
Hard ClampingThe engine strictly limits specific numeric bounds upon load: Gender is clamped structurally at a maximum of 4, and GoodEvil is fiercely clamped so that it cannot exceed 100.
Appearance ShiftingIf Appearance_Head is 0, the engine overrides it to 1 to prevent rendering bugs.

Legacy & Ignored Data

Finding TypeExplanation
Legacy Engine ArtifactsA staggering 17 .utc fields (such as Morale, SaveWill, BlindSpot, PaletteID) present in older files are actually Neverwinter Nights or KOTOR 2 superset metrics that the K1 engine natively ignores.

Implemented Linter Rules (Rakata-Lint)

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

  1. Class Duplications: Checks if a creature is misconfigured with identical core class identifiers (preventing Game Crash Error 0x5f7).
  2. Race Bounds: Asserts the mapped Race identifier exists against the actual row bounds of the compiled racialtypes.2da map (preventing Game Crash Error 0x5f4).
  3. Class Limit: Ensures the creature never exceeds the hard-limit of two defined classes.
  4. Structure Clamping: Flags invalid scalars by actively verifying Gender (max 4) and GoodEvil (max 100) configurations, directly mirroring the binary’s hard clamp logic.
  5. Appearance Correction: Detects unconfigured Appearance_Head fields tracking to 0, predicting the engine’s hard override to 1.
  6. Dead Field Tracking: Validates that legacy or ignored values (like SaveWill and SaveFortitude) aren’t configured, saving payload evaluation cost.