Avatar Creators

Using the prebuilt Avatar Creator

MSquared provides a ready-to-go Avatar Creator; you can check out a preview here. Adding it to your web app is as simple as taking the URL provided on the Avatar Creator page in the MSquared dashboard and embedding it using an iframe in your web app. Then use a window event listener to listen for export events from the user. For example:

const handleAvatarExport = async (event: {
        origin: string;
        data: {
            type: string;
            avatarMml: string;
        };
    }) => {
        // Validate the event.
        if (event.data.type !== "MSQUARED_AVATAR_EXPORT") {
            return;
        }
        const avatarMml = event.data.avatarMml;
        if (!avatarMml) {
           return;
        }
        // Send the avatarMml to be processed.     
        // ...
    };
window.addEventListener("message", handleAvatarExport);

Once you have received the avatarMml string, see the Optimization Settings section for more information on processing. Alternatively, check out the Getting Started page for a complete guide on how to set up the end-to-end flow.

Customizing the Export Button

The MSquared Avatar creator supports two modes for triggering exports:

• Embedded - The export button is created for you in the Avatar Creator

• External - You trigger the export event yourself through your own button or some other means

Using Embedded mode, the button is created for you and nothing else is needed to complete the integration besides embedding the iframe.

Using External mode to trigger the MSQUARED_AVATAR_EXPORT event, you must post a message to the Avatar Creator iframe like so:

const handleTriggerAvatarExport = () => {
  // iframeRef is a reference to the iframe containing the MSquared Avatar Creator
  if (iframeRef.current) {
    iframeRef.current.contentWindow?.postMessage(
    {
      type: "MSQUARED_TRIGGER_AVATAR_EXPORT",
    },
    "*");
  }
};

Triggering the function will post a message leading to the export event being posted back out. Handling the export event is no different to when using Embedded mode.

Importing Avatars

It is possible to re-import an Avatar into the creator in order to continue editing.

The iframed Avatar Creator signals to its parent that it's ready to import by posting a message with type MSQUARED_AVATAR_IMPORT_READY.

To load an existing AvatarMML string, post a message to the iframed Avatar Creator with type MSQUARED_TRIGGER_AVATAR_IMPORT and field avatarMml containing the string to import.

const EXAMPLE_AVATAR_MML = `<m-character class="bodyB skin04" src="https://storage.googleapis.com/glb-content-bucket/parts/Body_B_BodyTorsoHeadless_04.glb">
	<m-model class="legs" src="https://storage.googleapis.com/glb-content-bucket/parts/Body_B_BodyLegs_04.glb"></m-model>
	<m-model class="head" src="https://storage.googleapis.com/glb-content-bucket/parts/Head_B_Black_African_A_04.glb"></m-model>
	<m-model class="hair" src="https://storage.googleapis.com/glb-content-bucket/parts/Hair_B_AndronellaHair_Ginger_01.glb"></m-model>
	<m-model class="top" src="https://storage.googleapis.com/glb-content-bucket/parts/Top_B_RockTopLong_White_01.glb"></m-model>
	<m-model class="bottom" src="https://storage.googleapis.com/glb-content-bucket/parts/Bottom_B_PleatedSkirt_PlaidTartanBlack_01.glb"></m-model>
	<m-model class="bottomSecondary" src="https://storage.googleapis.com/glb-content-bucket/parts/Bottom_B_StockingsUnderKnee_Black_01.glb"></m-model>
	<m-model class="shoes" src="https://storage.googleapis.com/glb-content-bucket/parts/Shoes_B_HighTopChunky_Blue_01.glb"></m-model>
</m-character>`

const handleTriggerAvatarImport = () => {
  // iframeRef is a reference to the iframe containing the MSquared Avatar Creator
  if (iframeRef.current) {
    iframeRef.current.contentWindow?.postMessage(
    {
      type: "MSQUARED_TRIGGER_AVATAR_IMPORT",
      avatarMml: EXAMPLE_AVATAR_MML
    },
    "*");
  }
};

It is only possible to re-import the unoptimized MML string, not the baked model. Therefore, in your user system, you may want to store the MML from the Avatar Creator as well as the optimized model if you would like to reload the Avatar into the creator.

Preview Mode

In some cases you may want to show an avatar without allowing the user to customize it, for example if you wanted to show your avatar to a friend. To do this, from the Project Dashboard, select Avatars, then the avatar creator you're targeting. In the General tab, enable Preview Mode. This will allow an avatar to be shown, and emotes to be triggered, without any of the customization controls being usable. The process for importing an avatar is the same as with any other Avatar Creator as described above.

The Avatar Creator used for previewing is a separate iframe that must be embedded to the one used for customization.

Catalog modes

The MSquared Avatar Creator supports two catalog modes:

• Default Mode – Uses the built-in catalog (recommended for getting started).

• Webhook Mode – Uses a catalog you host yourself.

To set up a custom catalog, follow this guide. Once ready, configure the Avatar Creator to use it by:

1. Setting Catalog Mode to Webhook.

2. Providing the URL of your catalog’s JSON endpoint.

Optionally, you can also pass a token when embedding the Avatar Creator iframe. This token is forwarded to the catalog webhook endpoint, allowing you to return catalogs based on a user’s context.

Example using webhook mode with a token

Catalog Mode is set to Webhook with URL:

https://example.com/api/catalog

Iframe embed:

<iframe src="https://project-example_creator-config-example.creator.msquaredavatars.com?token=my_token" />

Resulting request:

GET https://example.com/api/catalog?token=my_token

Your catalog API can then decide how to use the token.

Generating Avatar Portraits

It is possible to generate a portrait of the current avatar in the creator - this can be useful for example for setting a user's default profile picture. To generate a portrait, post a message to the iframed Avatar Creator with type MSQUARED_TRIGGER_GENERATE_AVATAR_IMAGE and an optional field resolution containing the desired portrait resolution as a number. The portrait is a square and by default 256x256.

Portrait generation is asynchronous and a listener must be set up to handle the response. The incoming message will have type MSQUARED_GENERATED_AVATAR_IMAGE and the image will be stored in the dataUrl field.

const handleAvatarImageGenerated = async (event: {
        origin: string;
        data: {
            type: string;
            dataUrl: string;
        };
    }) => {
        // Validate the event.
        if (event.data.type !== "MSQUARED_GENERATED_AVATAR_IMAGE") {
            return;
        }
        const dataUrl = event.data.dataUrl;
        if (!dataUrl) {
           return;
        }
        // Use the dataUrl.     
        // ...
    };
window.addEventListener("message", handleAvatarExport);

Custom Logo

By default, every avatar creator is displaying the MSquared logo. You can show your own logo by going to the Theming tab for the desired avatar creator, and uploading an image.

Custom Background Image

You can use a custom background image for your avatar creator. From the Project Dashboard, select Avatars, then the avatar creator you're targeting. In the Environment tab, you can input the URLs you want the background image to be served from. Some advice:

• Use public URLs with the right CORS policies enabled such that they can be accessed from your domain.

• Use multiple URLs, each serving a different image resolution, and put the lower quality first. When specifying multiple URLs, the avatar creator will progressively load them.

• Use HDR domes for the best results.

Bring Your Own Editor

To get started building your own custom editor fork our Avatar Creator repository and start making changes. Further information about building your entirely own custom editor will be available soon.