From 389e307f205f9b7edf604fb9f86e1038ead736ef Mon Sep 17 00:00:00 2001
From: historia <[not public]>
Date: Tue, 16 Jun 2026 23:37:50 -0400
Subject: feat: major xterm256 color overhaul, see worldbuilding docs.

---
 worldbuilding_guide/items.md | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

(limited to 'worldbuilding_guide/items.md')

diff --git a/worldbuilding_guide/items.md b/worldbuilding_guide/items.md
index 73f497b..e9e4352 100644
--- a/worldbuilding_guide/items.md
+++ b/worldbuilding_guide/items.md
@@ -3,6 +3,7 @@
 ```yaml
 id: bronze_pickaxe
 name: bronze pickaxe
+color: "178"                   # xterm-256 color index (0-255)
 aliases: ["pick", "pickaxe"]
 description: "A sturdy bronze pickaxe."
 value: 10
@@ -17,6 +18,18 @@ tool_type: pickaxe            # used by gather behaviors that require "tool: pic
 tool_speed: 2                 # reduces gather wait time
 ```
 
+### Color
+
+The `color` field accepts xterm-256 palette indices (0-255) with optional modifiers:
+
+```yaml
+color: "178"                   # bronze/gold
+color: "75 bold"               # bold steel blue
+color: "g:196,208,226"         # gradient red → orange → gold
+```
+
+In ANSI mode, extended colors (16-255) automatically downgrade to the nearest ANSI color. Use `colortable` in-game to see all 256 colors.
+
 Key item (quest token, not equippable):
 ```yaml
 id: pass_stub
@@ -43,7 +56,7 @@ burn_ticks: 24        # how long the fire burns
 ```yaml
 id: bread
 name: bread
-color: "fg=bright_yellow"
+color: "222"
 description: "A fresh loaf of bread, still warm from the oven."
 value: 5
 heal_value: 5         # positive = heal, negative = damage
@@ -57,7 +70,7 @@ Define what items combine to make this item. Used by the `use` command.
 ```yaml
 id: bread_dough
 name: bread dough
-color: "fg=bright_yellow"
+color: "222"
 made_from:
   - items: [pot_of_flour]
     qty: 1
-- 
cgit v1.2.3