# Attachments

{% hint style="success" %}
verified: 2025-12-08 version: v39
{% endhint %}

Static mesh attachments can be socketed 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 Attachments](/creation/unreal-development/features-and-tutorials/avatars/avatar-attachments/mml-attachments.md).

## Adding attachments to characters

Use the `AddAttachment` and `RemoveAttachment` functions on the Morpheus Actor's `M2M_CharacterAssetComponent` to add and remove attachments. The attachment will then automatically be applied to the character, whether it's in the crowd or a full actor, and regardless of the avatar type (MML or a static mesh).

Note that attachments are **NOT REPLICATED**. Automatic replication of all possible attachment states would add significant overhead, and would be unnecessary in 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 crowd system is limited to 16 total meshes per character including attachments, however up to 32 attachments will work for full actor (non-crowd) players.

<figure><img src="/files/RLoSknEbX6trFVSCObm9" alt=""><figcaption></figcaption></figure>

Adding an attachment to a character returns a `FM2_StaticMeshAttachmentHandle` which can be cached to later retrieve this attachment, or the attached Mesh. Note 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.

<figure><img src="/files/v2gSbPgqtQp8zl8Mi8EL" alt=""><figcaption><p>Example of using an <code>FM2_StaticMeshAttachmentHandle</code> to retrieve an attached mesh</p></figcaption></figure>

## Customising colors

It is possible to dynamically set material colors for attachments, but it requires some additional setup.

#### Crowd pipeline setup

Materials are customised by passing in additional color data with each mesh in the crowd. This additional data has a small memory and performance cost to the crowd rendering, so is disabled by default. To enabled it, on the `MorpheusActorRenderTargetComponent` on your player Morpheus Actor blueprint, look for the `Crowd Data` property (under Advanced -> Crowd Details).

<figure><img src="/files/WVV15DVdMdj45QarRc9t" alt=""><figcaption></figcaption></figure>

Either edit the data asset, or create a new data asset of type `SkeletalAnimatedCrowdData` and set it as the `Crowd Data`. In the data asset, set `NumCustomDataFloatsPerMesh` to 4 to enable the color to be passed correctly:

<figure><img src="/files/08m9TPqNilMj1Kn3rrvJ" alt=""><figcaption></figcaption></figure>

#### Setting the attachment color

A custom color can be passed into `AddAttachment` as part of the `M2_StaticMeshAttachment` struct, or the color can be updated on an existing attachment with `M2M_CharacterAssetComponent::SetCustomColorForAttachment`. As with adding/removing attachments, these changes will not be visible until the character has been reloaded and **the changes are not replicated automatically**.

<figure><img src="/files/ImvCzFeTTddrKHK78uGA" alt=""><figcaption><p>Example of how one might update the colour of an attachment</p></figcaption></figure>

#### Material setup

To access the custom color in the mesh material you must use a specific custom node setup.

The material must have the `MF_SkeletalCrowdPerMeshCustomDataRGB` node followed by a `VertexInterpolator` node. This node handles reading the crowd data if it's in the crowd, or the standard custom parameter if it's an actor.  The material must also have a Vector Param named `CustomValue`, which will receive the data.

A typical setup should look like this:

<figure><img src="/files/tIpqpFGPBvi9UCUa3XW4" alt=""><figcaption></figcaption></figure>

The Index input allows you to swizzle the custom data input channels. Typically this should be left as `0, 1, 2` which will pass the color through unchanged.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.msquared.io/creation/unreal-development/features-and-tutorials/avatars/avatar-attachments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.