From c36c1dc0c65e65b4d6ee53df6bbcc3a860eb6e4b Mon Sep 17 00:00:00 2001
From: historia <[not public]>
Date: Sun, 21 Jun 2026 01:05:35 -0400
Subject: Added %i, %n, %b to production skill messages to consistent color
 inputs, item names, and byproducts

---
 worldbuilding_guide/recipes.md | 56 +++++++++++++++++++++++++++++++++++-------
 1 file changed, 47 insertions(+), 9 deletions(-)

(limited to 'worldbuilding_guide')

diff --git a/worldbuilding_guide/recipes.md b/worldbuilding_guide/recipes.md
index e442c8c..450ded9 100644
--- a/worldbuilding_guide/recipes.md
+++ b/worldbuilding_guide/recipes.md
@@ -18,13 +18,49 @@ Crafting information lives on the **output item's YAML file** via the `craft:` b
 | `consume`      | []ConsumeEntry | Ingredients consumed (see below)                |
 | `output_qty`   | int            | Quantity produced (default 1, for stackables)   |
 | `fail`         | string         | ItemID produced on failure (optional)           |
-| `message`      | string         | Success message                                 |
-| `fail_message` | string         | Failure message                                 |
+| `message`      | string         | Success message per cycle (optional, see message defaults) |
+| `fail_message` | string         | Failure message (optional, empty = silent fail) |
+| `start_message`| string         | Message when action begins (optional, see message defaults) |
+| `end_message`  | string         | Message when action completes (optional, see message defaults) |
 | `steps`        | []CraftStep    | Multi-step messages at tick intervals (optional)|
 | `success`      | SuccessFormula | Optional skill check formula (see Behaviors)    |
 
 The output is the item itself — no `output` field needed. The item ID IS the craft ID.
 
+### Message Variables
+
+All message fields (`message`, `fail_message`, `start_message`, `end_message`, and `steps[].message`) support variables that expand to colorized item names:
+
+| Variable | Expands to                                      |
+| -------- | ----------------------------------------------- |
+| `%n`     | Output item name (colored, e.g. "stim potion")  |
+| `%i1`    | 1st consume entry's matched item (colored)      |
+| `%i2`    | 2nd consume entry's matched item (colored)      |
+| `%b1`    | 1st byproduct item name (colored, success only) |
+| `%b2`    | 2nd byproduct item name (colored, success only) |
+
+Numbering follows YAML consume/byproduct order. If a consume entry has multiple alternative items (`items: [a, b]`), the variable expands to whichever the player actually possesses, colored with that item's `color:` field.
+
+Variables work alongside inline color tags (`{196}text{/}`) which are expanded after variable substitution.
+
+### Message Defaults
+
+If a message field is omitted from the YAML, the game uses a skill-level default based on the craft `type`:
+
+| Type | Default `message` | Default `start_message` |
+|------|-------------------|------------------------|
+| `cooking` | `"Cooked to perfection. %n looks great!"` | `"You start cooking %i1."` |
+| `smelting` | `"You remove a white hot %n!"` | `"You place the %i1 into the furnace."` |
+| `smithing` | `"You smith a %n."` | `"You begin smithing %i1."` |
+| `crafting` | `"You craft a %n."` | `"You begin crafting %i1."` |
+| `fletching` | `"You fletch a %n."` | `"You begin fletching %i1."` |
+| `pharmacy` | `"You mix a %n."` | `"You start mixing %i1."` |
+| `construction` | `"You construct a %n."` | `"You begin constructing %i1."` |
+| `clean` | `"You clean the %i1."` | `"You begin cleaning herbs."` |
+| (unset) | `"You produce %n."` | `"You start <verb> %i1."` |
+
+Any of these can be overridden per-item by setting the field in YAML. For skills that never fail (smithing, crafting, fletching, pharmacy, construction), `fail_message` defaults to empty — no message is shown on failure.
+
 ### CraftStep — Multi-Step Messages
 
 Optional interim messages fired at specific tick offsets during the craft cycle. The `tick` is the number of ticks elapsed since the start of the cycle.
@@ -85,7 +121,7 @@ craft:
       quantity: 1
     - items: [eye_of_newt]
       quantity: 1
-  message: "You mix a stim potion."
+  message: "You mix a %n."       # %n expands to "stim potion" colored
 ```
 
 ### Station-Based Production
@@ -104,7 +140,8 @@ craft:
       quantity: 1
     - items: [tin_ore]
       quantity: 1
-  message: "You smelt a bronze bar."
+  message: "You smelt a %n."     # default is "You remove a white hot %n!"
+                                 # overridden here for simpler flavor
 ```
 
 ```yaml
@@ -119,7 +156,7 @@ craft:
   consume:
     - items: [bronze_bar]
       quantity: 1
-  message: "You hammer out a bronze dagger."
+  # message omitted — uses default "You smith a %n."
 ```
 
 For stackable outputs, use `output_qty`:
@@ -137,7 +174,7 @@ craft:
     - items: [bronze_bar]
       quantity: 1
   output_qty: 15
-  message: "You hammer out some bronze nails."
+  # message omitted — uses default "You smith a %n."
 ```
 
 ### Tool-Based Production
@@ -172,7 +209,7 @@ craft:
       byproducts: [empty_vial, empty_jug]
     - items: [empty_bucket]
       quantity: 1
-  message: "You pour water into the bucket."
+  message: "You pour the %i1 into the %i2."  # %i1 = water source, %i2 = bucket
 ```
 
 ### Multi-Piece Assembly (3+ items → 1)
@@ -193,7 +230,7 @@ craft:
       message: "You try to puzzle how the pieces fit together."
     - tick: 3
       message: "Aha, this edge lines up here!"
-  message: "You assemble the ancient map."
+  message: "You assemble the %n."
 ```
 
 ### Clean Recipes
@@ -211,7 +248,8 @@ craft:
   consume:
     - items: [grimy_guam]
       quantity: 1
-  message: "You clean the grimy guam leaf."
+  # message omitted — uses default "You clean the %i1."
+  # %i1 expands to the grimy herb name with its color
 ```
 
 ### Food/Healing Items
-- 
cgit v1.2.3