Playing AI Dungeon
Common Questions
How to use Scripting in AI Dungeon
Scenarios
Scripts are attached to Scenarios. Adventures started from a Scenario have separate game states but share the same scripts.
Only Simple Start and Character Creator Scenarios can have scripts. Multiple Choice Scenarios can’t have scripts, but can have options that have scripts. Scripts in options for Multiple Choice Scenarios are independent.
Visibility
Only the creator of a scenario can see the scripts for that scenario.
Scripts for published scenarios may be reviewed as part of moderation to ensure they comply with AI Dungeon’s community guidelines.
Scripting UI
When editing a simple or character creation scenario, you can open scripting from the bottom of the Details tab.
Scripts
On the left, you can navigate between the four available scripts. Each script has default text to help you understand how to write your own scripts. For scripts other than Library, the last line must always be modifier(text)
- Library - a shared library of functions and values that can be used in other scripts
- Input - a script that should run during the
onInput
hook - Context - a script that should run during the
onModelContext
hook - Output - a script that should run during the
onOutput
hook
If you have unsaved changes, a white dot will appear next to the script with unsaved changes.
Script Test
After selecting a non-library script, you will see the Script Test option in a panel on the right.
Input
The Input text box starts with a default value to illustrate the structure of the inputs available for scripts. You can modify this value to test how your script responds to other inputs.
Submit
The Submit button will send the input, the library, and the script to the server for a test run.
Output
The Output section will then show the results of the test.
text
- this the text value returned by the scriptstop
- this is the stop value returned by the scriptlogs
- this is an array of log outputs from the scriptstate
- this is the updated state object after running the scriptstoryCards
- this is the array of story cards after running the script
Console Log
After selecting a non-library script, you will see the Console Log option in the panel on the right. This option will show recent console logs from adventures that you personally have started from this scenario. Only console logs from adventures created by the creator of the scenario will show up in the Console Log section.
Console logs are pushed to the Console Log section in real time, so if you can have one tab open with the Scripting Editor and a separate tab open with a play test, you can watch the console logs as they happen.
Logs are saved for 15 minutes.
Top Navigation Bar
Back Button
The back button takes you back to the Scenario Editor. If you have unsaved changes, pressing the back button will cause a confirmation dialog to appear which will ask you to Save or Discard your unsaved changes.
Help Button
The help button opens this Guidebook article in a new tab, so you have easy access to all of the reference information for the Scripting API.
Inspect Button
The inspect button opens a modal that shows the most recent model context and game state for adventures using the scripts from this scenario.
Only adventures where the owner of the adventure is the owner of the scenario will send model context and game state logs to the inspect modal.
Contents of the inspect modal expire after 15 minutes.
Play Button
The play button starts a new adventure from this scenario in a new tab, so you can easily test changes to your scripts.
When you play a child scenario of a multiple choice scenario, the play button will take you directly to the child scenario, rather than taking you to the menu, which would be the experience for players.
Save Button
The save button saves an unsaved changes.
Scripting API
Hooks
The Scripting API consists of three lifecycle hooks.
onInput
The input hook allows a script to modify the player’s input text before it is used to construct the model context.
onModelContext
The model context hook allows a script to change the text sent to the AI model before the model is called.
onOutput
The output hook allows a script to modify the model’s output text before it is returned to the player.
Params
Scripting API hooks have access to the following information. When referencing one of these params in a script, you can reference the name of the parameter directly—you do not need to deconstruct it from an object.
text
For the onInput
hook, this field has the text entered by the player.
For the onModelContext
hook, this field has the text that would otherwise be sent to the AI.
For the onOutput
hook, this field has the text that would otherwise be sent back to the player.
history
This field has an array of recent actions from the adventure.
Each action has the following fields.
text
- the text of the actionrawText
- the same as text, deprecated and included for backwards compatibility.type
- the type of the action, the most common types are listed belowstart
- the first action of an adventurecontinue
- an action created by the AIdo
- a do action submitted by a playersay
- a say action submitted by a playerstory
- a story action submitted by a playersee
- a see action submitted by a player
storyCards
This field has an array of story cards from the adventure.
Each story card has the following fields.
id
- a unique numerical id for the story cardkeys
- keys that should cause the story card to be included in the model contextentry
- the text that should be included in the model context if the story card is includedtype
- a text field that can be used to separate story cards into categories
This field was formerly named worldInfo
. References to worldInfo
are still valid for backwards compatibility.
state
This field is an object where scripts can store additional persistent information to be available across turns. Beyond being an object, this field can have any structure needed for the script.
To change the state, scripts can set values in the state object directly, without using a helper function.
In addition to creator-defined fields, the state object also expects to have the following fields.
memory
This field is an object with the current memory for the adventure, including the following fields.
context
- is added to the beginning of the context, before the history. Corresponds to the Memory available in the UI.authorsNote
- is added close to the end of the context, immediately before the most recent AI response. Corresponds to the Authors Note available in the UI.frontMemory
- is added to the very end of the context, after the most recent player input.
Note that setting the context
or authorsNote
here will take precedence over the memory or authors note from the UI, but will not update them. If the context
or authorsNote
is not set or is set to an empty string, then the settings from the UI will still be used, so it is not possible to use the state
to clear the memory or authors note completely.
Any updates made to the memory
in the onOutput
hook will not have any affect until the next player action.
message
This field is a string which will be shown to the user. (Not yet implemented on Phoenix).
info
This field is an object that can contain additional values that may sometimes be useful. These values may be different for different hooks.
- All Hooks
characterNames
- an array of character names for players of a multiplayer adventureactionCount
- the total number of actions in the adventureonModelContext
maxChars
- the estimated maximum number of characters that can be included in the model context (character per token can vary)memoryLength
- the number of characters included in the model context from thememory
Functions
Scripting API hooks have access to the following functions.
log
Logs information to the console.
console.log
also works to reduce confusion
sandboxConsole.log
also works for backward compatibility, but is deprecated.
addStoryCard
Adds a new story card and returns the index of the new card.
If there is already an existing card with the same keys, returns false.
addWorldEntry
also works for backwards compatibility, but is deprecated.
removeStoryCard
Removes a story card.
If the card doesn’t exist, throws an error
removeWorldEntry
also works for backwards compatibility, but is deprecated.
updateStoryCard
Updates a story card.
If the card doesn’t exist, throws an error
updateWorldEntry
also works for backwards compatibility, but is deprecated.
Return
Scripting API hooks can return the following values
text
For the onInput
hook, this will replace the text entered by the player.
Returning an empty string in onInput
throws an error which is shown to the player and says Unable to run scenario scripts
.
For the onModelContext
hook, this will replace the text sent to the AI.
Returning an empty string in onModelContext
causes the context to be built as though the script did not run.
For the onOutput
hook, this will replace the text returned to the player.
Returning an empty string in onOutput
throws an error which is shown to the player and says A custom script running on this scenario failed. Please try again or fix the script.
Returning the text stop
is equivalent to returning stop: true
.
stop
If stop === true
, then the game loop will not proceed. This is useful in cases where you want a player input to update the state but to not run the AI.
When you return stop
in the onInput
hook, it throws an error which is shown to the player and says Unable to run scenario scripts
When you return stop
in the onModelContext
hook, it throws an error which is shown to the player and says Sorry, the AI is stumped. Edit/retry your previous action, or write something to help it along.
When you return stop
in the onOutput
hook, it changes the output to stop
. Don’t do this.
Example Scripts
If you have additional example scripts that you’d like to submit for this section, please send them to support@aidungeon.com. The examples below are from the Scripting repo.
Basic Example
Don’t Be Negative
Notes
Reimplement Authors Note
Add Simple Inventory
Command Parser
Death Island
Guess or Die
Magic
Skills
Sundale
Known Issues
Story Cards
- Changes to story cards made in earlier hooks are not always present in later hooks.
- Update to story cards in the context hook are overwritten if separate updates are made in the output hook.
Reporting Issues
To report an issue with Scripting in AI Dungeon, please post to the bugs-feature-request channel on Discord.
In addition, if you can create and publish a Scenario with a minimal reproduction case showing the issue and include that published link in your bug report, that would significantly increase how quickly we can resolve the problem.
© Latitude 2023