Switchable Weapon Loadouts for One Rigged Character: A Practical Guide

A switchable loadout is a named set of props attached to the same rigged character, where switching sets means toggling mesh visibility, not re-attaching geometry or re-running animation retargeting. In GripForge, gripforge_loadout takes a Library character_id plus one or more named sets (for example sword, sword_and_shield), attaches each prop, creates predictable gf_prop_<slug>_<l|r> nodes, and writes a manifest that records the default set and every alternate set. Visibility toggling is a rendering decision only — colliders, damage activation, and inventory ownership are gameplay systems you still implement in your engine. Treat this article as the loadout-authoring step that happens before that gameplay wiring, not a replacement for it.

Step 1: Decide your named sets before attaching anything

Write down the sets as data first. This avoids re-attaching props twice because you forgot a variant.

Example (conceptual, not executable syntax):

• sword_only: main-hand sword, off-hand empty
• sword_and_offhand: main-hand sword, off-hand buckler (a static prop, not a second weapon)
• dual_wield: two matching daggers, one per hand

Each named set maps to a small list of props with which hand/socket they belong to. That mapping — set name → [{prop, hand}] — is the conceptual shape you should have ready before calling any tool, whether you use GripForge or hand-author it.

Acceptance criteria: every equipped set your gameplay code will request has a corresponding named entry. Choose the default deliberately. Unequipped or holstered behavior needs its own game design and attachment logic; do not assume a hand-attachment tool creates a holster workflow.

Step 2: Attach props per set with gripforge_loadout

Pass the Library character_id and your sets, where each entry references a Library prop_id (for example, a sword prop and a buckler prop pulled from your asset library). Per the documented behavior, the tool:

• attaches each prop to the rig and creates a gf_prop_<slug>_<l|r> node per attachment (so a right-hand sword and a left-hand buckler get distinct, predictable names),
• writes a manifest recording which set is default and which are alternates,
• defaults animate: true, which also retargets the standard clip pack. Equipment still follows its attachment; this option does not turn a rigid weapon into a deforming mesh.

Example loadout data (illustrative, not literal API call):

character_id: CHAR_123
sets:
  sword_and_offhand:
    - prop_id: SWORD_PROP_ID   -> right hand
    - prop_id: BUCKLER_PROP_ID -> left hand
  sword_only:
    - prop_id: SWORD_PROP_ID   -> right hand
default set: sword_only

This is a description of the data shape, not a guaranteed method signature — check current parameters in the MCP documentation before wiring it into a pipeline.

Acceptance criteria: after attachment, each prop has its own gf_prop_* node visible in the scene hierarchy, named distinctly for left/right, and the manifest lists your set names exactly as you defined them in Step 1.

Step 3: Separate visibility from colliders, damage, and inventory

Keep these responsibilities explicit in your design:

Do not assume that hiding the sword mesh for unarmed also disables its collider or damage trace — confirm in your engine that collision and hit-detection are explicitly tied to the active set, not to mesh visibility alone.

Acceptance criteria: when the sword is unequipped or inactive, its damage and collision behavior should match your design. Do not disable unrelated character collision or an intentional unarmed attack while testing the inactive weapon.

Step 4: Test every set against the actual animation clips

A loadout that looks correct in a static pose can still fail mid-swing. For each named set:

1. Play the character's core clip pack (idle, walk, attack, block) with that set visible.
2. Watch the off-hand prop during two-handed poses — bucklers and torches often clip into the forearm if the set wasn't tested against the attack clip specifically.
3. Confirm the sword doesn't detach from the hand socket during fast root-motion clips (a sign the attachment isn't tracking the correct bone).
4. Repeat with the configured default set and confirm it matches the initial visual and gameplay state.

Preview the resulting clips on the target character in the Studio or game engine. gripforge_animate prepares animation content; it is not a general-purpose viewer for an arbitrary existing clip.

Acceptance criteria: each named set passes a visual check across the full clip pack, not just idle. If a set only breaks during one clip (e.g., a heavy attack with a big swing arc), log which clip so animators can adjust the arc or you can adjust the grip offset for that prop.

Step 5: Save the manifest alongside the GLB

The manifest is what lets your game (or a teammate) know which sets exist without reverse-engineering node names. Keep it next to the exported GLB, and keep the gf_prop_* naming intact through export — that's what your engine-side code will query.

Example file layout (illustrative):

hero_character.glb
hero_character.loadout.json   # default + named sets, per Step 2

Acceptance criteria: opening the manifest tells you, without opening the GLB, which set is default and which prop nodes belong to each named set. If a teammate can't answer "what does sword_and_offhand include?" from the manifest alone, it's not documenting enough.

Troubleshooting

• Prop appears in the wrong hand. Check the _l/_r suffix on the gf_prop_* node against what your set definition intended — a swapped hand assignment in Step 1 is the usual cause.
• Prop scale looks wrong on export. Root scale and prop scale are different values; don't assume adjusting one fixes the other.
• Different-sized characters need different offsets. Identical grip offsets across two rigs are not a success requirement — proportions differ, so re-check offsets per character. See the size-fitting checklist below.
• Set switches but hitbox still triggers. That's a gameplay-code gap (Step 3), not a loadout/manifest bug.

FAQ

Does hiding a mesh also disable its collider?

No. Visibility and collision are separate systems; you must explicitly gate collision and damage logic to the active set in your own gameplay code.

How should the game handle an unequipped character?

Define that state explicitly in your gameplay logic. Check the current tool schema before relying on an empty equipment set; the absence of a visible prop alone does not establish collision, damage or inventory behavior.

Does the loadout tool track inventory or ownership?

No. It attaches and names geometry and records sets in a manifest; whether the player "owns" an item is your inventory/save system's responsibility.

For engine-specific attachment mechanics, see the Unreal socket transfer checklist and the weapon-fitting guide for different character sizes. Full parameter details live in the MCP documentation.