Table of Contents
Text-Based Actors comes with two types of items, which are "Attributes" and "Items". These represent two common concepts in TTRPGs:
- attributes represent your character's statistics, like how strong they are
- items represent all physical things that your character can hold, as well as anything else that you character might possess, this can be anything from weapons and armour, to Class Features if your system has those.
both of these item types allow some limited form of automation within the system, that you can make use of if you want to, you can utilize the automation by writing a Macro within Foundry and then attaching it to the item while editing it as the "Macro to Execute" on the item.
Basic Automation
Skills similar to how they function in D&D can be represented using
attribute items, where the value of the attribute is whatever the bonus
to that skill would be. Let's say you have two attributes: "Proficiency
Bonus" and "Arcana", if you wanted to write a Macro that could be used to
make rolls instead of manually typing it out every time in the formula of
1d20 + proficiency bonus + arcana bonus, your macro should be set to
type "chat" while the content of it is /r 1d20 + @proficiency_bonus + @arcana, and that will replace the proficiency and arcana bonuses when
you use that skill from the Actor sheet.
However, the above example requires making a separate Macro for each and
every skill you want to automate, which is really annoying if you have a
lot of them without any differences between the formula. So Text-Based
Actors actually provides a shortcut in order to make doing this easier.
In the chat macros, you can reference whatever Attribute was used to make
the roll with the @active.* special roll data group.
If the item being used is an Attribute, the available keys are:
@active.name: The name of the Attribute rolled@active.value: The current value of the Attribute item@active.min/@active.max: The minimum/maximum value of the Attribute's value
If the item being used was an Item, the available keys are:
@active.name: The name of the item used@active.quantity: The quantity of the item@active.equipped(0 or 1): Whether or not the item is considered equipped
Advanced Automation
Advanced automation requires knowledge of programming in JavaScript.
When writing macros for your items, you can make it as advanced as you want by writing a script macro instead of a chat macro. This gives full access to Foundry's API and making changes to stuff. Do you want a gun that automatically reduces the quantity of ammo when you shoot it? Then advanced automation is for you.
Using the example above, creating a gun that automatically reduces it's
ammo when using, the simplest way to do this is to treat the quantity
on the gun as the amount of ammo, in which the macro to do something like
that would be:
// "item" is passed in by the system, and is the full Item document
// of the item that this macro is attached to, it's a better version
// of the chat-macro's "@active" special data
// check that the gun has ammo
if (item.system.quantity <= 0) {
ui.notifications.error(`${item.name} is out of ammo, reload it before firing again!`);
return;
};
// The roll formula can be created however you need
const roll = new Roll(`1d20 + 2`);
await roll.evaluate(); // rolls the actual dice
await roll.toMessage(); // sends it to chat
await item.update({ "system.quantity": item.system.quantity - 1 });
- API
- How-To