Functions

Advanced users have access to various format string functions. These are specified using a dollar sign before the function name and a set of parentheses to enclose arguments (e.g., $PI()). If invalid inputs are given, the convention of these functions is to return the empty string.

Functions can accept an arbitrary number of arguments, which are delimited by spaces. These arguments may be tokens, text, or the results of other functions. Like tokens, functions are case-sensitive.

If a function returns multiple values, it will return them as an at-map. Individual return values can be accessed using the $NthValue(o n) function.

To include a literal space or multiple words in a single argument, text within functions can be enclosed within pairs of backticks (`). A dollar-sign can be used to escape backticks within the enclosed text.

$Set(_token `hello world`)$_token → hello world
$Reverse(`)(`) → ()
$Len(`$``) → 1

Other mods can extend the list of available functions using the API.

$Set(token ...)

This is a special function that can set the value of a token. It sets the value of the token with the name token to $Concat(...) and returns the empty string.

This can be used to redefine existing tokens, or to define entirely new tokens within the string. To avoid collisions with tokens that may be added in the future, however, custom tokens require an underscore prefix.

$Set(_value 2)$_value frog$If($GT($_value 1) s) → 2 frogs

String Functions

$Byte(s i j)

Returns a list of character codes in s, from indices i (default 1) to j (default i).

$Capitalize(s)

Converts the first non-whitespace character in s to its uppercase counterpart.

$Char(...)

Returns a string made up of the characters with the integer character codes passed as arguments.

$Concat(...)

Combines provided arguments into one string.

$Concats(separator ...)

Combines provided arguments into one string, using separator as a separator.

$Contains(this other)

Returns true if this contains other. Otherwise, returns the empty string.

$EndsWith(this other)

Returns true if this ends with other. Otherwise, returns the empty string.

$EscapeRichText(...)

Escapes the input for use in rich text.

$First(s)

Returns the first character of a given string.

$Gsub(s pattern repl n)

Replaces the first n copies of the pattern pattern in s with repl. Returns the result string, the number of matches that occurred, and any match groups that were captured. This behaves similarly to its Lua counterpart.

$Index(s i default)

Returns the character at index i in s, or default if there is no such index.

$Last(s)

Returns the last character of a given string.

$Len(s)

Returns the length of s.

$Lower(s)

Converts given arguments into a lowercase string.

$Match(s pattern init)

Looks for a match of pattern in s starting from init. Returns any captures from the pattern, or the entire match if none are specified. This behaves similarly to its Lua counterpart.

$Punctuate(s punctuation chars)

Adds punctuation to the end of s if it isn’t present.

If punctuation is provided, it will be used as the punctuation (default: .).

If chars is provided, the set of characters considered to be punctuation will be limited to the characters in this string. By default, the characters .,!?:/-~ are used.

$punctuate(hi) → hi.
$punctuate(hello !) → hello! $punctuate("hey" . ".) → "hey"

$Parens(...)

Returns the input wrapped in parentheses.

$Rep(s n)

Returns a string made up of n concatenated copies of s.

Use with caution; large strings can take up a lot of memory.

$Reverse(s)

Reverses the given string.

$StartsWith(this other)

Returns true if this starts with other. Otherwise, returns the empty string.

$Str(...)

Converts given arguments into a single string.

$StripColors(s)

Removes chat colors defined with <RGB> from the given string.

$Sub(s i j)

Returns a substring of s from i (default 1) to j (default #s).

$Trim(s)

Trims the beginning and end of a given string.

$TrimLeft(s)

Trims the beginning of a given string.

$TrimRight(s)

Trims the end of a given string.

$Upper(s)

Converts given arguments into an uppercase string.

Boolean Functions

$All(...)

Returns the last argument if all provided arguments are not the empty string. Otherwise, returns the empty string.

$Any(...)

Returns the first provided argument that’s not the empty string, or the empty string if there are none.

$EQ(this other)

Returns true if this is equivalent to other. Otherwise, returns the empty string.

$GT(this other)

Returns true if this is greater than other. Otherwise, returns the empty string. If both arguments are numbers, they will be compared numerically.

$GTE(this other)

Returns true if this is greater than or equal to other. Otherwise, returns the empty string. If both arguments are numbers, they will be compared numerically.

$If(condition ...)

Returns $concat(...) if condition is anything other than the empty string.

$IfElse(condition yes ...)

Returns yes if condition is anything other than the empty string. Otherwise, returns $Concat(...).

$LT(this other)

Returns true if this is less than other. Otherwise, returns the empty string. If both arguments are numbers, they will be compared numerically.

$LTE(this other)

Returns true if this is less than or equal to other. Otherwise, returns the empty string. If both arguments are numbers, they will be compared numerically.

$NEQ(this other)

Returns true if this is not equivalent to other. Otherwise, returns the empty string.

$Not(value)

Returns true if value is the empty string. Otherwise, returns the empty string.

$Unless(condition ...)

Returns $Concat(...) if condition is the empty string.

Math Functions

The majority of these functions map directly to their Lua counterparts.

$Abs(x)

Returns the absolute value of x.

$Acos(x)

Returns the arc cosine of x (in radians).

$Add(x y)

Returns x + y.

$Asin(x)

Returns the arc sine of x (in radians).

$Atan(x)

Returns the arc tangent of x (in radians).

$Atan2(y x)

Returns the arc tangent of y / x (in radians), but uses the signs of both parameters to find the quadrant of the result.

$Ceil(x)

Returns the smallest integer larger than or equal to x.

$Cos(x)

Returns the cosine of x (assumed to be in radians).

$Cosh(x)

Returns the hyperbolic cosine of x.

$Deg(x)

Returns the angle x (given in radians) in degrees.

$Div(x y)

Returns x / y.

$Exp(x)

Returns the value e^x.

$Floor(x)

Returns the largest integer smaller than or equal to x.

$Fmod(x y)

Returns the remainder of the division of x by y that rounds the quotient towards zero.

$Frexp(x)

Returns m and e such that x = m2^e, e is an integer, and the absolute value of m is in the range [0.5, 1) (or zero when x is zero).

$Int(x)

Returns the value of x converted to an integer.

$IsNan(x)

Returns true if the string value of x is equivalent to the string value of NaN.

$Ldexp(m e)

Returns m2^e (e should be an integer).

$Log(x)

Returns the natural logarithm of x.

$Log10(x)

Returns the base-10 logarithm of x.

$Max(...)

Returns the maximum among its arguments. If all arguments are numeric, they are compared as numbers. Otherwise, they’re compared as strings.

$Min(...)

Returns the minimum among its arguments. If all arguments are numeric, they are compared as numbers. Otherwise, they’re compared as strings.

$Mod(x y)

Returns x % y.

$Modf(x)

Returns two numbers, the integral part of x and the fractional part of x.

$Mul(x y)

Returns x * y.

$Num(x)

Returns the value of x converted to a number.

$PI()

Returns an approximate value of pi.

$Pow(x y)

Returns x ^ y.

$Rad(x)

Returns the angle x (given in degrees) in radians.

$Sin(x)

Returns the sine of x (assumed to be in radians).

$Sinh(x)

Returns the hyperbolic sine of x.

$Subtract(x y)

Returns x - y.

$Sqrt(x)

Returns the square root of x.

$Tan(x)

Returns the tangent of x.

$Tanh(x)

Returns the hyperbolic tangent of x.

At-Map Functions

These functions are related to working with at-maps.

$Concat(o)

Concatenates the values in the at-map.

$Concats(separator o)

Concatenates the values in the at-map, using separator as a separator.

$First(o)

Returns the value of the first entry in the at-map o.

$Get(o key default)

Returns the first value associated with key, or default if there are none.

$Has(o key)

Returns true if the at-map contains the key key. Otherwise, returns the empty string.

$Index(s key default)

Returns a list of entries associated with key, or default if there are none.

$Last(o)

Returns the value of the last entry in the at-map o.

$Len(o)

Returns the number of entries in the at-map.

$List(...)

Creates an at-map with keys from 1 to N, where N is the number of provided arguments. If a single argument is provided and it is an at-map, its values will be used. Otherwise, the list is made up of all provided arguments.

$Map(funcName o ...)

Maps elements of the at-map o onto the function funcName. Additional arguments will be passed to the map function as extra arguments.

$Concat($Map(Upper @(a;b;c))) → ABC

$NthValue(o n)

Returns the value of the nth entry in the at-map o.

$Unique(o)

Returns an at-map with only the unique values in the at-map o.

Random Functions

These functions are related to generating pseudo-random values.

Note

Many format strings are seeded with a constant value, to prevent changes when re-evaluating. To get pseudo-random values for these, use $Randomseed() first.

$Choose(...)

Selects and returns one of the inputs at random. If given a single at-map, returns one of its values.

$Random(m n)

Returns a pseudo-random number in [m, n]. If n is excluded, returns a number up to m. If both are excluded, returns a random float number.

$Randomseed(seed)

Seeds the randomizer with the given value.

Other Functions

$AddTag(tag)

Adds a tag to the tags token. If there is no tags token or it is not an at-map, this does nothing.

$ColorActions(s options)

Wraps actions within s in color tags. Actions are delimited by a quote followed by an asterisk (" *).

This accepts the following options in the form of an at-map:

• colorTargetTag: if this is given, it will be used as the search tag for the stream to copy the color from. By default, this uses the appropriate tag based on existing tags.
• optionalAsterisks: if this is true, actions will begin when any quote is encountered, instead of requiring " *.

$ColorQuotes(s options)

Wraps quoted text within s in color tags.

This accepts the following options in the form of an at-map:

• colorTargetTag: if this is given, it will be used as the search tag for the stream to copy the color from. By default, this uses the appropriate tag based on existing tags.

$Default()

Returns the default content for a format string. If used outside of a valid format string, this returns the empty string.

$DisallowSignedOverRadio(options)

Checks that a message is not being sent with a signed language. Returns the empty string if it is.

Unless suppressError is passed, this also sets the error token to a message that will inform the player that they cannot use a signed language over the radio.

This accepts the following options in the form of an at-map:

• condition: if this is given and is not truthy, the function will return true without checking the language.
• suppressError: if this is truthy, the error token will not be set.

$FormatRadio(frequency)

Returns the default formatting for a radio message prefix.

$Fragmented(text)

Returns a partial quote representing a fragment of what a player character understood. This used for unknown language messages.

$GetText(s ...)

Returns a translation. The first argument must be the translation name. Subsequent arguments may be translation substitutions.

Due to a limitation of the underlying function, only up to 4 additional substitution arguments are allowed. Arguments beyond this limit will be ignored.

$GetTextOrNull(s ...)

Behaves similarly to $GetText(), but returns the empty string for unknown translations instead of the translation name.

Due to a limitation of the underlying function, only up to 4 additional substitution arguments are allowed. Arguments beyond this limit will be ignored.

$HasTag(tag)

Checks whether a tag is present in the tags token.

$IsSigned(language)

Returns true if language is configured as a signed language.

$RemoveTag(tag)

Removes a tag from the tags token. If there is no tags token or it is not an at-map, this does nothing.

$StreamCategory(stream)

Returns 'chat', 'rp', or 'other' based on the type of the given stream. If the stream is unknown, returns the empty string.