15:16 ST

Adventure System Reference Sheet

Note: this guide is not intended as a tutorial, but as a reference sheet to look things up as needed.

An Adventure is an interactive storytelling experience. When you build an adventure, you are creating a setting for people to explore with their own characters. In its most basic form, it consists of interjecting occasional writing prompts to guide people through a setting you've created.

When creating an adventure, your goal should be to assist the adventurers in exploring their own characters through interesting scenarios. Remember that while you're providing the setting, the end result isn't about the setting: it's about the story you're enabling the adventurers to write for themselves. Guide them through the adventure, and remember to give them the space they need to develop their characters and create their own story.


Basic Structure

The fundamental building block of adventures is the COMMAND: commands may be executed when creating a post in an adventure thread, and are responsible for interjecting new posts and changing adventure state. They operate by executing a pre-programmed sequence of ACTIONS, which are like Lego-blocks of functionality that you can use to piece together what you want the command to do. Commands can be grouped logically into NODES, which are sort of like "folders" for commands. When an adventure is in a particular node, adventurers have access to commands that belong to that node.

Nodes may also contain ENCOUNTERS, which are events that happen to the adventurers and need to be resolved. For example, adventurers may encounter a slippery log, and each adventurer may attempt to cross the log without falling. Encounters typically involve a random element, and are triggered by a command action performed by an adventurer. They contain their own encounter commands, which need to be executed by all adventurers in order to resolve the encounter. While an encounter is active, only its encounter commands are available to the adventurers.

An adventure may define ENEMIES that present a battle to the adventurers. If an encounter specifies an enemy it becomes a BATTLE ENCOUNTER, in which the enemy must be defeated or fled from in order to resolve. During a battle encounter, COMBAT MECHANICS are engaged: attack / flee commands are available in addition to any encounter commands that may be defined, and adventurers pit their martial strength against that of the enemy.

Finally, an adventure may also define ITEMS that adventurers can collect. There are four types of items: weapons, armor, usable, and misc. Weapons provide additional attack commands for battle encounters, allowing adventurers to do more damage. Armor makes adventurers more difficult to hit. Usable items are items that can execute their own internal mini-commands, which can be used to construct items like health potions, fireball scrolls, etc. Misc items don't really do anything besides register being owned by an adventurer, and can be used for things like keys or talismans.


Adventure

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

Field What it does What this means
Title This is the name of the adventure Other players will see this as the title of the adventure. There is a 50 character limit.
Canon Adventure Check this box if the adventure will take place within Mycena Cave canon. This information is used for sorting and organizational purposes.
Max Adventurers This is the maximum number of characters that can go on this adventure together. Adventure builders may set this somewhere between 1 - 4 participants. Note that each character joining must belong to a separate player.
Adventurer HP This is the base value for how many Health Points (HP) with which a character starts. The default is set to 30, but you can set this to whatever makes the most sense for your adventure. An adventurer's maximum HP is modified by 15% for each point in their constitution modifier.

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:

Field What it does What it means
Encounter Name (required) This is the name of your command. It is never shown to the adventurer, and is for your reference only. Enter a name that you will recognize for the encounter. It can be changed at any time.
Encounter Title The encounter title is posted above the intro text when the encounter is triggered. If you don't want your encounter to have a title, leave this blank.
Success Command Execute this command when the encounter is resolved successfully. An encounter resolves successfully unless there is an undefeated enemy, or the end_encounter action is called with "success": false.
Battle Set the enemy (if any) to be fought in this encounter. See Battle Encounters for more details.
Encounter Pool Defines a "group" of encounters. When you trigger an encounter, you get a random encounter from the selected pool. Use this option to make separate pools to draw from.
Intro Text (required) The intro text is the forum post that is posted when the encounter gets triggered. Use this text to provide a setting, and describe anything the adventures need to know in order to resolve the encounter.

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:

As a result, it is not necessary to create custom commands in the encounter. However, adding custom commands can add additional flavor to the battle. For more details on battle commands and general combat mechanics, please see the Combat Section.


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:

Both of these components are optional, so a command can have one or the other or both. Technically speaking a command can also contain neither, but such a command would be completely pointless.

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

Default State What it does How to use Example
Command (Required) Any name the builder chooses This is the name of your command. It is never shown to the adventurer, and is for your reference only. Enter a name that you will recognize for the command. It can be changed at any time. knock or look at tree
Masked Deselected A masked command is not available to be executed, unless unmasked by an action. Select this if you don't want the command to be immediately available when the player enters the node. You might have a masked buy armor command, which is unmasked by an enter shop command. Adventurers cannot buy the armor until after they have entered the shop.
Description (required) What's displayed in the command dropdown menu to the adventurers. Type a brief description in the description text box. Approach the ruin and look around
Self-masking Deselected The command becomes masked after being executed. Select this if it only makes sense to execute this command once while in a node. You might have a self-masking collect treasure command, because once it has been collected it should not be collected again.
Required Condition (optional) Determines which conditions, if any, are required to gain access to this command. A required condition is an expression type that acts as a "guard" that implicitly masks commands until a certain condition is met. An advance node command may have a required condition of {var:num_encounters} > 2 to ensure that participants have performed more than two encounters before moving on. For more information on Required Conditions, please see the Expressions Section.
Destination Node (optional) (none) Determines which node, if any, the adventure should move to after executing this command. Select the desired node from the destination node menu. An advance node command may have the next node set as its destination node, as well as an introductory post in the Post Text field.
Actions []
(empty list)
A JSON-encoded list of actions to be performed when executing this command. Use the "add action" dropdown menu to add action customizable action templates to your command.
[
  {
    "action": "increment",
    "variable": "num_encounters",
    "individual": false
  },
  {
    "action": "trigger_encounter",
    "encounter_pool": ""
  }
]
will increment the "num_encounters" variable and trigger an encounter. For more information on Actions, please see the Actions Section.
Post Text (optional) This is a forum post which will be posted to the adventure thread when this command is executed. This text will be parsed for BBCode and posted by the Bone Monster. It supports text-replacement for the adventurer's name who executed the command ({{player}}) and any variables that are currently set ({{variable_name}}).
[h1]Account Summary[/h1]
{{player}} now has {{num_coins}} coins!
will create a forum post by the Bone Monster with a title of "Account Summary" and where the text may read "Ambrose now has 12 coins!"

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


Actions

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

acquire_item

Adds an item to the adventurer's inventory.

Fields Data-type Description
item_number num The number of the item to be given to the adventurer.
{
    "action": "acquire_item",
    "item_number": 1
}

attack_player

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

Fields Data-type Description
attack_index attack Which of the enemy's attacks to use. Set to false to use the enemy's attack weights.
{
    "action": "attack_player",
    "attack_index": false
}

attribute_check

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

Fields Data-type Description
dc check The difficulty of the check. Typical values might be 5 for easy, 10 for moderate, 15 for difficult.
stat stat The stat being used in the check. An "str" check is easier for adventurers with higher strength, etc. See the Adventurer Stats Section for details.
silent bool Whether the success or failure of the check should be hidden.
success actions A list of actions to perform if the check was successful.
failure actions A list of actions to perform if the check was unsuccessful.
{
    "action": "attribute_check",
    "dc": 10,
    "stat": "wis",
    "silent": false,
    "success": [],
    "failure": []
}

consume_item

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

{
    "action": "consume_item"
}

continue_encounter

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

{
    "action": "continue_encounter"
}

damage_enemy

Deals damage to the current enemy (if any).

Fields Data-type Description
roll dice A description of what dice to roll to determine how many HP to deduct.
type damage What type of damage to deal, relevant if the enemy has vulnerabilities or resistances.
{
    "action": "damage_enemy",
    "roll": "4d4+4",
    "type": "slashing"
}

damage_player

Deals damage to the adventurer executing this command.

Fields Data-type Description
roll dice A description of what dice to roll to determine how many HP to deduct.
type damage What type of damage to deal, relevant if the player has vulnerabilities or resistances.
{
    "action": "damage_player",
    "roll": "4d4+4",
    "type": "slashing"
}

decrement

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

Fields Data-type Description
variable varname The name of the variable to decrement.
individual bool Whether this variable relates to the adventurer or the party.
{
    "action": "decrement",
    "variable": "coins",
    "individual": false
}

end_adventure

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

{
    "action": "end_adventure"
}

end_encounter

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

Fields Data-type Description
success bool Whether the encounter is resolved in a "successful" manner.
{
    "action": "end_encounter",
    "success": false
}

execute_command

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.

Fields Data-type Description
command_number num The number of the command to be executed.
{
    "action": "execute_command",
    "command_number": 1
}

heal_enemy

Heals the current enemy (if any).

Fields Data-type Description
roll dice A description of what dice to roll to determine how many HP to heal.
{
    "action": "heal_enemy",
    "roll": "4d4+4"
}

heal_player

Heals the adventurer executing this command.

Fields Data-type Description
roll dice A description of what dice to roll to determine how many HP to heal.
{
    "action": "heal_player",
    "roll": "4d4+4"
}

if_check

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

Fields Data-type Description
condition expression The expression to evaluate.
success actions A list of actions to perform if the expression evaluated to true or non-zero
failure actions A list of actions to perform if the expression evaluated to false or zero
{
    "action": "if_check",
    "condition": "{var:a} < 2",
    "success": [],
    "failure": []
}

increment

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

Fields Data-type Description
variable varname The name of the variable to increment.
individual bool Whether this variable relates to the adventurer or the party.
{
    "action": "increment",
    "variable": "coins",
    "individual": false
}

make_post

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.

Fields Data-type Description
text text The content of the post. Supports BBCode, {{player}} and {{var_name}} syntax.
{
    "action": "make_post",
    "text": "[h1]Hello![/h1] ..."
}

mask_command

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

Fields Data-type Description
command_number num The number of the command to mask.
{
    "action": "mask_command",
    "command_number": 1
}

remove_item

Removes an item from the adventurer's inventory.

Fields Data-type Description
item_number num The number of the item to be taken from the adventurer.
{
    "action": "remove_item",
    "item_number": 1
}

revive_all

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

{
    "action": "revive_all"
}

stat_decrement

Decrements an adventurer stat.

Fields Data-type Description
stat stat The name of the stat to decrement.
{
    "action": "stat_decrement",
    "stat": "str"
}

stat_increment

Increments an adventurer stat.

Fields Data-type Description
stat stat The name of the stat to increment.
{
    "action": "stat_increment",
    "stat": "str"
}

stat_set

Sets the value of an adventurer stat.

Fields Data-type Description
stat stat The name of the stat to set.
value expression An expression describing the desired value.
{
    "action": "stat_set",
    "stat": "str",
    "value": "{stat:str} + 1"
}

status_message

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

Fields Data-type Description
text text The text to output. Supports {{player}} and {{var_name}} syntax.
{
    "action": "status_message",
    "text": "You are awesome."
}

trigger_encounter

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

Fields Data-type Description
encounter_pool text Which encounter pool to draw from. You can use encounter pools to create separate groups of encounters
{
    "action": "trigger_encounter",
    "encounter_pool": ""
}

unmask_command

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

Fields Data-type Description
command_number num The number of the command to unmask.
{
    "action": "unmask_command",
    "command_number": 1
}

var_set

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

Fields Data-type Description
variable varname The name of the variable to set.
value expression An expression describing the desired value.
individual bool Whether this variable relates to the adventurer or the party.
{
    "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.

Data-type Description
num A numeric value (e.g. 3, 12.5, -2, etc.)
varname A variable name, consisting of letters, numbers, hyphens, and underscores. It must begin with a letter.
check A number representing a difficulty for an attribute check. 5 is easy, 10 is moderate, 15 is hard.
stat One of the six stats: str (strength), dex (dexterity), con (constitution), int (intelligence), wis (wisdom), or cha (charisma).
See the Adventurer Stats section for details.
bool A boolean value, either true or false.
text Just some text. {{player}} will be replaced with the current player's adventurer, and {{varname}} will be replaced with that variable's value.
dice A representation of a dice roll, like d6 or 2d12 - d6 + 1.
See the Dice Section for details.
damage A name for the type of damage being dealt, used as flavor and when determining vulnerabilities and resistances. Must be a single word.
expression A formula that evaluates to a number, using numbers, mathematical operators, variables, and built-in functions.
See the Expression Section for details.
attack A field representing either a numeric zero-indexed attack number, or the boolean false.
actions A list of actions. It's easiest to just add actions to the main actions list for the command, then cut-and-paste them into this list.

Dice

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

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


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

Operator Description Example
+ Addition 6 + 3 evaluates to 9
- Subtraction 6 - 3 evaluates to 3
* Multiplication 6 * 3 evaluates to 18
/ Division 6 / 3 evaluates to 2
% Modulo (remainder) 9 % 4 evaluates to 1
() Parentheses (6 + 4) / 2 evaluates to 5

Supported comparators

Comparator Description Example
== Equals

Evaluates to 1 if the values are equal, 0 if they are not equal
3 + 4 == 7 evaluates to 1
3 + 4 == 8 evaluates to 0
!= Not equal to

Evaluates to 1 if the values are not equal, 0 if they are equal
3 + 4 != 54 evaluates to 1
3 + 4 != 7 evaluates to 0
< Less than

Evaluates to 1 if the first value is less than the second, 0 if it is greater or equal to the second
5 < 10 evaluates to 1
10 < 10 evaluates to 0
10 < 5 evaluates to 0
> Greater than

Evaluates to 1 if the first value is greater than the second, 0 if it is less than or equal to the second
10 > 5 evaluates to 1
10 > 10 evaluates to 0
5 > 10 evaluates to 0
<= Less than or equal to
Evaluates to 1 if the first value is less than or equal to the second, 0 if it is greater than the second
5 <= 10 evaluates to 1
10 <= 10 evaluates to 1
10 <= 5 evaluates to 0
>= Greater than or equal to

Evaluates to 1 if the first value is greater than or equal to the second, 0 if it is less than the second
10 >= 5 evaluates to 1
10 >= 10 evaluates to 1
5 >= 10 evaluates to 0

Supported boolean operators

Operator Description Example
&& Logical AND

Evaluates to 1 if both values are non-zero, otherwise evaluates to 0
1 && 1 evaluates to 1
1 && 0 evaluates to 0
0 && 1 evaluates to 0
0 && 0 evaluates to 0
|| Logical OR

Evaluates to 1 if either value is non-zero, otherwise evaluates to 0
1 || 1 evaluates to 1
1 || 0 evaluates to 1
0 || 1 evaluates to 1
0 || 0 evaluates to 0

Supported functions

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

Function Description Arguments Example
var Evaluates to the value of a variable, or 0 if the variable is not set Required:
  • varname: The name of the variable to retrieve
Optional:
  • num: The default value to retrieve (instead of 0) if the variable is not set
{var:coins}

{var:coins:5}
has_item Evaluates to 1 if the adventurer has the indicated item, 0 otherwise Required:
  • num: The number of the item to check for
Optional:
  • num: The number (instead of 1) to return on success
  • num: The number (instead of 0) to return on failure
{has_item:1}

{has_item:1:17:22}
count_item Evaluates to the number of a particular item carried by the adventurer Required:
  • num: The number of the item to count
{count_item:1}
roll Evaluates to the result of the indicated Dice roll Required:
  • dice: A representation of dice roll
{roll:4d4+4}
stat Evaluates to the value of the current adventurer's chosen stat Required:
  • stat: The stat to retrieve
{stat:str}
stat_bonus Evaluates to the bonus provided to the adventurer by the chosen stat Required:
  • stat: The stat for which to retrieve the bonus
{stat_bonus:str}
input_equals Evaluates to 1 if input in the adventurer's post (e.g. My input is [[secret-code]] in this post) equals the given value, 0 otherwise. Required:
  • text: The (case-insensitive) value to compare to
{input_equals:secret-code}
in_battle Evaluates to 1 if the adventurer is in a battle encounter, 0 otherwise (none) {in_battle}
player_hp Evaluates to the active player's HP (none) {player_hp}
player_ac Evaluates to the active player's AC (none) {player_ac}
enemy_hp Evaluates to the current enemy's HP, or 0 if not in battle (none) {enemy_hp}
enemy_hp_pct Evaluates to the current enemy's HP percentage, or 0 if not in battle (none) {enemy_hp_pct}
enemy_ac Evaluates to the current enemy's AC, or 0 if not in battle (none) {enemy_ac}
num_adventurers Evaluates to the number of adventurers currently participating in this adventure (none) {num_adventurers}

Expression Examples

Set your command up with the following actions:

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

Create your attack spells as Global Encounter Commands so that they're available in all encounters, and set them all to have:

Required Condition: {in_battle} && {has_item:2}

Edit the "Unlock Door" command to have:

Required Condition: {has_item:6}

Edit the "Unlock Door" command to have:

Required Condition: {has_item:3} && {has_item:15}

Edit the "Unlock Door" command to have:

Required Condition: {has_item:6} || ({has_item:3} && {has_item:15})

Set your command up with the following actions:

{
    "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:

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:

Field What it does What this means
Item Name (required) This is the name of your item. It is what's displayed in the adventurer's inventory. Enter a name that you and your adventurers will recognize for the item. It can be chanced at any time.
Category (automatic) This defines what additional properties are available on the item. Set cannot be edited directly, but is set by selecting the corresponding tab.
Description Add some flavor or context to the item by filling in a text-only description. This is displayed when an adventurer clicks on the item in their inventory.
Resistances (advanced) Having this item in an adventurer's inventory will grant them resistance to the selected damage types. Adventurers take half-damage from damage types they are resistant to. This option is visible in Expert Mode only.
Vulnerabilities (advanced) Having this item in an adventurer's inventory will make them vulnerable to the selected damage types. Adventurers take double-damage from damage types they are vulnerable to. This option is visible in Expert Mode only.

Weapon Items

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

Field What it does What this means
Hit bonus This value is added to the attack roll to make the attack more or less likely to hit. Unarmed strikes have a bonus of 0, so providing a positive or negative number increases or decreases the probability. See the Combat Section for details.
Damage roll This dice roll determines how much damage is dealt when an attack hits successfully. Unarmed strikes have a damage roll of 1d4.
Damage type This is the type of damage that will be dealt by this weapon. If an enemy is resistant or vulnerable to the selected damage type, it will take half or double damage respectively.
Attack group This determines which categories of counter-attacks will be available to enemies. Common values are "melee" and "ranged". Enemies are only able to counter with attacks of the same attack group. If an enemy has no ranged attacks and you attack with a ranged weapon, the enemy will be unable to strike back. See the Combat Section for details.

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:

Field What it does What this means
Defense bonus This value is added to the player's AC to make an enemy's attack less likely to hit. A player's default AC is 10 plus their dexterity modifier. See the Combat Section for details.

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."
      }
    ]
  }
]

Nodes cannot be changed directly via an action, so you'll need a supporting command to make this work.

Create a "teleport to [destination]" command (e.g. command #12), and ensure it's masked. Don't give it any actions, but set its Destination Node to the desired node, and write whatever Post Text you want.

Then give your Scroll of Teleportation the following action:

[
  {
    "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:

Field What it does What this means
Enemy name This is the name of your enemy. It is seen by adventurers in the enemy's counter-attacks. Enter a name that you and your adventurers will recognize for the enemy. It can be changed at any time.
Flee difficulty How difficult it is to flee from this enemy. Default is 10 (moderate). When attempting to flee, a dexterity check is made. It must meet or exceed this value to be successful.
Base HP Determines the enemy's health points Each additional adventurer adds 80% of the base to the total. For example, an enemy with a base HP of 10 will have 10 HP in a one-person adventure, 18 HP in a two-person adventure, 26 HP in a three-person adventure, or 34 HP in a four-person adventure.
Armor Class How difficult it is to hit the enemy. Default is 10 (moderate). When attacking the enemy, the attack roll must meet or exceed this value to hit. See the Combat Section for details.
Can't Flee (advanced) Adventurers are unable to attempt to flee from this enemy. This option is only visible in Expert Mode.
Resistances This enemy will be resistant to the selected damage types. Enemies take half-damage from damage types they are resistant to. This option is visible in Expert Mode only.
Vulnerabilities This enemy will be vulnerable to the selected damage types. Enemies take double-damage from damage types they are vulnerable to. This option is visible in Expert Mode only.
Attacks Define the counter-attacks available to this enemy. For instructions, please see the Enemy Attacks Section.

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.

Field What it does What this means
weapon This is the name of the attack. It is for flavor only, and results in messages like
The Jellyfish counters with a [weapon] attack and misses!
hit_bonus Much like when defining the hit_bonus for weapon items, an attack bonus makes the attack more likely to hit. An adventurer's unarmed strike has a hit bonus of 0.
damage_roll Much like when defining the damage roll for weapon items, a damage roll is a dice roll that defines how much damage is done if the attack hits. An adventurer's unarmed strike has a damage roll of 1d4.
damage_type Much like when defining the damage type for weapon items, the damage type can affect the damage dealt by the attack. If the player is resistant to the damage type, they will take half-damage. If they are vulnerable to the damage type, they will take double-damage.
attack_groups This is a list of attack groups that this particular attack is able to respond to. Common attack groups are "melee" and "ranged", though you can define any that you like.

For an enemy counter-attack that can respond to both melee and ranged attacks, you would enter
"attack_groups": ["melee", "ranged"]

If an enemy is attacked by a weapon with a particular attack group and does not have any attacks that specify that group, it will not perform a counter-attack. If you leave this field as an empty list ([]) the attack will be able to respond to any incoming attack. For more detail see the Attack Groups subsection below.

custom_miss_text You can optionally specify custom text for when this attack misses. For example, instead of the default miss-text:
The Siren counters with a song attack and misses!
you might want it to report that:
The Siren's song is haunting and melodic, but you keep your wits about you.
probability_weight When deciding on a counter-attack, the enemy will collect all applicable attacks and randomly choose one according to this weight. If an attack has a probability_weight of 3 is it three times more likely to be selected as an attack with a probability_weight of 1.

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:


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:

During combat, additional commands are created for each adventurer:

Unlike most combat mechanics, combat in Mycena Cave Adventures is purely reactive: an enemy will only attack in response to an adventurer's attack or attempt to flee, and each adventurer attack results in an enemy counter-attack to the same player. As such, if you have defined additional commands in the battle encounter, these will only result in an enemy attack if the command executes the enemy_counterattack action.

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:

  • Adventurer executes an attack command:
    • Is the adventurer using a weapon?
      • NO: hit bonus is 0, damage roll is 1d4, damage type is slashing, attack group is melee
      • YES: read the hit bonus, damage roll, and damage type and attack group from the weapon item
    • Attack the enemy by rolling the attack roll: d20 + (hit bonus) + (str bonus)
      • Was the attack roll greater or equal to the enemy's AC?
        • NO: you miss
        • YES: you hit!
          • Roll the damage roll: damage_roll + (str bonus)
            • Is the enemy resistant to the damage_type?
              • NO: damage remains unchanged
              • YES: divide the damage by 2
            • Is the enemy vulnerable to the damage_type?
              • NO: damage remains unchanged
              • YES: multiply the damage by 2
            • Deal the (potentially) modified damage to the enemy
            • Does the enemy have more than 0 HP?
              • NO: encounter ends, you were victorious!
              • YES: encouner continues
    • Enemy initiates a counter-attack against the adventurer that attacked it
      • Determine which counter-attack to use
        • Look at all of the enemy's attacks, and remove any that do not have the appropriate attack_group it was attacked with
        • Are there any attacks left?
          • NO: enemy fails to perform a counter-attack
          • YES: enemy randomly chooses a counter-attack based on the probability_weight
            • Determine the attack's hit_bonus, damage_roll, and damage_type from the attack.
            • Determine the adventurer's AC:
              • Determine the highest defense bonus of any item carried by the adventurer
              • The adventurer's AC is 10 + (dex bonus) + (defense bonus)
            • Determine the adventurer's resistances and vulnerabilities:
              • Any resistances or vulnerabilities on any item carried by the adventurer apply
            • Roll the attack roll: d20 + (hit_bonus)
              • Was the attack roll greater or equal to the adventurer's AC?
              • NO: the counter-attack misses
              • YES: the counter-attack hits!
                • Roll the damage_roll of the enemy attack
                  • Is the adventurer resistant to the damage_type?
                    • NO: damage remains unchanged
                    • YES: divide the damage by 2
                  • Is the adventurer vulnerable to the damage_type?
                    • NO: damage remains unchanged
                    • YES: multiply the damage by 2
                  • Deal the (potentially) modified damage to the adventurer
    • Do any adventurers have at least 1 HP left?
      • NO: encounter ends, you were defeated! Execute the defeat command
      • YES: encounter continues

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:

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
would transform into the text
Hello I have 12 gold coins

In an expression, retrive the variable by calling the var function. If you want to require that a command only be run if the value of gold_coins is at least 12, then give it a Required Condition of
{var:gold_coins} >= 12
For more information, see the Expressions Section.

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:

DO NOT USE THE SAME NAME FOR GLOBAL AND INDIVIDUAL VARIABLES

Seriously. Don't do it. It gets confusing, and it probably doesn't behave the way you want.

Assume for a moment that we have an individual variable gold_coins to track how many coins an adventurer has, and we also have a global variable gold_coins to track a collective party-fund. Say my adventurer has 12 personal gold coins, and his party has 24.

Question: you want to increment the global gold coins by 1. How do I do that?

No problem -- just use the increment action:

{
    "action": "increment",
    "var_name": "gold_coins",
    "individual": false
}
Lets look at what this actually does.

  • Read the variable "gold_coins" variable
    • Is there an individual "gold_coins"? YES, so return it (answer: 12)
  • Add 1 (answer: 13)
  • Write 13 to the global "gold_coins" variable.

As a result, instead of gaining 1 coin to the party fund, we just lost 11 coins. Sad!


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.

View Variables

This tool shows you an overview of how you've used variables in your adventure. For each variable, it shows you locations in your adventure where the variable is written to, and locations in your adventure where the variable is read from. Any variables that are read but never written, or written but never read, are highlighted in red as a potential error for you to investigate.

Deleted Elements

This is the "trash can" for elements from your adventure that you've deleted. They can be restored at any time.

See / Edit Instances

When adventurers embark on an adventure, a new instance of the adventure is created. This is where the participants, adventure state, etc. are stored. This tool allows you to reach into adventure instances and view or modify its current state. This is useful when constructing and testing your adventure, because you can see exactly how the adventure state changes as a result of your commands. It can also help in situations where you've made a mistake in your adventure, so you can fix the broken states that adventurers may be in as a result.

In the "State" section, note that deleted elements are included as options (e.g. in the "Current Node" dropdown, etc.). If you attempt to set one of these, it will fail with an error.

Test Adventure

This tool allows you (or anybody you share the link with) to embark on your adventure before you publish it. Any adventure instances created via this tool run in "test mode", which means they track changes to the adventure as you make them, rather than waiting for the publish / upgrade cycle that ordinary adventures follow. You can also embark on test adventures without fixing problems identified by the Adventure Verifier during the Publish step. This makes it useful for testing out changes you're making as you go.

It is not recommended to use this feature for general adventuring.

Publish Adventure

This is how you make your adventure available to other people. Whenever you publish, a playable copy of your adventure is made. That way, if you are making changes to your adventure that people are already playing, you won't break their instances.

This tool will also run the Adventure Verifier, which does its best to determine whether or not your adventure is broken. It can find obvious things like syntax errors, invalid rolls, invalid item references, and so on. It's not perfect, though, and won't be able to find things like logic errors or inaccessible nodes. If the verifier finds issues with your adventure, you will need to fix them before you can publish.

When you perform your first publish, the adventure becomes available for other players to embark on. When you perform subsequent publishes of the same adventure, any adventurers currently playing your adventure will be given the option to upgrade. Depending on the scope of your changes, they may choose to continue playing the older version.