Scripting

Scripting

How to use Scripting in AI Dungeon

icon
Scripting allows creators to modify the player experience beyond what is supported in the Scenario Editor.

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 script
  • stop - this is the stop value returned by the script
  • logs - this is an array of log outputs from the script
  • state - this is the updated state object after running the script
  • storyCards - 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 action
  • rawText - the same as text, deprecated and included for backwards compatibility.
  • type - the type of the action, the most common types are listed below
    • start - the first action of an adventure
    • continue - an action created by the AI
    • do - a do action submitted by a player
    • say - a say action submitted by a player
    • story - a story action submitted by a player
    • see - 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 card
  • keys - keys that should cause the story card to be included in the model context
  • entry - the text that should be included in the model context if the story card is included
  • type - 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 adventure
    • actionCount - the total number of actions in the adventure
  • onModelContext
    • 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 the memory

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.

icon
image

© Latitude 2023