Mechanic

A Mechanic is, as the name implies, a functional piece of your RPG system. Mechanics represent things that your RPG system does, such as rolling dice, displaying resources, modifying character stats or running other mechanics (I bet you didn't see that one coming!).

Mechanics are mainly composed of effects. In fact, a mechanic can only do things through effects.

Every resource (and character) definition can contain mechanics, but these mechanics will only run within the context of a character sheet. This means that a mechanic will not run when editing a resource (say, editing a Spell), even if the Spell resource you defined in the system includes that mechanic. However, if the player is in the character sheet, and the character has a Spell as a value of one of its stats, that mechanic will be active while the player is in the character sheet.

To continue with this example, you might want to add a mechanic to a Spell so that the app rolls damage when the player tries to cast it.

Another potential mechanic use in a resource is to equip or unequip an armor, for example:

Example mechanic to toggle armor equip status

{
    "id": "armor_equip",
    "event_names": "toggle_equip",
    "effects": {
        "type": "when",
        "clauses": [
            {
                "condition": {
                    "type": "stat",
                    "stat": "is_equipped"
                },
                "effect": {
                    "type": "setStat",
                    "stat": "$character.equipped_armor_id",
                    "new_value": {
                        "type": "constant",
                        "value": "",
                        "value_type": "string"
                    },
                    "aggregation_type": "set"
                }
            },
            {
                "condition": {
                    "type": "constant",
                    "value": true,
                    "value_type": "bool"
                },
                "effect": {
                    "type": "setStat",
                    "stat": "$character.equipped_armor_id",
                    "new_value": {
                        "type": "stat",
                        "stat": "id"
                    },
                    "aggregation_type": "set"
                }
            }
        ]
    }
}

Notice how the mechanic defines a comma-separated list of event names. These event names will be the ones that trigger the mechanic. Events can be fired in a number of ways in the RPG Companion App, such as the Button view, or even the FireEvent effect. This means a mechanic could potentially trigger other mechanics.

info

Event names for mechanics can get tricky when trying to trigger mechanics by firing events from other resources. Internally, mechanics append a unique id to their event names in runtime to ensure that if you have multiple mechanics using the same event names simultaneously (e.g: multiple spell resource instances) they don't get triggered by accident. It would be pretty bad if the player tried to cast one spell and ended up casting all of them!

As a rule of thumb, whenever you're typing an event name directly (ie: not in a stat formula like "constant", for example), the appropriate id will be appended for you automatically. However, if you use a stat formula ( such as for the event_names property of the FireEvent effect), you are responsible with curating that event name. You can use the EventName stat formula component to achieve this easily (you DO NOT need to use EventName when defining calculated_event_names or calculated_revert_event_names for a mechanic, just when you want to fire it).

A scenario in which you would want to do the latter on purpose, for example, is if you're trying to trigger a mechanic by firing an event from a different resource mechanic or view.

Finally, mechanics can have revert event names. If provided, whenever one of the events listed is fired the mechanic will undo (ahem... revert) all reversible effects (e.g: setStat, addToStat, etc).

The RPG Companion App has some special events called Lifecycle events (see Character Sheet Lifecycle).

Phew! That was a handful!

JSON Format

{
  "type": "Mechanic",
  "id": ...,
  "name": ...,
  "description": ...,
  "effects": ...,
  "event_names": ...,
  "calculated_event_names": ...,
  "revert_event_names": ...,
  "calculated_revert_event_names": ...,
  "revert_on_remove": ...
}

Fields

Field	Type	Required	Description
id	String	✓	The identifier for this mechanic.
name	String		Optional. Defaults to null. A name for your mechanic. This is mostly for documentation purposes.
description	String		Optional. Defaults to null. A description for your mechanic. This is mostly for documentation purposes.
effects	Effect	✓	The effect that should execute for this mechanic whenever the appropriate events are fired.
event_names	List<String>		Optional. Defaults to an empty list. A list of event names that should cause this mechanic and its effect to be triggered if fired.
calculated_event_names	StatFormulaComponent		Optional. Defaults to formula returning an empty list. If event_names is provided, the resulting list from this formula will be appended to it. This list of names requires you to use the EventName stat formula to append the appropriate id to the event name if required. A formula that should compute to a list of strings representing event names that should cause this mechanic and its effect to be triggered if fired.
revert_event_names	List<String>		Optional. Defaults to an empty list. A list of event names that should cause this mechanic and its effect to be reverted (if it had already executed) if fired.
calculated_revert_event_names	StatFormulaComponent		Optional. Defaults to formula returning an empty list. If revert_event_names is provided, the resulting list from this formula will be appended to it. This list of names requires you to use the EventName stat formula to append the appropriate id to the event name if required. A formula that should compute to a list of strings representing event names that should cause this mechanic and its effect to be reverted if fired.
revert_on_remove	StatFormulaComponent		Optional. Defaults to a formula returning false. A formula for a bool value which will determine if this mechanic's effects should be reverted automatically when the resource that owns this mechanic is removed from the character. Note that this is only applicable when the mechanic is attached to a resource, and is irrelevant for mechanics directly attached to characters.