Godot
⚠️ Support Note: The Godot SDK is built and maintained by the developer community. Inworld will maintain the basic functionality of initially released features of this SDK, while continuous development and new features will be driven by our community. If you're keen on contributing to the Godot SDK, we welcome your involvement! For guidance on how to contribute, see GitHub.
Download
Download the latest version of the Inworld AI Godot SDK on our GitHub.
Prerequisites
Supported Platforms
Windows | Mac |
---|
Supported Godot Versions
4.2.1 |
---|
⚠️ Note: It is recommended to utilize headphones when using voice.
Sample project
A sample Godot project utilizing the Inworld SDK is included and can be found in the 'Project' folder.
To get started, either self-build the GDExtension, or copy a pre-built version to the /Project/addons/inworld
directory.
For instructions for cloning the sample Inworld workspace and configuring the nodes to use the clone, please reference the included ReadMe.md file.
Getting Started
Official documentation on GDExtensions can be found Here.
Self-built
The SDK contains several scripts for building the SDK with scons. They are also provided below for reference:
Windows
Build debug
build-win.bat
scons platform=windows use_static_cpp=False
Build release
build-win-release.bat
scons platform=windows use_static_cpp=False target=template_release
Clean
clean-win.bat
scons --clean
Mac
Build debug
build-mac.sh
scons platform=macos
Build release
build-mac-release.sh
scons platform=macos target=template_release
Clean
clean-mac.sh
scons --clean
Pre-built
Building the GDExtension is only required in order to contribute to, or modify, the Godot SDK for Inworld.ai. To utilize the GDExtension without modification, simply download the release .zip from the latest release: https://github.com/inworld-ai/inworld-godot-sdk/releases/
Installation
Extract the .zip file to your Godot project directory.
Edit the .godot file in this directory, and add or modify to include the following:
[native_extensions]
paths=["res://addons/inworld/inworld.gdextension"]
Nodes
Inworld is utilized in Godot via custom Node types.
Simply add Inworld nodes to a scene, configure their properties, and utilize their functionalities from gdscript.
Session
The InworldSession Node is responsible for starting and stopping sessions with Inworld.
Player (Optional)
If the player property is set before start() is called, the session will register the player properties with the session. This will enable characters from this session to reference the player by their given name.
Project Name (Optional)
A unique identifier for your project. Though not required, this will help the inworld support team to identify your sessions.
Workspace Name
The name of your Inworld Studio workspace.
⚠️ Note: Do not prepend 'workspaces/'. For example if the URL of your Inworld studio workspace is workspaces/my-godot-workspace-name, simply enter my-godot-workspace-name in this field.
Scene Type
The type of scene for the session to use.
Scene: A normal inworld scene. You can configure these scenes from the 'Scenes' tab in your inworld studio workspace.
Single-Character: An automatically generated scene that contains a single character. No scene from the inworld studio workspace is required.
Scene Name
The name of a scene in your Inworld Studio workspace.
For scene type, use the name of the desired scene from the 'Scenes' tab in your inworld studio workspace.
⚠️ Note: Do not prepend 'scenes/'. For example if the URL of your Inworld studio scene is workspaces/my-godot-workspace-name/scenes/my-godot-scene, simply enter my-godot-scene in this field.
For single-character type, use the name of the desired character from the 'Characters' tab in your Inworld Studio workspace.
⚠️ Note: Do not prepend 'characters/'. For example if the URL of your inworld studio character is workspaces/my-godot-workspace-name/characters/my-godot-character, simply enter my-godot-character in this field.
Auth
The Base64 Authorization Key generated from Inworld Studio.
You can generate a key from the 'Integrations' tab in your inworld studio workspace. Under the 'API Keys' section, click '+Generate new key', then click 'Copy Base64'.
Session Usage
Managing Sessions
func start() -> void
Start the inworld session.
func stop() -> void
Stop the inworld session.
Connection State
enum ConnectionState {
IDLE = 0,
CONNECTING = 1,
CONNECTED = 2,
FAILED = 3,
PAUSED = 4,
DISCONNECTED = 5,
RECONNECTING = 6,
};
func get_connection_state() -> ConnectionState
Get the current connection state.
signal: connection_state_changed(ConnectionState)
Emitted when the connection state changes.
func get_connected() -> bool
Get if the current connection state is CONNECTED.
signal: connected(bool)
Emitted when the connection state changes between CONNECTED and anything other than CONNECTED.
func get_established() -> bool
Get if the session has established session info.
signal: established(bool)
Emitted when the session establishes or is torn down.
Character
The InworldCharacter Node is responsible for representing an Inworld character within a session.
Brain
The brain of your Inworld character from your Inworld Studio workspace.
⚠️ Note: Do not prepend 'characters/'. If the URL of your Inworld Studio character is workspaces/my-godot-workspace-name/characters/my-godot-character, simply enter my-godot-character in this field.
⚠️ Note: Although it is common for the character name and brain to be the same value, the brain name is not the name of your character.
Given Name (Read-Only)
The brain of your Inworld character from your Inworld Studio workspace.
⚠️ Note: This value is read-only, and will be populated when the associated session for the character is established.
Session
The session for the character to receive data from.
Character Usage
Text
func send_text(String text)
Sends a text message of 'text' to the character.
Trigger
func send_trigger(String name, Dictionary params)
Sends a trigger of 'name' with parameters 'params' to the character.
Audio
func start_audio_session()
Starts an audio session with the character.
⚠️ Note: Audio session management is automatically handled by the SDK. Only call this if you know what you are doing!
func stop_audio_session()
Stops an audio session with the character.
⚠️ Note: Audio session management is automatically handled by the SDK. Only call this if you know what you are doing!
func send_audio(PackedByteArray data)
Sends PCM 'data' to the character.
⚠️ Note: Sending audio data is automatically handled by the SDK. Only call this if you know what you are doing!
Interrupt
func interrupt()
Interrupts the character, will signal 'interrupt' and remove any remaining unprocessed MessageTalk.
signal interrupt()
Emitted when the character has been interrupted.
⚠️ Note: Characters will be interrupted automatically when send text, sent a trigger, or STT is recognized.
Character Messages
As data is received from the inworld session, messages will be created and emitted from the character.
Message Talk
signal: message_talk(MessageTalk)
Emitted when the character has a MessageTalk to process.
⚠️ Note: Only one MessageTalk can be processed at a time per character. Call
func finish_current_message_talk()
to release the message.
Data
String text
Text representation of the talk.
PackedByteArray chunk
Raw PCM data representation of the talk.
TypedArray<Viseme> visemes
Lipsync visemes that represent the raw PCM data.
Viseme
StringName code
Code of the viseme.
float time_stamp
Timestamp of the PCM data that the viseme represents.
Message Speech To Text
signal: message_stt(MessageSpeechToText)
Emitted when the character has a MessageSpeechToText to process.
⚠️ Note: As audio data is received, the player speech will continue to update until a final representation has been determined. It is expected to receieve many partial STT messages before completion.
Data
String text
Text representation of the players speech.
bool complete
If the text representation has been finalized.
Message Emotion
signal: message_emotion(MessageEmotion)
Emitted when the character has a MessageEmotion to process.
enum EmotionBehavior {
AFFECTION = 0,
ANGER = 1,
BELLIGERENCE = 2,
CONTEMPT = 3,
CRITICISM = 4,
DEFENSIVENESS = 5,
DISGUST = 6,
DOMINEERING = 7,
HUMOR = 8,
INTEREST = 9,
JOY = 10,
NEUTRAL = 11,
SADNESS = 12,
STONEWALLING = 13,
SURPRISE = 14,
TENSE = 15,
TENSION = 16,
VALIDATION = 17,
WHINING = 18,
};
enum EmotionStrength {
WEAK = 0,
NORMAL = 1,
STRONG = 2,
};
Data
EmotionBehavior behavior
Type of emotion that the character is feeling.
EmotionStrength strength
The strength of the type of emotion that the charcter is feeling.
Message Trigger
signal: message_trigger(MessageTrigger)
Emitted when the character has a MessageTrigger to process.
Data
String name
Name of the trigger.
Dictionary params
Parameters of the trigger.
Player
The InworldPlayer Node is responsible for allowing the player to interface with inworld characters.
Given Name
The name of the player. If an Inworld session is configured with this player before it is started, characters in the session will refer to the player by this name.
Target Character
The Inworld character that the player has targeted. If the player is talking, audio data will be routed to this character.
Talking
If the microphone audio should be forwarded to the target character if available.
Conversing
signal conversing_start(InworldCharacter)
Emitted when the player has selected the character as a target.
signal conversing_stop(InworldCharacter)
Emitted when the player has deselected the character as a target.