Add a basic information guide on item and attribute automation

how-to/item-and-attribute-automation.md

@@ -0,0 +1,75 @@
+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:
+```js
+// "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 });
+```