From c4a8780b3406f746b1fcebc60303412e72ce5c4b Mon Sep 17 00:00:00 2001
From: Oliver <oliver@noreply.localhost>
Date: Sun, 3 May 2026 00:08:52 -0600
Subject: [PATCH] Add guide for migrating to v3.0.0

---
 Migrating to v3.0.0.md | 45 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 Migrating to v3.0.0.md

diff --git a/Migrating to v3.0.0.md b/Migrating to v3.0.0.md
new file mode 100644
index 0000000..30c3321
--- /dev/null
+++ b/Migrating to v3.0.0.md	
@@ -0,0 +1,45 @@
+Text-Based Actors v3.0.0 ships with some breaking changes that might affect macros
+or custom sheets within your world. This page will go over what those breaking
+changes are, and what you can do to restore functionality.
+
+**If you did not write any custom Macros or world scripts, you do not need to
+make any changes!**
+
+## API Location Change
+The easiest breaking change to fix, is that the globally available `taf` constant
+now contains multiple subsections. Wherever you used `taf` previously, can be
+directly replaced with `taf.api`. As there is now a `taf.config` as well, which
+contains all of the code-configurable properties of the system.
+
+You can read more about how stuff was moved in [this issue](https://git.varify.ca/Foundry/taf/issues/50)
+
+## Actor Attributes into Attribute Items
+Attributes used to exist in the Actor using the following format:
+```js
+system: {
+	attr: {
+		attr_key: {
+			name: "Attr Key",
+			value: 0,
+			max: 5,
+			isRange: true,
+		}
+	}
+}
+```
+however Attributes are now stored as an Item subtype. A one-time migration will
+be performed on all world and compendium actors that have attributes in order to
+convert them into the item subtypes. However this does not affect any macros or
+other shortcuts for creating Actors that you may have. What you should do while
+creating Actors programmatically now is to provide an `items` array with the
+required minimum-attribute-item data that you desire. There is no automatic
+migration from creating/updating actors in the old style to the embedded items.
+
+There is a short-cut for updating these attributes on the Actor though by doing
+something similar to:
+```js
+let actor = game.actors.getName(`Frankie`);
+await actor.setAttributeValue("strength", 20);
+```
+Which will update the "strength" attribute on the actor named "Frankie" to 20,
+if that attribute cannot be found, it will do nothing.