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 pressCreate 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
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.
- All modifications to
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 inmemory
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 byinfo.maxChars
.
info.memoryLength
is an integer value denoting the length of thetext
'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.gtrue
worldEntries
has the following inbuilt functions available for manipulations.
addWorldEntry(keys, entry, isNotHidden = true)
creates a newworldEntries
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 onstate.contextualString
.GoblinBot
(Output) Evaluates whether goblins were killed, health lost, and loot gainedKittenBot
(Output) Evaluates whether rapport was gained or a kitten got hungrierSpaceLootBot
(Output) Evaluates whether loot would be found (on a spaceship)HungerBot
(Output) Evaluates whether the player would get hungrier or notRestDetectBot
(Output) Evaluates whether or not the user got restKillBot
(Input/Output) Evaluates whether the player is killing thingsJudgeBot
(Input/Output) Evaluates whether an action was justEmpathyBot
(Input/Output) Evaluates whether an action showed empathySuccessBot
(Input/Output) Evaluates whether an action succeededSantaBot
(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.