Item Attachment System

How the engine positions held items (swords, shields) on animated characters at runtime. This is a vertex-tracking system — no skeleton or bone hierarchy exists in any Redguard format.

Overview

Character models (3D/3DC) are flat polygon meshes with per-frame vertex animation. There are no bones, joints, or named attachment points in the model data. Instead, the engine tracks a specific vertex index from the character’s animation, reads that vertex’s world position each frame, and places the held item there.

Animation commands select the character’s model and frame. Attachment vertex selection is separate from that frame selection. File ShowFrame commands must not be interpreted as vertex indices. RAEX retains the grip and scabbard vertex inputs.

Animation command stream

Groups contain packed three-byte commands. File ShowFrame commands use a twenty-bit reference into the concatenated RAAN model/frame table. The loader patches them into a runtime model handle and frame index. See animation playback and RGM.

Complete Opcode Table

Names follow UESP where available.

Opcodes 6–10 and 12–14 are implemented in the engine but do not appear in any of the 27 shipped RGM files.

Opcode Usage Census (all 27 shipped maps)

Bit Layout Summary

Frame reference patching

The loader resolves the entire twenty-bit file reference through RAAN. It rewrites the command with a runtime model handle and frame index. Neither field is an attachment vertex index.

Vertex Position Lookup

At each frame, the engine reads the tracked vertex position through this call chain:

1. Entry point — resolves animation handle and reads the tracked vertex.
2. 3D object manager — looks up handle in a table. For “virtual” animations (type 0x02), follows a parent handle chain recursively.
3. Frame builder — reads the requested vertices from the selected model frame. Frame encoding is described in 3DC.
4. Result is scaled by a global constant and rounded to integer world coordinates.

Actor model-point conversion

The runtime model-frame vertex query reads frame zero directly from its stored floating-point base vertices. Later frames with encoding nibble zero convert signed 32-bit coordinates to floating point with a factor of 1/256. Encoding nibble one subtracts signed byte deltas from the base vertex. Encoding nibble two subtracts signed 16-bit deltas from the base vertex, using a factor of 1/256 unless runtime flag 0x10 selects unscaled deltas. Each resulting coordinate is stored as single precision.

The animation-vertex query’s disable gate is the dummy 3D manager state. Initialization reads [3dmanager] dummy_manager from SYSTEM.INI, while the dm command-line option forces that state to one. Static-angle conversion, selected by [debug] convert_static_angles or the convert option, also forces dummy-manager state to one when enabled. The query’s disable comparison accepts exactly one as disabled.

A successful animation-frame vertex lookup supplies floating-point coordinates. The animation-vertex wrapper multiplies each coordinate by 256 and stores each product as single precision before converting the stored values to integers using the active floating-point rounding mode. With nearest-even rounding, half-integer ties select the even integer. It forwards the selected frame and vertex index to the model lookup. A nonpositive animation handle or an animation query-disable value equal to one returns the zero integer vector without model lookup.

The actor model-point query reads an integer vertex from the selected animation frame or the actor’s static model. It converts each coordinate to single precision before applying the actor matrix. For each transformed coordinate, it adds the actor’s local integer position before storing the sum as single precision. The integer position is not rounded to single precision separately before addition. The stored sums then convert to integer coordinates using the active floating-point rounding mode. With nearest-even rounding, half-integer ties select the even integer.

Item model data

Item definitions come from the ITEMS section of the configured item INI. Model names resolve against the loaded model registries, searching the primary registry before the secondary registry and selecting the first case-insensitive name match. The item initialization function iterates all items and populates per-item runtime fields:

World loading replaces the selected world-map filename’s extension with ROB and loads that archive into the primary model registry before initializing item geometry. Model filename resolution discards authored directory components and uses the configured art directory, whose empty-setting default is FXART\\. The inventory-item display loads INVENTRY.ROB into the secondary registry; menu presentation loads MENU.ROB into that same secondary registry. Loading a registry replaces its previous contents.

For weapon items, hand_object_file selects the hand model and hilt_object_file selects the stowed model. The hand model’s ROB segment bbox_extent_y supplies weapon length. The runtime reads that word as a signed 32-bit value before preparing the weapon’s collision spheres. The X and Z extents do not supply this length.

Attachment Transform

The drawn-weapon routine queries the signed RAEX grip vertex pair from the actor’s current animation handle and frame. It adds the supplied local offsets to each vertex with signed 32-bit wrapping, then transforms both points through the actor matrix. The transformed points supply the direction calculation.

The two-point direction subtracts the second point from the first with signed 32-bit wrapping. It computes horizontal distance from the X/Z difference using the integer distance query. With the signed bearing convention whose positive X axis is 512 and positive Z axis is zero, direction pitch is the bearing of (horizontal_distance, delta_y) minus 512. Direction heading is 1024 minus the bearing of (delta_x, delta_z). Both results are masked to 2047; direction roll is zero. Coincident points produce pitch 1536 and heading 1024.

The attachment matrix starts as identity. Its successive rotations use the negated direction heading, one quarter-turn minus the direction pitch, and the negated actor roll. Each angle is masked to 2047. The actor retains pitch plus one quarter-turn, heading, and roll, each masked to the same range.

For each attachment-position component, subtract the first transformed vertex from the second with signed 32-bit wrapping, shift the difference arithmetically right one bit, add the first vertex with wrapping, and shift that result arithmetically right eight bits. Add this integer midpoint to the actor’s floating position and store the sum as single precision. Separately, the actor retains the first transformed vertex plus its floating position multiplied by 256, converted to a signed integer by truncation.

If attachment allocation fails, the routine performs no vertex queries or transform publication.

The stowed-weapon routine uses the signed RAEX scabbard vertex pair with the same local-offset, actor-matrix and direction calculation. It builds the same matrix and retains the same angle fields. Its attachment position uses the first transformed vertex rather than the pair’s midpoint. Add that vertex to the actor’s floating position multiplied by 256 and truncate to a signed integer. Shift this integer arithmetically right eight bits and store it as single precision. An out-of-range integer conversion produces the signed minimum value before the shift.

Weapon State Machine

The weapon state machine selects which attachment routine and which model (hand vs hilt) to use based on the actor’s weapon state:

The draw/sheath frame thresholds are read from the actor’s attribute data (offsets +0x22 and +0x23 from an attribute block pointer at actor +0x272).

The collision sphere tip is offset from the grip point by item.length × -0x100, positioning it along the weapon axis for combat hit detection.

SOUP Script Interface

Scripts drive weapon state transitions through these SOUP functions:

Additional runtime state tracked per actor: hand_pos.vx/vy/vz, hand_angle.vx/vy/vz, hand_type, hand_length, weapon_drawn, hand_item.

Held-item assignment

HandItem(id) is separate from inventory selection and weapon drawing. It rejects assignment while the receiver is in deep water, on an edge, in the air, or holding a weapon. It also requires an open item system, a receiver, and execution outside the shell context. Deep water means stored surface 2 or 4; edge motion states are 10 through 19. The in-air predicate includes nonzero falling, sliding, or queued motion, and motion states 27 through 29.

After admission, the requested ID must resolve to an item record. No owned-count, visibility, or item-type check is made. Success stores the low eight bits of the ID in the actor’s held-item field. It does not change the selected inventory item, assign the weapon attribute, or immediately position or draw an attachment. The function returns zero both after assignment and after a rejected admission.

Data Flow Summary

Animation playback resolves the model and frame first. Item attachment then reads selected vertices from that model frame and computes the item transform. The frame reference and the vertex selection are distinct inputs.

External References

• UESP: Mod:RGM File Format § RAEX — RAEX field names from in-game console
• RGUnity/redguard-unity RGRGMFile.cs — RGMRAEXItem struct definition