Actions

Actions are a mechanic to describe what you want the mod to do, without needing to script it. So you can define what you want to do and the mod then figures out how it will do it. It will also figure out, how an action is represented (e.g. through a button the user can click on).

Currently, the only place where actions can be defined is in the scenario definition for overlay tiles. When an action is defined there, the overlay will automatically create a button which executes the action when a user clicks on them. You’ll probably know those button from doors and treasure chests, but they can be on any other overlay as well and do any other action as well (e.g. a treasure chest can be a door). In the future there will probably be other places as well where actions can be defined, e.g. a typical use-case would be something happens when an enemy is defeated.

Every action can set following attributes which defines how the button for the action will be shown. Each action type also defines defaults for those values, so you don’t have to always set them (e.g. the name for a door action will be "Open" by default). The different types of actions will be listed in the following sections.

Attributes

name

The name of the action, which will also be shown as the text on the button.

style

Defines the visual style for the button. This defines the background color, the font size and the width of the button that is created for the action.

confirm

If set to true, a user has to confirm the action again, after clicking the button for this action. Otherwise, clicking the button directly executes the action.
Example

The following example shows an action in the context of a scenario definition. Here the action is attached to a pressure plate tile. It will create a button with the text "Clockwise" that executes a call action, when clicked.

rooms = {
    [1] = {
        overlayTiles = { {
            bag = ScenarioApi.OverlayType.Corridor,
            type = { {
                name = "Pressure Plate",
                tiles = { {
                    position = { - 1.53, 1.88, 7.85},
                    rotation = {0.00, 30.00, 0.00},
                    tokens = { "b" },
                    action = {
                        name = "Clockwise",
                        call = {
                            functionName = "rotate100",
                            parameters = { 1 },
                        }
                    },
                } },
            } },
        } },
    }
}

Door

The door action is used to open rooms within the current scenario, just like the regular doors do.

Objects with a door action attached are still only considered to be part of the room they are defined in. E.g. a regular door defined in the doorTiles section of a scenario will also spawn, when one of the adjacent rooms is opened. An object with the door action will only spawn, when the room where it is defined is opened. To get the regular door behaviour the object has to be defined in multiple rooms with the same settings. It will still only spawn once, since a spawning object will be ignored, when there’s already an object with the same name at the target location.
Defaults

name

Open

style

Door

confirm

true
Attributes
Name Required Type Description

rooms

required

List<Number>

The list of room numbers that will be opened when this action is performed. Only rooms that weren’t opened before will be opened.
Example
action = {
    rooms = { 6, 2 }
}

Treasure

The treasure action will reveal a treasure card and then destroy the object the action is attached to. Treasure cards will be searched for in the treasure deck or the bag containing additional treasure (see Treasure for details on how to add custom treasure).

Defaults

name

The value of the treasure attribute

style

Treasure

confirm

false
Attributes
Name Required Type Description

treasure

required

Number or String

The name of the treasure that will be revealed. If the name is "G" the object is considered a goal treasure. No card is revealed and the object will not be destroyed when the action is performed.
Example
action = {
    name = "A",
    treasure = "SoX1A",
}

Spawn

This action can be used to spawn addition elements into the scenario.

Defaults

name

Execute

style

Pressure Plate

confirm

false
Attributes
Attributes
Name Required Type Description

spawn

required

[Spawnable Element]

Defines the object that will be spawned. See the documentation for [Spawnable Element] for details.
Example
action = {
    spawn = {
        element = { type = ScenarioApi.OverlayType.Door, name = "Stone Door Horizontal", },
        placement = { position = { -3.03, 1.77, 21.00}, rotation = { 0, 210, 0 }, },
        action = { rooms = {6, 2} },
    }
}

This action spawns a new door when performed.

Remove

This action is used to remove existing objects from the scenario. This can be useful for things like hidden rooms.

Defaults

name

Execute

style

Pressure Plate

confirm

false
Attributes
Name Required Type Description

remove

required

Element Search

Defines which element should be removed.

Element Search

Name Required Type Description

name

optional

String

The exact name of the object to remove. If tag is also set only elements with the tag will be considered.

tag

optional

String

The tag of the object to remove. If name is not set all objects with this tag will be removed.
Example
action = {
    remove = {
        tag = "Extra",
    }
}

Section

This action is used for scenario sections. Currently, the only thing it does is to set the color tint of the object it is attached to, so a black colored section tile will be revealed.

Defaults

name

"Section " plus the value of the section attribute

style

Section

confirm

false
Attributes
Name Required Type Description

section

required

Number or String

The section that will be revealed.
Example
action = {
    section = 68,
}

Compound

This is a container action that combines multiple actions into one action. The content of this action is a list of the containing actions.

Defaults

The action will take its defaults values from the first defined action.

Attributes
Name Required Type Description

compound

required

List<Action>

The list of actions that are combined.
Example
action = {
    compound = {
        { section = 68 },
        { spawn = {
            element = { type = ScenarioApi.OverlayType.DifficultTerrain, name = "Stairs Horizontal" },
            placement = { position = { -2.27, 1.89, 3.94 }, rotation = { 0, 270, 0 } },
        }},
    }
}

Call

This is kind of a fallback action when the existing actions are not sufficient. It will call any function on a game object when the action is performed.

Defaults

name

Execute

style

Pressure Plate

confirm

false
Attributes
Name Required Type Description

call

required

Call Definition

Describes which function on which object will be called.

Call Definition

Name Required Type Description

functionName

required

String

The name of the function that will be called.

owner

optional

GUID

The GUID of the game object where the function is located. If not set, it will default to "faad27" (which is the object containing the setup scripts).

parameters

optional

Table

Parameters for the function to call. By default this table will contain the values player (the player color performing the action), object (the GUID of the element where this action is defined) and button (-1 if the action was performed using a Left click, -2 in all other cases).
Example
action = {
    name = "Clockwise",
    call = {
        functionName = "rotate100",
        parameters = { 1 },
    }
}