Avatar Creation

Avatar Creation

This page details the process of creating a full-body avatar using Ready Player Me integration in the application. It covers the technical aspects of the implementation, including how to customize the avatar creation process and handle the resulting avatar data.

Table of Contents

• Overview
• Implementation Details
• Ready Player Me Subsite Configuration
• Handling Avatar Creation Events
• Customizing Avatar URL
• Known Limitations
• Troubleshooting

Overview

The avatar creation process utilizes Ready Player Me's web-based avatar creator, embedded within our application using an iframe. This approach allows users to create personalized 3D avatars without leaving our app's environment.

Implementation Details

The avatar creation page is implemented in AvatarPage.tsx. Here's a breakdown of the key components:

1. State Management:

   • showAvatarCreator: Boolean to toggle the avatar creator iframe visibility.
   • avatarCreatorUrl: URL of the Ready Player Me subsite.

2. useEffect Hook:

   • Listens for messages from the Ready Player Me iframe.
   • Handles avatar creation events and updates the application state.

3. Render Functions:

   • renderAppBar(): Renders the top navigation bar.
   • renderAvatarCreator(): Renders the iframe containing the Ready Player Me avatar creator.
   • renderButtons(): Renders buttons for initiating avatar creation or choosing other options.

Key Code Snippet

useEffect(() => {
  const handleMessage = (event: MessageEvent) => {
    if (event.origin !== 'https://*****.readyplayer.me') {
      return;
    }

    if (typeof event.data === 'string' && event.data.startsWith('https://models.readyplayer.me/')) {
      const modifiedUrl = `${event.data}?morphTargets=mouthOpen,Oculus Visemes`;
      setAvatarUrl(modifiedUrl);
      setShowAvatarCreator(false);
    } else if (event.data.eventName === 'v1.frame.ready') {
      if (iframeRef.current?.contentWindow) {
        iframeRef.current.contentWindow.postMessage(
          JSON.stringify({
            target: 'readyplayerme',
            type: 'subscribe',
            eventName: 'v1.**'
          }),
          '*'
        );
      }
    }
  };

  window.addEventListener('message', handleMessage);
  return () => window.removeEventListener('message', handleMessage);
}, [setAvatarUrl]);

This code handles messages from the Ready Player Me iframe, including the final avatar URL and initial frame ready event.

Ready Player Me Subsite Configuration

The Ready Player Me subsite URL is set in the renderButtons function:

setAvatarCreatorUrl('https://*****.readyplayer.me');

To use a different subsite:

1. Replace the URL with your custom Ready Player Me subsite URL.
2. Update the origin check in the handleMessage function to match your new subsite's origin.

Using a custom subsite allows for greater control over the avatar creation process, including available customization options and items.

Handling Avatar Creation Events

The application listens for the v1.avatar.exported event from the Ready Player Me iframe. When received, it processes the avatar URL and updates the application state.

To modify this behavior:

1. Update the condition in the handleMessage function that checks for the avatar URL.
2. Adjust the setAvatarUrl call to handle the avatar data as needed for your application.

Customizing Avatar URL

The avatar URL is modified to include specific morph targets:

const modifiedUrl = `${event.data}?morphTargets=mouthOpen,Oculus Visemes`;

To customize the avatar further:

1. Modify the morphTargets parameter to include different morph targets.
2. Add additional parameters as needed. Refer to the Ready Player Me API documentation for available options.

Example of adding more parameters:

const modifiedUrl = `${event.data}?morphTargets=mouthOpen,Oculus Visemes&textureAtlas=1024&textureSizeLimit=1024`;

Known Limitations

1. Demo Subsite Limitations: Using the demo subsite (https://demo.readyplayer.me) results in a model with only the Wolf3D_Avatar mesh, which has all morph targets coupled on it. This reduces animation flexibility.
2. Mesh Availability: The full set of meshes (e.g., Wolf3D_Head, Wolf3D_Teeth, Wolf3D_Beard) is only available when using a development or production subsite.

Troubleshooting

1. Avatar URL not received:

   • Check that the origin in the handleMessage function matches your Ready Player Me subsite's origin.
   • Verify that the Ready Player Me iframe is loading correctly.

2. Missing meshes or morph targets:

   • Ensure you're not using the demo subsite.
   • Check the avatar URL parameters to confirm the correct morph targets are being requested.

3. Customization options not appearing:

   • If using a custom subsite, verify that it's correctly configured with your desired options.
   • Check the Ready Player Me dashboard for your subsite configuration.

For more detailed information on the Ready Player Me API and available options, refer to the official documentation.