UTP Format (Placeable Blueprint)

A .utp file is a placeable: the containers, scenery and consoles a player can walk up to and use. It carries the object’s appearance, whether it is locked or trapped, how much damage it takes before breaking, and the scripts that fire when somebody interacts with it.

At a Glance

Field Schema

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

Engine Audits & Decompilation

Read from CSWSPlaceable::LoadPlaceable at 0x00585670 in swkotor.exe. Provenance: derived, not attested. The rows below have not been separately re-derived, so they sit on the reverse-engineering queue.

The load path

CSWSArea::LoadPlaceables allocates every placed entry and runs it through CSWSPlaceable’s real constructor unconditionally, before it looks at whether a template applies, the identical shape already confirmed for doors and triggers. So a save-restored placeable’s fields come off the same freshly-constructed object a templated one does, with no separate, lighter-weight path for the save-instance case. Confirmed directly: an absent script hook on a save-restored placeable resolves to an empty resref, since unlike doors and triggers CSWSPlaceable’s constructor never seeds its script slots to "default" (see below), and the trap-settings fields resolve to the same constructed defaults already documented for the blueprint path, identically on both load paths.

Rules the engine enforces

HasInventory and DieWhenEmpty Are Cross-Wired

Writing HasInventory has no observable effect. The label is read as a BYTE with an unconditional literal 0 into a member nothing else in LoadPlaceable acts on.

The member the engine treats as “has inventory” is populated from DieWhenEmpty instead. Both reads are ordinary; the surprise is entirely in the label-to-member wiring, which looks like a field renamed engine-side without the GFF label following.

HP, CurrentHP and the trap flags overwrite their constructed defaults

Five fields construct to a nonzero value and then read with a hardcoded literal 0, unconditional. An absent field lands on that 0, not on what the constructor set.

So a .utp omitting them loads a placeable with no hit points and a trap that neither detects nor disarms.

Plot and Invulnerable are one member, chosen by presence

CSWSPlaceable has no invulnerable member: both labels write the same plot flag. The loader reads Invulnerable first and, where that field is present at all, never reads Plot. Only an absent Invulnerable lets Plot be read. Both fall back to the object’s current plot value, 0 from construction, and either result then feeds the Static-forces-Plot=1 override above.

Invulnerable is live even though the vanilla toolset never writes it. A file supplying one pre-empts its own Plot entirely.

LightState takes its default from placeables.2da

LightState’s absent-value default is not a constant. The read looks the placeable’s already-resolved (and already-truncated) Appearance up in placeables.2da’s LightColor column: an entry there gives 1 (light on), no entry gives 0 (light off).

That makes it a sibling-derived default, unusual in taking its sibling through a 2DA row rather than another GFF field.

Open, Animation and AnimationState form a gated chain

Open is an ordinary unconditional-literal-0 field, and its resolved value decides whether the other two are read at all.

That last row is a presence-chain abort scoped to this one step rather than to the whole struct.

Remaining Absent-Field Defaults

Note

traps.2da columns differ by object type A door or placeable reads its default trap script from MineScript, where a trigger reads TrapScript. Doors and placeables also take their disarm and detect DCs from their own GFF fields rather than from the table’s DisarmDCMod and DetectDCMod, which only triggers consult. See UTT for the trigger side.

The rest of LoadPlaceable’s fields are unremarkable unconditional literals, no divergence between the read’s fallback and the constructed value: Tag and KeyName to an empty string, LocName/Description to an empty localized string, Conversation to an empty resref, Faction/AutoRemoveKey/KeyRequired/Lockable/Locked/OpenLockDC/CloseLockDC/Hardness/Fort/Will/Ref/PartyInteract/TrapDetectDC/DisarmDC/TrapFlag/Useable to 0. Min1HP, BodyBag, IsBodyBag, and IsCorpse carry over the object’s own constructed value (all 0/false) rather than using a fresh literal: mechanically distinct from the group above, same observable outcome. TrapType also carries over, and the constructed value there is the sentinel 0xFF (255), the same sentinel already documented for doors and triggers, feeding the same traps.2da fallback lookup.

The remaining script hooks (OnClosed, OnDamaged, OnDeath, OnDisarm, OnHeartbeat, OnInvDisturbed, OnLock, OnMeleeAttacked, OnOpen, OnSpellCastAt, OnUnlock, OnUsed, OnUserDefined, OnDialog, OnEndDialogue) default to an empty resref, unconditional. CSWSPlaceable’s constructor never seeds its script slots, so an absent hook is genuinely empty here where the same field on a door or trigger would carry the literal string "default". (OnTrapTriggered and OnFailToOpen are documented separately above.)

ItemList entries, and the nested container path

LoadPlaceable’s own ItemList loop reads one field per entry: ObjectId (DWORD), defaulting to the 0x7F000000 object-reference sentinel rather than 0. Everything else about an inventory item comes from the shared item-load chain.

Repos_PosX/Repos_Posy are live fields that do not belong to a placeable. Both BYTE, both defaulting to the sentinel 0xFF, they are read by CSWSItem::ReadContainerItemsFromGff, whose one caller (CSWSItem::LoadDataFromGff) fires only when the item being loaded is itself a container, a bag per baseitems.2da. So they position items nested inside a bag that happens to sit in a placeable’s inventory. LoadPlaceable never reads either.

Each contained item, Dropable included, goes through CSWSItem::LoadItem, the same function at the same address UTM’s ItemList entries call, so the resolution transfers by identity rather than analogy. Both of its branches land the same way:

• With neither EquippedRes nor InventoryRes, it falls through to LoadDataFromGff’s unconditional hardcoded 0.
• With either, it resolves the template, runs LoadDataFromGff (which zeroes the bit), then re-reads under a presence gate that can only push the bit to true.

So a container-nested item with Dropable absent ends up false either way.

An absent ItemList is a skip, not a clear, in both readers: LoadPlaceable’s own loop, and ReadContainerItemsFromGff’s read, the latter gated on the item’s repository pointer being non-null and the list resolving. Neither clears or deallocates first, so a placeable or bag that already holds inventory keeps it.

Fields the engine never reads

What a writer should do with each is a separate question, and it has four possible answers: see the engine ignores this is not you may leave it out.

Implemented Linter Rules (Rakata-Lint)

Phase 1 (intra-resource, no context)

Implemented under rakata_lint::rules::utp.

1. UTP-001 (Plot Chaining Context): Warns when Static=true but Plot=false; the engine forces Plot to true at runtime.
2. UTP-002 (Ghost Value Detection): Informs when GroundPile=false since the engine immediately overwrites this to true on load.
3. UTP-003 (Dead Hook Pruning): Flags OnFailToOpen instances because placeables ignore this event hook (it is door-exclusive).
4. UTP-004 (HP Health Ceiling): Errors when CurrentHP > HP; the engine clamps to HP on template load.
5. UTP-005 (Portrait Shadowing): Warns when PortraitId < 0xFFFE and Portrait resref is set; the resref is ignored at runtime.

Phase 2 (range / 2DA / resref existence, requires LintContext)

Implemented under rakata_lint::rules::utp_range.

6. UTP-006 (Appearance Bounds): Errors when Appearance does not resolve to a row in placeables.2da; engine renders missing model.
7. UTP-007 (Portrait Bounds): Errors when PortraitId (when not the 0xFFFE “use string Portrait” sentinel) does not resolve to a row in portraits.2da.
8. UTP-008 (Resref Existence): Warns when Conversation (.dlg), Portrait (.tga), any On* script hook (.ncs), or ItemList[i].InventoryRes (.uti) does not resolve in the configured resource sources. OnFailToOpen is intentionally excluded, since UTP-003 already flags it as door-exclusive dead data.

Pending

• Appearance Truncation: Warns when Appearance exceeds 255 (engine truncates to a single byte before lookup, distinct from the row-count check in UTP-006).
• Animation Conditional Limits: Verifies that custom AnimationState indices are strictly guarded by Open==0 closures.

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.