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
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:
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.
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.
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.
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.
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.
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.
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.
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.
For adding new metadata functions, please refer to the Unreal Plug-n-Play Content folder under:
- Inside, you can find several Blueprints for supporting various Metadata functions. These all inherit from the base Blueprint BP_MetadataFunction
- 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.
- 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.
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.
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.
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.
|Key||Value||Function of Metadata|
|set-player-speak||[no value required]||Brings up reply UI to allow player to speak or type a message|
|set-look-at||Makes specified character look at specified target for duration of node|
|move-to||Makes specified character walk to specified target|
|play-animation||Plays specified animation|
|block-interact||Prevents interactions with named object|
|allow-interact||Enables interactions with named object|
|reset-interact||Re-enables interactions with named objet once interacted with|