Unity Plug 'n' Play SDK Docs

For animations, we leverage Unity’s in-built Animator system. This allows us to create animation state machines for our NPCs using exported animation clips. It also allows us to control animation through script. The main Female NPC animation controller can be found under:

Assets/Samples/Charisma.ai/Plug-n-Play/0.1.0/Example/Animation/Controllers/CharismaNPCFemale.controller

As the name implies, this controller is targeted to the female NPC skeleton. Male animations are done using the AnimatorOverrideController named CharismaNPCMale, in the same folder.

The female controller can be opened up in the Animator view by double-clicking it. Inside, the animation is structured into several layers:

• Base Layer - primary layer, meant for movement, turning and idle animations. Has IK enabled for head tracking.
• Full Body - layer specifically for full body animations, primarily used for talking and also custom animations. Overrides the Base Layer if an animation clip is playing.
• Head - layer specifically for head-only animations. Used for talking animations.
• Upperbody - layer specifically for upper-body-only animations. Used for talking animations.

This section will go over the process of adding new animations to the existing layers. If you wish to extend the system, we recommend looking into the code base andmaking more in-depth changes according to your project's requirements.

Adding a new animation clip

• With the female animation controller open in the Animator view, Select the fullbody layer (or any non-base layer of your choice). Right click and add a new empty state.

  

• Select your newly added state and switch to the Inspector tab.

• Assign a unique name for your animation node, and set your animation clip. In our example, we will be naming this animation node “Wave” and assigning an existing Wave_f animation.

  

• Once you’ve assigned your animation clip and set your name, make sure to connect your animation Node back to the main Idle node:

  • Right click your node > Make transition > Drag the connection into the Idle node
  

• NOTE: You may need to add several transitions here with different conditions depending on the layer you’re working in and the context of the animation. For talking animations in Fullbody, for example, we exit when the animation finishes, when the NPC stops talking, or if the NPC starts walking. Please refer to other already existing transitions for examples.

• The animation controller features several parameters that the user can verify their transitions against, namely:

  • Rotate - integer value, represents how much the NPC needs to rotate in degrees
  • Walking - boolean value, only set to true when NPC needs to move to a destination
  • Talking - boolean value, only true when the NPC is actively outputting audio

• With the clip added, make sure to update the male animator override file mentioned previously, by adding a male variant of the animation (if available).

Updating the Animation Configuration

Once you’ve added your animation Node, you will have to update the Humanoid Animation Configuration mentioned in the Unity tutorial video. This configuration file can be found in:

Assets/Samples/Charisma.ai/Plug-n-Play/0.1.0/Example/Animation/Data/HumanoidNPCAnimationConfig.asset

When you open this asset in the Inspector view, you will see a detailed list of all the animation nodes present in the CharismaNPCFemale. As new nodes have been added, this file will need to be updated by pressing the “Get Animation Data From Controller” option. This will retain old data that has been set for existing layers and nodes, but add any new nodes and remove any deleted nodes respectively.

With the Configuration file updated, you can now customize your newly added animation depending on the context of when you want the animation to be played by setting Animation Tags and the Associated Charisma Emotion.

Depending on your animation needs, you may need to extend the AnimationTags and also the HumanoidNPCAnimationController script directly, as this parses any animation request based on tags.

For adding new metadata functions, please refer to the Unity Plug-n-Play Sample folder, under:

Assets/Samples/Charisma.ai Plug-n-Play/0.1.0/Example/Scripts/Playthrough/Metadata

Inside, you can find several scripts for supporting various Metadata functions. These all inherit from the base class “MetadataFunction”, which inherits from the Unity ScriptableObject.

To add your own Metadata function, create a new C# Script in your preferred location and set its parent class to “MetadataFunction”. You will need to implement the base class functions for this script to compile:

• MetadataId - this value is the Metadata Key present in the Charisma Story. This acts as a filter; only metadata with this key will be parsed by the Execute function.

• Execute - this handles the Metadata Value, received whenever a message with a metadata entry is received. The body of this function depends on what you want the metadata to affect in the context of the Playthrough, be it the player, entities or Unity-side data.

  

Once you’ve created your new metadata class, you will have to create an instance of it as a ScriptableObject. This can be done in two ways:

Automatic

• Make sure your newly added Metadata function contains the word Function in its naming. Examples: YourMetadataFunction.cs This applies to both the class name and the file name of the script.

• Once the name has been changed, open your Charisma tab and hit the “Create Playthrough Metadata” operation

  

• This will automatically create a new ScriptableObject for your new MetadataFunction in the Sample folder under: Assets/Samples/Charisma.ai Plug-n-Play/0.1.0/Example/Data/Playthrough/Metadata

Manual

• Right click in your project view and create a new ScriptableObject under Create > Charisma > Scriptable Object.

  

• Once the ScriptableObject is created, assign it your new MetadataFunction

  

• With the new MetadataScriptable object created, the last step is to add it to your PlaythroughInstance list of Metadata and it will automatically be interpreted in your Charisma story.

  

Q: I cannot find any of the provided anims in the package!
A: When selecting assets using the Unity picker tool, make sure to toggle the Package Visibility button.

Q: My NPCs have green skin!
A: -Select either of your NPCs in the Hierarchy view and navigate to their meshes.

• Once here, open one of their skin materials under the Skinned Mesh Renderer component.

  

• Once opened, navigate to the bottom of the Material, to the Skin Diffusion Profile. Make sure this is assigned to the SkinDiffusionProfile provided in the example folder.

  

NOTE: You will need to do this for all “skin” materials present on the characters. Re-importing the Plug-N-Play package and its sample may also fix this.

Charisma’s Plug ‘n’ Play Unity SDK comes with a number of basic metadata instructions that are ready to work out of the box. As soon as your Charisma story and characters are connected to our Unity Plug ‘n’ Play sample project and 3D avatars, the metadata instructions in the table below will trigger the specified events in your Unity project. Simply add the required piece of metadata to the Metadata Manager on a Charisma Character node in your story graph – the Key in the left field and the Value, where required, in the right field.