Plug 'n' Play
Unreal Engine

Unreal Engine Plug 'n' Play SDK Docs

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

First, you’ll need to download both the Charisma Unreal SDK and the Charisma Unreal Engine 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 Unreal 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 Unreal Plug ‘n’ Play SDK
Connecting your Unreal 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 Unreal’s Animation Blueprint and suite of animation features. This allows us to create comprehensive animation state machines, with multiple layers and levels of control. To get started, open up the main Animation blueprint found in:

Plugins/CharismaPlugNPlay Content/Animations/ABP_NPCFemale

As in our Unity implementation, the NPCFemale acts as the main animation controller with the Male variant simply replacing animations with male counterparts. The Animation Blueprint event graph is broken down into 3 key state machines which are then composited together depending on parameters. These are:

  • MovementState/Locomotion - Fullbody state machine, mainly focused on Idle, Turning and Walking animations – managing the current movement state of the NPC.
  • Head - Head-only state machine, used for talking animations and also head tracking.
  • Upperbody - Upperbody-only state machine, used for talking animations.
Various state machines, pre-compositing.

In this section, we’ll go over the process of adding new animations to the existing state machines. For running custom animations via the “play-animation” metadata function, please refer to the Unreal tutorial video.

Adding an animation to existing state

  • Once you have your animation and know which layer it suits best, start by opening that layer’s state machine. In our example case, we will be adding a fullbody “Wave” animation, which we’ll place in the MovementState state machine. This should only be used as an example, and implementation may vary depending on the requirements of the animation.

    MovementState machine. Currently composed of Still and Walking sub-states. Our Standing sub-state can be found inside the Still state.
  • Inside the Standing state machine, we’ll find three key states: Idle, Mannerism and Talking. As our Wave animation will only play under certain circumstances, make sure to add a new State named Wave by Right Clicking > Add New State.

    Wave state added to the Standing state machine.
  • Inside the Wave state, we can hook up the existing Wave_f animation clip. The implementation inside your newly added state may require more involved sequences. Please review some of the other existing states for examples of randomly assigned animations and more complex blending.

    Wave_f sequence added and now outputting to the Wave state.
  • With the Wave state set up, we can connect it to Idle via a conduit. Drag from the Wave state box into the Idle state box and vice versa to create a two-way connection.

    Creating a transition from Idle to Wave.
  • From here, the newly created transitions can have conditions added for when the state should change. In our case, we will play the Wave animation when a Joy emotion is detected with an intensity of over 0.5. The same should be done for exiting the state, but in reverse, when the Joy emotion subsides. In this particular case, the "Joy" field itself is a parameter set up in the AnimationBlueprint.

    Example of Joy condition being applied.

From here, the new Wave animation is successfully added. These principles can be re-used for other animations depending on their requirements. We also recommend adding new parameters to the blueprint to facilitate any custom behavior that isn’t already supported.

Custom metadata

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

Plugins/CharismaPlugNPlay Content/Blueprint/Metadata

  • Inside, you can find several Blueprints for supporting various Metadata functions. These all inherit from the base Blueprint BP_MetadataFunction
Collection of in-built metadata functions.
  • To add your own Metadata function, create a new Blueprint in your preferred location (Right Click in Content Browser > Blueprint > Blueprint Class) and set your Parent class to BP_MetadataFunction.
Metadata Function parent class being selected.
  • To start interpreting your own metadata entries in the Charisma story, you will need to update your new MetadataFunction:
    • Open your new Blueprint.

    • Under Class Defaults, you will need to set the Metadata ID. This is the Key field inside the Metadata entry.

      Metadata ID field within class defaults. Metadata Manager showing the structure of a Metadata Entry.
    • Once the Metadata ID is set, you will need to Override the base class named Execute. To do this, hover over the Functions section in the Blueprint and click the Override dropdown. Select the Execute Function.

      Display of where to find the override functions.
    • Once the Execute function is overridden, you can set up this function to your own specifications. You can reference the PlaythroughEntities structure for any objects you want to affect within the world.

Lastly, with the MetadataFunction blueprint created and fully set up, you will need to add it to the existing BP_PlugNPlayGameMode in order to be parsed when the Playthrough sends a message.

  • Open Plugins/CharismaPlugNPlay Content/Blueprint/GameMode/BP_PlugNPlayGameMode
  • Open Class Defaults
  • In the Details Panel, open the Metadata Classes and add your new Metadata blueprint. Adding a new metadata class to the list.
List of metadata included

Charisma’s Plug ‘n’ Play Unreal 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 Unreal Plug ‘n’ Play sample project and 3D avatars, the metadata instructions in the table below will trigger the specified events in your Unreal 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