M² Avatar System
An in-game avatar editor to create avatars that will work across experiences!
Experimental - Customers are encouraged to test this feature in their experiences, but it may still require some additional support and there will be issues present.
The MSquared Avatar System works by taking tagged assets from a datasource i.e. Hats, Clothes and Bodies and it uses them to populate an avatar creator. Once the player has selected the items they want, we save out their configuration to the players Inventory as an MML so it works in any supporting Web and Unreal experience.
NOTE: Please reach out if you want items adding to your projects datasource
Enabling avatars from profiles
The avatar editor relies on players automatically loading their MML avatars from their profiles. This is currently disabled by default and must be enabled in the game
live config:
Character.UseCharacterFromProfile: true
If this is disabled, players will still be able to access the avatar editor and edit and save their avatar, but changes won't be applied to the in-game avatar after saving.
Configuring the avatar asset data source
The editor pulls the list of available glTF meshes from public organization datasources and the user's own collection. By default all available meshes will be available. However, if you want to restrict it to meshes from specific public datasources, you can configure this in the game
live config with a comma-separated list of datasource IDs, for example:
AvatarEditor.PermittedDatasourceIds: TgfE4YU7hf4GoyKGy6gD
NOTE: Please reach out for support setting up your datasource and getting your ID
Avatar Item properties
Each avatar asset in a datasource must have an avatarAsset
property object that defines how it functions in the editor. Use the following properties on the avatarAsset
object:
bodyType
(required) : Groups items into a specific body type. The Body Type selector cycles between themattachmentPoint
(required) : Groups items into categories, and is used to look up the category nameattributes
(optional) : Tags that can be used in rules (see below)
Objects must also contain model and thumbnail links to be considered valid.
Rules
Often you'll want to add, remove or swap out certain meshes depending on which other meshes are equipped. This is useful to avoid clipping issues, if you want to use a different hair mesh when wearing a hat, or remove the base models legs when wearing trousers.
You can add rules to your avatar items by using the attributes
, addIf
and removeIf
properties.
attributes
: A list of attribute names that rules reference. Only the property name is used - the property value is currently ignored.addIf
: Avatar items with anaddIf
property don't appear in the editor as selectable assets. Instead they are automatically added to the avatar if all the attributes are present on the equipped items. Use this for example to add a separate legs mesh when selecting a torso, or in conjunction withremoveIf
to fix clipping issues by swapping out a torso for an arms-only version when equipping certain tops.removeIf
: Items with aremoveIf
property will be removed if all the attributes are present on the equipped items. Use this for example to fix clipping issues by removing the legs mesh when leggings are equipped.
Attachments
As well as skeletal meshes, you can also optionally support socketed static meshes in the editor. First this must be enabled in the game
live config:
AvatarEditor.AllowAttachments: true
Static mesh attachments are added in a similar way to skeletal meshes, but the have a socket
property instead of attachmentPoint
. The socket
must be set to the name of a bone or socket in the UE5 skeleton, and is there the mesh will be attached. Each unique socket will be given its own selector in the editor.
You can also specify an additional transform that will be applied to the static mesh before it is socketed, by using position
, rotation
and scale
properties. For example:
Also notice that the bodyType
property is not included. Attachments aren't affected by the selected body type, and all attachment meshes are available for all body types. Rules are also not supported currently.
Enabling the editor in your project
You need to add the BP_AvatarEditorActor
(or child class) into your map.
Secondly you need to either add a WBP_AvatarEditor_HUDButton
to your HUD widget, or add your own system that calls BP_AvatarEditorActor::OpenEditor
on the editor actor.
See the FeatureTestGym
map for an example setup.
Customizing the editor
You may wish to subclass BP_AvatarEditorActor
to add further configuration:
Creating a custom UI
The editor comes with a default UI widget WBP_AvatarEditor_MainContainer
. You can make your own UI, or duplicate this one and tweak it if required. To use your custom class, set it as the WidgetClass
variable on the editor actor. You class must implement the BPI_AvatarEditorUI
interface.
Category customization
Each different attachmentPoint
property on a datasource objects defines a different item category in the editor. You can configure each category in the Category Config
array on the editor actor:
The order in the array defines the order in which the categories appear in the editor. You can set the display name for each category in the editor, as well as make a category optional which allows no asset to be set for that category.
There is also Attachment Config
which does the same for attachment sockets. Attachments sockets are always optional.
Mannequin lighting setup
The avatar model in the editor is rendered using an actor with a scene capture component, by default BP_AvatarEditor_RenderTargetActor_Default
. This contains the capture camera and the lighting setup. To customize this, create your own actor deriving from BP_AvatarEditor_RenderTargetActor_Base
and set it as the Render Target Actor Class
on the editor actor.
By default the mannequin will also be affected by any existing scene lighting. Use Disable Scene Lights in Editor
to disable this. If any further customization is required, use the OnAvatarSelectorEnabled
and OnAvatarSelectorDisabled
events which fire as the editor is opened and closed.
Avatar in your Collection
The Avatar created will be in your collection on Web once saved.
Last updated