From e059bac63329dff483c2327895baca7e1403933c Mon Sep 17 00:00:00 2001
From: Jared Miller <jared@smell.flowers>
Date: Sat, 7 Feb 2026 15:39:36 -0500
Subject: [PATCH] Add research on graphicmud

---
 docs/how/mud-ecosystem.txt    |  4 ++
 docs/how/mudlib-landscape.txt | 79 +++++++++++++++++++++++++++++++++++
 2 files changed, 83 insertions(+)

diff --git a/docs/how/mud-ecosystem.txt b/docs/how/mud-ecosystem.txt
index 2c007ea..4bb311c 100644
--- a/docs/how/mud-ecosystem.txt
+++ b/docs/how/mud-ecosystem.txt
@@ -185,6 +185,10 @@ java:
     https://github.com/bozimmerman/CoffeeMud
     most feature-complete. 217 stars
 
+  - graphicmud
+    https://bitbucket.org/taranion/graphicmud
+    java 21, tile graphics + text hybrid. sixel rendering, ECS, behavior trees, multi-connector (telnet/discord/telegram/websocket). 30+ plugins
+
 C#:
   - archaicquest
     https://github.com/ArchaicQuest/ArchaicQuest-II
diff --git a/docs/how/mudlib-landscape.txt b/docs/how/mudlib-landscape.txt
index a5b7ab5..2980916 100644
--- a/docs/how/mudlib-landscape.txt
+++ b/docs/how/mudlib-landscape.txt
@@ -112,6 +112,14 @@ compiled engine + scripted logic pattern:
   - dragon-mud (go+lua)
   - ataxia (rust+lua)
 
+graphicmud (java)
+  tile-based graphics over telnet via sixel encoding. ECS architecture instead of
+  inheritance. behavior trees for NPC AI. 4-tier action system with automatic
+  dependency chaining. multi-connector: telnet, discord, telegram, websocket, MCP.
+  30+ plugins. symbol system maps each tile to multiple representations (ascii,
+  cp437, unicode, ansi colors, pixel bitmaps) — client capability detection picks
+  the best one.
+
 taleweave-ai (python)
   AI NPCs via LLMs, discord integration, stable diffusion visuals.
 
@@ -248,6 +256,14 @@ continuous/coordinate
   advantages: seamless movement, true spatial relationships
   challenge: rendering continuous space as text
 
+tile graphics (graphicmud)
+  3D tile grid (x, y, z) with toroidal wrap. the unique part: tiles render as
+  actual bitmap graphics via sixel encoding over telnet, not just colored text
+  characters. symbol system gives each tile multiple representations — ascii
+  fallback, cp437 glyph, unicode, ansi colors (16/256/24-bit), and pixel-grid
+  bitmaps. client capability detection picks the richest format supported.
+  standalone symbol editor for creating tile sets.
+
 OUR APPROACH (from dreambook)
   2D toroidal tile grid with terrain types. viewport centered on player. hybrid -
   overworld is grid, interiors can be rooms. this is relatively uncommon in the
@@ -373,6 +389,48 @@ OUR APPROACH (from dreambook)
   content.
 
 
+npc behavior
+-----------
+most muds: simple scripts or state machines. mobs patrol, aggro, flee at low hp.
+
+diku
+  mobprog/mudprog triggers (on_greet, on_fight, on_death). procedural scripts.
+
+lpc
+  NPC code in LPC, full programming language. powerful but requires coding skill.
+
+evennia
+  no built-in NPC system. roll your own with scripts and tickers.
+
+graphicmud
+  behavior trees. hierarchical node structure (sequence, best-effort, action
+  nodes). NPCs make decisions via tree traversal each tick. supports conditional
+  logic, parallel execution, error handling. combat AI: survive, eliminate threat,
+  patrol, assist.
+
+OUR APPROACH (from dreambook)
+  not yet designed. behavior trees worth considering.
+
+
+action architecture
+-------------------
+how commands turn into world changes.
+
+simple (most muds)
+  command handler directly modifies state. "kill goblin" -> find goblin, check
+  conditions, deal damage, all in one function.
+
+graphicmud (4-tier)
+  rawactions (atomic ops) -> cookedactions (single pulse) -> mudactions (multi-pulse
+  with conditions) -> commands (user input). actions automatically chain to resolve
+  dependencies — "attack goblin with sword" generates: walk to sword, pick up,
+  equip, walk to goblin, attack. planning system handles the sequencing.
+
+evennia
+  at_pre_cmd -> parse -> func -> at_post_cmd. hooks at each stage but no
+  automatic chaining.
+
+
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 SECTION 4: protocols
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -590,3 +648,24 @@ the prototype/spawn pattern (evennia, diku zone resets) is how everyone handles
 mob/item templates.
 
 define once, instantiate many.
+
+
+9. entity component system
+---------------------------
+graphicmud uses ECS (composition over inheritance). entities are bags of
+components, archetypes define which components they get.
+
+most MUDs use deep inheritance hierarchies (Object -> Item -> Weapon -> Sword).
+ECS avoids the diamond problem and makes it easier to add cross-cutting features.
+
+worth considering if our entity model gets complex.
+
+
+10. capability-based rendering
+------------------------------
+graphicmud's symbol system — same tile has ascii, ansi, and sixel representations,
+client detection picks the richest — is elegant.
+
+we already adapt to NAWS for viewport size. extending this pattern to rendering
+quality (plain text -> colored text -> graphics) would let us support everything
+from raw telnet to sixel-capable terminals.