• Knowledgebase››
• Adventure Reference Guide

Adventure

When creating a new adventure, there are four primary options to configure:

Nodes

A Node is a "container" for commands and encounters. Nodes represent distinct parts or subdivisions of your adventure. You can choose to make them represent distinct locations, or distinct times at the same location, or whatever makes the most sense for your adventure.

At any given time, there is a single active node for an adventure. This means that all adventurers are always in the same node. The active node defines which commands and encounters are available to the adventurers.

Encounters

An encounter lives inside a node, and represents an event or situation that happens to the adventurers. Adventurers are introduced to the encounter by a post from the Bone Monster, and must then respond to the encounter in order to progress. Typically, an encounter requires some kind of response from all members of the party.

You can think of encounter as a mini-node that adventurers travel to temporarily while it is active. It has its own commands, which become the only commands accessible until the encounter has been resolved. An encounter is resolved once every adventurer has executed one of the encounters' commands. Note that if there are no available encounter commands available to adventurers, the encounter resolves itself immediately.

Some encounters may harm an adventurer. Adventurers who drop to zero HP are rendered unconscious and can no longer execute commands. When an encounter is resolved, adventurers tend to their fallen companions: as long as there is at least one adventurer who is still consious, all unconscious adventurers are brought back to 1 HP. If all adventurers drop to zero HP, the encounter ends immediately and the Defeat Command is executed.

An encounter has a number of attributes that you can set:

Battle Encounters

If you specify an enemy in the Battle field of an encounter, the encounter becomes a Battle Encounter. Battle encounters result in a combat situation, in which adventurers are pitted against the enemy indicated. They do not resolve in the usual way, but require that the enemy be defeated, or that all adventurers successfully flee.

During a battle encounter, adventurers are given several additional commands automatically:

• An unarmed attack command
• An attack command for every weapon they have
• A flee command

Commands

A command lives inside a node or encounter, and represents an adventure-specific "thing" that adventurers can do while in that node. A command has two driving components:

• A list of actions which to be performed by whoever executed the command
• A forum post to be posted in the thread

A command has a number of attribues which you can set:

[
  {
    "action": "increment",
    "variable": "num_encounters",
    "individual": false
  },
  {
    "action": "trigger_encounter",
    "encounter_pool": ""
  }
]

[h1]Account Summary[/h1]
{{player}} now has {{num_coins}} coins!

Most commands are attached to a node, or attached to an encounter within a node. There are three notable exceptions:

• The "Start" Command
  This command is automatically added to new adventure. It is responsible for initial introductory post, and moves the adventure into the first node.
• The "Defeat" Command
  This command is also automatically added to new adventures. It is executed whenever all adventurers in an adventure hit 0 HP. By default it simply revives everyone, but its actions can be customized to include things like moving the party to an Underworld node, or whatever you like.
• Global Commands
  These are an advanced feature, which is hidden by default. Global commands allow you to create commands available to adventurers in any node, or in any encounter.

Actions

Actions are the building-blocks of functionality for commands. String them together in order to construct complex behavior.

Adds an item to the adventurer's inventory.

{
    "action": "acquire_item",
    "item_number": 1
}

Triggers an attack against the player from the current enemy (if any).

{
    "action": "attack_player",
    "attack_index": false
}

Performs an attribute check, and executes a sequence of actions depending on whether the check was successful or not.

{
    "action": "attribute_check",
    "dc": 10,
    "stat": "wis",
    "silent": false,
    "success": [],
    "failure": []
}

Consumes the item being used. Only applicable in Usable Item actions.

{
    "action": "consume_item"
}

Prevents the command from resolving the encounter for the adventurer executing the command.

{
    "action": "continue_encounter"
}

Deals damage to the current enemy (if any).

{
    "action": "damage_enemy",
    "roll": "4d4+4",
    "type": "slashing"
}

Deals damage to the adventurer executing this command.

{
    "action": "damage_player",
    "roll": "4d4+4",
    "type": "slashing"
}

Decrements a variable. If the variable does not exist, it is initialized to -1.

{
    "action": "decrement",
    "variable": "coins",
    "individual": false
}

Ends the adventure. Players can continue to post in the thread, but no more commands will be executed.

{
    "action": "end_adventure"
}

Ends the encounter immediately for all adventurers, instead of waiting for all adventurers to resolve the encounter individually.

{
    "action": "end_encounter",
    "success": false
}

Executes a different command, then resumes the current one where it left off. Use this action with care, there is usually a better way of accomplishing what you're trying to do.

{
    "action": "execute_command",
    "command_number": 1
}

Heals the current enemy (if any).

{
    "action": "heal_enemy",
    "roll": "4d4+4"
}

Heals the adventurer executing this command.

{
    "action": "heal_player",
    "roll": "4d4+4"
}

Evaluates an expression, and executes a sequence of actions depending on whether the expression is true or false.

{
    "action": "if_check",
    "condition": "{var:a} < 2",
    "success": [],
    "failure": []
}

Increments a variable. If the variable does not exist, it is initialized to 1.

{
    "action": "increment",
    "variable": "coins",
    "individual": false
}

Outputs a full forum-post by the Bone Monster. Typically this would be done via a command's Post Text, but this action is useful if you want to conditionally set the text via attribute_check or if_check.

{
    "action": "make_post",
    "text": "[h1]Hello![/h1] ..."
}

Masks a command, making a previously available command unavailable to advenurers.

{
    "action": "mask_command",
    "command_number": 1
}

Removes an item from the adventurer's inventory.

{
    "action": "remove_item",
    "item_number": 1
}

Revives all adventurers and brings them to full HP. This is typically used in the Defeat command.

{
    "action": "revive_all"
}

Decrements an adventurer stat.

{
    "action": "stat_decrement",
    "stat": "str"
}

Increments an adventurer stat.

{
    "action": "stat_increment",
    "stat": "str"
}

Sets the value of an adventurer stat.

{
    "action": "stat_set",
    "stat": "str",
    "value": "{stat:str} + 1"
}

Adds a custom entry to the bulleted list of things that occurred during a command.

{
    "action": "status_message",
    "text": "You are awesome."
}

Triggers a random encounter that has not yet been triggered from the specified encounter pool

{
    "action": "trigger_encounter",
    "encounter_pool": ""
}

Unmasks a command, making a previously unavailable command available to adventurers.

{
    "action": "unmask_command",
    "command_number": 1
}

Sets the value of a variable. If the variable does not exist, it is created.

{
    "action": "var_set",
    "variable": "coins",
    "value": "{var:coins} + 6",
    "individual": false
}

Data-types

In the Actions Section, each field has a specific data-type that has a specific format. These formats are described here.

Dice

Dice play a large role in adventures. The adventure system operates on the same set of dice as Dungeons and Dragons:

• A four-sided die
• A six-sided die
• An eight-sided die
• A twelve-sided die
• A twenty-sided die
• A hundred-sided die

Typically when we refer to a particular die, we call it a "d" followed by the number of sides. That is, we refer to a 6-sided die as a "d6", and a 20-sided die as a "d20". Sometimes, you may want to roll multiple dice, in which we prefix that number in front: rolling two six-sided dice and adding the result together is referred to as rolling "2d6".

The most-commonly rolled die is the d20, because it's what underlies attribute checks and attack rolls. For an attribute check, a d20 is rolled, the adventurer's stat bonus for that particular attribute is added, and the result is checked against the check's Difficulty Class (DC). For an attack roll, a d20 is rolled, the adventurer's strength bonus is added, and the result is checked against the target's Armor Class (AC).

Several actions have fields with a Dice datatype, which require a description of a roll. You can add or subtract up to 50 of any valid dice in a single roll.

Examples

• 2d6 - rolls two six-sided dice and sums the result
• d6 + 2d4 - rolls a six-sided die and two four-sided dice, and sums the result
• 6d6 + 6 - rolls six six-sided dice, sums the result, then adds 6
• 3d12 - d6 + d4 - 3 - rolls three twelve-sided dice and sums the result, then rolls a six-sided die and subtracts the result, rolls a four-sided die and adds it to the result, then subtracts 3.
• 12 - doesn't roll any dice, then adds 12... so... basically just 12

Expressions

An Expression represents some kind of calculation, and evaluates to a number. It supports numeric values, basic arithmetic, comparators, boolean operators, and a few built-in functions.

Logical Operator Note

When evaluating logical operators or when resolving a condition (e.g. in an if_check action or in a Required Condition), evaluating to 0 is equivalent to false or failure, and evaluating to anything else is equivalent to true or success. As such, if you set a required condition of 0 the command will never be available, if you set it to 1 or 7222 or -12 the command will always be available.

Supported arithmetic operators

Supported comparators

Supported boolean operators

Supported functions

To evaluate the "beep" function with arguments "boop" and "bop" in an expression, you would enter {beep:boop:bop}.

Expression Examples

{
    "action": "var_set",
    "variable": "gold_pieces",
    "value": "{var:gold_pieces} + {roll:d6+1}",
    "individual": true
}

{
    "action": "if_check",
    "condition": "{var:num_blessings} >= {var:num_curses} + 2",
    "success": [
        {
            "action": "heal_player",
            "roll": "4d4 + 4"
        },
        {
            "action": "status_message",
            "text": "A good thing happened :)"
        }
    ],
    "failure": [
        {
            "action": "damage_player",
            "roll": "4d4 + 4"
        },
        {
            "action": "status_message",
            "text": "A bad thing happened :("
        }
    ]
}

Items

Adventurers can acquire items to help them in their adventure, or generally to add flavor. Items come in one of four categories:

• Weapon
• Armor
• Usable
• Misc

In addition to any functionality provided by the item itself, items can be interacted with the adventurer by clicking on them in their inventory. All items can be given to another adventurer or discarded (destroying the item).

All items have a number of attribues which you can set:

Weapon Items

Weapon items grant additional attack commands during combat. The details of this command are set in the following weapon options:

Armor Items

Armor makes an adventurer harder to hit by raising the AC against which enemy attack rolls are made. It does not lessen or absorb damage dealt by an attack that does hit. The armor's efficacy is set via the following option:

There is no concept of equipping or unequipping armor. When resolving an attack against an adventurer that has multiple armor items, the highest defense bonus available is used during the calculation. In essence, you can think of the adventurer as wearing all available armor at the same time, but where defense bonuses do not stack.

This means that if the adventurer has a weak armor that provides resistance to fire and a strong armor that provides no resistance, a fire-attack will have to roll against the stronger armor and, if it hits, will still deal only half damage due to the resistance provided by the weaker armor.

Usable Items

Usable items are items which can be used at any time. When an item is used, a sequence of actions (much like a command) is executed. In essence, you can think of a consumable item as containing a mini-use command. If the item is a single-use item (e.g. a health potion), you can include the consume_item action to cause the item to be consumed when the action is processed.

Usable Item Examples

[
  {
    "action": "status_message",
    "text": "A warm feeling fills {{player}} as their wounds begin to close."
  },
  {
    "action": "heal_player",
    "roll": "4d4+4"
  },
  {
    "action": "consume_item"
  }
]

[
  {
    "action": "if_check",
    "condition": "{in_battle}",
    "success": [
      {
        "action": "status_message",
        "text": "{{player}} recites the words on the scroll, and a fireball leaps at your opponent!"
      },
      {
        "action": "damage_enemy",
        "roll": "8d6",
        "type": "fire"
      },
      {
        "action": "consume_item"
      }
    ],
    "failure": [
      {
        "action": "status_message",
        "text": "Not having a target, the scroll is inert and is not consumed."
      }
    ]
  }
]

[
  {
    "action": "execute_command",
    "command_number": 12
  },
  {
    "action": "consume_item"
  }
]

Misc Items

Misc items do not have any configurable options. They exist only as items that can be carried by the player, to be used as flavor or as the target for has_item function calls in expressions.

Enemies

Enemies represent battles that may be fought by the adventurers in an encounter. They can be configured with the following options:

Enemy Attacks

Click the + button to add an enemy attack, after which you can configure its fields. Each of these fields adjusts the combat mechanics, so you can find more details in the Combat Section.

Attack Groups

Attack groups exist as an advanced feature. Many adventures do not need advanced combat mechanics, and this feature can be entirely ignored: if you leave the attack groups list as empty, this implicitly indicates that you do not wish to restrict which attacks it can respond to. However, you may find this feature useful if, for example, you want to differentiate ranged attacks from melee attacks from magic attacks, etc.

Every enemy attack includes a list of attack groups to which it is able to respond. As such, when attacked with a "melee" attack, the enemy is only able to perform a counter-attack that lists "melee" in its attack groups. For example, consider an enemy with a "bow" attack:

• If you want your enemy to pull a Legolas and be just as proficient with his bow when up close and personal and at a distance, you could set its "bow" attack to have "attack_groups": ["melee", "ranged"]. That way, the bow attack will be available to the enemy regardless of whether an adventurer hits it with a melee or ranged attack.
• If you want your enemy to be more like a normal archer and have trouble hitting things that are too close, you could set up two separate attacks: a "ranged bow" attack and a "close-contact" bow attack. Give the first "attack_groups": ["ranged"], and give the second a lower (possibly negative) attack bonus, and "attack_groups": ["melee"]. That way, the ranged bow attack will only be available if the adventurer hit with a ranged attack, and the enemy will need to use the close-contact bow attack when responding to a melee attack.

Combat

Combat mechanics are invoked during battle encounters. These are a special kind of encounter in that the usual encounter resolution procedure doesn't apply. Once initiated, combat continues until one of three things happens:

• The adventurers defeat the enemy, after which the encounter is resolved and the success command (if any) is executed
• All adventurers have disengaged and fled, after which the encounter is resolved without executing the success command
• The enemy defeats the adventurers, after which the defeat command is executed

During combat, additional commands are created for each adventurer:

• Unarmed Strike
• Weapon Strike (for each unique weapon carried by the adventurer)
• Flee

Combat Flow

Combat is pretty straight-forward: an adventurer performs an attack, and if the enemy is still alive, it performs a counter-attack. In most cases, that's all you really need to know. However, if you are curious exactly what is happening behind the scenes, during combat, the full flow is reproduced here:

Fleeing

Unless the enemy has the "Can't Flee" attribute set, adventurers may attempt to flee instead of continuing the battle. When attempting to flee, a dexterity check is made by rolling a d20 + (dex bonus). If this roll is greater than or equal to the enemy's Flee Difficulty, the attempt is successful and the adventurer is no longer engaged. If the roll is less than the enemy's Flee Difficulty, the attempt fails, the adventurer remains engaged, and the enemy gets a free counter-attack.

After successfully fleeing, an adventurer is no longer engaged in the battle, and the attack and flee commands are not available to them. If all adventurers flee, the battle encounter ends: the adventurers got away! When adventurers have fled and are not engaged but the battle is still ongoing, the attack and flee commands are not available to them. Instead, they have a new command to re-engage in the battle if they want to. If they re-engage, they will need to successfully flee again in order to count towards all adventurers having successfully fled to end the encounter.

Adventurer Stats

There are six attributes that all adventurers have:

• Strength (str)
  used for things that require brawn, such as forcing open a jammed door or punching something really hard.
• Dexterity (dex)
  used for things that require a light touch, picking locks or dodging a hazard.
• Constitution (con)
  used for things that require a solid body, like emerging unscathed from an unpleasant fall, or resisting the effects of poison.
• Intelligence (int)
  used for booksmarts, whether you'd be able to make a cognitive leap or maybe would know something about a given topic.
• Wisdom (wis)
  used for things that depend on lessons learned from experience, like tracking animals in nature, or knowing when someone's lying.
• Charisma (cha)
  used for things that require force of character, whether persuading others, or perhaps intimidating them.

The base value for each of these stats is 10, which provides neither a positive nor a negative bonus. For every two points that a stat increases or decreases, your "attribute modifier" increases or decreases by one. These bonuses are used when calculating ability checks via the attribute_check action. For example, if your strength is 12, then when performing a strength check you would roll a d20 + 1 instead of just a d20. Similarly, if your dexterity was 17, dexterity checks would involve a roll of d20 + 3 instead of just a d20.

Your strength is used during combat: your strength bonus is added to both your attack and damage rolls. For example, when attacking an enemy with an AC of 10, an adventurer with a strength of 10 would need to roll a 10 or above in order to hit, whereas an adventurer with a strength of 12 would only need to roll a 9 or above. The adventurer with strength 12 would also deal one more damage per hit than the adventurer whose strength is 10.

Your dexterity is also used during combat: Your dexterity bonus is added to your AC. For example, when being attacked by an enemy that rolls a 10, an adventurer with a dexterity of 10 would get hit, but an adventurer with a dexterity of 12 would not.

Similarly, attempting to flee from an enemy performs a dexterity check against the enemy's flee difficulty. For example, when fleeing from an enemy with a flee difficulty of 10, an adventurer with a dexterity of 10 would need to roll a 10 or above whereas an adventurer with a dexterity of 12 would only need to roll a 9 or above.

Finally, an adventurer's maximum HP is determined by the adventure's Adventurer HP then affected by 15% for each point in the Adventurer's constitution modifier, rounded to the nearest HP. For example, in an adventure where the Adventurer HP is set to 30, 15% of 30 rounds to 5, so an adventurer with a constitution of 12 would have 35 HP, an adventurer with a constitution of 17 would have 45 HP, and an adventurer with a constitution of only 8 would have only 25 HP.

Note that intelligence, wisdom, and charisma are not used by adventure mechanics. It is recommended that you make use of these in attribute checks to balance their utility.

Variables

Variables represent the primary way of keeping state in an Adventure. While some state is kept in terms of the currently active node and adventure items, variables allow the adventure to "remember" arbitrary values which can be read back as needed. In short, a variable is essentially a number that can be referenced by some name. For example, an adventure may track a encounters_completed variable to count the number of encounters that have been triggered so far. In so doing, an adventure can change its behavior depending on previous actions (perhaps a particular command is only available after 5 encounters have been triggered, etc).

Generally speaking, an n-player adventure has n+1 distinct sets of variables: each player has their own set of individual variables, and there is also a global set of variables that applies to the entire party. For example, the adventure as a whole might track the number of encounters_completed, but each player might have their own individual gold_coins variable that tracks how many gold coins they have collected. Any action which writes a variable takes a parameter called individual, which determines whether to write to the current player's individual variables or to the global party variables. Actions executed by an adventurer have access to the adventurer's individual variables and the global party variables, but not to the individual variables of any other adventurer.

A variable's name may consist of only upper- and lower-case letters, hyphens, and underscores.

Writing Variables

The simplest way of writing or changing the value of a variable is via the increment and decrement actions. These actions take an existing variable and add 1 or subtract 1 from it respectively. If the named variable doesn't exist, it is initialized at 0 before being incremented or decremented.

A more advanced way of writing a variable is using the var_set action. This allows you to set the value of a variable to the calculated result of a given expression. Unlike using increment and decrement, the var_set action allows you to base the value to be written on the contents of other variables, supported functions, and arbitrary calculations.

Reading Variables

Variables can be read in two contexts: within the text datatype (including Post Text fields), and within expressions.

In a str, reference the variable by wrapping it in double curly-braces. If you have a variable called gold_goins that has a current value of 12, then a str of

Hello I have {{gold_coins}} gold coins

Hello I have 12 gold coins

{var:gold_coins} >= 12

Variable Precedence

When writing to a variable, you specify whether to write to the player's individual variables or to the party's global variables. As a result, it is possible to write variables in such a way that an adventurer has both an individual and a global variable with the same name. When reading a variable, you don't specify whether to read an individual or global variable. As such, the adventure needs to answer the question: if there are two variables with the same name, which do I return? The answer is: individual variables always have precedence over global variables.

But the real answer is:

{
    "action": "increment",
    "var_name": "gold_coins",
    "individual": false
}

Tools

The adventure system makes a number of tools available to you in order to help you construct your adventure and to check for errors. These can be found at the bottom of the sidebar.