feat: major xterm256 color overhaul, see worldbuilding docs.

1 files changed, 50 insertions, 32 deletions

diff --git a/data/help/color.yaml b/data/help/color.yaml
index 777aa07..5927e9a 100644
--- a/data/help/color.yaml
+++ b/data/help/color.yaml
@@ -10,65 +10,83 @@ description: |
   Usage:
     color                     List all targets and their current values
     color <target>            Show current color for a target
-    color <target> <string>   Set a custom color
+    color <target> <spec>     Set a custom color
     color <target> reset      Reset to server default
     color <target> off        Disable color for this target entirely
 
-  Color string format (space-separated tokens):
-    fg=<color>   Foreground color
-    bg=<color>   Background color
+  Color spec format (space-separated tokens):
+    <0-255>      Foreground color (xterm-256 palette index)
+    bg:<0-255>   Background color
+    g:<a>,<b>    Gradient between two or more colors
     bold         Bold text
     dim          Dim text
-    italic       Italic text
     underline    Underlined text
 
-  Example: fg=green bg=black bold
+  Examples:
+    color room_name 6 bold
+    color fire 208
+    color death 1 bold
+    color broadcast 214 bg:0
 
-  Available color names:
-    black, red, green, yellow, blue, magenta, cyan, white,
-    bright_black, bright_red, bright_green, bright_yellow,
-    bright_blue, bright_magenta, bright_cyan, bright_white
+  Gradients interpolate across characters in RGB space:
+    color item g:196,82           Red to green
+    color room_name g:45,39,59    Three-stop gradient
+
+  Use 'colortable' to see all 256 colors and their indices.
+
+  Colors use the xterm-256 palette (0-255). When a player's color
+  mode is set to "ansi", extended colors (16-255) automatically
+  downgrade to the nearest of the 16 standard ANSI colors.
+
+  Standard colors (0-15):
+    0 black     1 red       2 green     3 yellow
+    4 blue      5 magenta   6 cyan      7 white
+    8-15 bright variants of the above
+
+  Inline color tags in room descriptions:
+    {<spec>}colored text{/}
+    {182 bold}mysterious vase{/}
+    {g:196,82}gradient text{/}
 
   Color targets:
     room_name      Room name headers
     room_number    Room number display (#id)
-    room_desc      Room description text
-    direction      Movement direction text ("You walk north")
-    exit_direction Exit direction labels (north, south, etc.)
+    room_desc      Room description text (default for untagged text)
+    direction      Movement direction text
+    exit_direction Exit direction labels
     exit_name      Exit destination room names
     mob_name       Mob names in combat
-    friendly_npc   Friendly NPC names (cannot be attacked)
-    hostile_npc    Hostile NPC/mob names in room listings
+    friendly_npc   Friendly NPC names
+    hostile_npc    Hostile mob names in room listings
     damage         Damage numbers
-    enemy_hp       Enemy HP in combat messages
-    character_hp   Your HP in combat messages
+    enemy_hp       Enemy HP in combat
+    character_hp   Your HP in combat
     xp             XP gain messages
     level_up       Level-up announcements
-    item           Item names on pickup/drop/gather
+    item           Item names (default)
     player_name    Player names in broadcasts
     death          Death message
     victory        Combat victory message
-    miss           Miss messages in combat
+    miss           Missed attack messages
     error          Error messages
+    say            Player chat text
+    dialog         NPC conversation text
+    broadcast      Room-wide event messages
+    fire           Firemaking messages
+    eat_food       Eating/healing messages
+    drop_message   Mob loot drops
+    credits_pickup Currency/credit messages
 
   Resolution order:
     1. Account override (set via "color" command)
     2. Server default (set in config.yaml)
     3. Built-in fallback
 
-  Auto-colored elements (not configurable):
-    - Objects: fishing spots are blue, rocks are earth-toned, trees green
-    - Items: ores, logs, fish, gems, and tools have their own colors
-    - Mob/player levels: displayed relative to your combat level
-      (red if higher, orange if <5 higher, white if equal,
-       yellow if <5 lower, green if much lower)
-
   The "color" option (option color none/ansi/xterm256) controls
-  whether ANSI codes are emitted and which mode is used.
-  "none" strips all color; the "color" command settings are
-  still saved but have no visual effect until color mode is
-  enabled.
+  whether ANSI codes are emitted. "none" strips all color.
+  In "ansi" mode, extended palette colors (16-255) are
+  automatically downgraded to the nearest ANSI color.
 
-  You can use color blocks in your prompt using the same format:
-    option prompt {fg=green bold}Ready>{/} %h/%Hhp
+  You can use color blocks in your prompt:
+    prompt {2 bold}Ready>{/} %h/%Hhp
   See 'help prompt' for full prompt customization.