This Unity plugin is verified to work with projects using Unity versions 2021.3 and 2022.*. If you find the plugin also works in another version, feel free to submit a pull request to update this!
If you have any questions or need a hand, please reach out to us at [email protected]!
Important: Before setting up the Charisma SDK for Unity, you’ll need to have created a Pro story (not a Starter story!), which requires a Charisma licence. Please visit the licencing docs on our website for more info!
If you haven’t already, go ahead and create an Unity project. Make sure you are using a version of the engine that is supported by this plugin.
Open Unity's Package Manager by heading to Window -> Package Manager. Click the plus icon, and select "Add package from Git URL". Enter https://github.com/charisma-ai/charisma-sdk-unity.git and press Add.
Unity will download the Charisma package into your project as a package. This includes an example scene and script which can be found by expanding the "Samples" drop-down when the package is highlighted in the Package Manager, and importing the "Example".
Once the SDK is imported, you can also optionally import the Plug-N-Play package before continuing with this guide.
This package contains more in-depth examples of how Charisma can be used to power your stories!
In order to connect to a Charisma story, you will need find the 'Playthrough' configuration object. This object can be found in the example scenes by default.
For the SDK example scene - this object will be called 'ExampleScript'
For the Plug-N-Play example scene - this object will be called 'PlaythroughInstance'
You will need to provide various tokens in order to connect to you Charisma story:
- StoryID
- StoryVersion
- ApiKey
- StartGraphReferenceID
The StoryId is the unique ID of the story that you want to play. To find this, navigate to your story on the Charisma website, and copy the ID number after /stories in the URL.
This is the version of the story you want to play.
-
To play the latest published version, keep this at 0.
-
To play a specific, published, version of your story, set the number to that particular version.
-
To play the draft version, set the number to -1. To do this, you must also supply your API key.
An apiKey can be provided to play an unpublished version of your story that isn't available to the public, including the draft version. API keys do not expire (unless regenerated). Please make sure to not share the API key with anyone you do not trust, and strip the key from any public builds.
If you are referencing a pro story you can use the StartGraphReferenceId to reference the scene you want to start. The StartGraphReferenceId is the same across the draft and published versions of your story. To find the StartGraphReferenceId of the particular graph you want to start, go to your story in the Charisma platform. In the sidebar click on the three dots next to the subplot's name. Then click 'edit details...' and copy (or change) the ID.
To include voice audio in replies, either include SpeechOptions when creating the playthrough, or call setSpeechOptions at some later point.
Two options can be set:
The output format of voice audio generated by Charisma. Supported audio formats include ogg, mp3 and wav.
Audio can be received both as an audio clip (buffer) and a URL. Out of the box, only the buffer option is supported. This is because audio can be both a byte[] and a string depending on what the server sends back, but msgpack only supports deserialising a single type. However, to support url instead, you can adjust byte[] to string in the Speech object in Events.cs, and then uncomment Url in the AudioOutput enum in Audio.cs.