Function Nodes

With function nodes, you can use the power of JavaScript to do things like bringing in data to your story from external APIs to use in character replies, or gating a node based on complex, custom conditions.

For example, you could gate a node based on a condition like "if the player is playing on a Monday between 3 and 4pm, and their name is in the first half of the alphabet, and the time they've spent in the story is more than 5 minutes or Arsenal scored twice over their last 5 games, then continue".

Examples of what function nodes can be used for in Charisma:

• Fetching live weather. So a character could say, “It’s raining where I am in London”.
• Fetching wikipedia info. So a character could talk for hours about their favourite species of frog... should they wish.
• Fetching the football results. So a character could boast about their infinitely better team than yours!

Using function nodes

When a player hits a function node, the script authored for that function node is run in a secure, sandboxed environment. Each invocation occurs in a new sandbox.

Important: The script is executed when the branch in the story graph is being considered, so functions will execute even if that node is not ultimately selected to be part of the final reply! Consider making your functions idempotent by only reading data instead of setting data.

The script has a timeout of 5000ms. If it exceeds this time, it will be terminated, and Charisma will not pass through the function node.

Returning true or no value from the script will allow Charisma to pass through this function node, and returning false will prevent Charisma from continuing through this node. This is the way that you can author custom conditions!

Global functions

The script you provide can make use of the following global functions, additional to the native V8 runtime built-ins:

• fetch(...): This API is the same as the fetch API available in the browser (opens in a new tab).
• getMemory(memoryName: string): Promise<JSONValue | null>: Returns the current saved value of a memory in this playthrough. memoryName should be the recall value.
• setMemory(memoryName: string, saveValue: JSONValue): Promise<void>: Sets the current saved value of a memory in this playthrough to the passed value. memoryName should be the recall value. saveValue can be any JSON-serialisable value, including arrays and objects. Important: this is not committed to the playthrough until the branch with this node in is selected as the final reply!
• getContext(contextKey: string): Promise<JSONValue>: Context is a way to persist any data (such as JSON from a fetch result) between now and the next emitted character node, at which point the context is cleared. Returns the current value in context for the key provided.
• setContext(contextKey: string, contextValue: JSONValue): Promise<void>: Sets the current value in context for the key provided to the value provided.