Spells/Learning.md

 Spells can be learned by players in a variety of ways, and not all ways need to be used on your server.
 
-Any castable spells a player learns will appear in their [Spellbook](/Spells/Spellbook)  
+Any castable spells a player learns will appear in their [Spellbook](/Spells/Spellbook).
 
 [[_TOC_]]
 
 
 # Learnable Spells
+
 ## Admin Commands
-The most obvious way to learn spells is by using admin commands.
+The most direct way to teach someone a spell:
 
-The admin command to teach someone a spell is:
-`/mythicrpg spells teach [name] [spell]`
+```
+/mythicrpg spells teach [player] [spell] (level)
+```
 
-You can also use the `unlearn` command to remove a spell from someone.
+You can also remove a spell with `/mythicrpg spells unlearn [player] [spell]`, and list a player's known spells with `/mythicrpg spells get [player]`.
 
 ## Archetypes
+
 ### Leveling
-Spells can be configured to automatically be given by an archetype upon reaching a certain level.
+Spells can be configured to be granted automatically by an archetype upon reaching a certain level. Configured under an archetype's `SpellUnlocks` section.
+
+Each entry is a single line with the format `<spell>[:<spellLevel>] [<archetypeLevel>]`:
+
+- `<spell>` — the spell id
+- `<spellLevel>` *(optional)* — the level the spell is taught at. Defaults to `1`.
+- `<archetypeLevel>` *(optional)* — the archetype level at which the spell is unlocked. Defaults to the archetype's `MinLevel`.
 
-This is configured in an archetype's `SpellUnlocks` section.
 ```yaml
 Pyromancer:
   Group: CLASS
@@ -26,21 +34,35 @@ Pyromancer:
   SpellUnlocks:
   - Fireball
   - RainOfFire 10
+  - Inferno:3 25
 ```
+
 In this example:
-- A player would learn `Fireball` immediately upon gaining the Pyromancer archetype
-- The player would then learn `RainOfFire` upon reaching level 10
+- `Fireball` is learned immediately upon gaining the Pyromancer archetype.
+- `RainOfFire` is learned upon reaching archetype level 10.
+- `Inferno` is learned at spell level 3 upon reaching archetype level 25.
 
-If a player loses an archetype, all spells learned from it will be lost. 
+If a player loses an archetype, all spells learned from it are removed.
 
 ### Talent Trees
-_coming soon_
+Talents can teach spells via the `SPELL` component. Investing additional points into the talent raises the taught spell's level. See [Talents](/Archetypes/Talents#spell-component) for the full configuration.
+
+```yaml
+Cleave:
+  Display: 'Cleave'
+  MaxPoints: 5
+  Components:
+    - Type: SPELL
+      Spell: warrior_cleave
+```
+
+Spells learned through a talent are removed if the talent is refunded or the player loses access to the tree.
 
 
 ## Mechanics
-Players can be taught spells using the `teachSpell` mechanic (or have them removed via the `forgetspell` mechanic).
+Players can be taught spells with the [`teachRPGSpell`](/Skills/Mechanics/TeachSpell) mechanic (alias `teachSpell`) and have them removed with [`forgetRPGSpell`](/Skills/Mechanics/ForgetSpell) (alias `forgetSpell`).
 
-You can use this to create NPCs or [Custom Menus](/../../../MythicMobs/-/wikis/Custom-Menus) that teach spells, have a boss that teaches a spell upon being defeated, or to use with Crucible to create your own custom tome-type items.
+You can use these to build NPCs or [Custom Menus](/../../../MythicMobs/-/wikis/Custom-Menus) that teach spells, hand a spell out as a boss-kill reward, or wire up custom tome-style items.
 
 ```yaml
 Skills:
@@ -48,50 +70,51 @@ Skills:
 ```
 
 ## Signs
-Spell Signs can be used to create signs that will teach spells when right-clicked.
+Spell signs teach a spell when a player right-clicks them.
 
-To create one, you simply make a sign with the first line as `[Learn Spell]` and the 2nd line as the spell's ID.
+To create one, place a sign with `[Learn Spell]` (or `[Learn Skill]`) on the first line, and the spell's id on the second line.
 
 ![image](uploads/d48450ed19e9af3f7ea3c0fd260b515c/image.png)
 
 ## Tomes
-Tomes are special items that can teach you a spell. These can be given to players directly or (more likely) put in loot chests, dropped by mobs, etc.
+Tomes are custom written-book items that teach a spell when right-clicked. Hand them to players directly or place them in loot chests, etc.
 
-**You can obtain a tome using admin commands:**
-`/mythicrpg spells tome get [spell]`
+Get a tome via the admin command:
 
-Mobs can also drop a tome using the custom `spelltome{spell=X}` drop type.
+```
+/mythicrpg spells tome get [spell] (uses)
+```
 
+You can also specify a spell level by appending `:<level>` to the spell id, e.g. `/mythicrpg spells tome get Fireball:3 1`.
 
-# Globally Available Spells
-Global Spells and Global Mechanics are spells and mechanics you can have automatically apply to all players.
+> A `spelltome{...}` drop type for distributing tomes through MythicMobs droptables is not currently implemented.
 
-These included both active and passive spells, as well as special mechanics you can define to run on all players in the `config-spells.yml` config file.
+
+# Globally Available Spells
+Global Spells and Global Mechanics let you apply spells and mechanics to every player automatically.
 
 ## Global Spells
-Global Spells are spells that are automatically given to everyone.
+Global Spells are spells that are auto-granted to everyone. Add `Global: true` to the metaskill:
 
-To make a spell global, you simply put `Global: true` in the mythic skill's configuration.
 ```yaml
 SomeGlobalSkill:
   Spell: true
   Global: true
   ...
 ```
+
 This will cause the spell to be given to all players, and if it's a passive it will automatically trigger for all players.
 
 ## Global Mechanics
-Global Mechanics are defined in the `config-spells.yml` file, at the bottom under the `GlobalSkills` section. These are defined exactly like your typical mob skills, and will apply to all players.
+Global Mechanics are defined in `config-spells.yml` under `Configuration.GlobalSkills`. They are written like normal mob skill lines and apply to all online players.
+
+The default config ships with an example that gives everyone basic mana regeneration:
 
-The default config file comes with a single example that would be used to give people basic "mana regeneration":
 ```yaml
 Configuration:
-
   GlobalSkills:
-  #
   # Example of using this to implement global mana regeneration
-  - modifyReagent{reagent=mana;amount=10} @self ~onTimer:20
-  #
+  - modifyResource{resource=mana;amount=10} @self ~onTimer:20
 ```
 
-However, you are able to use pretty much any mechanics or mythic triggers that apply to players here, and call any other mythic skills, allowing you to use the mythic skill system to trigger all sorts of other random things you may want.
\ No newline at end of file
+You can use any mechanic and any [trigger](/Skills/Triggers) here that applies to players, including calls into your own custom mythic skills.