README.md

LALib

Library of STScript commands.

• Help (lalib?)
• Boolean Operations (=, test, and, or, not)
• List Operations and Loops (pop, push, shift, unshift, foreach, map, whilee, reduce, sorte, flatten, filter, find, slice, splice, shuffle, pick, reverse, dict, keys)
• Split & Join (split, join)
• Text Operations (trim, pad-start, pad-end, pad-both, diff, json-pretty, substitute, wordcount, sentencecount, segment)
• Regular Expressions (re-escape, re-test, re-replace, re-exec)
• Accessing & Manipulating Structured Data (getat, setat)
• Exception Handling (try, catch)
• Null Handling (ifempty, ifnullish)
• Copy & Download (copy, download)
• DOM Interaction (dom)
• Characters (char-get)
• Group Chats (memberpos, group-get)
• Conditionals - switch (switch, case)
• Conditionals - if (ife, elseif, else, then)
• World Info (wi-list-books, wi-list-entries, wi-activate)
• Costumes / Sprites (costumes)
• Quick Replies (qr-edit, qr-add)
• Chat Messages (swipes-get, swipes-get, swipes-list, swipes-count, swipes-index, swipes-add, swipes-del, swipes-go, swipes-swipe, message-edit, message-move)
• Chat Management (chat-list, chat-parent, message-on, message-off, message-listeners, role-swap)
• Time & Date (timestamp)
• Async (fireandforget)
• Logging (console-log, console-warn, console-error)
• Audio (sfx)
• Miscellaneous (fonts)
• Web Requests (fetch, $, $$)

Requirements

• (optional) Costumes Plugin for /costumes command.

Commands

Help

/lalib?

• (slash|expressions)? = slash
  (optional) help topic

Lists LALib commands

Examples

/lalib? |
// command documentation |

/lalib? expressions |
// expressions documentation |

Boolean Operations

/=

• ...[expression variables:bool|closure|dictionary|list|number|string]?
  (optional) named arguments assigned to scoped variables to be used in the expression
• ...(string)
  boolean / arithmetic expression

Evaluates a boolean or arithmetic expression

See /lalib? expressions for more details on expressions.

Examples

/= true or false |

/= 1 < 2 and ('a' in x or 'b' not in y) and !z |

/= 1 + 2 * 3 ** 4 |

/= (1 + 2) * 3 ** 4 |

/genraw say either foo or bar |
/= result={{pipe}} ('foo' in result) |
// use named arguments to provide variables to the expression |

/test

• [left:varname|number|string]
  the left operand value
• [rule=gt|gte|lt|lte|eq|neq|not|in|nin]
  the boolean operation rule
• [right:varname|number|string]
  the right operand value

Compares the value of the left operand a with the value of the right operand b, and returns the result of the comparison (true or false).

Numeric values and string literals for left and right operands supported.

Available rules:

• gt => a > b
• gte => a >= b
• lt => a < b
• lte => a <= b
• eq => a == b
• neq => a != b
• not => !a
• in (strings) => a includes b
• nin (strings) => a not includes b

Examples

/setvar key=i 0 | /test left=i rule=lte right=10 | /echo |
// returns true |

/and

• ...(true|false)
  the values to evaluate

Returns true if all values are true, otherwise false.

Examples

/and true true true |
// Returns true. |

/and true false true |
// Returns false. |

/or

• ...(true|false)
  the values to evaluate

Returns true if at least one of the values is true, false if all are false.

Examples

/or true true true |
// Returns true. |

/or true false true |
// Returns true. |

/or false false false |
// Returns false. |

/not

• (true|false)
  the value to negate

Returns true if value is false, otherwise true.

Examples

/not false |
// Returns true. |

/not true |
// Returns false. |

List Operations and Loops

/pop

• (varname|list)
  target list

Removes the last element from a list and returns it.

Examples

/pop ["A", "B", "C"] |
// returns C |

/let x [1, 2, 3, 4, 5] |
/pop x |
// returns 5 |

/push

• (varname|list)
  target list
• ...(bool|closure|dictionary|list|number|string)
  items to add

Appends new elements to the end of a list, and returns the list.

Examples

/push ["A", "B", "C"] foo bar |
// returns ["A", "B", "C", "foo", "bar"] |

/let x [1, 2, 3, 4, 5] |
/push x 10 |
// returns [1, 2, 3, 4, 5, 10] |

/shift

• (varname|list)
  target list

Removes the first element from a list and returns it.

Examples

/shift ["A", "B", "C"] |
// returns A |

/let x [1, 2, 3, 4, 5] |
/shift x |
// returns 1 |

/unshift

• (varname|list)
  target list
• ...(bool|closure|dictionary|list|number|string)
  items to add

Inserts new elements at the start of a list, and returns the list.

Examples

/unshift ["A", "B", "C"] foo bar |
// returns ["foo", "bar", "A", "B", "C"] |

/let x [1, 2, 3, 4, 5] |
/unshift x 10 |
// returns [10, 1, 2, 3, 4, 5] |

/foreach

• (list|dictionary)
  the list or dictionary to iterate over
• (closure|subcommand)
  the closure to execute for each item, with {{var::item}} and {{var::index}} (or the first two closure arguments) placeholders

Executes the provided command for each item of a list or dictionary, replacing {{var::item}} and {{var::index}} (or the first two closure arguments) with the current item and index.

Use /break to break out of the loop early.

Examples

/foreach ["A", "B", "C"] {:
    /echo Item {{var::index}} is {{var::item}} |
    /delay 400 |
:} |

/let x {"a":"foo","b":"bar"} |
/foreach {{var::x}} {:
    /echo Item {{var::index}} is {{var::item}} |
    /delay 400 |
:} |

/foreach ["A", "B", "C"] {: it= i=
    /echo Item {{var::it}} is {{var::i}} |
    /delay 400 |
:} |
// uses custom closure arguments it and i instead of the default item and index. |

/foreach ["A", "B", "C"] {: foo= bar=
    /echo Item {{var::foo}} is {{var::bar}} |
    /delay 400 |
:} |
// uses custom closure arguments foo and bar instead of the default item and index. |

/map

• [aslist=true|false]? = false
  (optional) whether to return the results of a dictionary as a list
• (list|dictionary)
  the list or dictionary to iterate over
• (closure|subcommand)
  the closure to execute for each item, with {{var::item}} and {{var::index}} (or the first two closure arguments) placeholders

Executes a command for each item of a list or dictionary and returns the list or dictionary of the command results.

Use /break to break out of the loop early.

Examples

/map [1,2,3] {:
    /mul {{var::item}} {{var::item}}
:} |
// Calculates the square of each number. |

/map [1,2,3] {: it= i=
    /mul {{var::it}} {{var::it}}
:} |
// Calculates the square of each number. |

/map [1,2,3] {: foo= bar=
    /mul {{var::foo}} {{var::foo}}
:} |
// Calculates the square of each number. |

/map {"a":1,"b":2,"c":3} {: /mul {{var::item}} {{var::item}} :} |
// Calculates the square of each number. |

/map aslist= {"a":1,"b":2,"c":3} {: /mul {{var::item}} {{var::item}} :} |
// Calculates the square of each number. |

/whilee

• ...[expression variables:bool|closure|dictionary|list|number|string]?
  (optional) named arguments assigned to scoped variables to be used in the expression
• ...(string|closure)
  the expression or closure to evaluate
• (closure)
  the closure to execute

Creates a loop that executes a specified closure as long as the test condition (expression or closure) evaluates to true. The condition is evaluated before executing the closure.

Use /break to break out of the loop early.

See /lalib? expressions for more details on expressions.

Examples

/whilee (i++ < 3) {:
    /echo i: {{var::i}} |
    /delay 400 |
:} |

/reduce

• [initial:bool|dictionary|list|number|string]?
  (optional) initial value
• (list)
  the list to reduce
• (closure)
  the closure to execute for each item, takes up to three arguments (accumulator, current value, current index)

Executes a "reducer" closure on each element of the list, in order, passing in the return value from the calculation on the preceding element. The final result of running the reducer across all elements of the list is a single value.

The first time that the closure is run there is no "return value of the previous calculation". If supplied, an initial value may be used in its place. Otherwise the list element at index 0 is used as the initial value and iteration starts from the next element (index 1 instead of index 0).

The reducer closure accepts up to three arguments:

• accumulator
  The value resulting from the previous call to closure. On the first call, its value is initial= if that argument is provided; otherwise its value is the first list item.
• currentValue
  The value of the current element. On the first call, its value is the first list item if initial= is specified; otherwise its value is the second list item.
• currentIndex
  The index position of currentValue in the list. On the first call, its value is 0 if initial= is specified, otherwise 1.

Examples

/reduce [1,2,3] {: acc= cur= /= acc + cur :} |
// returns 6 (1+2 = 3 -> 3 + 3 = 6) |

/reduce initial=10 [1,2,3] {: acc= cur= /= acc + cur :} |
// returns 16 (10+1 = 11 -> 11+2 = 13 -> 13 + 3 = 16) |

/let x [["a",1],["b",2],["c",3]] |
/reduce initial={} {{var::x}} {: acc= cur=
    /var key=acc index={: /= cur.0 :}() {: /= cur.1 :}() |
    /return {{var::acc}} |
:} |
// returns {"a":"1","b":"2","c":"3"} |

/sorte

• [key:closure]?
  (optional) closure that returns the value to be used for sorting
• (list|varname)
  the list to sort
• ...(string|closure)? = (a <=> b)
  (optional) the expression or closure used to compare two items a and b

Sorts a list.

The comparison closure must accept two named arguments which will be equivalent to a and b in the expression.
Using a comparison closure can be very performance and time intensive on longer lists.

If given a variable name, the variable will be modified.

See /lalib? expressions for more details on expressions.

Examples

/sorte [5,3,-10,-99,0] |
// returns [-99,-10,0,3,5] |

/let x [5,3,-10,-99,0] |
/sorte x |
/echo {{var::x}} |
// returns [-99,-10,0,3,5] |

/let x [5,3,-10,-99,0] |
/sorte {{var::x}} |
/echo {{var::x}} |
// returns [5,3,-10,-99,0] |

/sorte [5,3,-10,-99,0] (a <=> b) |
// returns [-99,-10,0,3,5] |

/sorte [5,3,-10,-99,0] (b <=> a) |
// returns [5,3,0,-10,-99] |

/sorte [5,3,-10,-99,0] {: a= b= /sub a b :} |
// returns [-99,-10,0,3,5] |

/flatten

• [depth:number]? = 1
  (optional) The depth level specifying how deep a nested list structure should be flattened. Defaults to 1. Use 0 to flatten all levels.
• (list)
  the list to flatten

Creates a new list with all sub-list elements concatenated into it recursively up to the specified depth.

Examples

/flatten [1, 2, 3, [4, 5, 6, [7, 8, 9]]] |
// returns [1, 2, 3, 4, 5, 6, [7, 8, 9]] |

/flatten depth=0 [1, 2, 3, [4, 5, 6, [7, 8, 9]]] |
// returns [1, 2, 3, 4, 5, 6, 7, 8, 9] |

/filter

• (list|dictionary)
  the list or dictionary to iterate over
• ...(closure|string)
  the closure or expression to execute for each item, with {{var::item}} and {{var::index}} placeholders

Executes command for each item of a list or dictionary and returns the list or dictionary of only those items where the command returned true.

See /lalib? expressions for more details on expressions.

Examples

/filter [1,2,3,4,5] {:
    /test left={{var::item}} rule=gt right=2
:} |
// returns [3, 4, 5] |

/filter [1,2,3,4,5] {: it=
    /test left={{var::it}} rule=gt right=2
:} |
// returns [3, 4, 5] |

/filter [1,2,3,4,5] (item > 2) |
// returns [3, 4, 5] |

/find

• [index=true|false]? = false
  (optional) return the matching item's index instead of the item
• [last=true|false]? = false
  (optional) return the last instead of the first matching item
• (list|dictionary)
  the list or dictionary to iterate over
• ...(closure|subcommand)
  the command to execute for each item, using {{var::item}} and {{var::index}} as placeholders

Executes the provided closure or expression for each item of a list or dictionary and returns the first item where the command returned true.

See /lalib? expressions for more details on expressions.

Examples

/find [1,2,3,4,5] {:
    /test left={{var::item}} rule=gt right=2
:} |
/echo |
// returns 3 |

/find [1,2,3,4,5] {: it=
    /test left={{var::it}} rule=gt right=2
:} |
/echo |
// returns 3 |

/find [1,2,3,4,5] (item > 2) | /echo |
// returns 3 |

/slice

• [start:number]
  the starting index of the slice, negative numbers start from the back
• [end:number]?
  (optional) the ending index of the slice (non-inclusive)
• [length:number]?
  (optional) the length of the slice
• (string|list)?
  (optional) the value to slice

Retrieves a slice of a list or string.

Examples

/slice start=2 length=3 [1,2,3,4,5,6] | /echo |
// returns [3,4,5] |

/slice start=-8 The quick brown fox jumps over the lazy dog | /echo |
// returns lazy dog |

/splice

• [start:number]
  the starting index of the splice, negative numbers start from the back
• [delete:number]?
  (optional) the number of elements to remove in the list from start (use delete= to remove everything)
• [insert:list|string]?
  (optional) the elements to add at index start=
• (string|number|bool|list|dictionary)?
  (optional) the list or string to operate on

Creates a new list with some elements removed and / or replaced at a given index.

Examples

/splice insert=[30, 40, 50] start=3 delete=3 [0,1,2,3,4,5,6] |
/echo |
// returns [0,1,2,30,40,50,6] |

/splice start=3 delete=3 [0,1,2,3,4,5,6] |
/echo |
// returns [0,1,2,6] |

/splice insert=100 start=3 [0,1,2,3,4,5,6] |
/echo |
// returns [0,1,2,100,3,4,5,6] |

/splice start=-1 delete=1 [0,1,2,3,4,5,6] |
/echo |
// returns [0,1,2,3,4,5] |

/shuffle

• (list)
  the list to shuffle

Returns a shuffled list.

Examples

/shuffle [1, 2, 3, 4] |
// could be [2, 4, 3, 1] |

/pick

• [items:number]? = 1
  (optional) how many items to pick (if greater than one, will return a list)
• [list=true|false]? = false
  (optional) whether to return a list, even if only one item is picked
• (list)
  the list to pick from

Picks one random item or items number of random items from a list (no duplicates).

Examples

/pick [1, 2, 3, 4] |
// could be 3 |

/pick list= [1, 2, 3, 4] |
// could be [3] |

/pick items=2 [1, 2, 3, 4] |
// could be [1, 4] |

/reverse

• (list)
  the list to reverse

Returns a reversed list.

Examples

/reverse [1, 2, 3, 4] |
// returns [4, 3, 2, 1] |

/dict

• [var:varname]?
  (optional) name of the chat variable to use as input
• [globalvar:varname]?
  (optional) name of the global variable to use as input
• (list)
  a list of lists, where each inner list has at least two elements

Takes a list of lists (each item must be a list of at least two items) and creates a dictionary by using each items first item as key and each items second item as value.

Examples

/let x [
    ["a", 1],
    ["b", 2],
    ["c", 3]
] |
/dict {{var::x}} |
/echo |
// returns {a:1, b:2, c:3} |

/keys

• (dictionary)?
  (optional) the dictionary to get keys from

Return the list of keys of a dictionary.

Examples

/let x {"a":1, "b":2, "c":3} |
/keys {{var::x}} |
// returns ["a", "b", "c"] |

Split & Join

/split

• [find:string]? = ,
  (optional) the text to split at
• [trim=true|false]? = true
  (optional) whether to trim the resulting values
• (string)?
  (optional) the value to split

Splits value into list at every occurrence of find. Supports regex find="/\s/"

Examples

/split find="/\s/" The quick brown fox jumps over the lazy dog | /echo |

/join

• [glue:string]? = ,
  (optional) the string to join the list items with
• (list)?
  (optional) the list to join

Joins the items of a list with glue into a single string. Use glue={{space}} to join with a space.

Examples

/join ["apple", "banana", "cherry"] |
// returns "apple, banana, cherry" |

/join glue=" | " ["apple", "banana", "cherry"] |
// returns "apple | banana | cherry" |

Text Operations

/trim

• (string)
  text to trim

Removes whitespace at the start and end of the text.

Examples

/let x "  foo " |
/trim {{var::x}} |
// return "foo" |

/pad-start

• [fill:string]? =
  (optional) the character to use to pad the text
• (number)
  target length
• (string)
  the text to pad

Pad the provided text at the start if it is shorter then the target length.

Examples

/pad-start 5 foo |
// returns   foo |

/pad-start fill=+ 5 foo |
// returns ++foo |

/pad-end

• [fill:string]? =
  (optional) the character to use to pad the text
• (number)
  target length
• (string)
  the text to pad

Pad the provided text at the end if it is shorter then the target length.

Examples

/pad-end 5 foo |
// returns foo   |

/pad-end fill=+ 5 foo |
// returns foo++ |

/pad-both

• [fill:string]? =
  (optional) the character to use to pad the text
• (number)
  target length
• (string)
  the text to pad

Pad the provided text at both ends if it is shorter then the target length.

If an odd number of characters needs to be added, the remaining character will be added at the end of the text.

Examples

/pad-both 5 foo |
// returns  foo  |

/pad-both fill=+ 5 foo |
// returns +foo+ |

/pad-both fill=+ 6 foo |
// returns +foo++ |

/diff

• [all=true|false]? = true
  (optional) show new, old, and diff side by side
• [buttons=true|false]? = true
  (optional) add buttons to pick which text to return
• [stripcode=true|false]? = true
  (optional) remove all codeblocks before diffing
• [notes:string]?
  (optional) show additional notes or comments above the comparison
• [old:string]
  the old text to compare
• [new:string]
  the new text to compare

Compares old text vs new text and displays the difference between the two. Use all=true to show new, old, and diff side by side. Use buttons=true to add buttons to pick which text to return. Use stripcode=true to remove all codeblocks before diffing. Use notes="some text" to show additional notes or comments above the comparison.

Examples

/sub {{lastMessageId}} 1 |
/messages names=off |
/let old {{pipe}} |
/setvar key=old {{var::old}} |

/messages names=off {{lastMessageId}} |
/let new {{pipe}} |
/setvar key=new {{var::new}} |

/diff old={{var::old}} new={{var::new}} |
// compares the last two messages |

/json-pretty

• (string)
  JSON to pretty print

Pretty print JSON.

Examples

/json-pretty {"a":1, "b":[1,2,3]} |
/send ```json{{newline}}{{pipe}}{{newline}}``` |

/substitute

• (string)
  text to substitute macros in

Substitute macros in text.

Examples

/let x foo |
/substitute x is \{\{var::x\}\} |

/wordcount

• [language:string]? = en
  (optional) Two character language code according to IETF BCP 47
• (string)
  the text to count words in

Count the number of words in text. Language defaults to "en". Supply a two character language according to IETF BCP 47 language tags for other languages.

Examples

/wordcount The quick brown fox jumps over the lazy dog. |
// returns 9 |

/sentencecount

• [language:string]? = en
  (optional) Two character language code according to IETF BCP 47
• (string)
  the text to count sentences in

Count the number of sentences in text. Language defaults to "en". Supply a two character language according to IETF BCP 47 language tags for other languages.

Examples

/sentencecount The quick brown fox jumps over the lazy dog. Does the quick brown fox jump over the lazy dog? |
// returns 2 |

/segment

• [granularity=grapheme|word|sentence]? = word
  (optional) The unit to segment the text into: grapheme, word or sentence
• [language:string]? = en
  (optional) Two character language code according to IETF BCP 47
• (string)
  the text to segment

Return the graphemes (characters, basically), words or sentences found in the text. Supply a two character language according to IETF BCP 47 language tags for other languages.

Examples

/segment granularity=sentence The fox. The dog. |
// returns ["The fox.", "The dog."] |

/segment granularity=word The fox. The dog. |
// returns ["The", "fox", "The", "dog"] |

Regular Expressions

/re-escape

• (string)
  text to escape

Escapes text to be used literally inside a regex.

Examples

/re-escape foo/bar foo.bar |
/echo |
// Will echo foo\/bar foo\.bar. |

/re-escape {{char}} |
/re-replace find=/\b{{pipe}}\b/g replace=FOO {{lastMessage}} |
/echo |

/re-test

• [find:string]
  the regular expression to test against
• (string)?
  (optional) the value to test

Tests if the provided variable or value matches a regular expression.

Examples

/re-test find=/dog/i The quick brown fox jumps over the lazy dog. |
// returns true |

// pipes in the regex must to be escaped |
/re-test find=/dog\|cat/i The quick brown fox jumps over the lazy dog. |
// returns true |

// if you want to find a literal pipe, you have to also escape the backslash escaping it |
/re-test find=/dog\\\|cat/i The quick brown fox jumps over the lazy dog. |
// returns false |

// or you can put quote around the regex and forget about escaping... |
/re-test find="/dog|cat/i" The quick brown fox jumps over the lazy dog. |
// returns true ("dog" or "cat") |

/re-test find="/dog\|cat/i" The quick brown fox jumps over the lazy dog. |
// result will be false (only matching literally "dog|cat") |

/re-replace

• [find:string]
  the regular expression (/pattern/flags)
• [replace:string]?
  (optional) the replacement text
• [cmd:closure|subcommand]?
  (optional) a closure or slash command to execute for each match
• (string)?
  (optional) the value to perform the replacement on

Searches the provided variable or value with the regular expression and replaces matches with the replace value or the return value of the provided closure or slash command. For text replacements and slash commands, use $1, $2, ... to reference capturing groups. In closures use {{$1}}, {{$2}}, ... to reference capturing groups.

Examples

/re-replace find=/\s+/ replace=" " The quick   brown  fox  jumps over the lazy dog | /echo |
// replaces multiple whitespace with a single space |

/re-replace find=/([a-z]+) ([a-z]+)/ cmd="/echo $2 $1" the quick brown fox | /echo |
// swaps words using a slash command on each match |

/re-exec

• [find:string]
  the regular expression (/pattern/flags)
• [first=true|false]? = false
  (optional) return only the first match instead of a list
• (string)?
  (optional) the value to execute the regex on

Searches the provided value with the regular expression and returns a list of all matches.

Examples

/re-exec find=/\b(?\w+?(o+)\w+?)\b/g The quick brown fox jumps over the lazy fool dog. |
/json-pretty |
/comment ```{{newline}}{{pipe}}{{newline}}``` |

/re-exec first= find=/\b(?\w+?(o+)\w+?)\b/g The quick brown fox jumps over the lazy fool dog. |
/json-pretty |
/comment ```{{newline}}{{pipe}}{{newline}}``` |

Accessing & Manipulating Structured Data

/getat

• [index:string|number|list]
  the index, field name, or list of indices/field names to retrieve
• (string)?
  (optional) the value to retrieve from (if not using a variable)

Retrieves an item from a list or a property from a dictionary.

Examples

/setvar key=x {
    "a": [
        1,
        2,
        {
            "b": "foo",
            "c": "bar"
        }
    ],
    "d": "D"
} |
/getat var=x index=d |
// returns "D" |

/return {
    "a": [
        1,
        2,
        {
            "b": "foo",
            "c": "bar"
        }
    ],
    "d": "D"
} |
/getat index=["a", 2, "b"] |
// returns "foo" |

/return {
    "a": [
        1,
        2,
        {
            "b": "foo",
            "c": "bar"
        }
    ],
    "d": "D"
} |
/getat index=a |
/getat index=2 |
/getat index=c |
// returns "bar" |

/setat

• [index:string|list]
  the index or key to set the value at
• [value:list|dictionary]?
  (optional) the value to update
• (string)
  the value to set

Sets an item in a list or a property in a dictionary.

Examples

/setat value=[1,2,3] index=1 X |
// returns [1,"X",3] |

/setat value={{var::myVariable}} index=[1,2,"someProperty"] foobar |
// sets the value of myVariable[1][2].someProperty to "foobar" (the variable will be updated and the resulting value of myVariable will be returned) |

Exception Handling

/try

• (closure|subcommand)
  the command to try

Attempts to execute the provided command and catches any exceptions thrown. Use with /catch.

Examples

/try {: /var x :} |
/catch {: /echo An error occurred: {{exception}} :} |

/catch

• (closure|subcommand)
  the command to execute if an exception occurred

Used with the /try command to handle exceptions. Use {{exception}} or {{error}} to get the exception's message.

Examples

/try {: /var x :} |
/catch {: /echo An error occurred: {{exception}} :} |

Null Handling

/ifempty

• [value:string]
  the value to check
• (string)
  the fallback value

Returns the fallback value if value is empty (empty string, empty list, empty dictionary).

Examples

/ifempty value=[] [1,2,3] |
// returns [1, 2, 3] |

/setvar key=x |
/setvar key=y bar |
/ifempty value={{getvar::x}} foo |
/setvar key=xx {{pipe}} |
/ifempty value={{getvar::y}} foo |
/setvar key=yy {{pipe}} |
// sets xx to "foo" and yy to "bar" |

/ifnullish

• [value:string]
  the value to check
• (string)
  the fallback value

Returns the fallback value if value is nullish (empty string).

Examples

/ifnullish value=[] [1,2,3] |
// returns [] |

/setvar key=x |
/setvar key=y bar |
/ifnullish value={{getvar::x}} foo |
/setvar key=xx {{pipe}} |
/ifnullish value={{getvar::y}} foo |
/setvar key=yy {{pipe}} |
// sets xx to "foo" and yy to "bar" |

Copy & Download

/copy

• (string)
  the value to copy

Copies value into clipboard.

Examples

/copy this text is now in your clipboard |

/copy {{lastMessage}} |
// puts the last chat message in your clipboard |

/download

• [name:string]? = SillyTavern-2024-11-06T15:46:46.129Z
  (optional) the filename for the downloaded file
• [ext:string]? = txt
  (optional) the file extension for the downloaded file
• (string)
  the value to download as a text file

Downloads value as a text file.

Examples

/download Let's download this text. |
// downloads a txt file containing "Let's download this text." |

/download name=TheLastMessage ext=md {{lastMessage}} |
// downloads a file TheLastMessage.md containing the last chat message |

DOM Interaction

/dom

• [quiet=true|false]? = false
  (optional) true: don't show warnings
• [multi=true|false]? = false
  (optional) true: target all matching elements; false: target first matching element
• [target:number]?
  (optional) target the n-th matching element if multi=true (zero-based)
• [action=click|value|property|attribute|call]
  the action to perform
• [value:string]?
  (optional) new value to set (for action=value or action=property or action=attribute)
• [property:string]?
  (optional) property name to get/set/call (for action=property or action=call)
• [attribute:string]?
  (optional) attribute name to get/set (for action=attribute)
• (string)
  CSS selector to target an element

Click on an element, change its value, retrieve a property, or retrieve an attribute. To select the targeted element, use CSS selectors.

Examples

/dom action=click #expandMessageActions |

/dom action=value value=0 #avatar_style |

Characters

/char-get

• [index:string]?
  (optional) the field to retrieve
• (string)? = current character
  (optional) character avatar (filename) or name

Get a character object or one of its properties.

Examples

/char-get Seraphina |
/getat index=description |
/echo |

/char-get index=description Seraphina |
/echo |

Group Chats

/memberpos

• (string)
  name of the group member
• (number)
  new position index for the member

Move group member to position (index starts with 0).

Examples

/memberpos Alice 3 |
/echo Alice has been moved to position 3 |

/group-get

• [index:string]?
  (optional) the field to retrieve
• [chars=true|false]? = false
  (optional) resolve characters
• (string)? = current group
  (optional) group name

Get a group object or one of its properties.

Examples

/group-get MyGroup |
/getat index=description |
/echo |

/group-get index=description MyGroup |
/echo |

/group-get index=members chars=true MyGroup |
/echo |

Conditionals - switch

/switch

• (string|number)
  the value to use as the switch value

Use with /case to conditionally execute commands based on a value.

Examples

/let x foo |
/switch {{var::x}} |
    /case 1 {: /echo value is one :} |
    /case foo {: /echo value is foo :} |
    /case bar {: /echo value is bar :} |
    /case {: /echo value is something else :} |
// returns "value is foo" |

/case

• (string|number)
  the value to compare against the switch value
• (closure|subcommand)
  the command to execute if the value matches the switch value

Execute a command if the provided value matches the switch value from /switch.

Examples

// see /switch |

Conditionals - if

/ife

• ...[expression variables:bool|closure|dictionary|list|number|string]?
  (optional) named arguments assigned to scoped variables to be used in the expression
• ...(string|closure)
  the expression or closure to evaluate, followed by the closure to execute if true

Execute a closure if the expression or first closure returns true.

Use with /elseif and /else.

See /lalib? expressions for more details on expressions.

Examples

/setvar key=x foo |
/ife (x == 1) {:
    /echo value is one
:} |
/elseif (x == 'foo') {:
    /echo value is foo
:} |
/elseif (x == 'bar') {:
    /echo value is bar
:} |
/else {:
    /echo value is something else
:} |

/genraw say either foo or bar |
/ife result={{pipe}} ('foo' in result) {:
    /echo said "foo" |
:} |
/else {:
    /echo did not say "foo" |
:} |
// use named arguments to provide variables to the expression |

/elseif

• ...[expression variables:bool|closure|dictionary|list|number|string]?
  (optional) named arguments assigned to scoped variables to be used in the expression
• ...(string|closure)
  the expression or closure to evaluate, followed by the closure to execute if true

Execute a closure if none of the preceeding /ife and /elseif executed and the expression or first closure returns true.

Use with /ife and /else.

See /lalib? expressions for more details on expressions.

Examples

/setvar key=x foo |
/ife (x == 1) {:
    /echo value is one
:} |
/elseif (x == 'foo') {:
    /echo value is foo
:} |
/elseif (x == 'bar') {:
    /echo value is bar
:} |
/else {:
    /echo value is something else
:} |

/else

• (closure|subcommand)
  the command to execute

Execute a closure if none of the preceeding /ife and /elseif executed.

Use with /ife and /elseif.

See /lalib? expressions for more details on expressions.

Examples

/setvar key=x foo |
/ife (x == 1) {:
    /echo value is one
:} |
/elseif (x == 'foo') {:
    /echo value is foo
:} |
/elseif (x == 'bar') {:
    /echo value is bar
:} |
/else {:
    /echo value is something else
:} |

/then

• (closure|subcommand)
  the command to execute

DEPRECATED

Examples

// DEPRECATED |

World Info

/wi-list-books

• [source=true|false]? = false
  (optional) whether to include the activation source for each book

Get a list of currently active World Info books. Use source= to get a dictionary of lists where the keys are the activation sources.

Examples

/wi-list-books |
// returns a list of active books |

/wi-list-books source= |
/json-pretty |
/comment Currently active WI books:{{newline}}```json{{newline}}{{pipe}}{{newline}}``` |

/wi-list-entries

• [flat=true|false]? = false
  (optional) whether to list all entries in a flat list
• (string)?
  (optional) the name of the book to list entries from

Get a list of World Info entries from currently active books or from the book with the provided name. Use flat= to list all entries in a flat list instead of a dictionary with entries per book.

Examples

/wi-list-entries |
/map {{pipe}} {:
    /getat index=entries {{var::item}} |
    /map {{pipe}} {:
        /getat index=comment {{var::item}}
    :}
:} |
/echo Overview of WI entries in currently active books: {{pipe}} |

/wi-activate

Activate World Info entries based on the current chat and trigger their Automation IDs.

Examples

/wi-activate |

Costumes / Sprites

/costumes

• [recurse=true|false]? = true
  (optional) whether to recurse into subfolders (SillyTavern can only load expressions from the first subfolder level)
• (string)?
  (optional) the folder to list costumes from

Get a list of costume / sprite folders, recursive by default.

Examples

/costumes Alice |
/echo Alice's costumes: {{pipe}} |

Quick Replies

/qr-edit

• [set:string]?
  (optional) the name of the quick reply set
• [label:string]?
  (optional) the label of the quick reply
• (string)?
  (optional) the label of the quick reply

Show the Quick Reply editor. If no QR set is provided, tries to find a QR in one of the active sets.

Examples

/qr-edit My QR From An Active Set |

/qr-edit set=MyQrSet label=MyQr |

/qr-add

• [set:string]?
  (optional) the name of the quick reply set
• [label:string]?
  (optional) the label of the quick reply
• (string)?
  (optional) the label of the quick reply

Create a new Quick Reply and open its editor. If no QR set is provided, tries to find a QR in one of the active sets.

Examples

/qr-add New QR In Active Set |

/qr-add set=MyQrSet label=MyNewQr |

Chat Messages

/swipes-get

• [message:number]?
  (optional) the message ID to get swipes from
• (number)
  the index of the swipe to get

Get the n-th swipe (zero-based index) from the last message or the message with the given message ID.

Examples

/swipes-get 5 |
/echo Swipe number five: {{pipe}} |

/sub {{lastMessageId}} 2 |
/swipes-get message={{pipe}} 5 |
/echo swipe number five: {{pipe}} |

/swipes-get

• [message:number]?
  (optional) the message ID to get swipes from
• (number)
  the index of the swipe to get

Get the n-th swipe (zero-based index) from the last message or the message with the given message ID.

Examples

/swipes-get 5 |
/echo Swipe number five: {{pipe}} |

/sub {{lastMessageId}} 2 |
/swipes-get message={{pipe}} 5 |
/echo swipe number five: {{pipe}} |

/swipes-list

• [message:number]?
  (optional) the message ID to get swipes from

Get a list of all swipes from the last message or the message with the given message ID.

Examples

/swipes-list |
/echo |

/sub {{lastMessageId}} 2 |
/swipes-list message={{pipe}} |
/echo |

/swipes-count

• [message:number]?
  (optional) the message ID to get swipes from

Get the number of all swipes from the last message or the message with the given message ID.

Examples

/swipes-count |
/echo |

/sub {{lastMessageId}} 2 |
/swipes-count message={{pipe}} |
/echo |

/swipes-index

• [message:number]?
  (optional) the message ID to get the swipe index from

Get the current swipe index from the last message or the message with the given message ID.

Examples

/swipes-index |
/echo |

/sub {{lastMessageId}} 2 |
/swipes-index message={{pipe}} |
/echo |

/swipes-add

• [message:number]?
  (optional) the ID of the message to add the swipe to
• (string)
  the text to add as a new swipe

Add a new swipe to the last message or the message with the provided messageId.

Examples

/sendas name=Alice foo |
/delay 1000 |
/swipes-add bar |
// creates a new message "foo", then addes a swipe "bar" |

/swipes-del

• [message:number]?
  (optional) the id of the message to delete the swipe from
• [filter:string|closure]?
  (optional) expression or closure accepting a swipe dictionary as argument returning true or false
• (number)?
  (optional) the index of the swipe to delete (0-based)

Delete the current swipe or the swipe at the specified index (0-based).

Use filter={: swipe= /return true :} to remove multiple swipes.

See /lalib? expressions for more details on expressions.

Examples

/swipes-del |
// delete current swipe of last message |

/swipes-del 5 |
// delete swipe number 5 (0-based index) of last message |

/swipes-del message=20 |
// delete current swipe of message #20 |

/swipes-del filter="swipe.index % 2" |
// delete all odd swipes (0-based index) of last message |

/swipes-del filter="swipe.index != 5" |
// delete all but swipe at idnex 5 (0-based index) of last message |

/swipes-del filter="'bad word' in swipe.mes" |
// delete all swipes with "bad word" in their message text of last message |

/swipes-del filter={: swipe=
    /var key=swipe index=mes |
    /test left={{pipe}} rule=in right="bad word" |
:} |
// delete all swipes with "bad word" in their message text of last message |

/swipes-go

• [message:number]?
  (optional) the message ID to go to the swipe for
• (number)
  the index of the swipe to go to

Go to the swipe. 0-based index.

Examples

/sendas name=Alice foo |
/delay 1000 |
/swipes-add bar |
/delay 1000 |
/swipes-add foobar |
/delay 1000 |
/swipes-go 0 |

/swipes-swipe

Trigger a new swipe on the last message.

Examples

/swipes-swipe |
/echo swiping has finished |

/message-edit

• [message:number]?
  (optional) the message ID to edit
• [append=true|false]? = false
  (optional) whether to append the new text to the end of the message
• (string)
  the new text for the message

Edit the current message or the message at the provided message ID. Use append= to add the provided text at the end of the message. Use {{space}} to add space at the beginning of the text.

Examples

/sendas name=Alice foo |
/delay 1000 |
/message-edit bar |
// adds a new message "foo" then changes it to "bar" |

/sendas name=Alice foo |
/delay 1000 |
/message-edit append= bar |
// adds a new message "foo" then changes it to "foobar" |

/message-move

• [from:number]
  the message ID to move
• [to:number]?
  (optional) where to move the message
• [up:number]?
  (optional) number of slots to move the message up (decrease message ID)
• [down:number]?
  (optional) number of slots to move the message down (increase message ID)

Move a message up or down in the chat.

Examples

/message-move from={{lastMessageId}} to=10 |/message-move from={{lastMessageId}} up=2 |/message-move from=3 down=10 |

Chat Management

/chat-list

• [char:string]? = current char
  (optional) avatar name of the char

Get a list of all chats of the current or provided character.

Examples

/chat-list |/chat-list char=default_Seraphina.png |

/chat-parent

returns the name of the parent chat

Examples

/chat-parent |
// returns name of the parent chat (if this is a branch) |

/message-on

• [event:string]
  event type to listen for
• [callback:closure]
  closure to run when triggered
• [quiet=true|false]? = true
  (optional) whether to show toast messages when event listeners are attached
• (string)
  CSS selector to target an element in the last message

Add event listeners to the last chat message.

Stops listening when changing to another chat.

Examples

/message-on event=click quiet=false callback={:
    /$ take=textContent {{target}} |
    /let prompt Continue by weaving the following suggestion into your next response: {{pipe}} |
    /inputhistory-add {{var::prompt}} |
    /send {{var::prompt}} |
    /trigger
:} .custom-suggestion |
/setvar key=listenerId |

/message-off

• [id:string]?
  (optional) listener ID
• [event:string]?
  (optional) event type to listen for
• [query:string]?
  (optional) CSS selector to target an element in the last message
• [quiet=true|false]? = true
  (optional) whether to show toast messages when event listeners are attached

Remove an event listener added with /message-on.

Examples

/message-off id={{getvar::listenerId}} |
// All messages: |

/message-listeners

Lists all currently active listeners.

Examples

/message-listeners |

/role-swap

• (number|range)?
  (optional) message id or range to swap

Swap roles (user/AI) for all messages in the chat, or for a selected message or range of messages.

Examples

/role-swap |
// All messages: |

/role-swap {{lastMessageId}} |
// Last message: |

/role-swap -1 |
// Last message: |

/role-swap -2 |
// Second to last message: |

/role-swap 0-10 |
// First 10 messages: |

/role-swap -10- |
// Last 10 messages: |

/role-swap 0--10 |
// All messages except last 10: |

Time & Date

/timestamp

Returns the number of milliseconds midnight at the beginning of January 1, 1970, UTC.

Examples

/timestamp |

Async

/fireandforget

• (closure|subcommand)
  the closure or command to execute

Execute a closure or command without waiting for it to finish.

Examples

/fireandforget {:
    /delay 1000 |
    /echo firing |
    /delay 1000 |
    /echo fired script is done
:} |
/echo main script is done |
// will show "main script is done", then "firing", then "fired script is done" |

Logging

/console-log

• (string)
  the value to log

logs a value to the browser console

Examples

/console-log Hello, World! |

/console-warn

• (string)
  the value to log

logs a value to the browser console as a warning

Examples

/console-warn This is a warning! |

/console-error

• (string)
  the value to log

logs a value to the browser console as an error

Examples

/console-error OOPS! |

Audio

/sfx

• [volume:number]? = 1.0
  (optional) playback volume
• [await=true|false]? = false
  (optional) whether to wait for the sound to finish playing before continuing
• (string)
  url to audio file

Plays an audio file.

Examples

/sfx volume=1.5 await=true /user/audio/mySound.wav | /echo finished playing sound |

Miscellaneous

/fonts

returns a list of all system fonts available to you

Examples

/fonts |
/comment |

Web Requests

/fetch

• (string)
  the url to fetch

Fetch the contents of the provided URL.

Examples

/fetch http://example.com |
/echo |

/$

• [query:string]?
  (optional) css selector to query the provided html
• [take:string]? = outerHTML
  (optional) property to take from the resulting element
• [call:string]?
  (optional) method to call on the resulting element
• (string)
  the html to operate on

Retrieve the first matching element from the provided HTML or call a method on the first matching element and return the resulting HTML.

Examples

/fetch http://example.com |
/$ query=h1 take=textContent |
/echo |

/$$

• [query:string]?
  (optional) css selector to query the provided html
• [take:string]? = outerHTML
  (optional) property to take from the resulting elements
• [call:string]?
  (optional) method to call on the resulting elements
• (string)
  the html to operate on

Retrieve all matching elements from the provided HTML or call a method on all matching elements and return the resulting HTML.

Examples

/fetch http://example.com |
/$$ query=h1 take=textContent |
/echo |