UTI Format (Item Blueprint)

The Item (.uti) blueprint serves as the central data model for all tangible loot, weapons, armor, and usable gear in the game. It defines how an item physically appears on characters, what custom properties or stat bonuses it applies through specific upgrade hierarchies, its intrinsic monetary cost, and exactly what its runtime state behaves like when dropped into the world map.

At a Glance

Data Model Structure

Rakata maps an Item into the rakata_generics::Uti struct. The struct’s Rustdocs document every field’s binary schema and GFF mapping; the table below is the high-level anatomy.

rakata-lint validates these fields against the engine constraints documented below.

Engine Audits & Decompilation

The following information documents the engine’s exact load sequence and field requirements for .uti 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 CSWSItem::LoadDataFromGff at 0x0055fcd0, the active-property predicate CSWSItem::IsFriendlyUsableItem at 0x00553900, the property-string resolver CSWSItem::GetPropertyStrings at 0x00554e00, and the IPRP table loaders CTwoDimArrays::LoadIPRPCostTables at 0x005c4730 / LoadIPRPParamTables at 0x005c49c0.)

Structural Load Phasing

The engine processes an Item structurally across multi-pass capabilities mappings.

Core Structural Findings

The engine rigorously evaluates base-item mapping constraints from 2DA arrays and aggressively overrides improperly defined models.

Most of the remaining top-level fields default to a carried-over constructed value rather than a fresh literal, in the same “read’s own default argument is the object’s current member” mechanism documented elsewhere on this page: BaseItem carries over to 30, LocalizedName/Tag to empty, StackSize to 1, Plot/Stolen/NonEquippable/NewItem/DELETING to false, and AddCost/Upgrades to 0. TextureVar is the one exception among these – when it’s actually consulted at all (base item’s model_type == 1), it’s read with a hardcoded literal default of 1, unconditional, not a carry-over.

PropertiesList Scalars: Six of Seven Default to Uninitialized Memory, Not Zero

PropertyName, Subtype, CostTable, CostValue, Param1, Param1Value, and ChanceAppear each get read with a literal default of 0 passed to the read call – but that 0 is never actually committed if the field is absent. Each of the seven writes is individually gated on its own presence flag, checked field-by-field right before the property struct member is set. Because the property array itself comes from a raw, unzeroed allocator, an absent field on an otherwise-populated PropertiesList entry doesn’t resolve to 0 at all – it leaves that struct member holding whatever was already sitting in that heap memory. This is a real correctness hazard, not just a documentation nuance: a linter (or a decoder) that assumes “absent property field reads as 0” is wrong for all seven of these, and should instead flag partially-specified property entries as producing undefined values.

(Note also: rakata models PropertyName as an INT-typed field, but the engine actually reads it with a 16-bit WORD read, same as Subtype and CostValue.)

Useable, UsesPerDay, and UpgradeType (already documented above) are the exception: those three are stamped unconditionally with no presence gate on the write, so they’re the only fields in a PropertiesList entry that are genuinely deterministic when absent.

A related edge case at the entry level, distinct from the per-field gating above: if a PropertiesList entry’s own struct is completely empty (zero fields at all, not just one missing label), the engine’s counting pass folds it into the passive tally, but the populate pass then skips writing it entirely once it reaches that entry. The property array was sized assuming that entry would be populated, so the slot it would have occupied is left as the same kind of uninitialized heap memory described above – an entirely empty entry doesn’t drop cleanly, it leaves a hole.

Property Table Dispatch

A UtiProperty carries three indices that point through three separate registry-of-registries chains. The engine holds no hardcoded mapping for any of them; every dispatch is a 2DA cell read, so mods that extend the underlying tables surface without engine modification.

Per-property subtype dispatch (resolved at display time inside GetPropertyStrings at 0x00554e00):

Cost-table dispatch (resolved eagerly at startup inside LoadIPRPCostTables at 0x005c4730):

Param-table dispatch (resolved eagerly at startup inside LoadIPRPParamTables at 0x005c49c0):

Engine constraints:

• Both iprp_costtable.2da and iprp_paramtable.2da row counts are stored as byte (u8) in CTwoDimArrays. Rows past index 255 are silently truncated by the loader and the affected per-property tables never get loaded into memory.
• Column-name lookups in 2DAs are case-sensitive at the engine API (C2DA::GetINTEntry / GetCExoStringEntry compare verbatim). The exact spellings the engine uses are Name, SubTypeResRef, TableResRef, Label, and ClientLoad.
• The subtype 2DA listed in SubTypeResRef is loaded lazily on display via GetPropertyStrings, not eagerly at startup. A missing subtype 2DA fails only the call that needs it, not the whole game load.
• The Name column on every level of the dispatch is a TLK strref. The Label column on the same row holds a developer-readable identifier (e.g. Damage_Bonus) that does not require talktable resolution.

Cost-Table Magnitude Resolution

The cost-table dispatch chain documented above ends at “the row at CostValue carries the cost effect for this property; column layout varies per cost table.” This section pins down the column layout for vanilla K1’s iprp_costtable.2da entries and how each Apply<PropertyKind> handler reads from them, sourced from the CSWSItemPropertyHandler::Apply* family in swkotor.exe (handlers cluster around 0x004e5490-0x004e7e80 and 0x004e9230-0x004e9390).

iprp_costtable.2da (vanilla K1) — index to per-cost 2DA mapping:

Per-handler magnitude resolution. Each Apply<Kind> handler that needs a cost-table magnitude calls CTwoDimArrays::GetIPRPCostTable(<index>) then C2DA::GetINTEntry(table, row=CostValue, column, out). The integer that comes back is the engine-side magnitude (in the units appropriate to the property kind: bonus number, damage soak amount, save delta, etc.). The column name is read case-sensitively; the only two columns the vanilla handlers consult are Value and Amount.

Handlers that bypass the cost-table dispatch. A surprising number of vanilla handlers do not call GetIPRPCostTable at all and instead consume CostValue (or another property field) directly as the magnitude:

• ApplyDamageBonus (covers PropertyName 11 Damage, 12 DamageAlignmentGroup, and 13 DamageRacialGroup in one switch) reads CostValue straight as the damage amount. There is no per-cost 2DA lookup. The iprp_damagecost.2da table is used for cost calculation (GetCost), not for damage-magnitude resolution.
• ApplyEnhancementBonus and ApplyAttackBonus read (Rules->internal).all_2DAs->iprp_meleecost via direct struct-field access (not through GetIPRPCostTable), then read column Value. Equivalent to a cost-table-index 2 (iprp_meleecost) dispatch, just inlined.
• ApplySkillBonus and ApplyBonusFeat read the magnitude / feat id from the property struct directly.
• ApplyImmunity switches on the subtype id and assigns one of ten hardcoded engine constants; no 2DA is consulted.
• ApplyRegeneration uses CostValue as the regen amount and a hardcoded 6000 ms tick interval; no 2DA.

Implications for decoded magnitude resolution. A decoder that resolves property magnitudes should:

1. First check whether the property kind is on the cost-table list above; if yes, read the resolved magnitude from the listed cost 2DA at row CostValue, column Value or Amount, with the documented post-processing.
2. If the property kind is on the bypass list, the magnitude is CostValue directly (or, for ApplyImmunity, hardcoded per subtype).
3. For ApplyDamageImmunity, the cost-table index is read from the property’s own CostTable field rather than being hardcoded per handler; mod-extended cost tables resolve through the same path.

Vanilla itempropdef.2da Label Reference

The following table lists every label in the vanilla K1 itempropdef.2da. The decoder in rakata_generics::decoded matches on the Label column at the row indexed by UtiProperty::property_name. The Subtype 2DA column is the file’s SubTypeResRef cell verbatim (lowercased per the engine’s case-insensitive resref handling); an empty cell means the property has no subtype dimension.

The four rows the engine treats as active (loaded into the per-character usable-ability table per IsFriendlyUsableItem) are marked. Every other row is passive.

Mod content extends this table with rows past index 59. The decoder’s typed-variant dispatch matches by Label, so a mod-added kind surfaces as DecodedProperty::Unknown { property_label: Some("ModLabel"), .. } instead of as a dispatch hole.

Legacy & Ignored Data

Implemented Linter Rules (Rakata-Lint)

Phase 1 (intra-resource, no context)

Implemented under rakata_lint::rules::uti.

1. UTI-001 (Model Truncation Safety): Warns when ModelVariation == 0; the engine forces this to 1 at runtime.
2. UTI-002 (Dead Cost Fields): Informs when Cost is set; the engine ignores this and computes item cost dynamically.
3. UTI-003 (Dead Body Overrides): Informs when BodyVariation is set; the engine queries baseitems.2da instead.
4. UTI-004 (Toolset-Only Fields): Informs when any of TemplateResRef, Comment, PaletteID, or UpgradeLevel are set; never read by the K1 engine.
5. UTI-005 (Conditional TextureVar): Informs when TextureVar is set; only evaluated if the base item’s 2DA model_type is exactly 1.

Phase 2 (range / 2DA, requires LintContext)

Implemented under rakata_lint::rules::uti_range.

6. UTI-006 (Base Item Bounds): Errors when BaseItem does not resolve to a row in baseitems.2da (or is negative); the engine indexes the table directly to look up model type, equip slot, and weapon class – an invalid id either crashes the load or produces a corrupt item.
7. UTI-007 (Valid Capability Bounds): Errors per PropertiesList entry when PropertyName does not resolve to a row in itempropdef.2da, or when Subtype does not resolve to a row in the per-property iprp_*.2da named by itempropdef[PropertyName].SubTypeResRef (skipped when the row has no SubTypeResRef, i.e. the property kind has no subtype dimension). UpgradeType and UsesPerDay use the engine’s 0xFF “not set” sentinel; both the absent-field and explicit-0xFF forms decode as “not set” and the rule does not flag either.

Pending

• Resref Existence: UTI’s only ResRef field is the toolset-only TemplateResRef (never read by the engine), so the per-format resref-existence rule from B6 was deliberately omitted.