Avatar System
An in-game avatar editor to create avatars that will work across experiences!
Last updated
An in-game avatar editor to create avatars that will work across experiences!
Last updated
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
If you're on a version before v27, you need to explicitly enable this via live config under Game > Character:
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.
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
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.
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.
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
attachmentPointandsocketproperties 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.
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:
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.
Add the BP_AvatarEditorActor (or child class) into your map.
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.
You may wish to subclass BP_AvatarEditorActor to add further configuration:
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.
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.
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.
The Avatar created will be in your collection on Web once saved.
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.
