Item Visuals

If you want your made gadget to have visuals that are seen by other clients, follow these steps!

Visuals for nearby clients (foreground/LOD0 render target actors)

Initial setup for item visuals

  • Add an "item visuals details" object to your item PDA's Custom Item Details field.

    • If you're wanting a "gadget in hand", the simplest solution here would be to use the existing BP_ItemVisualsDetails_MeshInHand, which provides some defaults for easy configuration:

      • In the MeshInHand section, you can replace the mesh used (either static mesh or skeletal mesh), modify its material, or change its relative transform and attach socket (the mesh will be transformed and attached to the provided socket on your character's skeleton)

      • All classes provide an Item Visuals Class (extending M2_ItemVisualsBase)

        • This is the object that is spawned on all clients when the item is "active", and is used to actually create the visuals. Any custom behavior required for handling your visuals would be handled here. BP_ItemVisuals_MeshInHand_Default should be enough for most basic use cases - spawning a mesh for players in the foreground & LOD0, and attaching it to the right place. If you need more custom behavior, see Making an Item Visuals Class.

      • Any class extending M2_ItemVisualsGadgetDetails will include animation details:

        • If an Equip Animation is provided, this will be played any time you select/equip the gadget. For more details on how to make equip animations, see Equip/Unequip Animations.

        • If an Unequip Animation is provided, it will be played whenever the gadget is unequipped (returning to no gadget equipped, rather than switching to a different gadget).

        • If a Pose Override Layer is provided, you can swap out the animation set whilst the gadget is in your hand, e.g. changing your upper body pose to be "holding the gadget". For more details on this, see Pose Overrides.

        • NOTE: If using M2_ItemVisualsGadgetDetails, the Item Visuals Class must at least extend M2_ItemVisualsGadget to make the animation changes take effect automatically.

Making an Item Visuals Class

If you want custom behavior that is seen by nearby clients, making a custom child of M2_ItemVisualsBase is the way to go.

There are a number of exposed events that can be implemented to supply your desired behavior:

  • Initialize - called when the class is first created (e.g. when equipping the item)

  • Tear Down - called just before the visuals are removed (when the item is unequipped)

  • Notify Render Target Updated - called when the render target changes, e.g. when switching role, or switching from LOD0 to the animated crowd. This can be used to attach the model to the right place, or show/hide the visuals, depending on whether you need the visuals working in the crowd

  • Notify Network Level Updated - similar to the above, but for network level changing. If you e.g. only want your item present in the network foreground, you can respond to updates here.

  • Notify Details Updated - called when the item's properties have updated. (e.g. by calling InventoryComponent->SetItemProperty). If you want your visuals to respond to some property on the item, you can use this. For more details, see Listening to property updates.

  • Notify Begin Unequip - called when we begin unequipping. We can use this to delay actually removing the visuals, e.g. by first playing an animation. This is handled automatically within classes inheriting from M2_ItemVisualsGadgetDetails. If you do override the unequip behaviour, you will need to make sure to call InformUnequipComplete when done. NOTE: We only trigger this if explicitly unequipping, not if switching from one equipped item to another.

See BP_ItemVisuals_MeshInHand and BP_ItemVisuals_Glowstick_ColorChange for some examples of how these work

Listening to property updates

If you set an item property as Foreground (on the server) or Foreground Client Auth (on the client), it will be reflected in the item visuals

once the property has been set, it can be reachable on the item visuals object, via the NotifyDetailsUpdated event. You can then get the property by calling GetVisualSlotProperty on the Item Visuals Component, using the current item's slot:

Equip/Unequip Animations

If your item PDA's visuals details extends BP_ItemVisualsGadgetDetails and provides an Equip and/or Unequip animation(s), the equip and unequip animations will be played by default.

  • The animations to be played must be "animation montages".

  • The animation should also be set to be "upper body only", so that it looks correct whilst moving. To do that, you need to change the slot to be DefaultGroup.UpperBody

    • NOTE: When you change the slot, your character may end up T-posing. if you move the animation inside the group, it will refresh and fix itself.

  • By default, the gadget visuals will be shown at the start of the equip animation, and hidden at the start of the unequip animation. If you want to show/hide the gadget at a specific point in the animations, you can add the M2 Anim Notify Hide/Show Gadget respectively

Pose Overrides

Some gadgets will want to update your animation set once equipped. We achieve these using the Pose Override Layer field in the BP_ItemVisualsGadgetDetails.

  • The pose override layer is a fresh AnimInstance

    • See ABP_OverrideLayer_GenericGadget for an example.

    • Your "override layer" anim instance will need to implement the ALI_Layers interface, to provide the Animation Layers to override. (These can be controlled in the class settings)

    • For each of the animation layers defined, you can provide an override.

    • If you don't want to override the behavior, pass the input pose straight through.

    • NOTE: Currently we only support overriding the idle animation, or applying a constant override layer to the upper body pose. Further pose overrides beyond these could be doable, but would require modifying the animation blueprints and interfaces. You could provide your own, or the defaults could be extended upon request.

  • The pose is applied at the point NotifyShowGadget is called.

Visuals for distant clients (background/animated crowd)

For characters on the animated crowd, we don't have a lot of the visual polish present for LOD0 actors, such as pose overrides, or equip/unequip animations. Equally, some steps in terms of setup are different:

Setup for animated crowd meshes

  • We need a new item detail added to the PDA: M2_ItemAnimatedCrowdVisualDetails

    • You need to specify a mesh, a socket to attach the model to, and optionally an offset transform.

    • If you are using the same mesh in the crowd and for full actors, the transforms should be the same.

Make sure the static mesh you use has Allow CPUAccess set to true in its details panel. Otherwise you may run into crashes in cooked builds.

See Attaching static meshes to crowd members for more details on this setup.

Playing "use animations"

You will need to use emotes, since abilities are not supported on the background. See e.g. BP_ItemExecutor_Glowstick_SingleColor - when we "use" the item, we are calling RequestEmoteById.

Missing pieces

  • "Pose Overrides" for the animated crowd is a long way off

  • Adding visuals for items other than your equipped gadgets is a supported extension of the visuals system, but hasn't been done yet.

Last updated