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 M² Avatar System works by taking tagged assets from a datasource i.e. Hats, Clothes and Bodies and using them to populate an avatar creator. Once the player has selected the items they want, we save their configuration to the players Inventory as an MML so it works in any modern web browser 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 if you wish to use this feature:

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 pulled meshes will be available for use in experience. 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 them

  • attachmentPoint (required) : Groups items into categories, and is used to look up the category name

  • attributes (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 an addIf 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 with removeIf to fix clipping issues by swapping out a torso for an arms-only version when equipping certain tops.

  • removeIf : Items with a removeIf 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

For Gameplay Attachments, see Avatar Gameplay 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 cannot use attachmentPoint and socket properties together on the same asset

You can also specify an additional transform that will be applied to the static mesh before it is socketed, by using position, rotationand scaleproperties. For example:

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.

Bulk uploading assets to the datasource

The easiest way to add avatar assets to your public datasource is with a bulk upload, using a .tsv file (tab-separated values). The .tsv file should be in this format, including the header:

name	thumbnailUrl	glbUrl	properties
Body1	https://my-url.com/Body1.png	https://my-url.com/Body1.glb	{ "avatarAsset": {"attachmentPoint":"body", "bodyType": "BodyA"} }
Body2	https://my-url.com/Body2.png	https://my-url.com/Body2.glb	{ "avatarAsset": {"attachmentPoint":"body", "bodyType": "BodyA"} }

The name and thumbnail will be used for the asset in the collection (the thumbnail URL must be publicly accessible). The glbUrl must be a publicly accessible URL to the GLB file for each item. The properties are as described above. Most spreadsheet application will allow exporting TSV files in the correct format.

Navigate to one of your project's public datasources and use the Add button. Select Bulk Avatar Assets and select the .tsv file to upload. This is limited to 1000 assets per upload - if you have more you may need to split it over multiple .tsv files.

Enabling the editor in your project

  1. Add the BP_AvatarEditorActor (or child class) into your map.

  2. 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 Feature Test Gym 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 as 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.

Changing avatars from the inventory quickbar

If you're using the inventory system it's possible to use it to change your avatar, without entering an editor. Two example quickbars are provided - one for loading a new avatar, and one for equipping items onto your current avatar. You can enable them with live config:

Inventory.Quickbar.UsingEquipmentTabs must be enabled first.

Inventory.Quickbar.ShowAvatarsTab will enable a tab containing all of your full avatars. Using one from the quickbar will load the avatar and set it as your default avatar.

Inventory.Quickbar.ShowAvatarItemsTab will enable a tab containing all avatar assets compatible with your profile avatar. Using one from the quickbar will equip it on your current avatar, and save the updated avatar as your default.

Last updated