Plug 'n' Play

Unity Plug 'n' Play SDK Docs

This page contains everything you need to get your Charisma-powered project up and running in Unity!

First, you'll need to download both the Charisma Unity SDK and the Charisma Unity Plug 'n' Play SDK from GitHub via the links below:

Then check out the tutorial videos on this page to find out how to easily link your Charisma story to our sample Unity project and character models. You can also watch the full version of the tutorial video on YouTube here (opens in a new tab).

Installing the Charisma Unity Plug ‘n’ Play SDK
Connecting your Unity project to your Charisma story
Linking your Charisma character to a 3D character model
Character animations and default behaviour
Character facial expressions
Setting ‘move-to’ behaviour
Setting ‘look-at’ behaviour
Object interact controls
The player
UI controls
Custom animations

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:


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.

    Adding an empty animation state to the Animation controller
  • 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.

    Updated the animation state to “Wave”
  • 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
    Wave example being connected to 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:


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.

Animation Configuration object in Inspector view. Button to get Animation Data from the reference Animation Controller is selected.

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.

The newly added “Wave” animation added to the Fullbody layer’s node data.

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.

Custom metadata

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

Assets/Samples/ 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.

Collection of in built metadata functions.

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.

    Metadata Manager showing the structure of a Metadata Entry, composed of Key and Value fields.

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:


  • 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

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


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

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

    Assigning an example WaveFunction to a new ScriptableObject.
  • 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.

    The example WaveFunction added to the PlaythroughInstance.

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.

Where to find Package Visibility toggle.

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

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

    Material highlight in 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.

    Skin Diffusion profile location.

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.

List of metadata included

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.

KeyValueFunction of Metadata
set-player-speak[no value required]Brings up reply UI to allow player to speak or type a message
set-look-at<character name>,<look at target>Makes specified character look at specified target for duration of node
move-to<character name>, <move to target>Makes specified character walk to specified target
play-animation<animation name>Plays specified animation
block-interact<interactable name>Prevents interactions with named object
allow-interact<interactable name>Enables interactions with named object
reset-interact<interactable name>Re-enables interactions with named objet once interacted with