Gall Agent

::  === IDENTITY ===
::
+$  session-id   @uv                         ::  unique session token
+$  room-id      @ud                         ::  room identifier
+$  mob-id       @ud                         ::  mob template identifier
+$  instance-id  @uv                         ::  spawned mob/item instance
+$  item-id      @ud                         ::  item template identifier
+$  area-id      @tas                        ::  area short name
+$  quest-id     @ud                         ::  quest identifier
::
::  === ENUMERATIONS ===
::
+$  direction
  $?  %north  %south  %east  %west  %up  %down  ==
::
+$  sector
  $?  %city  %forest  %mountain  %water  %underground
      %indoor  %field  %desert  %road  %swamp  %air
  ==
::
+$  player-class
  $?  %mage  %warrior  %thief  %ranger  %cleric  %paladin  %psionicist  ==
::
+$  player-race
  $?  %human  %elf  %dwarf  %halfling  %orc  %troll
      %gnome  %goblin  %sprite  %centaur
  ==
::
+$  damage-type
  $?  %slash  %pierce  %bash  %fire  %cold
      %lightning  %acid  %poison  %holy  %shadow
  ==
::
+$  item-type
  $?  %weapon  %armor  %potion  %scroll  %food
      %drink  %container  %key  %trash  %other
  ==
::
+$  wear-slot
  $?  %head  %neck  %torso  %arms  %hands  %waist
      %legs  %feet  %finger-l  %finger-r  %wield  %shield
      %wrist-l  %wrist-r  %about  %hold
  ==
::
+$  mob-flag
  $?  %aggressive  %sentinel  %scavenger  %wimpy
      %assist  %shopkeeper  %questmaster  %trainer
      %healer  %banker
  ==
::
+$  room-flag
  $?  %dark  %no-mob  %indoors  %no-recall  %no-magic
      %no-flee  %no-pk  %safe  %pet-shop
  ==
::
+$  combat-state  ?(%idle %fighting %fleeing %dead)
::
+$  char-position  ?(%standing %sitting %resting %sleeping %fighting %dead)
::
::  === STAT BLOCK ===
::
+$  stats
  $:  str=@ud  int=@ud  wis=@ud
      dex=@ud  con=@ud  luck=@ud
  ==
::
::  === CHARACTER CREATION CONSTANTS ===
::
::  Base stat: 10 for all races/classes
::  Free points at creation: 12
::  Max any single stat at creation: 20
::  Formula: base(10) + race_mod + class_mod + player_allocation
::
::  Race modifiers:
::            STR  INT  WIS  DEX  CON  LUCK
::  human:    +0   +0   +0   +0   +0   +0    (versatile, no weaknesses)
::  elf:      -1   +2   +1   +1   -1   +0    (smart and agile, fragile)
::  dwarf:    +1   -1   +0   -1   +2   +1    (tough and lucky, slow)
::  halfling: -1   +0   +1   +2   -1   +1    (nimble, weak)
::  orc:      +2   -2   -1   +0   +2   +1    (brute force, dumb)
::  troll:    +2   -2   +0   -1   +3   +0    (walking tank, very dumb)
::  gnome:    -1   +2   +2   +0   -1   +0    (intellectual, squishy)
::  goblin:   -1   +0   -1   +2   +0   +2    (fast and lucky, weak)
::  sprite:   -2   +1   +1   +2   -2   +2    (glass cannon caster)
::  centaur:  +2   +0   +0   +1   +1   -2    (strong and fast, unlucky)
::
::  Class primary stat bonus (+2):
::  warrior:     +2 STR
::  mage:        +2 INT
::  cleric:      +2 WIS
::  thief:       +2 DEX
::  ranger:      +1 STR, +1 DEX
::  paladin:     +1 STR, +1 WIS
::  psionicist:  +1 INT, +1 WIS
::
::  Stat effects (maps to combat formulas):
::  STR:  +melee damage (STR/5 per hit), carry capacity
::  INT:  +spell damage (INT/4), +max mana (INT * 3 per level)
::  WIS:  +heal power (WIS/4), +mana regen, skill practice efficiency
::  DEX:  +dodge chance (DEX/3 %), +move cost reduction
::  CON:  +max HP (CON * 4 per level), +HP regen, poison/disease resist
::  LUCK: +crit chance (LUCK/10 %), +loot quality, quest reward bonus
::
::
::  === ROOM ===
::
+$  room
  $:  id=room-id
      name=@t
      description=@t
      area=area-id
      sector=sector
      exits=(map direction exit-info)
      flags=(set room-flag)
      coord=(unit coord)                     ::  for mapping (optional — client infers via BFS if absent)
  ==
::
+$  exit-info
  $:  target=room-id
      door=(unit door)                       ::  ~ = open passage, no door
      hidden=?                               ::  hidden exits don't show in exit list until discovered
  ==
::
+$  door
  $:  state=door-state
      key=(unit item-id)                     ::  item required to unlock (~ = no key needed)
      pick-dc=@ud                            ::  difficulty for thief pick lock (0 = unpickable)
      description=@t                         ::  "a heavy iron door"
  ==
::
+$  door-state  ?(%open %closed %locked)
::
+$  coord  [x=@sd y=@sd z=@sd]              ::  signed integers for map position
::
::  === AREA ===
::
+$  area
  $:  id=area-id
      name=@t
      min-level=@ud
      max-level=@ud
      rooms=(set room-id)
      resets=(list reset-cmd)
      reset-interval=@dr                     ::  how often area repopulates
      last-reset=@da                         ::  last reset time
  ==
::
+$  reset-cmd
  $%  [%mob-load mob-id=@ud room=room-id max=@ud]
      [%obj-load item-id=@ud room=room-id]
      [%obj-give item-id=@ud mob-inst=instance-id]
      [%obj-equip item-id=@ud mob-inst=instance-id slot=wear-slot]
      [%door room=room-id dir=direction locked=?]
  ==
::
::  === MOB (NPC/Monster) ===
::
+$  mob-template
  $:  id=mob-id
      name=@t
      short-desc=@t                          ::  "a snarling wolf"
      long-desc=@t                           ::  seen in room
      look-desc=@t                           ::  on examine
      area=area-id
      level=@ud
      =stats
      max-hp=@ud
      damage=@ud                             ::  base damage per hit
      hit-bonus=@ud                          ::  bonus to hit roll
      xp-reward=@ud
      gold-min=@ud
      gold-max=@ud
      =damage-type
      flags=(set mob-flag)
      loot=(list [item-id @ud])              ::  item-id, drop-chance-in-100
  ==
::
+$  mob-instance
  $:  id=instance-id
      template=mob-id
      room=room-id
      hp=@ud
      max-hp=@ud
      =combat-state
      target=(unit session-id)               ::  who it's fighting
      spawn-time=@da
  ==
::
::  === ITEM ===
::
+$  item-template
  $:  id=item-id
      name=@t
      short-desc=@t                          ::  "a rusty sword"
      long-desc=@t                           ::  seen on ground
      look-desc=@t                           ::  on examine
      =item-type
      =item-binding                          ::  loot protection classification
      level=@ud                              ::  minimum level to use
      weight=@ud
      value=@ud                              ::  gold value for shops
      slot=(unit wear-slot)                  ::  where it's worn, if equippable
      weapon-stats=(unit weapon-data)
      armor-stats=(unit armor-data)
      effects=(list effect)
  ==
::
::  Item binding / loot protection
::  Controls whether others can take this item from your corpse.
::  Full design TBD — this is a placeholder classification that will
::  need fleshing out. Considerations:
::    - Quest rewards and achievement items should probably be protected
::    - Common drops and shop-bought gear might be lootable
::    - Cross-world items need special handling (can you even loot
::      something that "belongs" to another world's item system?)
::    - PvP vs PvE death may have different loot rules
::    - World operators should be able to configure loot policies
::    - Some items might be "soulbound" (can never leave your possession)
::    - Citizen items that live on their ship vs guest items that live
::      on the host — different ownership models, different loot rules?
::
+$  item-binding
  $?  %none                                  ::  anyone can loot from corpse
      %protected                             ::  cannot be looted by others
      %soulbound                             ::  cannot be dropped, traded, or looted
  ==
::
+$  weapon-data
  $:  dice-num=@ud                           ::  number of damage dice
      dice-size=@ud                          ::  size of each die
      =damage-type
  ==
::
+$  armor-data
  $:  defense=@ud                            ::  damage reduction
      resistances=(map damage-type @ud)      ::  % resistance per type
  ==
::
+$  effect
  $:  stat=@tas                              ::  which stat/property affected
      modifier=@sd                           ::  signed: +5 or -3
  ==
::
+$  item-instance
  $:  id=instance-id
      template=item-id
      location=item-location
      overrides=(map @tas @t)                ::  fields that differ from template
      ::
      ::  Instances inherit everything from their template.
      ::  The overrides map stores ONLY what's different.
      ::
      ::  90% of instances have empty overrides — a "rusty sword" from
      ::  a mob drop is identical to the template, just with a unique ID.
      ::
      ::  Overrides enable:
      ::    - Enchanted items: {"damage-type": "fire", "name": "Flamebrand"}
      ::    - Quest rewards: {"binding": "protected", "look-desc": "..."}
      ::    - GM-created uniques: {"name": "Excalibur", "short-desc": "...",
      ::        "dice-num": "5", "dice-size": "12", "binding": "soulbound"}
      ::    - Named items: {"name": "Wanderer's Trusty Blade"}
      ::    - Degraded items: {"defense": "8"}  (was 12, worn down)
      ::
      ::  To read an item property:
      ::    check overrides first → fall back to template
      ::
      ::  Override keys match template field names. Values are stored as
      ::  @t (cords) and parsed by type when read. This keeps the map
      ::  generic without needing a typed union for every possible override.
      ::
      ::  Admin commands for creating special items:
      ::    > item-override <instance-id> name "Shadowfang"
      ::    > item-override <instance-id> damage-type "shadow"
      ::    > item-override <instance-id> binding "soulbound"
      ::
      ::  A fully overridden item with no matching template is effectively
      ::  a one-of-a-kind creation — the template just provides defaults
      ::  for any field NOT overridden.
      ::
  ==
::
+$  item-location
  $%  [%room room=room-id]
      [%player session=session-id]
      [%equipped session=session-id slot=wear-slot]
      [%mob inst=instance-id]
      [%nowhere ~]                           ::  despawned / destroyed
  ==
::
::  === PLAYER CHARACTER ===
::
+$  character
  $:  name=@t
      =player-race
      =player-class
      level=@ud
      xp=@ud
      xp-to-level=@ud
      =stats
      hp=@ud
      max-hp=@ud
      mana=@ud
      max-mana=@ud
      moves=@ud
      max-moves=@ud
      gold=@ud
      quest-points=@ud
      room=room-id
      =char-position
      =combat-state
      target=(unit instance-id)              ::  mob instance in combat
      inventory=(list instance-id)
      equipment=(map wear-slot instance-id)
      skills=(map @tas @ud)                  ::  skill-name → proficiency
      cooldowns=(map @tas @ud)               ::  skill → round number when usable
      active-effects=(list active-effect)    ::  buffs/debuffs currently active
      discovered-waypoints=(set room-id)     ::  waypoints this player has found
      last-waypoint-use=@da                  ::  for cooldown tracking
      corpse-locations=(list [world=@p room=room-id])  ::  where your corpses are
      trains=@ud
      practices=@ud
      kills=@ud
      deaths=@ud
      played=@dr                             ::  total time played
  ==
::
::  === SESSION (active connection) ===
::
+$  player-session
  $:  id=session-id
      =player-type
      =character
      connected-at=@da
      last-input=@da
      idle-warned=?
  ==
::
+$  player-type
  $%  [%guest ip-hash=@uv created=@da]
      [%citizen ship=@p]
  ==
::
::  === COMBAT ===
::
+$  combat-round
  $:  attacker=session-id
      defender=instance-id
      round=@ud
  ==
::
::  === MAIL ===
::
+$  mail-message
  $:  id=@ud
      from=@t                                ::  sender name
      from-ship=(unit @p)                    ::  sender @p if citizen, ~ if guest
      to=@t                                  ::  recipient name
      text=@t
      sent=@da
      read=?
  ==
::
::  === BULLETIN BOARD ===
::
+$  board
  $:  room=room-id                           ::  the room this board is in
      name=@t                                ::  "Town Square Notice Board"
      posts=(list board-post)
      max-posts=@ud                          ::  capacity, default 50
  ==
::
+$  board-post
  $:  id=@ud
      author=@t
      author-ship=(unit @p)                  ::  @p if citizen
      subject=@t
      body=@t
      posted=@da
      pinned=?                               ::  pinned posts always show at top
  ==
::
::  === QUEST ===
::
+$  quest-type  ?(%kill %fetch %explore)
::
+$  active-quest
  $:  id=quest-id
      player=session-id
      =quest-type
      target=@t                              ::  mob name, item name, or room name
      target-id=@ud                          ::  mob-id, item-id, or room-id
      area=area-id
      timer=@da                              ::  deadline
      completed=?
  ==
::
::  === SHOP ===
::
+$  shop
  $:  keeper=@ud                             ::  NPC id that runs this shop
      room=room-id
      inventory=(list item-id)               ::  what they sell (templates)
      buy-markup=@ud                         ::  percentage above base value
      sell-markdown=@ud                      ::  percentage below base value
  ==
::
::  === ADMIN DELEGATION ===
::
::  Three roles, flat hierarchy. No per-command granularity.
::  Owner = host @p, always has full access, cannot be revoked.
::  Admins cannot act on other admins — only on regular players/guests.
::  Only the owner can delegate or modify world-config.
::
+$  admin-role  ?(%admin %builder)
::
::  What each role can do:
::
::  owner:   everything
::  admin:   moderate players (mute, boot, ban, restore, snoop, transfer)
::           + all builder powers
::           cannot: set-config, delegate, act on other admins
::  builder: create/edit rooms, mobs, items, areas, shops, spawn, purge, reset
::           cannot: moderate players, set-config, delegate
::
::  === WORLD CONFIG ===
::
+$  world-config
  $:  name=@t
      description=@t
      owner=@p
      max-guests=@ud
      guest-level-cap=@ud
      guest-purge-days=@ud                  ::  days before inactive guest is purged (default 30)
      spawn-room=room-id                    ::  where guests respawn / new players start
      recall-room=room-id                   ::  where %recall sends you (usually same as spawn)
      tick-interval=@dr                      ::  combat tick rate
      regen-interval=@dr                     ::  HP/mana/moves regen rate
      allow-pk=?
      motd=@t                               ::  message of the day
      loot-policy=loot-policy               ::  corpse looting rules
      delegations=(map @p admin-role)        ::  admin/builder delegation
      trusted-worlds=(set @p)               ::  worlds whose XP we respect
      trust-policy=trust-mode               ::  how we handle external XP
  ==
::
+$  trust-mode
  $?  %whitelist-only                        ::  only trust worlds on the list
      %trust-all                             ::  trust everyone (risky)
      %trust-none                            ::  ignore all external XP
  ==

+$  state-0
  $:  %0                                     ::  state version (for migrations)
      config=world-config
      ::  world content
      rooms=(map room-id room)
      areas=(map area-id area)
      mob-templates=(map mob-id mob-template)
      item-templates=(map item-id item-template)
      shops=(map room-id shop)
      ::  live instances
      mob-instances=(map instance-id mob-instance)
      item-instances=(map instance-id item-instance)
      ::  players
      sessions=(map session-id player-session)
      citizen-index=(map @p session-id)      ::  lookup session by @p
      guest-tokens=(map @uv session-id)      ::  lookup session by cookie token
      ::  game state
      active-combats=(set session-id)        ::  sessions currently fighting
      active-quests=(map session-id active-quest)
      ::  communication
      mailboxes=(map @t (list mail-message)) ::  keyed by recipient name
      boards=(map room-id board)             ::  bulletin boards by room
      ::  timers
      last-tick=@da
      last-regen=@da
      ::  admin
      banned-ships=(set @p)
      banned-ips=(set @uv)                   ::  hashed IPs
      ::  counters
      next-quest-id=@ud
      next-mail-id=@ud
      next-post-id=@ud
  ==

Start Behn timer for game tick.
Set default world config.
Load world content (rooms, mobs, items) from initial state or bundled data.
Run all area resets to populate the world.
Bind Eyre endpoint at /mud.

+$  mud-command
  $%  ::  movement
      [%move dir=direction]
      [%look target=(unit @t)]               ::  look, or look <thing>
      [%examine target=@t]
      ::  combat
      [%kill target=@t]
      [%flee ~]
      [%cast spell=@tas target=(unit @t)]
      [%skill skill=@tas target=(unit @t)]
      ::  inventory
      [%get target=@t]
      [%drop target=@t]
      [%wear target=@t]
      [%remove target=@t]
      [%wield target=@t]
      [%inventory ~]
      ::  communication
      [%say text=@t]                         ::  room only
      [%yell text=@t]                        ::  area-wide
      [%tell target=@t text=@t]              ::  direct, both must be online
      [%mail target=@t text=@t]              ::  async DM, stored on host
      [%mail-read ~]                         ::  read your inbox
      [%mail-delete id=@ud]                  ::  delete a message
      [%gossip text=@t]                      ::  world-wide chat
      [%newbie text=@t]                      ::  new player help channel
      ::  bulletin boards
      [%board-read target=(unit @ud)]        ::  list posts, or read specific post
      [%board-post subject=@t body=@t]       ::  post to board in current room
      [%board-remove id=@ud]                 ::  remove your post (or any if admin)
      ::  character
      [%score ~]
      [%who ~]
      [%train stat=@tas]
      [%practice skill=@tas]
      [%equipment ~]                         ::  show equipped items by slot
      ::  group
      [%group-invite target=@t]              ::  invite player to your group
      [%group-accept ~]                      ::  accept pending invite
      [%group-decline ~]                     ::  decline pending invite
      [%group-leave ~]                       ::  leave your current group
      [%group-kick target=@t]               ::  kick member (leader only)
      [%group-leader target=@t]             ::  transfer leadership
      [%gtell text=@t]                       ::  group chat
      ::  trading
      [%give target=@t item=@t]              ::  give item to player in room
      [%give-gold target=@t amount=@ud]      ::  give gold to player in room
      ::  doors
      [%open dir=direction]                  ::  open a door
      [%close dir=direction]                 ::  close a door
      [%unlock dir=direction]                ::  unlock with key in inventory
      [%lock dir=direction]                  ::  lock with key in inventory
      ::  quest
      [%quest ~]                             ::  request auto-quest from quest master
      [%quest-complete ~]
      [%quest-abandon ~]
      ::  corpse
      [%loot target=@t]                      ::  loot %none items from a corpse
      [%retrieve target=@t]                  ::  retrieve your own %protected items
      [%corpses ~]                           ::  list where your corpses are
      ::  travel
      [%waypoint target=(unit @ud)]          ::  list waypoints, or travel to one
      [%recall ~]                            ::  teleport to world's recall-room
                                             ::  costs 50 moves, can't use in combat
                                             ::  citizens: recall sends to world recall-room (NOT home)
                                             ::  to go home: use portal or die
      ::  misc
      [%save ~]                              ::  force save (citizens)
      [%quit ~]                              ::  disconnect
  ==

+$  mud-admin
  $%  ::  player management
      [%goto room=room-id]
      [%transfer session=session-id room=room-id]
      [%force session=session-id cmd=@t]
      [%snoop session=session-id]
      [%restore session=session-id]          ::  full heal
      [%boot session=session-id reason=@t]
      ::  punishment
      [%mute session=session-id duration=@dr]
      [%ban-ship ship=@p reason=@t]
      [%ban-ip ip-hash=@uv reason=@t]
      [%unban-ship ship=@p]
      ::  communication
      [%announce text=@t]                    ::  broadcast to all connected players
      [%immtalk text=@t]                     ::  admin-only private channel
      [%board-pin board=room-id post=@ud]    ::  pin post to top of board
      [%board-unpin board=room-id post=@ud]
      ::  world management
      [%purge room=room-id]                  ::  remove all mobs/items from room
      [%reset-area area=area-id]             ::  force area reset
      [%spawn-mob mob-id=@ud room=room-id]
      [%spawn-item item-id=@ud room=room-id]
      [%set-config config=world-config]
      ::  delegation (owner only)
      [%delegate ship=@p role=admin-role]
      [%undelegate ship=@p]
      [%trust-world ship=@p]                 ::  add to trusted-worlds
      [%untrust-world ship=@p]               ::  remove from trusted-worlds
      ::  building (OLC)
      [%room-create ~]
      [%room-edit room=room-id field=@tas value=@t]
      [%room-exit room=room-id dir=direction target=room-id]
      [%room-delete room=room-id]
      [%mob-create template=mob-template]
      [%mob-edit mob=mob-id field=@tas value=@t]
      [%item-create template=item-template]
      [%item-edit item=item-id field=@tas value=@t]
      [%item-override inst=instance-id field=@tas value=@t]  ::  modify a specific instance
      [%item-unique template=item-id overrides=(map @tas @t) room=room-id]  ::  spawn a one-off
      [%area-create area=area]
      [%area-edit area=area-id field=@tas value=@t]
      [%shop-create shop=shop]
  ==

+$  mud-guest-auth
  $%  [%create name=@t race=player-race class=player-class]
      [%resume token=@uv]
      [%logout token=@uv]
  ==

/game/[session-id]       — primary game feed for this player
                           room changes, combat output, system messages
                           this is the main SSE stream the client reads

/chat/[channel-name]     — channel-specific messages
                           channels: say, tell, gossip, newbie, clan

/online                  — player connect/disconnect events
                           used by the OnlineUsers panel

/ticker                  — game tick pulse (for debug/admin)

/x/mud-world/status                    → world-status
/x/mud-world/config                    → world-config
/x/mud-world/online                    → (list player-summary)
/x/mud-world/room/[room-id]            → room (with contents)
/x/mud-world/room/[room-id]/contents   → (list @t) items and mobs in room
/x/mud-world/area/[area-id]            → area
/x/mud-world/areas                     → (list area-summary)
/x/mud-world/character/[session-id]    → character (full stats)
/x/mud-world/mob/[mob-id]              → mob-template
/x/mud-world/item/[item-id]            → item-template
/x/mud-world/who                       → (list who-entry)
/x/mud-world/quest/[session-id]        → (unit active-quest)
/x/mud-world/map/[session-id]          → (list room-summary) explored rooms

+$  world-status
  $:  name=@t
      owner=@p
      online-count=@ud
      guest-count=@ud
      citizen-count=@ud
      uptime=@dr
      area-count=@ud
      room-count=@ud
  ==
::
+$  player-summary
  $:  name=@t
      level=@ud
      class=player-class
      area=@t                                ::  area name (not room — privacy)
      =player-type
      idle=@dr
  ==
::
+$  who-entry
  $:  name=@t
      level=@ud
      class=player-class
      race=player-race
      title=(unit @t)
      clan=(unit @t)
      idle=@dr
      is-guest=?
  ==
::
+$  area-summary
  $:  id=area-id
      name=@t
      min-level=@ud
      max-level=@ud
      room-count=@ud
  ==
::
+$  room-summary
  $:  id=room-id
      name=@t
      sector=sector
      exits=(map direction room-id)
      coord=(unit coord)
  ==

Every tick (configurable, default 2 seconds):
  1. Process combat rounds for all active combats
  2. Check quest timers (expire overdue quests)
  3. Increment idle timers, warn/disconnect AFK players

Every regen tick (default 30 seconds):
  4. Regenerate HP/mana/moves for all connected players
  5. Run mob AI (wander, aggro checks)
  6. Check hunger/thirst (if implemented)

Every area reset check (every 60 seconds):
  7. Check each area's reset timer
  8. Reset areas that are due (respawn mobs/items)

After processing:
  9. Re-arm Behn timer for next tick
  10. Emit subscription updates for all affected players

Citizen's ship pokes %mud-world to enter the world
  → on-poke processes the join
  → creates session, subscribes citizen to /game/[session-id]

Citizen's ship sends character data for validation
  → on-agent receives the response
  → validates character, creates local session state

If we poke another world (future: cross-world portals)
  → on-agent handles acknowledgments and errors

1. Find session by subscription wire
2. If in combat: mob wins, player "dies" (respawn rules apply)
3. Remove from room's player list
4. Emit "X has left the game" to other players in room
5. For guests: keep character in state (can resume later)
6. For citizens: clean up session, send final character state back to their ship
7. Update online count

GET /mud                → serve index.html (SolidJS app)
GET /mud/assets/*       → serve JS/CSS/images from glob

POST /mud/api/guest/create
  Request:  {"name": "Wanderer", "race": "human", "class": "warrior"}
  Response: {"ok": true, "token": "0v1a2b3c...", "session": "0v4d5e6f..."}
  Sets cookie: mud-session=0v1a2b3c...
  Creates guest character, returns session token

POST /mud/api/guest/resume
  Request:  {"token": "0v1a2b3c..."}
  Response: {"ok": true, "session": "0v4d5e6f...", "character": {...}}
  Resumes existing guest session if character still exists

POST /mud/api/guest/logout
  Request:  {"token": "0v1a2b3c..."}
  Response: {"ok": true}
  Ends guest session (character persists for later resume)

GET /mud/api/status
  Response: {"name": "...", "online": 23, "guests": 15, "citizens": 8, ...}
  Public — no auth required. Used by world directory crawlers.

GET /mud/api/who
  Response: [{"name": "Aragorn", "level": 45, "class": "warrior", ...}, ...]
  Public — online player list for the lobby/login screen

GET /mud/api/areas
  Response: [{"id": "dark-forest", "name": "The Dark Forest", "levels": "10-20"}, ...]
  Public — area listing for world info

PUT  /~/channel/mud-{timestamp}     → poke, subscribe, ack, delete
GET  /~/channel/mud-{timestamp}     → SSE event stream

+$  mud-update
  $%  ::  room updates
      [%room-enter =room players=(list @t) mobs=(list @t) items=(list @t)]
      [%room-desc description=@t]
      [%room-exits exits=(map direction room-id)]
      [%player-enters name=@t]
      [%player-leaves name=@t]
      [%mob-enters short-desc=@t]
      [%mob-leaves short-desc=@t]
      ::  combat
      [%combat-start target=@t]
      [%combat-round lines=(list log-line)]
      [%combat-end victory=? xp=@ud gold=@ud loot=(list @t)]
      [%combat-flee success=?]
      [%you-died ~]
      ::  vitals
      [%vitals hp=@ud max-hp=@ud mana=@ud max-mana=@ud moves=@ud max-moves=@ud]
      ::  character
      [%xp-gain amount=@ud tnl=@ud]
      [%level-up new-level=@ud gains=@t]
      [%gold-change amount=@sd balance=@ud]  ::  signed: +50 or -30
      [%stat-update =stats]
      ::  inventory
      [%item-get name=@t]
      [%item-drop name=@t]
      [%item-wear name=@t slot=wear-slot]
      [%item-remove name=@t slot=wear-slot]
      ::  communication
      [%chat channel=@t from=@t text=@t]
      ::    channel values: "say", "yell", "tell", "gossip", "newbie",
      ::    "announce", "immtalk"
      [%overheard ~]                         ::  "You hear talking nearby..."
      ::    sent to adjacent rooms when someone uses say
      ::  mail
      [%mail-received =mail-message]         ::  new mail (real-time if online)
      [%mail-inbox messages=(list mail-message)]  ::  full inbox on request/login
      [%mail-notification count=@ud]         ::  "You have 3 unread messages."
      ::  bulletin board
      [%board-contents =board]               ::  full board on %board-read
      [%board-post =board-post]              ::  single post on %board-read N
      [%board-updated room=room-id]          ::  notify: board in this room changed
      ::  quest
      [%quest-assigned =active-quest]
      [%quest-complete qp=@ud gold=@ud bonus=@t]
      [%quest-failed reason=@t]
      [%quest-timer-warning minutes=@ud]
      ::  system
      [%system-message text=@t]
      [%motd text=@t]
      [%tick ~]                              ::  heartbeat for client keepalive
      ::  map
      [%map-room =room-summary]              ::  room data for client map cache
      ::  who
      [%online-join name=@t level=@ud class=player-class is-guest=?]
      [%online-leave name=@t]
  ==
::
+$  log-line
  $:  type=@tas                              ::  combat, system, loot, xp, etc.
      text=@t
  ==

{"room-enter": {
  "room": {"id": 42, "name": "The Dark Forest", "sector": "forest",
           "exits": {"north": 41, "east": 43, "south": 45},
           "coord": {"x": 5, "y": -3, "z": 0}},
  "players": ["Aragorn", "Luna"],
  "mobs": ["a snarling wolf", "a forest spider"],
  "items": ["a rusty sword"]
}}

{"combat-round": {
  "lines": [
    {"type": "combat", "text": "Your slash hits the wolf for 15 damage!"},
    {"type": "combat", "text": "The wolf bites you for 8 damage!"}
  ]
}}

{"vitals": {"hp": 85, "max-hp": 100, "mana": 50, "max-mana": 50,
            "moves": 72, "max-moves": 100}}

{"chat": {"channel": "gossip", "from": "Aragorn",
          "text": "anyone want to group for Dark Forest?"}}

::  in on-init:
=/  next-tick  (add now.bowl tick-interval.config.state)
:_  this
[%pass /tick %arvo %b %wait next-tick]~

::  in on-arvo, when /tick wire fires:
++  on-arvo
  |=  [=wire =sign-arvo]
  ?+  wire  (on-arvo:def wire sign-arvo)
    [%tick ~]
      =/  now  now.bowl
      ::  1. process combat rounds
      =.  state  (process-combats state now)
      ::  2. check quest timers
      =.  state  (check-quest-timers state now)
      ::  3. check idle players
      =.  state  (check-idle-players state now)
      ::  4. regen (if regen interval elapsed)
      =?  state  (gte (sub now last-regen.state) regen-interval.config.state)
        (process-regen state now)
      ::  5. mob AI (on regen tick)
      =?  state  (gte (sub now last-regen.state) regen-interval.config.state)
        (process-mob-ai state now)
      ::  6. area resets
      =.  state  (check-area-resets state now)
      ::  7. re-arm timer
      =/  next  (add now tick-interval.config.state)
      :_  this
      [%pass /tick %arvo %b %wait next]~
  ==

For each session in active-combats:
  1. Player auto-attacks mob (see Combat Formulas below)
  2. Mob auto-attacks player
  3. Check mob death:
     - If mob HP <= 0: award XP + gold, roll loot, end combat
  4. Check player death:
     - If player HP <= 0:
       - Create corpse (binding rules apply)
       - If guest: respawn at world spawn-room
       - If citizen AND citizen.ship == our.bowl: respawn at spawn-room (own host)
       - If citizen AND citizen.ship != our.bowl: Ames poke to citizen's ship
         with %mud-portal-exit (reason: %death), drop subscription
  5. Check mob flee (if wimpy flag and HP < 20%):
     - Mob flees to random exit
  6. Emit combat-round update with all log lines
  7. Emit vitals update

+$  skill-def
  $:  name=@tas                              ::  skill identifier
      display-name=@t                        ::  "Magic Missile"
      class=player-class                     ::  which class learns this
      level=@ud                              ::  level when available
      cost-type=?(%mana %moves)              ::  resource consumed
      cost=@ud                               ::  amount consumed
      cooldown=@ud                           ::  rounds before reuse (0 = none)
      target-type=?(%self %ally %enemy %group %room)
      =skill-effect
  ==
::
+$  skill-effect
  $%  [%damage base=@ud stat=?(%str %int %wis) divisor=@ud dtype=damage-type]
      [%heal base=@ud stat=?(%str %int %wis) divisor=@ud]
      [%buff stat=@tas modifier=@sd duration=@ud]
      [%debuff stat=@tas modifier=@sd duration=@ud]
      [%special tag=@tas]                    ::  unique effects handled in code
  ==
::
+$  active-cooldown  [skill=@tas expires=@ud]  ::  round number when available
::
::  Add to character type:
::  cooldowns=(map @tas @ud)                 ::  skill → round when usable
::  proficiencies=(map @tas @ud)             ::  skill → proficiency 0-95
::  active-effects=(list active-effect)
::
+$  active-effect
  $:  name=@t
      stat=@tas
      modifier=@sd
      expires=@ud                            ::  round number
  ==

:: Player attacking mob:
raw_damage  = weapon_base + (STR / 5)
variance    = raw_damage * random(-20, +20) / 100     :: ±20% swing
gross       = (raw_damage + variance) * proficiency_mult

:: Proficiency multiplier (applies to skills and auto-attack weapon proficiency):
::   proficiency 50% (freshly learned) → 0.75x damage
::   proficiency 75% → 1.0x damage (baseline)
::   proficiency 95% (mastered) → 1.15x damage
proficiency_mult = 0.5 + (proficiency / 200)           :: range: 0.75 to 0.975

:: Armor reduction (flat, not percentage):
armor_value = sum of all equipped armor defense values
reduction   = armor_value / 3                          :: armor absorbs 1/3 of its value

:: Resistance (percentage, per damage type):
resist_pct  = defender resistance to this damage type  :: 0-75%, hard capped
resist_amt  = gross * resist_pct / 100

:: Final damage:
net_damage  = max(1, gross - reduction - resist_amt)   :: always deal at least 1

weapon_base = 12 (a 2d6 average sword)
STR         = 18 → STR/5 = 3
raw_damage  = 15
variance    = 15 * (+14%) = +2  (rolled +14 out of ±20 range)
gross       = 17

wolf armor  = 5 → reduction = 1
wolf resist = 0% to slash

net_damage  = max(1, 17 - 1 - 0) = 16

raw_damage  = mob.damage + (mob.str / 5)
variance    = ±20%
gross       = raw + variance
reduction   = player_armor / 3
resist      = player resistance to mob's damage type
net_damage  = max(1, gross - reduction - resist)

wolf raw_damage  = 8
variance         = 8 * (-7%) = -1
gross            = 7

warrior armor    = 15 → reduction = 5
warrior parry    = triggers (65% chance) → 7 * 30% = 2 absorbed
warrior dodge    = doesn't trigger (40% chance)
warrior resist   = 0% to pierce

net_damage       = max(1, 7 - 5 - 2) = 1

crit_chance  = 5 + (LUCK / 10) + skill_bonus     :: base 5%, scales with luck
if random(1, 100) <= crit_chance:
    damage *= 1.5                                 :: 50% bonus damage
    emit "CRITICAL HIT!" message

raw_damage  = spell_base + (INT / 4)
variance    = ±15%                                :: slightly tighter than melee
gross       = (raw + variance) * proficiency_mult :: same proficiency formula as melee

:: Spells bypass physical armor entirely
:: Only magical resistance applies:
resist_pct  = defender resistance to spell's damage type
resist_amt  = gross * resist_pct / 100

net_damage  = max(1, gross - resist_amt)

heal_amount = spell_base + (WIS / 4)
variance    = ±10%                                :: tighter than damage — healing should be reliable
actual_heal = min(heal + variance, max_hp - current_hp)   :: can't overheal

Your slash strikes the forest wolf! [16 damage]
The forest wolf claws at you! [1 damage, parried]
Your slash strikes the forest wolf! [19 damage, CRITICAL!]
The forest wolf is looking pretty hurt.

For each mob instance in the world:
  If mob has %aggressive flag:
    Check if any player in same room
    If player level within aggro range: initiate combat
  If mob has %scavenger flag:
    Check if any items on the floor in same room
    Pick up random item
  If mob does NOT have %sentinel flag:
    Small random chance (5%) to wander to adjacent room
  If mob is in combat and HP < wimpy threshold:
    Attempt to flee

For each area:
  If (now - last-reset) > reset-interval:
    For each reset command in area.resets:
      Execute: spawn mob, place item, lock door, etc.
      Only spawn if current count < max allowed
    Update last-reset timestamp
    Emit repop message to players in area

HP gained   = CON * 4 + class_hp_bonus
Mana gained = INT * 3 + class_mana_bonus
Moves gained = DEX * 2 + 10

Trains gained  = 1 per level (spend to increase stats)
Pracs gained   = 2 per level (spend to learn/improve skills)

HP:    18 * 4 + 8 = 80 HP gained
Mana:  8 * 3 + 0  = 24 mana gained
Moves: 9 * 2 + 10 = 28 moves gained

HP:    8 * 4 + 1  = 33 HP gained
Mana:  20 * 3 + 7 = 67 mana gained
Moves: 12 * 2 + 10 = 34 moves gained

stat_cost = 1 train per +1, up to stat 25
            2 trains per +1, from 26-35
            3 trains per +1, from 36-50

xp_to_level(n) = 100 * n * (1 + n/50)

mob_xp(level) = level * 10 + (level * level / 10)

level_diff = player_level - mob_level

scaling:
  diff <= 5:     100%    :: on-level, full XP
  diff 6-10:      75%    :: slightly below, mild penalty
  diff 11-15:     40%    :: noticeably below
  diff 16-20:     10%    :: gray mobs, barely worth it
  diff 21+:       1 XP   :: token — not zero, but not worth farming

  diff -1 to -5:  120%   :: slightly above, small bonus
  diff -6 to -10: 150%   :: significantly harder, real reward
  diff < -10:     200%   :: danger zone, double XP

quest_xp = player_level * 50    :: scales with you, always relevant

On XP gain:
  if player is guest AND character.level >= world.config.guest-level-cap:
    store XP (it counts if they upgrade to citizen)
    do NOT level up
    emit: "You've reached the limit of what a wanderer can achieve.
           Claim your true name to continue growing."

total_xp = mob_xp * (1 + 0.1 * (group_size - 1))    :: 10% bonus per extra member
split_xp = total_xp / group_size

:: Example: 3 players kill a mob worth 500 XP
:: total = 500 * 1.2 = 600
:: each gets 200 (vs 500 solo — grouping costs XP but has safety/speed benefits)

SYNCHRONOUS (real-time, requires both parties online):

  Room     ← say        "You say, 'hello'"
                         Only players in the same room see it
                         Adjacent rooms get: "You hear talking nearby..."

  Area     ← yell       "You yell, 'anyone around?'"
                         All players in any room in the same area hear it
                         Formatted distinctly: "[Darkwood Forest] Wanderer yells, '...'"

  Direct   ← tell       "You tell Aragorn, 'nice sword'"
                         Private, both must be online
                         If target offline: "Aragorn is not here." (use mail instead)

  World    ← gossip     "Wanderer gossips, 'first time here, any tips?'"
                         All connected players in this world hear it
                         Guests: available after level 5 (anti-spam gate)

  Help     ← newbie     "Wanderer asks, 'how do I equip a sword?'"
                         All connected players hear it, styled for help context

  Admin    ← announce   "[ANNOUNCEMENT] Server maintenance in 30 minutes."
                         Bright, distinct formatting, cannot be muted
                         Admin-only send, all players receive

  Admin    ← immtalk    "Lasher: 'someone's botting in Dark Forest, checking'"
                         Admin-only channel, invisible to players

ASYNCHRONOUS (stored, delivered on login or immediately if online):

  Mail     ← mail       Stored on host world, delivered on next login
                         If recipient online: delivered immediately (feels like tell)
                         Persists across sessions, capped at 50 per player

Wanderer says "hello" in Room 42
  │
  ├── Room 42: all players see "Wanderer says, 'hello'"
  ├── Room 41 (north exit): players see "You hear talking nearby..."
  ├── Room 43 (east exit): players see "You hear talking nearby..."
  └── Room 45 (south exit): players see "You hear talking nearby..."

> mail Aragorn Hey, found a great farming spot in Shadowfen. Let me
  know when you're online and I'll show you.

  "Message sent to Aragorn."
  (If Aragorn is online: delivered immediately as a tell-like notification)
  (If Aragorn is offline: stored, delivered on next login)

> mail
  Your messages:
    1. [unread] From Aragorn (2 hours ago): "Thanks! I'll be on tonight"
    2. [read] From Luna (yesterday): "Can you craft me a leather helm?"
    3. [read] From [System] (3 days ago): "Your quest reward has arrived."

> mail 1
  From: Aragorn
  Date: March 26, 2026 14:32
  "Thanks! I'll be on tonight around 8pm. Meet at Darkwood Bridge waypoint?"

> mail-delete 3
  Message deleted.

Welcome back, Wanderer.
You have 2 unread messages. Type 'mail' to read them.

The Town Square of Aylor

  A weathered stone fountain stands at the center of a bustling square.
  Merchants hawk their wares from colorful stalls, and the smell of fresh
  bread drifts from a nearby bakery.

  A large wooden notice board stands near the fountain, covered in pinned
  notes and official decrees.

  Exits: [north] [east] [south] [west]

> read board
  === Aylor Town Notice Board ===
  [pinned] 1. ANNOUNCEMENT: Dragon sighting near Shadowfen (Admin)
  [pinned] 2. New adventurers: read 'help newbie' for tips (Admin)
           3. LFG Shadowfen Caves tonight — whisper Aragorn (Aragorn, 2h ago)
           4. Selling enchanted leather armor, 500g — mail Luna (Luna, 5h ago)
           5. Has anyone found the secret room in Old Library? (Wanderer, 1d ago)

> read board 3
  === Post #3 by Aragorn ===
  Date: March 26, 2026 18:45
  Subject: LFG Shadowfen Caves tonight

  Looking for 2-3 people to clear Shadowfen Caves. I'm a level 25
  paladin, could use a healer and some DPS. Meet at Darkwood Bridge
  waypoint around 9pm. Mail me if interested.

> post board
  Subject: WTB fire resist gear
  Body: Looking to buy any gear with fire resistance. Heading into
  the Volcanic Depths soon. Mail me with offers. —Wanderer

  Posted to Aylor Town Notice Board.

> group invite Aragorn
  You invite Aragorn to join your group.
  (Aragorn sees: "Wanderer invites you to join their group. Type 'group accept' or 'group decline'.")

> group accept
  You join Wanderer's group.

> group leave
  You leave the group.

+$  group
  $:  id=@uv
      leader=session-id
      members=(list session-id)              ::  ordered, leader first
      loot-policy=loot-rule
      created=@da
  ==
::
+$  loot-rule  ?(%round-robin %free-for-all)
::
+$  group-invite
  $:  from=session-id
      to=session-id
      expires=@da                            ::  auto-expire after 60 seconds
  ==

::  Add to state-0:
  groups=(map @uv group)                     ::  active groups
  player-group=(map session-id @uv)          ::  player → group id
  pending-invites=(map session-id group-invite)  ::  target → pending invite

total_xp = mob_xp * (1 + 0.1 * (group_size - 1))
split_xp = total_xp / group_size

[Group] Wanderer: "ready to pull the boss?"
[Group] Aragorn: "one sec, need mana"

::  Add to mud-update:
[%group-invite from=@t]                      ::  you've been invited
[%group-join name=@t]                        ::  someone joined your group
[%group-leave name=@t]                       ::  someone left your group
[%group-disband ~]                           ::  group disbanded
[%gtell from=@t text=@t]                     ::  group chat message
[%group-info =group]                         ::  full group state (on join/change)

> give sword to Aragorn
  You give a rusty sword to Aragorn.
  (Aragorn sees: "Wanderer gives you a rusty sword.")

> give 500 gold to Aragorn
  You give 500 gold to Aragorn.

::  Add to mud-update:
[%item-given item=@t to=@t]                  ::  you gave something
[%item-received item=@t from=@t]             ::  you received something
[%gold-given amount=@ud to=@t]
[%gold-received amount=@ud from=@t]

+$  door
  $:  state=door-state
      key=(unit item-id)                     ::  item required to unlock (~ = no key needed)
      pick-dc=@ud                            ::  difficulty to pick (0 = unpickable)
      description=@t                         ::  "a heavy iron door"
  ==
::
+$  door-state  ?(%open %closed %locked)

::  Update room type — exits can have doors:
+$  exit-info
  $:  target=room-id
      door=(unit door)                       ::  ~ = open passage, no door
  ==
::
::  Room exits become:
::  exits=(map direction exit-info)           ::  instead of (map direction room-id)

> north
  The heavy iron door is closed.

> open north
  You open the heavy iron door.

> north
  [movement succeeds]

---

> north
  The heavy iron door is locked.

> unlock north
  You unlock the heavy iron door with the iron key.
  (key is consumed if it's a one-use key, or stays if reusable)

> open north
  You open the heavy iron door.

---

> pick north
  You attempt to pick the lock...
  [Thief skill check: DEX + pick_lock proficiency vs door.pick-dc]
  Success: "Click. The lock gives way."
  Failure: "The lock resists your efforts."

{"type": "door", "room": 1012, "dir": "east", "state": "locked"}

::  Add to mud-update:
[%door-state dir=direction state=door-state desc=@t]

> quest
  The Quest Master studies you for a moment.
  "I have a task for you. A shadow wolf has been terrorizing the
   Overgrown Trail. Find it and put it down."

  Quest: Kill a shadow wolf
  Location: Overgrown Trail (Darkwood Forest)
  Time limit: 15 minutes
  Reward: 750 XP, 120 gold, 8 QP

On [%quest ~] poke from player:

1. Check preconditions:
   - Player not already on an auto-quest (one at a time)
   - Cooldown elapsed since last quest (5 minutes)
   - Player is in a room with a questmaster NPC

2. Select quest type (weighted random):
   - %kill (60%): kill a specific mob
   - %fetch (25%): find and bring back an item
   - %explore (15%): visit a specific room

3. Select target based on type:

   %kill:
     - Pick a random mob-template from areas within ±5 levels of player
     - Pick a random room where that mob spawns (from resets or encounters)
     - Target: "Kill [mob short-desc] in [room name] ([area name])"

   %fetch:
     - Pick a random item-template from areas within ±5 levels of player
     - Must be an item that drops from mobs (in loot tables) or spawns in rooms
     - Target: "Find [item short-desc] and bring it to [questmaster name]"

   %explore:
     - Pick a random room in an area within ±5 levels of player
     - Prefer rooms the player hasn't visited (check explored rooms if tracked)
     - Target: "Find your way to [room name] in [area name]"

4. Calculate rewards:
   quest_xp  = player_level * 50
   quest_gold = player_level * 8 + random(0, player_level * 4)
   quest_qp  = 5 + (player_level / 5)

5. Set timer: 15 minutes (configurable per world)

6. Create active-quest, emit [%quest-assigned ...]

+$  auto-quest
  $:  id=quest-id
      player=session-id
      =quest-type                            ::  %kill, %fetch, %explore
      target-name=@t                         ::  "a shadow wolf"
      target-id=@ud                          ::  mob-id, item-id, or room-id
      target-area=area-id
      target-room=(unit room-id)             ::  specific room (for %kill/%explore)
      timer=@da                              ::  deadline
      rewards=auto-quest-rewards
  ==
::
+$  auto-quest-rewards
  $:  xp=@ud  gold=@ud  qp=@ud  ==

> quest
  The Quest Master nods approvingly.
  "Well done. Here is your reward."

  Quest complete! Earned: 750 XP, 120 gold, 8 QP

  Your quest has expired. The Quest Master will have another task
  for you in a few minutes.

  [%quest-failed reason="Time expired"]

> score
  ═══════════════════════════════════════════
   Wanderer the Human Warrior          Level 15
  ───────────────────────────────────────────
   HP: 485/620     Mana: 120/180    Moves: 245/310

   STR: 18    INT: 10    WIS: 10
   DEX: 14    CON: 16    LUCK: 12

   Gold: 2,340           Quest Points: 87
   Trains: 3             Practices: 4
   XP: 12,450 / 24,000   (to next level)

   Kills: 342    Deaths: 5    Quests: 28
   Time Played: 14h 32m
  ───────────────────────────────────────────
   Group: Wanderer's Party (3 members)
   World: ~sneagan-world (Darkwood Forest)
  ═══════════════════════════════════════════

> equipment
  ── Equipped Items ─────────────────────────
   Head:     a leather helm [+3 DEF]
   Neck:     (empty)
   Torso:    chainmail armor [+12 DEF, +5% slash resist]
   Arms:     (empty)
   Hands:    leather gloves [+2 DEF]
   Waist:    (empty)
   Legs:     iron greaves [+6 DEF]
   Feet:     sturdy boots [+2 DEF, +1 DEX]
   Finger L: (empty)
   Finger R: ring of strength [+2 STR]
   Wrist L:  (empty)
   Wrist R:  (empty)
   About:    a shadowhide cloak [+8 DEF, +15% shadow resist]
   Wield:    a steel longsword [3d6 slash, +2 STR]
   Shield:   wooden buckler [+4 DEF]
   Hold:     (empty)
  ──────────────────────────────────────────

   Total Defense: 37 (absorbs 12 per hit)
   Resistances: slash 5%, shadow 15%

::  Add to mud-update:
[%score =character]                          ::  full character data for score display
[%equipment slots=(map wear-slot @t)]        ::  slot → item description string

Player HP reaches 0:

  FOR CITIZENS:
  1. Combat ends. Mob disengages.
  2. Player's corpse appears in the room (contains equipped items — see below)
  3. Emit [%you-died ~] to player
  4. Emit "X has been slain!" to others in room
  5. 3-second delay (dramatic pause, client shows death screen)
  6. Host world pokes citizen's ship: "your player died, respawn them"
  7. Citizen's %mud-character agent receives death event
  8. Player appears in their home world spawn room, full HP/mana/moves
  9. Host world removes player from session/room
  10. Player's subscription to host world ends
  11. Player sees: "You awaken in the familiar comfort of home..."

  FOR GUESTS:
  1. Combat ends. Mob disengages.
  2. Corpse appears (same as citizen)
  3. Emit [%you-died ~]
  4. 3-second delay
  5. Guest respawns at world spawn point (configurable per world)
  6. Full HP/mana/moves restored
  7. Player sees: "The world blurs... you awaken at the crossroads."

+$  item-binding
  $?  %none                                  ::  lootable from corpse, freely tradeable
      %protected                             ::  stays on corpse but only owner retrieves
      %soulbound                             ::  never leaves your person, skips corpse
  ==

+$  corpse
  $:  owner-ship=@p                         ::  citizen @p (for retrieval tracking)
      owner-name=@t
      owner-session=(unit session-id)        ::  session if still connected (guests)
      room=room-id
      lootable=(list instance-id)            ::  %none items — anyone can take
      protected=(list instance-id)           ::  %protected items — owner only
      gold=@ud                               ::  10% of player's gold (lootable)
      created=@da
  ==

The corpse of Wanderer lies here.
  Lootable:  a rusty sword, a leather helmet, 34 gold
  Protected: Blade of the Forest Guardian, Ring of the Lost

> corpses
Your remains can be found at:
  1. The Dark Forest, Room of Shadows (~sneagan-world) — 3 items, 34 gold
  2. Crystal Caverns, Deep Pool (~friend-world) — 1 item, 0 gold

+$  loot-policy
  $?  %standard                              ::  bindings work as described above
      %protected-all                         ::  all items act as %protected (casual/friendly)
      %hardcore                              ::  all items act as %none except %soulbound (full loot)
  ==

+$  waypoint
  $:  id=room-id                             ::  the room that IS the waypoint
      name=@t                                ::  "Darkwood Crossroads"
      area=area-id
      discovered-by=(set @p)                 ::  citizens who've found it
      ::  guests track discovery in their session
  ==

> waypoint
Available waypoints:
  1. Aylor Crossroads (Aylor)
  2. Darkwood Bridge (Darkwood Forest)
  3. Mountain Gate (Granite Peaks)

> waypoint 2
You close your eyes and focus on the memory of Darkwood Bridge...
The world shifts around you.

[movement to Darkwood Bridge room]

::  Add to character type:
+$  character
  $:  ...existing fields...
      discovered-waypoints=(set room-id)     ::  waypoints this player has found
      last-waypoint-use=@da                  ::  for cooldown tracking
  ==

::  Add %waypoint to room-flag:
+$  room-flag
  $?  %dark  %no-mob  %indoors  %no-recall  %no-magic
      %no-flee  %no-pk  %safe  %pet-shop  %waypoint
  ==

::  Add to mud-update:
[%waypoint-discovered name=@t room=room-id]
[%waypoint-travel room=room-id]

1. Client sends poke:
   {command: {kill: {target: "wolf"}}}

2. on-poke receives %mud-command [%kill "wolf"]

3. Validate session (is this player connected?)

4. Find player's current room

5. Match "wolf" against mobs in room:
   - Search mob-instances where room matches
   - Match "wolf" against mob-template short-desc
   - If multiple matches: use first (or ask "which wolf?")
   - If no match: emit error "You don't see that here."

6. Check preconditions:
   - Player not already in combat
   - Player not dead/sleeping
   - Target mob exists and is alive

7. Initiate combat:
   - Set player combat-state to %fighting
   - Set player target to mob instance-id
   - Set mob target to session-id
   - Add session-id to active-combats set

8. Process first round immediately:
   - Player attacks mob (roll hit, roll damage)
   - Mob attacks player (roll hit, roll damage)

9. Emit updates:
   - [%combat-start "a snarling wolf"] to player
   - [%combat-round [...lines...]] to player
   - [%vitals ...] to player
   - [%player-enters "Warrior is fighting a wolf!"] to others in room
     (or however we handle combat visibility)

10. Future ticks continue processing via active-combats set

1. Client sends poke:
   {command: {move: {dir: "north"}}}

2. Validate session

3. Check preconditions:
   - Not in combat (must flee first)
   - Not sleeping
   - Has moves > 0

4. Look up current room's exits for %north
   - If no north exit: "You can't go that way."

5. Move player:
   - Remove from old room's player list
   - Emit [%player-leaves name] to players in old room
   - Add to new room's player list
   - Emit [%player-enters name] to players in new room
   - Decrement moves by 1

6. Send new room to player:
   - [%room-enter room players mobs items]
   - [%vitals ...] (moves changed)
   - [%map-room room-summary] (for client map cache)

7. Check quest triggers for this room:
   - For each active quest on this player:
     - Current step type == %explore AND this room in target-rooms?
       → Mark step complete, emit [%system-message on-complete.text]
       → Unlock next step, update journal
     - Current step type == %interact AND this room is target-room?
       → NPC interaction now available (triggered by talking to NPC)
   - Check encounter triggers for this room

EXPLORE steps:
  Trigger: player enters a target room
  Checked in: movement handler (after room-enter)
  Complete when: all target-rooms visited

KILL steps:
  Trigger: target mob dies while quest active
  Checked in: combat death handler (after mob HP reaches 0)
  Complete when: target mob is dead

FETCH steps:
  Trigger: player picks up / already has N of target item
  Checked in: get-item handler AND on quest accept (might already have them)
  Complete when: count reached

INTERACT steps:
  Trigger: player talks to target NPC in target room
  Checked in: say/dialogue handler when NPC is quest-target
  Complete when: NPC interaction happens

DELIVER steps:
  Trigger: player gives target item to target NPC
  Checked in: give-item handler
  Complete when: item delivered

ESCORT steps:
  Trigger: NPC reaches destination room alive
  Checked in: movement handler (NPC follows player)
  Complete when: NPC in destination room

On step completion:
  1. Mark step in quest-progress.completed-steps
  2. Emit on-complete.text as [%system-message ...]
  3. Set any flags from on-complete.set-flags
  4. If on-complete.unlock-step exists: set quest-progress.current-step
  5. If on-complete.return-to-giver: mark quest as "return to giver"
  6. Update journal: emit [%quest-step-complete step-id journal-text]

On quest turn-in (player talks to quest giver with all steps done):
  1. NPC delivers "complete" dialogue
  2. Grant rewards (XP, gold, QP, items)
  3. Apply world-effects (flags, description changes, NPC relocations, etc.)
  4. Activate followup-quests (if any)
  5. Emit [%quest-complete ...]

1. POST /mud/api/guest/create
   → Generate session-id and guest token
   → Create character with starting stats
   → Place in tutorial room (or world spawn point)
   → Return token and session-id
   → Set cookie

2. Client opens Eyre channel, subscribes to /game/[session-id]

3. Player plays normally via poke/subscription

4. On disconnect (on-leave or explicit quit):
   → Character state preserved in agent state
   → Token remains valid for resume

5. On resume (POST /mud/api/guest/resume):
   → Look up token in guest-tokens map
   → Restore session, resubscribe
   → Player appears where they left off

6. On purge (after N days inactive):
   → Cron-like check on area reset tick
   → Remove guest sessions older than threshold
   → Reclaim the character name

1. Citizen authenticates via Eyre +code (standard Urbit login)

2. Citizen's ship pokes host %mud-world with %mud-portal-enter:
   → Character snapshot + per-world XP credentials
   → Host validates: banned? plausible? meets world rules?
   → Host checks XP credentials against its trust whitelist
   → Host sets local effective level based on trusted XP
   → Creates session with %citizen player-type
   → Places character in last known room (or world spawn)

3. Subscribes to /game/[session-id]

4. Plays normally — all game state tracked by host

5. On disconnect (clean or unclean):
   → Host signs a world-record of everything earned during visit
   → Pokes citizen's %mud-character with the signed record
   → Host RETAINS citizen's world-record in its own state
     (citizen can re-request it if the poke was lost)
   → Session cleaned up, player removed from rooms

6. On reconnect:
   → Citizen sends character snapshot again
   → Host checks for retained world-record, resumes from last state
   → If citizen already has this world's record, picks up where they left off

+$  world-record
  $:  world=@p                               ::  host ship that created this record
      citizen=@p                             ::  player this record belongs to
      timestamp=@da                          ::  when record was last updated
      ::  progression
      xp-earned=@ud                          ::  total XP earned in THIS world
      levels-earned=@ud                      ::  levels gained in THIS world
      quests-completed=@ud
      quest-points-earned=@ud
      kills=@ud
      deaths=@ud
      time-played=@dr                        ::  total time in THIS world
      ::  achievements / game state
      flags=(set @tas)                       ::  world-specific flags: "killed-dragon",
                                             ::  "completed-main-quest", "found-secret-room"
      ::  social
      reputation=@sd                         ::  world's opinion of this player (signed)
      guild-memberships=(list @tas)          ::  guilds/clans joined in this world
      ::  items
      items-held=(list item-snapshot)        ::  items currently in possession from this world
      ::  integrity
      signature=@uv                          ::  host's cryptographic signature over this record
  ==
::
+$  item-snapshot
  $:  id=instance-id                         ::  unique instance identity (persists across worlds)
      template-id=item-id
      template-name=@t                       ::  human-readable, for display in foreign worlds
      overrides=(map @tas @t)                ::  instance overrides
      origin-world=@p                        ::  world that created this item
      =item-binding
  ==

Citizen's ship (~citizen):
  %mud-character agent stores:
    world-records=(map @p world-record)      ::  keyed by world host @p
    ::  One record per world visited. Updated on disconnect.

Host world (~host):
  %mud-world agent stores:
    citizen-records=(map @p world-record)    ::  retained copy for every citizen
    ::  NOT deleted on disconnect. Citizen can re-request.
    ::  Pruned after configurable inactivity period (default 90 days).

1. Citizen presents world-records from all worlds they've visited
2. Host filters: only records from worlds in trusted-worlds set
3. Host sums trusted XP across those records
4. Host applies its own XP curve to determine effective level
5. Citizen plays at that effective level in this world

Example:
  Citizen has:
    ~sneagan-world: 500,000 XP (trusted)
    ~friend-world:  200,000 XP (trusted)
    ~sketchy-farm:  99,999,999 XP (NOT trusted)

  Host sums trusted XP: 700,000
  Host XP curve says 700,000 = level 85
  Citizen enters at effective level 85
  The 99M from the farm world is ignored entirely

Examples for sneagan's world:
  "completed-tutorial"
  "killed-forest-dragon"
  "found-secret-library"
  "completed-main-quest-act-1"
  "allied-with-merchant-guild"
  "betrayed-shadow-council"

::  Citizen entering a world
+$  mud-portal-enter
  $:  ship=@p
      character=character-snapshot
      world-records=(map @p world-record)    ::  all records for host to evaluate
  ==
::
+$  character-snapshot
  $:  name=@t
      =player-race
      =player-class
      =stats
      skills=(map @tas @ud)                  ::  skill proficiencies
      inventory=(list item-snapshot)
      equipment=(map wear-slot item-snapshot)
      total-played=@dr
  ==
::
::  Host responding to entry request
+$  mud-portal-response
  $%  [%admitted session=session-id effective-level=@ud]
      [%rejected reason=@t]
  ==
::
::  Host sending record on disconnect (or on request)
+$  mud-portal-exit
  $:  world=@p
      reason=?(%quit %death %disconnect %kicked)
      =world-record                          ::  signed, updated record
  ==
::
::  Citizen requesting a missed record
+$  mud-record-request
  $:  citizen=@p
      world=@p                               ::  "give me my record from your world"
  ==

Normal disconnect:
  1. Host signs world-record with latest data
  2. Host pokes citizen's ship with %mud-portal-exit
  3. Host retains record in citizen-records map
  4. Citizen's %mud-character applies record to local state
  5. Done

Unclean disconnect (network partition, ship crash):
  1. Host detects dropped subscription (on-leave)
  2. Host signs world-record with latest data
  3. Host attempts poke to citizen — may fail if citizen is offline
  4. Host retains record regardless
  5. When citizen comes back online (to any world):
     → Citizen's ship can poke old hosts with %mud-record-request
     → Host sends the retained record
     → Citizen applies it

Citizen re-entering same world:
  1. Host checks citizen-records for existing record
  2. If found: citizen resumes with their world-specific state intact
     (flags, reputation, guild memberships, waypoints, etc.)
  3. XP is cumulative — new visits add to the existing record

trusted-worlds: {~sneagan-world}   :: initially just itself
trust-policy: %whitelist-only

:: As the ecosystem grows, add trusted community worlds:
:: trusted-worlds: {~sneagan-world, ~friend-world, ~vetted-world}

%mud/
├── app/
│   ├── mud-world.hoon            :: world host agent
│   └── mud-character.hoon        :: citizen character agent
│
├── sur/
│   └── mud.hoon                  :: all shared types (room, mob, item, character, etc.)
│
├── mar/
│   ├── mud/
│   │   ├── command.hoon          :: %mud-command mark
│   │   ├── admin.hoon            :: %mud-admin mark
│   │   ├── guest-auth.hoon       :: %mud-guest-auth mark
│   │   ├── update.hoon           :: %mud-update mark (subscription updates)
│   │   ├── portal-enter.hoon     :: %mud-portal-enter mark
│   │   ├── portal-exit.hoon      :: %mud-portal-exit mark
│   │   ├── portal-response.hoon  :: %mud-portal-response mark
│   │   └── record-request.hoon   :: %mud-record-request mark
│   └── ...
│
├── lib/
│   ├── mud-combat.hoon           :: combat formula library
│   ├── mud-xp.hoon               :: XP curves, level calc
│   └── mud-utils.hoon            :: shared helpers
│
├── sys/
│   └── kelvin                    :: kernel version compatibility
│
├── desk.bill                     :: agents to start on install
├── desk.docket-0                 :: app metadata, glob source, tile config
└── desk.ship                     :: publisher ship

:~
  title+'MUD'
  info+'A Multi-User Dungeon on Urbit'
  color+0x1a.1a2e                            :: our dark navy theme color
  image+'https://[url]/mud-icon.png'
  glob-ames+[~sneagan-ship 0v0]             :: glob served from publisher over Ames
  base+'mud'
  version+[0 1 0]
  website+'https://[mud-website-url]'
  license+'MIT'
==

# 1. Build the SolidJS frontend
cd mud-client/
npm run build                     # → dist/

# 2. Upload to ship via globulator
#    Navigate to http://your-ship:8080/docket/upload
#    Select the %mud desk
#    Choose the dist/ directory
#    Click "glob!"

# Or for HTTP-hosted glob (CDN/S3):
#    Upload dist/ contents to your CDN
#    Use glob-http in docket file instead of glob-ames

index.html
assets/
  index-[hash].js                 :: SolidJS app bundle
  index-[hash].css                :: styles
  favicon.ico

Install %mud desk → starts %mud-world and %mud-character agents
Upload glob → web client served at /mud
Load world content → rooms, mobs, items, areas into %mud-world state
Open for business → guests can visit the URL, citizens can portal in

|install ~sneagan-ship %mud → installs desk, starts %mud-character agent
%mud-character stores: character data, world-records, home world rooms
Player visits any world host's /mud URL → web client connects

Visit https://sneagan-ship.urbit.org/mud in a browser
Web client loads from glob
Create guest character via /mud/api/guest/create
Play. Nothing installed anywhere.

Developer pushes new code to %mud desk on publisher ship
Citizens receive OTA update automatically via Kiln
%mud-character agent migrates state via on-load
%mud-world agent migrates state via on-load (world hosts update separately)

Developer builds new SolidJS bundle
Uploads new glob to publisher ship
Glob propagates to world hosts via Ames (or they re-glob manually)
Players see new UI on next page load — no action required

These are NOT code updates — they're state changes
World host uses admin/builder commands or OLC to add content
No desk update needed, no glob update needed
Content is live immediately

# Start fake ships for testing
urbit -F zod                      # host world
urbit -F bus                      # citizen

# On ~zod: install desk from local
|new-desk %mud
|mount %mud
# copy files into /path/to/zod/mud/
|commit %mud
|install our %mud

# On ~bus: install from ~zod
|install ~zod %mud

# Frontend dev: run vite dev server pointing at ~zod's Eyre
cd mud-client/
VITE_SHIP_URL=http://localhost:8080 npm run dev
# Hot reload on localhost:3000, proxying to ~zod for API calls

# When ready: build and glob
npm run build
# Upload dist/ via globulator