Macro Reference Guide

The official macro reference guide for the TableTop Macro Language.

Table of Contents

Commands

TTML provides comamnds to execute, modify, and automate tabletop role-playing scenarios.

Command Usage Description
Case !case Executes a command based on input.
Exit !exit Stops execution of a macro.
Hidden Roll !hroll, !hr <command> Roll dice without displaying the output.
Input !input, !i <message> Prompt for user input.
Prompt !prompt, !p <message> <options> Prompt a list of options.
Roll !roll, !r <command> Roll dice.
Say !say, !s <from> <message> Send a message.
Target !target, !t <message> Prompt to select a token.
Template !template <name> <data> Output a custom chat template.
Test !test <boolean> Toggle “testmode”
Whisper !whisper, !w <to> <message> Send a message privately.
Whisper Roll !wroll, !wr <to> <command> Roll dice as a private message.

Example

The below example heals a token +1 each time a successful heal check is rolled otherwise it subtracts 1 from the token’s health.

#heal
!say "I cast a bad healing spell" !roll 1d20 >> ${1} >= 15 ? @me.hp = @me.hp + 1 : @me.hp = @me.hp - 1

Let’s break down that example:

#heal

All macros start with a # and some unique identifying name. Any code following can be referenced and executed from the chat console or other macros.

!say "I cast a bad healing spell"

There are many commands you can run in TTML, one of them is the !say command which outputs a message to everyone.

!roll 1d20

Here we define our next step. Notice how there was nothing for us to do but simply write it. We use the !roll command to roll a single d20 die.

>>

Here, we are saving the result from the previous roll command to be used in a later step. We can save or ignore step results with TTML.

${1} >= 15

Here ${1}, a special type in TTML known as VariableReserved, refers to the value of the previous roll. We compare the value and check if it’s greater than or equal to 15. You can use any standard comparative operation.

?

The ? at the begining here denotes that we have a true/false statement to make. Based on the outcome of the true/false statement we setup, we can define two different results to run.

If the roll we just made is greater than or equal to 15, we will execute the next statement that is between the ? and before the :. Otherwise, if the roll is less than 15, we will execute only the section beyond the :.

@me.hp = @me.hp + 1

When we are successful, we are going to modify HP by updating our token attribute. We tell the command to use our token using the reserved token variable @me and add one (1) to our hp by using @me.hp = @me.hp + 1.

@me.hp = @me.hp + 1

In the case that the roll was below 15, we would run the same command but subtract one from our health instead.

Now that we’ve seen an example, let’s dive into the details of each TTML command.

Case

The !case command takes an input and executes a given statement based on that input. You can think of this like a Prompt command that fires immediately.

Syntax

!case, !c <input> [<option>[, <optionN>]]
Argument Type Description
input Any* The input to compare
option Option An option to present

Example

!hroll 1d3 >> !case ${0} [1:"I have flaw 1", 2:"I have flaw 2", 3:"I have flaw 3"] >> @{me}.flaws += ${0}

Exit

The !exit command stops the execution of a macro, useful for debugging.

Syntax

!exit

Example

!roll 1d20
!say "I'm not sure what goes wrong after this"
!exit
!roll 1d8

Hidden Roll

Roll dice without showing the output. See Roll for additional syntax.

Syntax

!hroll, !hr <command>

Example

!hroll 1d[0,1] >> !case ${0} ["I am happy", "I am sad"] >> !say @{me} ${0}

Input

The !input command allows you to stop execution of the program and prompt the user for additional input.

Syntax

!input, !i <message>
Argument Type Description
message String The message to display to the user

Example

!input "Choose an attack multiplier"

!input 'Enter an amount' >> !say "I throw ${1} gold pieces into the air"

!i 'Enter a new alias' >> @me.name = ${1}

Prompt

The !prompt command allows you to select from a list of options. Similar to !input, this will stop the execution of the program and wait for the user to select an option.

Syntax

!prompt, !p <message> [<option>]
Argument Type Description
message String The message to display to the user
option Option An option to present

Example

!prompt "Choose a mod" [@me.dexterity_mod, @me.strength_mod]

!prompt 'Choose a number' [42, 16.3, "No, I don't want to"]

!p "Choose an option" [ value:label, 'Can mix and match option types', ${hp} ]

Roll

Roll complicated or simple sets of dice. This uses the Astral Roll API to execute crypto-random rolls.

Syntax

!roll, !r [<as>] <command>
Argument Type Description
as Token (optional) The token to roll as
command Roll The roll command (see below)

Roll Command

Syntax Usage
(number)d(die)[ (flags) [ (comment) ]] 1d20, 2d8k1, 3d6 "Uncanny dodge!", 1d[2,4,6,8]

Die

Die Description
# Specify any number to roll that many-sided die (e.g. d20)
[#, #, ..] Specify custom faces. The roll value is generated from these numbers only (e.g. d[1,5,7])

Flags

Flag Description Syntax
e Exploding dice. Re-roll and add dice >= to a threshold. (dice)rr(threshold) (e.g. !r 2d20e15)
gt Keep die > than a threshold. (dice)gt(threshold) (e.g. !r 3d8gt3)
gte Keep die >= to a threshold. (dice)gte(threshold) (e.g. !r 3d8gte6)
lt Keep die < a threshold. (dice)lt(threshold) (e.g. !r 2d8lt5)
lte Keep die <= to a threshold. (dice)lte(threshold) (e.g. !r 2d8lte4)
kl Keep the lowest # of dice (dice)kl(number) (e.g. !r 2d20kl1)
kh Keep the highest # of dice (dice)kh(number) (e.g. !r 4d8kh2)
max Set the die maximum. (dice)max(threshold) (e.g. !r 1d20max16)
min Set the die minimum. (dice)min(threshold) (e.g. !r 1d8min3)
ro Re-roll dice once above or below a threshold. (dice)ro[comparative](threshold) (e.g. !r 1d8ro2)
rr Re-roll dice forever above or below a threshold. (dice)rr[comparative](threshold) (e.g. !r 1d8rr<2)

Alternative Syntax

Instead of specifying a complete <command>, the roll command can also be given the below arguments for specific types of rolls.

Syntax Usage
adv, advantage Roll advantage
dis, disadvantage Roll disadvantage

Example

Roll advantage.

!roll adv
!r advantage
!r 2d20kh1

Roll disadvantage.

!roll dis
!r disadvantage
!r 2d20kl1

Roll overriding minimum

!roll 1d20min2

Roll 3x d8’s and keep only the top 2.

!roll 3d8kh2

Roll and keep any die above 3

!roll 3d8gt3

Exploding dice.

!roll 3d8e8

Exploding dice with a comment.

!roll 3d8e8 "Going for gold"

Say

Send a message to the room.

Syntax

!say <from> <message>
Argument Type Description
from Token (optional) The token to send the message as
message String The message to send

Example

!say "Hello, everyone!"

!say @npc1 'Hello, everyone!'

!s "Combine ${variables} and messages"

Target

The !target command allows you to select a token while executing a macro. Similar to !input, this will stop the execution of the program and wait for the user to select a token.

Syntax

!target, !t <message>
Argument Type Description
message String The message to display to the user

Example

!target "Select a token to attack" >> !say "Charge!" >> !roll 1d8 >> @target.hp = @target.hp - $1

!t >> @target->some_macro_attack

Template

The !template command allows you to output custom Chat Templates.

Syntax

!template <name> <data>
Argument Type Description
name String The ID/name of the chat template
data JSON Data used to render the chat template

Example

!roll 1d20 >> !roll 1d20 >> !template roll_2 {
	roll1: ${1},
	roll2: ${2},
}

!target "Select an opponent" >> !prompt "Choose attack die" [4:d4, 8:d8, 12:d12] >> !roll 1d${1} >> !template custom_template {
	"target": @{target},
	'roll': ${2},
	attack_die: ${1}
}

Test

Use the !test command to disable or enable chat output, useful for testing new macros.

Syntax

!test <boolean>

Example

!test true
!say "This message and the rolls below will be hidden"
!r 1d20 >> !r 1d${0}
!test false
!say "This is public again"

Whisper

Similar to !say but privately sends a message to a particular token/user.

Syntax

!whisper <to> <message> <from>
Argument Type Description
message String The message to send
to Token The token to send the message to
from Token (optional) The token to send the message as

Example

!whisper @selected "How you doin'"

!target >> !r 1d20 >> !w @target "Hey! I rolled a ${1}"

Whisper Roll

Roll dice as a private message. See Roll for additional syntax.

Syntax

!wroll, !wr <to> <command>

Example

!wroll  @{gm} 1d20[My Secret Initiative]

Functions

Functions are special actions that can fetch data or perform tasks. Special functions can be defined in character sheets but Astral provides a few functions for use inside the macro language.

Syntax

<function_name>{<...arguments>}
Argument Type Description
function_name String Name of the function to run
arguments Any Any number of arguments to pass to the function, pipe (|) separated

Example

@{me}.attacks += get{'5esrd'|'Magic Missle'}

Astral-Provided Functions

Function Name Arguments Description
get String, String Get data from a compendium item such as a spell or item

Comparative Operations

Sometimes, it’s necessary to run macros based on the outcome of a condition such as if a roll is greater than another value. We can accomplish this with Comparative Operations

Syntax

<left> <comparative> <right> ? <success> : <failure>
Argument Type Description
left Any (number only) Number to be compared
comparative Comparative The comparative operation
right Any (number only) Number to be compared
success Any Macro to be run if comparative succeeds
failure Any Macro to be run if comparative fails

Example

#simple-expression
15 > 10 ? !say "This is true" : !say "This is false"

#ignore-failure-case
$foo < 42.5 ? !roll 1d20+${foo} :|

#conditional-assignment
@me.strength_mod >= @me.dexterity_mod ? ${smart_mod} = @me.strength_mod : ${smart_mod} = @me.dexterity_mod

Saving Results

Results from commands run in TTML can be “Saved” or “Ignored”.

Syntax Description
>> Save the result. Can be referenced by calling $#
|, Ignore the result of the command (default)

Sometimes you want to save the result of a command to the input of another command. You can easily accomplish this in TTML with the >> operator. Saving a result means you can then reference that result from any consecutive command by referencing ${#} (where # is a number that represents the index of the saved result we can to fetch.)

You can also use ${0} to grab the most recent saved result.

Sounds complicated, but it’s very easy. Take the below example to roll initiative.

Example

!roll 2d20kh1+@me.dexterity >> @me.initiative = ${1}

Here, we roll a d20 die and add our dexterity modifier to it. We then pass that result to the next command and set our token’s initiative equal to our roll result using ${1} We use ${1} because we want to use the result of the first command we ran.

Let’s look at a slightly more complicated example. In the below example, we roll a 1d8 to determine how many d10s we should roll which we then use to determine how many d20s to roll.

!roll 1d8 >> !roll ${1}d10 >> !roll ${2}d20

In the above code, we save each result and use it in the next command by reference ${1}, ${2} where ${1} is the result of !roll 1d8 and ${2} is the result of !roll ${1}d10.

Let’s look at one more example.

!roll 1d3 >> !case ${0} [1:"Bad", 2:"Good", 3:"Best"]

Here, we use ${0} to grab the last saved result. We could have also used ${1}. If you are nesting macros together, it is generally good-practice to use ${0}.

Using Variables

Variables can be assigned and referenced using a $ followed by any alphanumeric sequence.

When assigning custom variable names, names cannot be strict numbers as the results of commands are referenced using numbers.

Assign Variable

Example:

$dex = @me.dexterity
// or
${str} = @me.strength

Use Variable

Example:

!roll 1d20+$dex

$foo = 2
!roll ${foo}d20+5

Using Tokens

Similar to variables, tokens can be assigned and referenced using the @ operator followed by any alphanumeric sequence. Like variables, token attributes can be created and updated on-the-fly but tokens can not be directly assigned.

Assign Token

Tokens cannot be directly assigned but rather attributes of the token can be updated.

Example:

# Not allowed
@me = 1

# Allowed
@me.strength_mod = 5

Token Attributes

Tokens attributes can be used in almost any command and can be referenced with a ..

Example:

#roll
!roll 1d20+@me.dexterity

#say
!say "Hello," @me.name

Tokens Macros

Tokens can have macros attached to them, meaning it’s possible to write macros that call and execute inline token macros.

Example:

#target
!target >> @target->execute_macro

Reserved Token Variables

If you use Power Virtual TableTop, there are already several reserved tokens for you to use.

These tokens can be accessed (assuming they are available) from any macro within Astral.

Name Description
@me A reference to your token, if available
@selected A reference to the selected token, if available
@target When using the !target command, a reference to the targeted token

Types

Types allow you to define different data for your macros. The following types are supported.

Comparative

>=
>
<=
<
==

Float

7.0

-1.55

593.2020

JSON

JSON data is written like JavaScript and can include quotes, single quotes, or no quotes at all for the keys. JSON data is used to pass data to the !template command.

{
	key: "Value containing string and ${variable}.",
	"key2": 'values can any type',
	'token': @{me},
	attribute1: {
		nested: 42,
		usefulArray: [
			@{npc}.hp,
			@{npc2}.hp
		]
	}
}

Number

1

1000

-52

Option

Options are used in the !case and !prompt commands.

[ option, option2, option3 ]

[ value:label, "Just a label", @token.attribute, $score ]

String

"Double-quoted string"

'Single-quoted string'

OneWord

Token

@me

@test.attribute

@npc->some_macro

@{me}.with_optional_curly_braces

Variable

$score = @me.hp + 100

${message} = "Go forth!"

VariableReserved

These are the results saved from previous macro steps.

$1

${2}
Was this article helpful? Votes: 0
Article details: