Basics

Text and Math

Text helpers format usernames, command names, and response text before Kicklet sends it to chat. Number expressions are useful when a command reads points, counters, or arguments and then calculates a result.

Engine v2

Use text.upper(value) and text.lower(value) for simple case changes. They convert the input to text first, so they are safe for usernames, arguments, and helper results.

Uppercase text

Converts a value to uppercase text.

UppercaseAdvanced Script

const shouted = text.upper("hello, world!");
async.messages.send(`You shouted: ${shouted}.`);

API reference

text.upper

text.upper(value)

Input

value

stringnumberbooleanobject

Value to convert to text.

Output

string

Uppercase text.

Lowercase text

Converts a value to lowercase text.

LowercaseAdvanced Script

const whispered = text.lower("I LOVE CHOCOLATE");
async.messages.send(`You whispered: ${whispered}.`);

API reference

text.lower

text.lower(value)

Input

value

stringnumberbooleanobject

Value to convert to text.

Output

string

Lowercase text.

Truncate text

Shortens text to a maximum length and appends a suffix when it was cut.

Truncate textAdvanced Script

const title = "This is a very long stream title that should be shortened";
const shortTitle = text.truncate(title, 28);
async.messages.send(`Title: ${shortTitle}`);

API reference

text.truncate

text.truncate(value, maxLength, suffix?)

Input

value

any

Value to convert to text.

maxLength

number

Maximum output length.

suffixoptional

string

Suffix for shortened text. Defaults to ....

Output

string

Shortened text.

Clean whitespace

Trims text and collapses repeated whitespace to a single space.

Clean whitespaceAdvanced Script

const messyText = "  hello    chat\n\nwelcome   back  ";
const query = text.clean(messyText);
async.messages.send(`Clean text: ${query}`);

API reference

text.clean

text.clean(value)

Input

value

any

Value to clean.

Output

string

Cleaned text.

Plural word

Returns the singular word for count 1 and a plural word otherwise. Pass plural for irregular words that are not covered by the built-in English rules.

Plural wordAdvanced Script

const count = 2;
async.messages.send(`${count} ${text.plural(count, "child")}`);

API reference

text.plural

text.plural(count, singular, plural?)

Input

count

number

Amount to check.

singular

string

Word for one item.

pluraloptional

string

Explicit word for multiple items.

Output

string

Singular or plural word.

Compact number

Formats large numbers with K, M, or B suffixes.

Compact numberAdvanced Script

const followers = channel.followers();
async.messages.send(`Followers: ${text.compactNumber(followers)}`);

API reference

text.compactNumber

text.compactNumber(value)

Input

value

number

Number to format.

Output

string

Compact number text.

Replace Text

Replaces every occurrence of one text fragment with another.

Replaces every occurrence of a text fragment. This is useful for cleanup before showing user input back in chat.

Replace TextAdvanced Script

const cleaned = text.replace("hello-world", "-", " ");
async.messages.send(`Clean text: ${cleaned}`);

API reference

text.replace

text.replace(value, oldValue, newValue)

Input

value

any

Value to convert to text before replacing.

oldValue

string

Text fragment to replace.

newValue

string

Replacement text.

Output

string

Text with all replacements applied.

Remove prefix

Removes a prefix from text when it is present.

Remove prefixAdvanced Script

const commandName = text.removePrefix("!discord", "!");
async.messages.send(`Command: ${commandName}`);

API reference

text.removePrefix

text.removePrefix(value, prefix)

Input

value

any

Value to convert to text.

prefix

string

Prefix to remove.

Output

string

Text without the prefix, or the original text when it did not start with the prefix.

Command Name

Removes a leading exclamation mark from a command name.

Removes a leading ! from a command name before displaying it. This is useful when listing commands or building responses from command settings.

Command NameAdvanced Script

const name = command.name("!discord");
async.messages.send(`Command: ${name}`);

API reference

command.name

command.name(value)

Input

value

string

Command name with or without a leading !.

Output

string

Command name without the leading !.

Add and Sum

Use + to add numbers. Use parentheses when the result is part of a larger calculation.

Add and SumAdvanced Script

const added = 10 + 2;
const summed = 10 + 2 + 3 + 4;

async.messages.send(`Adding 2 to 10 gives ${added}.
Summing 10, 2, 3, and 4 gives ${summed}.`);

Subtract

SubtractAdvanced Script

const result = 10 - 2;
async.messages.send(`Subtracting 2 from 10 gives ${result}.`);

Multiply

MultiplyAdvanced Script

const result = 10 * 2.1;
async.messages.send(`Multiplying 10 by 2.1 gives ${result}.`);

Divide

DivideAdvanced Script

const result = 10 / 2;
async.messages.send(`Dividing 10 by 2 gives ${result}.`);

Modulo

Modulo returns the remainder after division. This is useful for even/odd checks, counters, and rotation logic.

ModuloAdvanced Script

const result = 10 % 3;
async.messages.send(`The remainder of 10 divided by 3 is ${result}.`);

Absolute Value

Use Math.abs(value) when a number should always be positive.

Absolute ValueAdvanced Script

const distance = Math.abs(-15);
async.messages.send(`Distance from zero: ${distance}.`);

Parse an Integer

Use parseInt(value, 10) before integer math when a number is stored as text.

Parse an IntegerAdvanced Script

const count = parseInt("42", 10);
const result = count + 5;
async.messages.send(`Adding 5 gives ${result}.`);

Parse a Float

Use parseFloat(value) for decimal numbers.

Parse a FloatAdvanced Script

const price = parseFloat("3.14");
const result = price * 2;
async.messages.send(`Double price: ${result}.`);

Check Numbers

Use JavaScript number checks before trusting text as a number.

Check NumbersAdvanced Script

const value = Number("12.7");
if (Number.isInteger(value)) {
  async.messages.send("That is an integer.");
} else if (Number.isFinite(value)) {
  async.messages.send("That is a number with decimals.");
} else {
  async.messages.send("That is not a number.");
}

Engine v1

Use upper and lower for case changes, replace for text replacement, and fmtCmd when a command should be displayed without a leading !.

Use number helpers when a value arrives as text. isInt checks whether a string can be parsed as an integer, and parseInt converts it. Arithmetic helpers such as sum, sub, mul, and div are useful in Go templates because normal JavaScript operators are not available in template expressions.

Uppercase

Returns text in uppercase.

You shouted: {{upper "hello, world!"}}.

JavaScript equivalent:

"hello, world!".toUpperCase();

Lowercase

Returns text in lowercase.

You whispered: {{lower "I LOVE CHOCOLATE"}}.

JavaScript equivalent:

"I LOVE CHOCOLATE".toLowerCase();

Replace Text

Replaces text. The last argument controls how many replacements are made; use -1 to replace all occurrences.

Clean text: {{replace "hello-world-world" "-" " " -1}}
First only: {{replace "hello-world-world" "-" " " 1}}

Command Name

Removes one leading ! from a command before displaying it.

Command: {{fmtCmd "!discord"}}

Add

Adds one number to another.

{{$number := 10}}
Adding 2 to {{$number}} gives {{add $number 2}}.

Sum

Adds multiple numbers together.

{{$number := 10}}
Summing {{$number}} with 2, 3, and 4 gives {{sum $number 2 3 4}}.

Subtract

Subtracts one number from another.

{{$number := 10}}
Subtracting 2 from {{$number}} gives {{sub $number 2}}.

Multiply

Multiplies two numbers.

{{$number := 10}}
Multiplying {{$number}} by 2.1 gives {{mul $number 2.1}}.

Divide

Divides one number by another.

{{$number := 10}}
Dividing {{$number}} by 2 gives {{div $number 2}}.

Modulo

Returns the remainder after division. mod expects integers.

{{$number := 10}}
The remainder of {{$number}} divided by 3 is {{mod $number 3}}.

Absolute Value

Returns a positive version of the number.

Distance from zero: {{abs -15}}.

Parse an Integer

Converts text to an integer before math or comparisons.

{{$str := "42"}}
{{$intVal := parseInt $str}}
Parsed integer: {{$intVal}}
Adding 5 gives {{add $intVal 5}}.

Parse a Float

Converts text to a decimal number.

{{$str := "3.14"}}
{{$floatVal := parseFloat $str}}
Parsed float: {{$floatVal}}
Double value: {{mul $floatVal 2}}.

Check Numbers

Checks whether text can be parsed as an integer or float.

{{$strInt := "12"}}
Is integer: {{isInt $strInt}}

{{$strFloat := "12.7"}}
Is float: {{isFloat $strFloat}}

Random Values

Random helpers are useful for dice rolls, roulette commands, random viewer selection, and response variety.

Engine v2

Random integer

Returns a random integer between min and max.

Random integerAdvanced Script

const roll = random.int(1, 100);
async.messages.send(`Roll: ${roll}`);

API reference

random.int

random.int(min, max)

Input

min

number

Lowest possible integer.

max

number

Highest possible integer.

Output

number

Random whole number in the inclusive range.

Random item

Returns a random item from an array with equal chance for every item.

Random itemAdvanced Script

const color = random.item(["red", "blue", "green"]);
async.messages.send(`Color: ${color}`);

API reference

random.item

random.item(items)

Input

items

T[]

Array of possible values.

Output

Tnull

One item from the array, or null when the array is empty.

Weighted random item

Returns an entry value selected by weight.

Weighted random itemAdvanced Script

const result = random.weighted([
  { value: "win", weight: 1 },
  { value: "lose", weight: 9 },
]);
async.messages.send(`Result: ${result}`);

API reference

random.weighted

random.weighted(entries)

Input

entries

WeightedEntry<T>[]

Weighted entries. Larger weights are picked more often.

value

T

Value returned when this entry is selected.

weight

number

Relative selection weight. Larger numbers are more likely.

Output

Tnull

Selected entry value, or null when no entry can be selected.

Random chance

Returns true with the given percentage chance.

Random chanceAdvanced Script

if (random.chance(10)) {
  async.messages.send("Lucky roll!");
} else {
  async.messages.send("Try again.");
}

API reference

random.chance

random.chance(percent)

Input

percent

number

Chance from 0 to 100.

Output

boolean

Whether the chance roll succeeded.

Shuffle array

Returns a shuffled copy of an array without modifying the original.

Shuffle optionsAdvanced Script

const order = random.shuffle(["red", "blue", "green"]);
async.messages.send(`Order: ${order.join(", ")}`);

API reference

random.shuffle

random.shuffle(items)

Input

items

T[]

Items to shuffle.

Output

T[]

Shuffled copy.

Weighted random item alias

Alias for random.weighted(entries).

API reference

random.pickWeighted

random.pickWeighted(entries)

Input

entries

WeightedEntry<T>[]

Weighted entries. Larger weights are picked more often.

value

T

Value returned when this entry is selected.

weight

number

Relative selection weight. Larger numbers are more likely.

Output

Tnull

Selected entry value, or null when no entry can be selected.

Engine v1

Template examples:

Use rand min max for dice rolls, cooldown variation, or any command that needs one whole number in a range. The example returns a number from 1 to 100.

Roll: {{rand 1 100}}

Use randItem when every option should have the same chance. The example picks one color from the provided values.

Color: {{randItem "red" "blue" "green"}}

Use randItemPercentage when some outcomes should be more likely than others. The helper receives alternating value and odds pairs. In the example, lose is nine times as likely as win.

Result: {{randItemPercentage "win" 10 "lose" 90}}

Advanced Script example:

<template>
Random roll: {{script.Var "roll"}}
</template>

<script>
let roll = Math.floor(Math.random() * 100) + 1;
</script>