Attachments

Having attachments to allow gameplay.

Experimental - Customers are encouraged to test and use this feature in their experiences, but it may still require some additional support

Overview

Projects can socket static mesh attachments to player characters, for example weapons, glow sticks, or other accessories.

This page describes the process for attaching Unreal StaticMesh assets. You can also use attachments defined in MML - for details see MML Attachment.

This system is designed for more gameplay-like attachments, but if you just want cosmetic attachments, they can be done via the M² Avatar System (see Attachments).

Enabling attachments in the crowd

To use an attachment with the crowd system, the mesh must be registered with the crowd Mesh Store. There are two options here - either specifying the meshes directly in the asset, or dynamically adding them at map start-up.

Each attachment is added along with a joint and an offset transform. If you want the same mesh attached in multiple places (e.g. a weapon that can be held in either hand) then it must be added twice as two separate attachments.

Adding to the mesh store asset

For this method you need to create your own mesh store asset, and reference it from your J_PawnSetAsset. You must add every attachment mesh that will ever be drawn in the crowd. You must also specify the bone (or socket) name that the mesh will be attached to.

Add to the mesh store dynamically

Currently all meshes must be added before the first crowd member actor is created. The simplest way to do this is in the BeginPlay event of an actor placed directly in your level, for example in a custom "attachment manager" singleton.

Dynamically adding to the mesh store method is preferable as you can for example automatically add meshes specified in other assets, and it removes the need to maintain the mesh store asset separately.

• Set up your actor to implement the ISkeletalCrowdMeshProviderInterface interface

• Call USkeletalCrowdMeshStoreSubsystem::RegisterCrowdMeshProvider before any crowd has been created (for example in the BeginPlay)

• Override AddMeshesToStore and call AddMesh on the MeshStoreSubsystem for every mesh that you want to use in the crowd.

There is an existing asset BP_AttachmentManagerExample you can use for reference, or even use directly (subclass it to add some logic, or edit the CrowdMeshes field on an instance to add your meshes).

Adding attachments to characters

Now your meshes are registered for use in the crowd, you can add them to the player characters in the game. For this you should use the AddAttachment and RemoveAttachment functions on the Morpheus Actor's M2M_CharacterAssetComponent. The attachment will then automatically be applied to the character, whether it's the crowd or full actor, and regardless of the character type (modular character, MML, or default mesh).

Note that attachments are NOT REPLICATED. Automatic replication of all possible attachment states would add significant overhead, and would be wasteful on most projects. Therefore it is up to projects to replicate their own state. This may be as simple as a single background integer specifying which item is equipped - in the OnRep, simply call RemoveAttachment with the previously equipped item and AddAttachment with the new one.

The Add and Remove functions have a Reload Character option. If you're making multiple calls to add and/or remove attachments to a character, it's more efficient to only reload the character on the final call. The character visuals won't be updated until it's reloaded.

The Attachment Static Mesh, Attachment Socket and Attachment Transform passed in is the same as the one passed to the mesh store - to prevent errors it's best to have a central source of attachments for using in both cases.

From v25.0.0 attachment are limited to 20 per character. Earlier versions had a limit of 4.

Example of adding and removing an attachment

After adding an attachment to a character, we receive a FM2_StaticMeshAttachmentHandle which we can cache to later retrieve this attachment or the attached Mesh. Be aware that passing in a null mesh, or a mesh which has already been attached, will return an invalid handle, so be careful not to overwrite any previously saved handle.

Example of using an FM2_StaticMeshAttachmentHandle to retrieve an attached mesh

Customising attachments

Image shows example of how one might update the colour of an attachment

If you have access to a valid attachment handle for the attachment you are hoping to customise, you can pass that and an FLinearColor to "Set Custom Color for Attachment" on your M2M_CharacterAssetComponent. As with adding/removing attachments, these changes will not be visible until the character has been reloaded and the changes are not replicated automatically.

Once a Blueprint has been created to set your custom value, we need to ensure that the attachment is able to use this value. To do that we must:

• Enable Per Mesh Custom data in our Avatar Scheme set

• Ensure the static mesh has a material that can process the custom data

Enabling per mesh custom data in the avatar scheme set

Example of a material set up to handle custom data for attachments

To use the custom data your material will need the MF_SkeletalCrowdPerMeshCustomDataRGB node, which we then pass to a VertexInterpolator node. The value attached to "Default Value (V3)" should be named "Custom Value" to coincide with how the data is processed behind the scenes.

Video shows how customising an attachment may appear in an experience

Once set up correctly, you should see changes to attachments reflected in LOD 0 and Crowd Actors for all clients told to update this data.

The bubble example here is from within BPM_Combat_PlayerCharacter which is part of the https://docs.msquared.io/tutorials-and-features/action-gameplay content. It may serve as a useful reference point, but due to the experimental nature of that content it could be subject to change at any time.