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.

The tracked vertex index is encoded per-frame in packed 3-byte animation commands within the RGM RAGR section (or the equivalent AIAN section in standalone .AI files). Each animation frame can specify which vertex to track, allowing the attachment point to change as the animation progresses.

Locating the Vertex Index in a File

To find an actor’s attachment vertex index in an RGM file:

RAHD record (165 bytes per actor, at payload offset 8 + i × 165)
  └─ offset 0x31: ragr_offset (u32 LE)
        │
        ▼
RAGR section payload + ragr_offset
  └─ read u16 entry_size (0 = end, else payload bytes follow)
  └─ animation group entry:
       +0x02: group_index (u16)
       +0x04: anim_id     (u16)
       +0x06: flag         (u16, low byte only)
       +0x08: frame_count  (u16)
       +0x0A: commands     (frame_count × 3 bytes)
  └─ next entry at: current_position + 2 + entry_size
                │
                ▼
       Per-frame command (3 bytes, packed LE):
         byte0 & 0x0F = opcode
         If opcode is 0, 4, or 10:
           vertex_index = (byte1 >> 6) | (byte2 << 2)
           Sign-extend from 10 bits: if value & 0x200, subtract 0x400

In ISLAND.RGM, Cyrus has 152 animation groups, 58 with attachment commands. Key vertex indices are 1 (hand/sword grip) and −10 (scabbard/hip).

The full animation command format is documented in RGM § RAGR.

Animation Command Stream

Animation group data consists of a 10-byte entry header followed by frame_count × 3-byte packed commands (see RGM § RAGR for the entry layout).

Animation Command (3 bytes, packed)

Each command is a 24-bit packed value. The low 4 bits select the opcode type, which determines how remaining bits are allocated to parameters.

Opcode 0 — ShowFrame (Set Handle + Vertex)

The only opcode that sets the attachment vertex. Encoding: 10-bit handle + 10-bit vertex.

byte 0          byte 1          byte 2
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
├─hdl─┤ ├─op──┤ ├v┤ ├──handle─┤ ├───vertex────┤

opcode       = byte0 & 0x0F                          (4 bits)
handle_index = (byte0 >> 4) | ((byte1 & 0x3F) << 4)  (10-bit signed)
vertex_index = (byte1 >> 6) | (byte2 << 2)            (10-bit signed)

During animation playback, the decoded values are written to the actor struct:

• handle_index → actor animation handle (which 3D object to read from)
• vertex_index → actor tracked vertex (which vertex to read position of)

In ISLAND.RGM, Cyrus uses vertex 1 (hand grip) in 664 commands across combat animations.

Complete Opcode Table

Semantics from engine analysis. Names from UESP where available.

Opcodes 6–10 and 12–14 are implemented in the engine but never appear in any of the 27 shipped RGM files. They may exist in standalone .AI files or be entirely vestigial.

Opcode Usage Census (all 27 shipped maps)

Bit Layout Summary

Handle Index Patching

During loading, commands with opcode type 0 are post-processed. The handle_index field contains a relative index into a per-actor animation handle lookup table. The engine rewrites the packed command in-place to replace the relative index with the resolved runtime animation handle. This table is built from RAAN entries loaded for the actor.

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 (x, y, z) float position of the given vertex from the current animation frame. For frame 0: reads base_vertices[vertex_index × 12]. For animated frames: applies delta-compressed offsets (i8×3 or i16×3) from the base frame. Returns float[3].
4. Result is scaled by a global constant and rounded to integer world coordinates.

Item Data (from INVENTRY.ROB)

Items are loaded from a ROB file keyed as "ITEMS" (INVENTRY.ROB). The item initialization function iterates all items and populates per-item runtime fields:

Attachment Transform

Two nearly-identical functions compute the held item’s world transform. Both:

1. Read two vertex positions from the actor’s current animation frame (via the tracked vertex index).
2. Add world position offsets.
3. Rotate by the actor’s orientation matrix (actor struct +0x51).
4. Compute heading and pitch from the direction between the two points.
5. Build item rotation from the computed direction + actor roll.
6. Set item world position = vertex position + (actor radius × scale factor).

The two routines differ in scale factor, corresponding to the “in-hand” and “on-hip/scabbard” attachment positions.

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.

Data Flow Summary

File data (RGM):
  RAHD record → ragr_offset (offset 0x31)
       │
       ▼
  RAGR section payload + ragr_offset
       → size-prefixed entries (u16 entry_size; 0 = end):
            +0x02 group_index, +0x04 anim_id, +0x06 flag,
            +0x08 frame_count, +0x0A commands (frame_count × 3 bytes)
            command bits 14–23 = vertex_index (for opcode 0/4/10)

Map load:
  RAAN entries → load .3DC animation files → get runtime handles
  RAGR         → load animation command streams
                 → patch handle_index from relative to absolute

Runtime (per frame):
  Animation playback → decode 3-byte command for current frame
                     → extract vertex_index + handle_index
                     → store in actor struct (+0x24f, +0x251)

  Item attachment    → read vertex position from current anim frame
                       using stored handle + vertex index
                     → compute world transform (position + orientation)
                     → place item model at computed transform

External References

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