19. Weapons

In short: every attack with a weapon shows that weapon in every battle mode: guns aim and fire, bows release arrows, blades swing with a trail, staves glow. The look is a Weapon Presentation data asset, and how the weapon sits in the hand is fitted in Unreal's own Skeleton Editor with the Fit Weapon tool, with the left hand placed by IK. This chapter covers both, from the first working weapon to sockets, stances, recoil and validation.

19.1 Basics

19.1.1 What you see in battle

• Guns aim, then fire a burst. Each shot has a muzzle flash, an ejected shell, a fire sound, a small camera kick, a tracer that flies to the target and an impact on the target's surface. Each shot gets its own hit reaction.
• Bows and crossbows release an arrow that flies on an arc (straight for a crossbow) and lands with its impact.
• Blades, axes, maces, spears and fists swing with a ribbon trail and a swing sound. The blow lands with the hit effect of the target's surface. A heavy weapon adds a hit-stop.
• Staves play the cast animation and glow at the tip.

The plugin ships one presentation per weapon kind, built only from its own procedural meshes, effects and synthesized sounds, so a project with no effects pack still gets visible gunfire.

19.1.2 Your first weapon, step by step

1. Make the presentation. Content Browser → Add → Miscellaneous → Data Asset → RSE Weapon Presentation. Set Weapon Kind (Sword, Axe, Dagger, Spear, Blunt, Fist, Pistol, Rifle, Shotgun, Bow, Crossbow, Staff, Thrown). The stance follows the kind unless you override it.
2. Put it on a character. Open the character's look (URSECharacterAppearance), add a part in the weapon slot with the weapon's mesh, and set the part's Weapon Presentation. Or give an equipment item its own presentation.
3. Fit it in the hand. Open Tools → RPG Saga Engine → Fit Weapon, pick the character and the weapon, press Fit in Skeleton Editor, and move the socket until the weapon sits right. Save the skeleton.
4. Check. Press Validate in the same tab.
5. Play a battle. The attack uses the presentation.

Shortcut: run Dress My Abilities in the Animation & FX Library (option Weapon Presentations). It classifies your weapon meshes, finds their muzzles, and writes DA_WeaponPresentation_<Mesh> assets from your pack's effects, sounds and gun clips. A presentation you set by hand is never replaced.

19.2 How it works

19.2.1 Which presentation an attack uses

In order:

1. The weapon the unit visibly holds: the look's weapon part (Appearance → Parts → Weapon Presentation) or a worn item's mesh.
2. Its equipped weapon: Equipment → Weapon Presentation, else the presentation of its equipment type (Project Settings → RPG Saga Engine → Weapon Presentation → Equipment Type Kinds and Kind Presentations).
3. In action battles, its action weapon.
4. Otherwise the approach default: Default Melee for melee attacks and Default Ranged for ranged ones. Spells and items show no weapon, except a staff's cast animation.

A unit with a ranged weapon shoots its basic attack from where it stands, even when the rules call that attack melee.

19.2.2 Surfaces

The surface of a hit unit comes from an actor tag named like the surface (Surface.Metal) or a Surface.* tag in the character's personal traits, else Default Unit Surface (Surface.Flesh). A presentation has one impact entry per surface (Surface.Flesh, Metal, Stone, Wood, Energy, or your own child tags) and a Default Impact for the rest. In action battles, world hits use their physical material through Physical Surfaces.

19.2.3 How a weapon is attached to the hand

All attachment goes through one path (RSEWeaponHold). A weapon part of a look, or a worn item mesh, is attached to the wielder's hand for its hold type:

The hold type is Auto from the weapon kind unless you override it on the part or in Fit Weapon.

The right hand has one socket per hold type on the skeleton, on the hand bone: RSE_Pistol_R, RSE_Rifle_R, RSE_OneHand_R, RSE_TwoHand_R, RSE_Polearm_R, RSE_Bow_L and RSE_Staff_R (the names are in Weapon Hold → Hold Sockets). The weapon's pivot sits on the socket. The Skeleton Editor previews an attached asset exactly that way, so what you see in the editor is what battles and exploration show. When the skeleton has the socket, it wins over any hold profile or generated hold, which remain as the fallback.

A weapon whose pivot differs from its category's gets its own socket on the skeleton, RSE_W_<WeaponMesh> (the prefix is Weapon Hold → Weapon Socket Prefix), which wins over the category socket.

The weapon's own sockets (static or skeletal mesh):

They win over a presentation's stored grip and over the measured one. The names are settings (Weapon Hold → Weapon Sockets). Without a Muzzle or Tip socket, a presentation falls back to its own socket names and offsets, then to the weapon's measured tip: the far end of the mesh from the grip along its longest side.

If the skeleton has no sockets at all, weapons attach through a Weapon Hold Profile (URSEWeaponHoldProfile, one per skeleton) or a hold generated from the skeleton's hand (the finger bones tell the palm and finger directions). RSE.Weapons.Hold.SkeletonSockets 0 turns the sockets off, to compare.

19.2.4 The left hand

The left hand reaches the weapon's LeftHand socket with the Two Bone IK of the character's Anim Blueprint, then turns to the socket's rotation with the RSE Hand Rotation node, so the fingers wrap under the handguard. Rotate the LeftHand socket in the mesh editor and the hand turns by as much, live, also in the Skeleton Editor preview.

The hand is described in a frame that is the same on every skeleton (X along the fingers, Z out of the back of the hand), so one weapon socket works on every body. Weapon Hold → Support Hand Rotations gives, per hold type, the hand's orientation when the socket keeps the weapon's own axes; the plugin sets the rifle and the pistol. A hold type without an entry keeps the IK's own rotation, so add one for two-hand melee or staves if you need it. A hold profile can override it per skeleton and hold type (Override Support Hand Rotation).

The animation curve DisableLeftHandIK (or the profile's Disable Support Hand IK Curve) turns off position and rotation together, for reloads or bashes.

19.2.5 The weapon layers in the Anim Blueprint

Add Weapon Layers to Anim Blueprints puts this chain before the output pose of every RSE character Anim Blueprint. Every node is driven by the anim instance; nothing is set by hand:

1. RSE Stance Overlay (from the first upper-body bone): the held weapon's stance over the upper body.
2. Local To Component.
3. Transform (Modify) Bone on the upper spine: the recoil kick of the chest.
4. Transform (Modify) Bone on the weapon arm: the recoil kick of the arm.
5. Two Bone IK on the left hand: the support hand on the weapon.
6. RSE Hand Rotation on the left hand.
7. Component To Local.

Bones come from the skeleton's hold profile, else from the name lists in Weapon Hold settings. A node whose bone the skeleton lacks is skipped by the engine. Anim Blueprints you made earlier get the nodes only after you run the tool; running it again updates the nodes it made.

19.2.6 Stance animations

Each hold of a hold profile has stance clips for its skeleton: Ready, Upper Body Overlay, Aim, Fire, Reload, Attack (variants picked deterministically per battle), Heavy Attack and Cast.

• While a weapon is held, its hold's Ready plays according to Ready Mode: Upper Body (the RSE Stance Overlay node: the legs keep the locomotion, also while walking) or Full Body (replaces the animation set's battle Ready). Profile Default follows the profile's Default Ready Mode (Upper Body unless you change it). The stance fades out while attacks, hits and knock-outs play (Stance Blend Time, 0.2 s).
• A prone, crouched or death clip never plays as a stance: clips pass the same filter as the Fit Weapon idle (Idle Reject Words: prone, crouch, death, sit, ko, lying...). A clip of another skeleton never plays.
• Presentations pick per attacker: the presentation's clip when the attacker's skeleton takes it, else the attacker's own hold profile clip for that role and hold type, else the older fallbacks.
• Suggest Stance Animations fills the empty slots from the Animation & FX Library for one skeleton, best confidence first. Slots you set by hand are never changed.

19.2.7 Guns: fire clips and recoil

A gun never plays a melee clip. Its shot plays, in order: the presentation's clip for the attacker's skeleton, the hold profile's Fire, the animation set's action Fire, the animation set's Recoil pose clip, each only when its name does not read as a melee swing (Gun Reject Clip Words: slash, swing, punch, kick, stab...). Without a fitting clip the gun uses the procedural recoil: the upper spine pitches back and the weapon arm rises, then both recover. Later shots in a burst kick again at 0.6 strength. The kick per hold type is in Weapon Hold → Recoil Defaults (Spine Pitch, Arm Pitch, Duration, Peak Time, an optional Curve), overridable per hold profile (Override Recoil). Characters without an RSE anim instance (placeholder units) keep a simple recoil slide of the whole unit.

19.2.8 Weapons that are part of the body mesh

Some characters carry the weapon inside the body mesh (a gun arm, a modelled blade). Their muzzle and tip are found on the body by name patterns: Body Muzzle Socket Patterns (*muzzle*, *barrel_end*) and Body Tip Socket Patterns (*weapon_tip*, *blade_tip*), sockets first, then bones. When the look holds no weapon part, shots leave from that muzzle and trails follow that tip. The look's own Anchors mapping still wins.

19.2.9 Ranged attacks without a gun

A character holding no gun or bow (a monster's breath, a caster's palm) fires ranged attacks from its Unarmed Shot Anchor: the look's, else Weapon Presentation → Unarmed Shot Anchor (the chest). It never fires from a melee weapon's tip.

19.3 The Fit Weapon tool

Open Tools → RPG Saga Engine → Fit Weapon. (The older Weapon Hold Workbench actor is no longer in the menus; Fit Weapon replaces it and uses the engine's own editors, with live gizmos, undo and preview.)

Pick the Character (a character, a look or a skeletal mesh) and the Weapon (a presentation, an item or a mesh; empty = the look's own weapon). The tab shows the resolved hold type (override with Hold Override), the socket and the idle it will play.

The idle is the hold's stance Ready, else the animation set's Ready, else the standing sample of the locomotion blend space. Without a fitting idle the reference pose shows, never a random clip. Fit Weapon writes only project content (/Game), never the plugin's or the engine's. In the Skeleton Editor, choosing another preview animation ends the Fit session and stops the IK preview, since the IK runs only with the Anim Blueprint.

19.4 Key classes and assets

19.5 Settings

Project Settings → RPG Saga Engine. Full list: Appendix B.

Weapon Hold:

Weapon Presentation: Equipment Type Kinds, Kind Presentations, Default Melee and Default Ranged, Approach Defaults, Unarmed Shot Anchor, Max Tracers Per Attack, Decal Lifetime, Physical Surfaces, Default Unit Surface, Default World Surface.

Weapon Library: the name rules that classify meshes (rifle, ak, smg → Rifle; katana, blade → Sword), Muzzle Socket Words, Shape Overrides Name, Stance Suggestions.

19.5.1 The Weapon Presentation asset

19.6 Blueprint usage

In timelines, four cues use the weapon: Weapon Attack (the whole attack: aim, burst or swing, impacts and hit reactions; fields Weapon, Stance, Heavy, Shots, Approach), Weapon Shot (tracers or projectiles from the muzzle), Weapon Hit Effects (the melee impact on each target's surface) and Weapon Animation (a stance clip on subjects whose skeleton takes it). Abilities without a presentation asset get a default timeline that already writes the weapon attack.

Editor Utility Blueprints and Python can drive Fit Weapon (category RPG Saga | Weapon Fit): Resolve Context, Ensure Hold Socket, Fit In Skeleton Editor, Edit Weapon Sockets, Plan Apply To Category, Execute Changes, Validate, Open Fit Weapon Tab, Is Writable. Category RPG Saga | Weapons has Add Support Hand IK To Anim Blueprints (the node behind Add Weapon Layers) and Suggest Stance Animations.

Example, validate every rifle on a skeleton from an Editor Utility Blueprint:

1. Resolve Context (Character = the look, Weapon = the rifle presentation, Hold Override = Rifle).
2. Validate (Context = the result, Whole Category = true).
3. For Each Loop over the returned strings → Print String.

At runtime, Play Weapon Recoil on the RSE character anim instance kicks the procedural recoil (it needs the recoil nodes of the Anim Blueprint).

ctx = unreal.RSEWeaponFitLibrary.resolve_context(look, weapon, unreal.RSEWeaponHoldType.AUTO)
ok, report = unreal.RSEWeaponFitLibrary.fit_in_skeleton_editor(ctx)
changes, notes = unreal.RSEWeaponFitLibrary.plan_apply_to_category(ctx, False)
unreal.RSEWeaponFitLibrary.execute_changes(changes)
unreal.RSEWeaponLibraryFunctions.dress_weapons_in_folders(["/Game/MyGame/Characters"], False)

19.7 C++ usage

// Kick the recoil of a unit whose Anim Blueprint has the weapon layers.
if (URSEAppearanceComponent* Look = Unit->FindComponentByClass<URSEAppearanceComponent>())
{
    if (URSECharacterAnimInstance* Anim = Look->GetAnimInstance())
    {
        const float Seconds = Anim->PlayWeaponRecoil(ERSEWeaponHoldType::Rifle);
        // 0 = recoil off (CVar RSE.Weapons.Recoil 0) or no recoil nodes.
    }
}

Extension points: author your own URSEWeaponPresentation assets; add a Weapon Hold Profile for a skeleton that needs a custom hand, stance clips or recoil; add rows to Support Hand Rotations and Recoil Defaults for hold types you tune; query the held weapon with URSEAppearanceComponent::GetHeldWeaponHold and GetHeldWeaponPresentation.

19.8 Advanced

• Classification. Handgun names (pistol, revolver, colt, magnum...) weigh more than melee words. Tools (shovel, pickaxe, rake...) hold two-handed. A shape check (Shape Overrides Name) treats a short, flat mesh with a level top and a dropping grip as a pistol even if its pack named it ..._Mace. Presentations made earlier keep their kind: set Weapon Kind or the Hold Override by hand.
• Packs with a different skeleton scale. Apply to Category scales the transferred socket by the hand's size and adds per-weapon RSE_W_ sockets only where the pivot is off tolerance.
• Co-op and headless. Presentations are visual only. Headless battles and simulations skip them and the result is unchanged.
• Performance. Tracers are one small mesh plus a short ribbon, capped by Max Tracers Per Attack. Shells and shot shakes are cues removed by Reduce Effects. Decals live Decal Lifetime seconds. Nothing ticks when idle. The weapon chain costs a few bone operations per animated character; the stance overlay evaluates its clip only while its weight is above zero, and the recoil nodes add zero rotation at rest.
• Debug CVars. RSE.Weapons.Presentation 0 turns presentations off; RSE.Weapons.Hold.SkeletonSockets 0, RSE.Weapons.SupportHandIK 0, RSE.Weapons.SupportHandRotation 0, RSE.Weapons.Recoil 0 and RSE.Weapons.Hold.FineOffsets toggle each part, to compare. See Appendix C.
• Plugin content. Under /RPGSagaEngine/Visual/Weapons, /RPGSagaEngine/Audio/Weapons and /RPGSagaEngine/Data/Weapons: a tracer streak, projectile core, arrow, faceted sword, rifle and gunblade, muzzle flash, shell, sparks, hit flash, trails, impact decal, synthesized sounds, and one presentation per kind plus DefaultMelee and DefaultRanged. All are ours; replace any in the settings or per weapon.

19.9 Troubleshooting

19.10 See also

• 17-characters-visuals-and-animation.md for looks, anim sets and Dress My Abilities.
• 12-battle-action.md for action weapons and the shooting controls.
• 19-camera-and-presentation.md for cues and timelines.
• 07-items-inventory-economy.md for equipment items and their meshes.
• Product page: docs/product/weapons.md.