UTI Format (Item Blueprint)

A .uti file is an item: every weapon, suit of armour, medpac, upgrade component and piece of loot in the game. It defines how the item appears on a character, what stat bonuses and abilities it carries, its cost, and how it behaves when dropped into the world.

UTI is built on GFF (Generic File Format), the engine’s labelled key/value tree. If you have not read the GFF page, start there.

This page documents UTI’s field defaults, load-order quirks, and the item-property dispatch chain into iprp_*.2da. Evidence is drawn from Ghidra decompilation of swkotor.exe (K1 GOG build), cross-checked against a full K1 install’s vanilla .uti corpus. The tables below are lookup surfaces, meant to be searched rather than read start to end.

At a Glance

The file is mostly indices, not values

Hold this and the rest of the page follows. A .uti says very little about an item directly. It says which rows of which 2DA tables describe it, and the tables carry the meaning.

An item’s damage bonus is not a number in the file. It is a PropertyName indexing itempropdef.2da to get the kind, a Subtype indexing whatever table that row names, and a CostValue indexing a cost table to get the magnitude. Change the tables and the same file means something different.

Three consequences run through everything below:

• Some fields in the file are dead because a table supplies the real value. Cost is recomputed from the properties. BodyVariation is overwritten from baseitems.2da. Neither reaches an engine decision.
• The tables load once, at startup. A mod’s baseitems.2da takes effect when the game launches, not when an item loads, so nothing about a .uti read consults the file on disk.
• Nothing is hardcoded, so mods extend the vocabulary. Property kinds come from a Label column rather than a compiled table, so an install with mods has kinds this page does not list.

The one place that model breaks is PropertiesList, where absent fields do not default at all. That is the sharpest hazard on the page and has its own section.

Field Schema

The format’s field families, as an orientation before the full list.

Engine Audits & Decompilation

Read 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 and LoadIPRPParamTables at 0x005c49c0.

(Provenance: derived, not attested. The rows below have not been separately re-derived, so they sit on the reverse-engineering queue. Claims resting on less than the rest say so inline.)

The load path

Rules the engine enforces

ModelVariation falls back through ModelPart1, then gets bumped off zero

A ModelVariation of 0 is forced to 1 on load, so an item always has visible geometry rather than rendering as nothing.

Where ModelVariation is absent entirely, the read falls back to the older ModelPart1 label before the same zero-check applies, so ancient files get the same protection.

ModelPart1’s own absent default is not a literal. Its fallback argument is whatever the already-failed ModelVariation read produced, which is the item’s prior model_variation. Two carry-overs chained, and only then the bump to 1.

ModelPart2 and ModelPart3 are read nowhere. Neither field-name string exists in the binary. Files carrying all three are following authoring-tool habit; only ModelPart1 reaches the engine.

Cost is dead, and you should still write it

GetCost() derives an item’s value from its properties, so the integer in the file reaches no engine decision. That makes it a recomputed-at-load field rather than one a writer may drop.

Every other toolset in the ecosystem displays the file’s copy, because deriving the number means walking the property list and the cost tables. An item written with no Cost reads as worthless everywhere except in the game itself, and a modder comparing two items in an editor has nothing to compare.

So compute it if you can and preserve it if you cannot. UTI-002 reporting that Cost is populated tells you the engine will not read it, which is worth knowing and is not an instruction to remove it.

BodyVariation is dead and TextureVar is gated

BodyVariation is dead by the strongest test available: no ReadField* or GetFieldByLabel call for the label exists anywhere in LoadDataFromGff, confirmed by reading the function in full. It is not “read and ignored” the way some legacy fields are. The string appears only in SaveItem, serializing a value that came from elsewhere.

The item’s body_var member is populated from baseitems.2da instead, in the model_type == 1 block that also gates TextureVar, and that overwrites whatever a .uti supplies. TextureVar is bypassed entirely unless the base type is model type 1.

The baseitems.2da columns, and when they are read

None of them are read while a .uti loads. CSWBaseItemArray::Load (0x005b31d0) reads the whole table into a cache once at startup, and CSWSItem::LoadDataFromGff (0x0055fcd0) consults that cache. So a baseitems.2da shipped by a mod takes effect at launch rather than per item.

BodyVar is a string column rather than an integer. The cache loader uppercases it, and where the value is a single letter A through J it becomes that letter’s offset from A, plus one. Anything else defaults to 1. All of that happens in the cache loader, not at read time.

Container gates on non-zero rather than on a particular value. Both consumers test the cached field the same way, so any non-zero entry turns the behaviour on.

No base item in a retail install is a container. Every populated row of baseitems.2da carries 0, and the one row that does not is a placeholder with an empty label and almost no cells filled at all. So an item’s nested ItemList is code the engine reaches and vanilla data never triggers: nothing shipped exercises the non-zero branch, and what the engine does with an item that declares contents is untested by shipped content. Containers a player opens are placeables, and their contents hang off the placeable rather than off an item.

Measured over baseitems.2da as read from the vanilla install’s chitin.key, by two independent paths through the table reader.

The read and write gates are the same condition, and that is a result rather than an assumption. CSWSItem::LoadDataFromGff consults the cache and hands off to ReadContainerItemsFromGff (0x0055f0f0) where Container is non-zero; CSWSItem::SaveItem (0x0055ccd0) makes the identical test off the identical lookup before handing off to SaveContainerItems (0x0055cfa0). They were checked against each other because a divergence would have meant an item could be written carrying contents its own loader then silently drops. There is no divergence.

Provenance: traced, per call site. The list transfer behind either handoff was not followed; the question was the gate.

Dropable and Pickpocketable cannot carry their constructed value

Dropable sets bit 3 of the item’s flag word and Pickpocketable sets bit 4.

CSWSItem’s constructor turns both bits on, but each read is a hardcoded literal 0 with no presence check, so it overwrites that true back to false on every load whether the field is present or not. Neither ever carries the constructed default forward.

An absent Identified means identified

Identified defaults to a hardcoded 1, stamped unconditionally with no presence check. That is a different mechanism from most of the item’s booleans, which carry over a constructed value.

There is a second override on top: once the property list finishes loading, an item with no active and no passive properties has the identified bit forced back to 1 regardless of the file. An explicit Identified = 0 on a property-less item is overwritten.

The ordinary carry-overs

The remaining top-level fields take the object’s current member as the read’s fallback:

TextureVar is the exception: where it is consulted at all, it reads with an unconditional hardcoded literal 1.

PropertiesList scalars hold uninitialized memory, not zero

This is the one place where “absent” does not resolve to anything predictable.

An absent property field does not read as 0. PropertyName, Subtype, CostTable, CostValue, Param1, Param1Value and ChanceAppear are each read with a literal 0 passed to the read call, but that 0 is never committed when the field is absent. Every one of those writes is separately gated on its own presence flag, checked right before the struct member is set.

The property array comes from a raw unzeroed allocator, so a missing field on an otherwise-populated entry leaves that member holding whatever was already in that heap memory.

That is a correctness hazard rather than a nuance. A linter or decoder assuming absent-reads-as-zero is wrong for every one of them, and should flag a partially-specified property entry as producing undefined values.

PropertyName is read with a 16-bit WORD read, same as Subtype and CostValue, not a 32-bit INT.

Useable, UsesPerDay and UpgradeType are the exception. Those three are stamped unconditionally with no presence gate on the write, so they are the only fields in a PropertiesList entry that are deterministic when absent.

An entirely empty entry leaves a hole rather than dropping cleanly. If an entry’s own struct carries no fields at all, the counting pass folds it into the passive tally, but the populate pass then skips writing it once it reaches that entry. The array was sized assuming the entry would be populated, so the slot it would have occupied is left as the same uninitialized heap memory.

Property table dispatch

A UtiProperty carries three indices pointing 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:

Constraints on the dispatch

• Both iprp_costtable.2da and iprp_paramtable.2da row counts are stored as a 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-insensitive at the engine API, unlike GFF’s own case-sensitive field-label lookup. C2DA::GetINTEntry and GetCExoStringEntry both resolve through a shared GetColumnIndex that compares case-insensitively, whether the table loaded from the binary (V2.b) or text (V2.0) path. That is also why the text loader’s _strlwr pass over column headers never causes a mismatch: a mixed-case lookup key matches a lowercased stored header or a verbatim-cased one either way. The conventional spellings the engine’s own callers use are Name, SubTypeResRef, TableResRef, Label and ClientLoad, but any casing resolves identically.
• The subtype 2DA named 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 at every level of the dispatch is a TLK strref. The Label column on the same row holds a developer-readable identifier, for example Damage_Bonus, that needs no talktable resolution.

Cost-table magnitude resolution

The dispatch chain above ends at “the row at CostValue carries the cost effect; column layout varies per cost table”. This section pins down that layout for vanilla K1 and how each Apply<PropertyKind> handler reads it, sourced from the CSWSItemPropertyHandler::Apply* family (handlers cluster around 0x004e5490-0x004e7e80 and 0x004e9230-0x004e9390).

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

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 whatever units suit the property kind: bonus number, damage soak amount, save delta.

The column name is read case-sensitively here, and the only columns the vanilla handlers consult are Value and Amount.

Handlers that bypass the cost-table dispatch. Many vanilla handlers never call GetIPRPCostTable and instead consume CostValue, or another property field, directly as the magnitude:

• ApplyDamageBonus, covering 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. iprp_damagecost.2da is used for cost calculation in GetCost, not for damage-magnitude resolution.
• ApplyEnhancementBonus and ApplyAttackBonus read (Rules->internal).all_2DAs->iprp_meleecost by direct struct-field access rather than through GetIPRPCostTable, then read column Value. Equivalent to a cost-table index 2 dispatch, inlined.
• ApplySkillBonus and ApplyBonusFeat read the magnitude or feat id from the property struct directly.
• ApplyImmunity switches on the subtype id and assigns a hardcoded engine constant per subtype; no 2DA is consulted.
• ApplyRegeneration uses CostValue as the regen amount and a hardcoded 6000 ms tick interval; no 2DA.

What a decoder should do. Resolving a property magnitude takes three steps:

1. If the property kind is on the cost-table list above, read the magnitude from the listed cost 2DA at row CostValue, column Value or Amount, applying the documented post-processing.
2. If it is on the bypass list, the magnitude is CostValue directly, or for ApplyImmunity a hardcoded constant per subtype.
3. For ApplyDamageImmunity, read the cost-table index from the property’s own CostTable field rather than hardcoding it per handler. Mod-extended cost tables resolve through the same path.

Vanilla itempropdef.2da label reference

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 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 past the last vanilla row, and the added rows carry labels this list does not have. A reader dispatching on the numeric index therefore meets kinds it has no case for, on any install with mods. Matching on Label and carrying an explicit unknown case, one that keeps the label it could not place, turns that from a dispatch hole into an ordinary value.

Fields the engine never reads

A field the engine never reads is not automatically one you may leave out; the toolset and other mod tools read these files too. See “the engine ignores this” is not “you may leave it out”.

Implemented Linter Rules (Rakata-Lint)

Intra-resource rules needing no context, under rakata_lint::rules::uti:

UTI-008 and UTI-009 read the raw GFF tree rather than the typed view, because both trigger on absent labels and a typed UtiProperty has already had values substituted. Neither fires on any PropertiesList entry in a retail install: the toolset that wrote them always fills the fields in, so a hand-edited or generated file is the only way to reach either.

Range and 2DA rules requiring a LintContext, under rakata_lint::rules::uti_range:

No resref-existence rule. UTI’s only ResRef field is the toolset-only TemplateResRef, which the engine never reads, so there is nothing for the per-format resref rule to check.

Open questions

• Which column carries the weapon class. WeaponType and WeaponWield are both INT columns in baseitems.2da and both cached independently. No consumer was found mapping either to what this page has informally called weapon class, and CheckProficiencies (0x00510e30) uses a separately cached required-feat array rather than either of them. Picking between them is a naming decision rather than an open trace.
• Which column drives the container gate. The gate itself is traced and the read and write sides agree, but the column behind it has not been followed. So ItemList is documented by what gates it rather than by which column does the gating.
• What the engine does with a container item. No base item in a retail install is a container, so the non-zero branch is code nothing shipped exercises. The behaviour is read from the call sites rather than observed.
• The list transfer behind the container handoff. Traced per call site, but neither ReadContainerItemsFromGff nor SaveContainerItems was followed into its body; the question at the time was the gate.

Every label the schema declares

Generated from the schema, so no label can be quietly left out. How to read these tables.

What the engine does with each field

Fields nobody has examined

Whether the engine reads these has not been established, which is not the same as establishing that it does not. Where When absent carries an answer, that half is settled.