How-To: Attach Visual Actors
Goal: put a mesh in the character's hand or on their head, decide which machines spawn it, drive armor from the character's skeleton, and know when gear needs an actor class of its own.
1. Add an entry to Actors To Spawn
Each FCrimsonEquipmentActorToSpawn entry produces one attached actor while the equipment is equipped, and is destroyed with it.
| Field | Type | Default | What it does |
|---|---|---|---|
Actor To Spawn | TSubclassOf<AActor> | empty | Optional. Leave empty and the plugin spawns the display actor with your meshes instead. |
Spawn Rule | ECrimsonEquipmentActorSpawnRule | All Machines | Which machines create the actor. See step 3. |
Static Mesh | UStaticMesh* | null | Shown by the display actor. Ignored when Actor To Spawn is set. |
Skeletal Mesh | USkeletalMesh* | null | Shown by the display actor. Ignored when Actor To Spawn is set. |
b Use Leader Pose | bool | true | Skeletal only: drive the mesh from the character's own mesh. See step 4. |
Attach Socket | FName | None | The socket to attach to. Empty attaches at the component origin. |
Attach Transform | FTransform | identity | A local offset applied on top of the socket transform. |
ACharacter, actors attach to its GetMesh() - so socket names are skeleton socket names. For any other pawn they attach to the root component, where a socket name will usually find nothing. Attachment uses KeepRelativeTransform, and Attach Transform is applied before the attach.In BP_Sword's Class Defaults, expand Actors To Spawn, press +, then set Static Mesh to your sword and Attach Socket to hand_r. Leave everything else at its default.
To nudge the fit, expand Attach Transform and adjust Rotation and Location - this is the usual fix when a weapon points the wrong way out of the hand.
hand_r. Unequip and it disappears - the instance destroys every actor it spawned.2. Spawn several actors from one definition
Actors To Spawn is an array. A two-handed weapon with a sheath, or a chest piece plus a cape, is two entries on one definition.
Press + again and fill a second entry with its own mesh and socket. Get Equipment Actors In Slot returns all of them; Get Equipment Actor In Slot returns only the first.
3. Choose the spawn rule
This is the decision that gets multiplayer gear wrong. Pick by asking whether the actor carries gameplay state or is only something to look at.
| Spawn Rule | Who spawns it | Use it for |
|---|---|---|
All Machines (default) | Every machine spawns its own copy, and the copy is forced non-replicating. The server spawns it during the equip; each client spawns it when the instance replicates in, which covers late joiners. | Cosmetics: meshes, shields, capes, anything a player only looks at. |
Server Only | One actor, on the server only. Clients skip it entirely and rely on the actor class replicating itself. Set Replicate Movement is forced on. | Gameplay actors: a projectile launcher that spawns things, a weapon that carries replicated durability. |
Server Only entry whose class does not have b Replicates set exists on the server and nowhere else - clients see nothing. The plugin logs a warning naming the class when it detects this, so check LogCrimsonEquipment if a piece of gear is invisible on clients.All Machines spawns on the server too, not only on clients. That is deliberate: server-side gameplay can query the actor's sockets and bones. Just do not put authoritative state on it - each machine has its own.All Machines entry is visible in both windows. Set the same entry to Server Only with a non-replicating class and it disappears from the client window while LogCrimsonEquipment warns about it.4. Drive armor from the character's skeleton
Armor pieces have to move with the body. b Use Leader Pose (on by default) calls Set Leader Pose Component on the spawned skeletal mesh, pointing it at the character's own mesh so it shares the animated pose instead of running its own animation.
Set Skeletal Mesh to the armor mesh, leave b Use Leader Pose ticked, and leave Attach Socket empty so the piece sits at the mesh origin and follows the skeleton.
The armor mesh must share the character's skeleton for this to work - that is what the leader-pose relationship requires.
b Use Leader Pose is read only when a Skeletal Mesh is set and the spawned actor is the display actor. It does nothing for a static mesh or for a custom Actor To Spawn class - a custom class does its own thing.5. When gear needs behavior, spawn your own actor
Set Actor To Spawn to your own actor class and the plugin spawns that instead of the display actor - your class is responsible for its own meshes. Everything else still applies: it is attached to the socket, and destroyed on unequip.
Create an actor Blueprint with whatever components the gear needs, then set it as Actor To Spawn on the entry. Static Mesh, Skeletal Mesh and b Use Leader Pose are ignored for that entry.
The spawned actor's Owner is the pawn, so Get Owner inside it gives you the wearer without any extra plumbing.
ACrimsonEquipmentDisplayActor, implement its On Display Initialized event, and point Display Actor Class in Project Settings -> Crimson -> Crimson Equipment at your subclass. Every mesh-only entry in the project then uses it, with no per-definition change.See also
- How-To: Add Per-Item Logic
- Concept: Multiplayer
- API Reference