Scripting

Scripting is one of AI Dungeon's scenario features.

• Scripting allows you to attach a custom JavaScript to the Input Modifier, Context Modifier, and Output Modifier of a Scenario.
• While scripts are constrained to a limited sandbox environment it offers the flexibility of accessing otherwise inaccessible functionalities such as scripted manipulation of state, world info, the user- input, context, and AI's output.

Until January 8. 2021, Scripting was a Premium-exclusive feature.

How to create a script

• Navigate to the scenario creation screen via My Stuff in the left-side panel of AI Dungeon's interface then press Create Scenario at the top of the interface or enter an existing scenario from your list of scenarios.
• At the bottom of the scenario creation screen, there's a button labeled Scripts that brings you to the scripting interface.
• In the scripting interface screen you will be presented with four tabs labeled Shared Library, Input Modifier, Context Modifier, and Output Modifier.
  • Replace or modify the contents of the panels with your own JavaScript then hit Save in the top-right corner to attach the script(s) to the scenario you are in.
  • Adventures played from this scenario will now be affected by the attached script(s), continue reading for specifics regarding scripting functions. Or see Tutorial:Scripting for information on how to make scripts.

Scripting Functions

Shared Library

The shared Library is prepended to the start of the three other Modifiers and can be used for code you want to share between all three.

Input Modifier

The Input Modifier script is always and only executed on a valid user- input.

• text is a manipulable string containing the user- input.

Context Modifier

The Context Modifier script is executed every time the AI would be sent text and allows the script to modify that text. It is always executed before the output modifier.

• text is a string containing the entirety of the AI's context.
  • All modifications to text are transient and invisible to the user.
  • You can edit up to 75% of the total context (text) through the context modifier according to Levenshtein Distance.

Output Modifier

The Output Modifier script is always executed before the AI displays a result.

• text is a manipulable string containing the result it intends to display.

Stop

In the Input and Context modifiers you can optionally supply a stop parameter that disables AI generation, and therefore causes the Output Modifier to not run.
return { text: null }

Behavior of Commands

• Continue triggers the context and output modifiers.
• Alter doesn't trigger scripts and could only be measured by looking for differences in history.
• Undo doesn't trigger any scripts but can be measured using info.actionCount
• Redo doesn't trigger any scripts but is equivalent to just doing less/no undos.
• Retry triggers the context and output modifiers because it is equivalent to undo + continue.
• Remember triggers no scripts but modifies memory
• World Info merely opens the world info page and so doesn't activate any scripts.

Import/Export Scripts

Scripts can be imported and exported in a zip file to and from the scenario. In the zip file there are 4 files: contextModifier.js,inputModifier.js,outputModifier.js, and shared.js.

• Note: As of February 2021 the system has bugs resulting in scripts being erased. It is highly recommended to export your scripts regularly.

Last Model Input

The Last Model Input (LMI) can be found within the scripting interface, top-right corner next to the save symbol.

• LMI displays the context that's fed to the AI on input/output in adventures that derive from the scenario.
• LMI wipes its information after two(2) minutes of displaying a result.
• LMI is used to see how, where and what sort of additional information is fed to the AI e.g World Info, Memory
• LMI also displays the adventure's current state at the bottom.
• LMI displays the console history in the second tab.

History

history is a (Read- only) object whose elements contain the keys text and type of the 100 most recent displayed results.

• text is a string containing the displayed text of the result.
• type is a string containing "story", "continue", "do" or "say" depending on which of those initiated the query.

Memory

memory is a (Read- Only) object that holds a singular string of the user- defined memory.

• memory characters that exceed the 1000 limit are excluded from the AI's context.

State

Values assigned to the state object are accessible from and shared between the various scripts.

• state is an object used to store and modify persistent data throughout an adventure.
• state.memory.context takes priority and neglects the user- defined memory contained in memory if assigned.
• state.memory.frontMemory appends a hidden string to the end of a user's input while assigned a value.
• state.memory.authorsNote injects a transient, bracket-encapsulated and prefixed string three(3) line-breaks(\n) into the context. e.g `[Author's Note: ${state.memory.authorsNote}]`

Message

state.message displays its assigned string as a persistent pop up message at the bottom of the scripted adventure. In single player state.message should be only a normal string.

In multiplayer state.message can be a normal string, which will display for all players but it can also be an object of the form { text: 'Only you can see this!', visibleTo: ['Sam', 'Jane']} where visibleTo is an array of the players the message is visible to. It can also be an array of objects of that form, in which case the first object that matches a player will determine their message. If a player is not given a message for a given turn it will appear blank.

Info

info is a (Read- only) object that stores informational data.

• info.actionCount is an integer value denoting the amount of actions made within the adventure.
• info.characters is an array of character info, currently each object has one key of name. E.g., { name: "Sam" }.

• info.maxChars is an integer value denoting the maximum length of context (text).
  • info.maxChars is only accessible via context modifier.
  • The server will truncate the length of text to conform itself to the amount of characters denoted by info.maxChars.

• info.memoryLength is an integer value denoting the length of the text's memory section.
  • info.memoryLength is only accessible via context modifier.

World Entries

worldEntries elements contain the keys: id, keys, entry and isNotHidden.

• id is a randomly generated float value contained in a string e.g "0.123456789".
• keys is a comma- delimited string e.g "these, are, your, keys".
• entry is a string e.g "This is your entry\nWith a linebreak.".
• isNotHidden is a boolean value that determines the visibility of the element from within an adventure e.g true

worldEntries has the following inbuilt functions available for manipulations.

• addWorldEntry(keys, entry, isNotHidden = true) creates a new worldEntries element.
• removeWorldEntry(index) removes an existing element.
• updateWorldEntry(index, keys, entry, isNotHidden = true) updates the keys and entry of an existing element.

Evaluation Bots

There are several bots for scripting, for different purposes. The most widely known of them is JudgeBot, the bot used for scoring. Here follows a list of bots:

• DCStatDifficultyBot (Input) Evaluates difficulty and stat needed for an action (difficulty = easy/medium/hard)
• InputDCattributeBot (Input) Evaluates difficulty and attribute for an action (difficulty = integer)
• SimplePossibilityBot (Input) Evaluates two possible actions (PossibleAction1 and PossibleAction2) based on a 75 character description on state.contextualString.
• GoblinBot (Output) Evaluates whether goblins were killed, health lost, and loot gained
• KittenBot (Output) Evaluates whether rapport was gained or a kitten got hungrier
• SpaceLootBot (Output) Evaluates whether loot would be found (on a spaceship)
• HungerBot (Output) Evaluates whether the player would get hungrier or not
• RestDetectBot (Output) Evaluates whether or not the user got rest
• KillBot (Input/Output) Evaluates whether the player is killing things
• JudgeBot (Input/Output) Evaluates whether an action was just
• EmpathyBot (Input/Output) Evaluates whether an action showed empathy
• SuccessBot (Input/Output) Evaluates whether an action succeeded
• SantaBot (Input/Output) Evaluates whether an action showed Christmas spirit

Bots can be selected using state.evaluationBot.

Console

console.log("Some message") logs messages to the scripting interface console and to the 'Script Logs & Errors' tab found within the 'Script Diagnostics' screen.