Distributed World Architecture

Status: Early ideation / rough plan Date: 2026-03-26

Core Concept

Every Urbit ship is a world. Not a client, not a player — a world. Your ship hosts your rooms, your NPCs, your rules. Other ships can visit. You can visit theirs.

The MUD isn’t one game on one server. It’s a network of worlds connected by portals, where each world operator controls their own domain.

The Metaphor

Think of it like the web, but for game worlds:

• Your ship is your website — you control the content
• Portals are hyperlinks — they take you to other worlds
• sneagan’s world is the first major destination — the Google of MUD worlds
• Anyone can build a world, just like anyone can build a website
• Some worlds are free, some charge admission

Architecture

What Lives Where

Player's Ship (~player-one)
├── %mud-character agent
│   ├── Character stats, inventory, progression
│   ├── Home world rooms (personal space)
│   ├── Quest log, achievements
│   └── Known portal registry (worlds you've visited)
│
├── %mud-world agent (optional — only if they build a world)
│   ├── Rooms, mobs, items, quests
│   ├── Access control rules
│   ├── Visitor list and permissions
│   └── World metadata (name, theme, level range, description)
│
└── %mud-client agent
    ├── UI state, preferences
    ├── Current location (which world, which room)
    └── Active subscriptions to remote worlds

World Host Ship (~sneagan-ship)
├── %mud-world agent
│   ├── 300+ rooms across multiple areas
│   ├── Mob instances, item spawns, quest state
│   ├── Active visitor tracking
│   ├── Access control (free areas, paid areas, level-gated areas)
│   ├── Game tick / combat loop for visitors
│   └── Economy (shops, drops, quest rewards)
│
└── Visitors connect via Ames subscriptions
    ├── ~player-one: subscribed to room updates in "Dark Forest"
    ├── ~player-two: subscribed to room updates in "Aylor Market"
    └── Actions arrive as pokes, validated by host world

The Trust Model

The host world is authoritative for world state. When you visit my world:

• My world decides what’s in each room
• My world runs combat resolution
• My world controls mob AI, quest logic, loot drops
• My world validates your actions (“can you really cast that spell?”)

Your ship is authoritative for your character. Your stats, inventory, and progression live on your ship:

• You carry your character between worlds
• Your level, skills, and equipment persist
• You can’t lose your character if a world host disappears

The tension: How does a host world trust that your character data is legitimate? (More on this below.)

Cross-World Travel

Player is in their Home World (on their own ship)
  │
  │  "enter portal"
  ▼
Player's client pokes ~sneagan-ship's %mud-world: {action: "enter", character: <char-data>}
  │
  │  Host validates character, checks access
  ▼
Host adds player to visitor list, subscribes them to room updates
  │
  │  Player receives room description, contents, exits
  ▼
Player is now "in" sneagan's world
  │
  │  All commands route to ~sneagan-ship as pokes
  │  All output arrives as subscription updates
  │
  │  "enter portal home"
  ▼
Host removes player from visitor list
Player's client reconnects to local %mud-world
Player is back in their Home World

Web Client & Player Tiers

The Client

The primary interface is a web UI served via Eyre, designed to feel like a modern MUD client in the browser:

• Main pane: Room descriptions, combat output, game text (scrolling log)
• Map panel: Auto-generated area map showing explored rooms, current position, exits
• Status bar: HP/mana/moves, level, current area, combat state
• Online users panel: Who’s in this world right now, their location (area-level, not room-level for privacy)
• Input: Command line at the bottom, with clickable exits/items/mobs where appropriate
• Channels: Tabbed chat panel for say/tell/gossip/newbie/clan
• Responsive: Works on desktop and mobile

This is the only client at launch. No telnet, no custom app. A URL you visit in your browser. Every Urbit running %mud-world serves this client to visitors via its own Eyre.

Two Player Tiers: Guests and Citizens

The critical insight: you shouldn’t need an Urbit to play. The barrier to entry must be as low as “click a link.” But owning an Urbit should be meaningfully better.

Guests (No Urbit Required)

Anyone who visits a world’s web URL can create a guest character — a single-lived, ephemeral identity tied to the Urbit that hosts the world they’re visiting.

How it works:

1. Visit https://[urbit-host]/mud in a browser
2. “Create Guest Character” — pick a name, race, class
3. Play immediately. No account, no download, no Urbit needed
4. Character exists only on the host world’s ship — stored in the %mud-world agent’s state
5. Session tracked by browser cookie / token

Guest restrictions:

Why this matters:

• Zero barrier to entry — anyone can try the game from a link
• Natural conversion funnel: “You’ve hit level 30. Get an Urbit to keep going.”
• Guest characters are cheap for the host — they’re just state in the world agent
• Guests provide population, making the world feel alive for citizens too
• The host Urbit bears the cost of storing guest state — an incentive to set reasonable limits

Guest lifecycle:

• Created on a specific host world — that world’s ship stores the character
• If the guest doesn’t connect for N days (configurable by host, default 30), character is purged
• Guest cannot transfer to another world — they exist only where they were created
• A guest who gets an Urbit can “claim” their guest character, migrating it to their ship and lifting all restrictions (one-time upgrade path)

Citizens (@p Identity)

Players with their own Urbit get the full experience:

• Persistent character on their own ship
• Cross-world travel via portals
• Home world with personal rooms
• All channels, clans, social features
• No level cap
• Character survives world host downtime
• Reputation that follows them across worlds
• Building and world creation tools

Guest Tracking & Moderation

Guests are tracked by the host Urbit, not by a central authority:

Guest character state (stored on host world's ship):
├── guest-id: unique token (browser cookie)
├── created-at: timestamp
├── last-seen: timestamp
├── name: "Wanderer"
├── character data: race, class, level, stats, inventory
├── ip-hash: salted hash for abuse tracking (not stored raw)
├── host-world: ~sneagan-ship (the world that created this guest)
└── restrictions: {level-cap: 30, channels: [say, newbie], no-portal: true}

Moderation for guests:

• Host world operator can ban guest tokens (blocks that browser)
• IP-hash based rate limiting prevents mass guest creation
• Guests start with limited communication (no gossip/tell until level 5 — reduces spam)
• Guest names are clearly marked: [Guest] Wanderer vs Wanderer — players know who’s ephemeral
• Bad behavior by a guest has no long-term consequence for the guest (they can make a new one) — but this is mitigated by rate limiting and the limited feature set

The conversion hook:

The guest experience should be genuinely fun but leave players wanting more. Natural friction points that encourage getting an Urbit:

• Level 30 cap: “You’ve mastered the basics. To continue your journey, claim your identity.”
• Can’t keep items between sessions: “Your hard-won Sword of Flames will be here when you return… if you claim your identity.”
• Can’t join clans: “The Crimson Order would welcome you… if you had a name they could trust.”
• Can’t visit other worlds: “A portal shimmers before you, leading to distant lands… but only those with a true name may pass.”

These aren’t annoying paywalls — they’re narrative-appropriate limitations. Guests are literally unnamed wanderers. Getting an Urbit is claiming your identity in the world.

Architecture Implications

Host Ship (~sneagan-ship)
├── %mud-world agent
│   ├── World state (rooms, mobs, items, quests)
│   ├── Citizen visitors (via Ames subscriptions from their ships)
│   │   └── Authenticated by @p — character data on their ship
│   ├── Guest characters (stored locally)
│   │   └── Authenticated by session token — character data here
│   └── Eyre endpoints
│       ├── /mud — Web client (HTML/JS/CSS)
│       ├── /mud/api — Game commands (pokes via HTTP for guests, Ames for citizens)
│       ├── /mud/sse — Real-time updates (SSE stream)
│       └── /mud/guest — Guest character creation/login

Two connection paths:

• Citizens: Connect from their ship via Ames. Pokes and subscriptions. Full Urbit networking.
• Guests: Connect via HTTP/SSE through Eyre. Pokes via REST API. Session-based auth.

Both paths hit the same game engine — the %mud-world agent doesn’t care how you connected, just whether you’re a guest or citizen. The difference is in permissions and where character data lives.

The New Player Experience

Path A: Urbit Owner

1. Install %mud on your ship
2. Wake up in your Home World — a small, empty room
3. A glowing portal stands before you: "The World of [sneagan's world name]"
4. Step through → arrive in sneagan's Tutorial Area
5. Tutorial teaches:
   a. Movement (rooms, exits, look)
   b. Combat (basic mob, auto-attack, skills)
   c. Questing (first quest from a quest master)
   d. Communication (say, channels)
   e. Portals (how to travel between worlds)
   f. Home (how to return to your own world)
6. Tutorial ends: "You've learned the basics. Return home and prepare."
7. Portal back to Home World
8. Home World now has:
   - A room with basic equipment
   - A portal back to sneagan's world (now leading to the main game, not tutorial)
   - A "World Directory" object listing known public worlds
   - A "Build" command hint for creating your own rooms
9. Player chooses: explore sneagan's world, try another world, or start building

Path B: Guest (No Urbit)

1. Click a link to sneagan's world (or any world's URL)
2. "Welcome, stranger. What shall we call you?" — name, race, class selection
3. Spawn directly in the Tutorial Area (no home world)
4. Tutorial teaches movement, combat, questing, communication
5. Tutorial does NOT teach portals or home world (guest can't use them)
6. Tutorial ends: "You are ready, wanderer. The world awaits."
7. Released into the free areas (levels 1-30)
8. Play, explore, fight, quest — full experience within the free tier
9. At level 30: "You've proven yourself. But to go further, you must claim your true name."
10. Option to get an Urbit and upgrade, or keep playing at level 30

Why Both Paths Matter

• Path A is the ideal experience — full ownership, full features
• Path B is the discovery experience — zero friction, try before you buy
• Path B players populate the world, making it feel alive for Path A players
• Path B is also a demo for Urbit itself — “this is what you can do with your own ship”
• The conversion from B→A isn’t just about the MUD — it’s an onramp to Urbit

Why This Loop Matters

• Teaches the core mechanic: worlds are places you visit, not where you live
• Establishes home base: your ship is yours — always there, always safe
• Introduces the network: you’re not trapped in one game
• Low commitment entry: tutorial is short, focused, gets you playing fast
• Hooks them: after tutorial, the full world is one portal away
• Urbit onramp: the MUD becomes a reason to get an Urbit

sneagan’s Flagship World

Role

The first, largest, and most polished world in the network. This is where most players will spend most of their time, especially early on. It’s the Aardwolf to our Urbit MUD ecosystem.

Content

Drawing from our Aardwolf research:

• Multiple continents/areas spanning level 1-200+
• Quest system (auto-quests, campaigns, area goals)
• Class/race system with deep progression (remort/tier inspired)
• Clans (cross-world social organizations?)
• Economy (gold, quest points)
• Regular events and new content

Access Model Options

The free tier is critical — players must be able to experience the game before paying. The tutorial and early-game areas need to be genuinely fun, not a demo that nags you to upgrade.

Business Model: Worlds as Products

The Creator Economy for MUDs

Anyone with an Urbit ship can build a world. Some will be free passion projects. Some will charge admission. This creates a marketplace of experiences:

• sneagan’s world: The flagship. Large, polished, Aardwolf-inspired. Paid access for full content.
• Community worlds: Fan-built areas — some free, some paid. Horror dungeons, puzzle worlds, PvP arenas, social spaces.
• Commissioned worlds: Builders-for-hire creating custom worlds for operators who want content but can’t build it themselves.

Payment Mechanisms

On Urbit, payment options include:

• Stars/planets: Urbit-native value transfer
• Bitcoin/crypto: Via Urbit payment channels if available
• Subscription: Monthly access via recurring payment
• One-time unlock: Pay once, access forever
• Per-area unlock: Free world, paid premium dungeons (IRE model without the pay-to-win)
• Tip jar: Free access, voluntary support

What You’re Paying For

This is important to get right. Players should feel they’re paying for content, not power:

Good (content access):

• Entry to new areas with unique stories, mobs, quests
• Access to exclusive narrative arcs
• Cosmetic customization options
• Housing/building in premium zones

Bad (pay-to-win):

• Stat-boosting items only available for money
• Level skips or XP boosts
• Combat advantages purchasable with cash
• Anything that makes paying players mechanically stronger

The IRE lesson: Pay-to-win works financially but creates persistent community tension. With Urbit’s near-zero operating costs, we don’t need aggressive monetization. Charge for access to content, not for power.

Revenue Split (If Ecosystem Grows)

If multiple world creators are charging for access:

• World creator keeps revenue from their world
• No platform tax (decentralized — no middleman)
• Optional: protocol-level tip to core developers? (community decision)

Character Portability

The Hard Problem

When a player brings their level 150 character from sneagan’s world into someone else’s level 1-50 world, what happens?

Options:

1. Host world scales the visitor: Your stats are temporarily adjusted to fit the world’s level range. You keep your skills but damage/HP are scaled. (Like level sync in FFXIV.)

2. Host world sets its own rules: Each world declares what character data it accepts. A low-level world might cap visitors at level 50. A PvP arena might standardize all stats.

3. Character data is advisory: Your ship says “I’m level 150 with 500 STR.” The host world can choose to trust that, verify it, or ignore it.

4. Progression is world-specific: Your character has a “global level” (portable) and “world-specific progress” (local to each world). Visiting a new world means starting fresh in that world while keeping your global identity.

Recommended Approach: Trust + Verification

Player enters world:
1. Player's ship sends character snapshot to host
2. Host checks:
   a. Is this @p on any known cheat lists? (community reputation)
   b. Does the character data look plausible? (level 150 with 10 hours played = suspicious)
   c. Does it comply with this world's rules? (level cap, allowed classes, etc.)
3. Host applies its own scaling/rules
4. Player enters world with adjusted stats
5. Any progression earned IN this world is tracked by the host
6. When player leaves, host sends progression update to player's ship

Anti-Cheat via @p Identity

Traditional MUDs can’t solve character integrity because players can make throwaway accounts. On Urbit:

• Your @p is your permanent identity
• Cheating on one world can get you banned from others (reputation propagates)
• Character data can be cryptographically signed by the world where it was earned
• “I earned level 150 in ~sneagan’s world” is a verifiable claim if sneagan’s world signs it

World Building for Operators

The Minimum Viable World

When someone installs %mud on their ship, they should be able to:

1. Immediately play: Visit other worlds, explore, fight, quest
2. Easily build: Create rooms, describe them, link them, add mobs
3. Optionally publish: Make their world visible in the directory, set access rules

Building Interface

Two approaches (both should exist):

In-game OLC (traditional):

> redit create
New room created. You are now editing Room #1.
> redit name The Rusty Anchor
> redit desc A cramped tavern smelling of salt and old wood. Fishing nets
  hang from the low ceiling, and a single candle gutters on the bar.
> redit exit north 2
Exit north now leads to Room #2.
> done
Room saved.

Web-based builder (modern, accessible):

• Visual map editor — click to create rooms, drag to connect
• Form-based room/mob/item editing
• Preview mode — see the room as a player would
• Served via Eyre from the player’s own ship
• Could integrate with the web game client

World Metadata

Each world publishes metadata so players can find it:

World: "The Sundered Isles"
Host: ~sneagan-ship
Theme: High fantasy adventure
Level Range: 1-200
Areas: 47
Players Online: 23
Access: Free (levels 1-30), Paid (full)
Rating: ★★★★☆ (player-rated)
Tags: [quest-heavy, group-content, pvp-optional]
Description: "A vast archipelago torn apart by ancient magic..."

World Directory

A decentralized directory of published worlds:

• Each world host publishes metadata to a shared index
• Players browse/search/filter from their client
• Ratings and reviews from visitors
• “Featured” worlds curated by community
• Could use a dedicated %mud-directory agent or integrate with existing Urbit discovery

Death Sends You Home

When a citizen dies in any world, they respawn in their own Urbit’s home world. This is a core mechanic with cascading design benefits:

For the player:

• Home becomes meaningful — worth decorating, even if you never build a full world
• Death has real consequence (lost position) without being punishing (no level/stat loss)
• Corpse stays where you died — your gear is recoverable
• Fast-travel waypoints soften the trip back

For the ecosystem:

• Reinforces that worlds are places you visit, not where you live
• Creates a natural rhythm: home → portal → adventure → death → home → portal again
• Players who customize their home room become more invested in the platform
• Guests can’t go home (they don’t have one) — they respawn at world spawn instead, which is another reason to get an Urbit

Cross-world death flow:

Citizen dies in ~sneagan's world
  → ~sneagan's %mud-world emits [%you-died ~] to player
  → ~sneagan's %mud-world pokes citizen's ship: [%death-event corpse-data]
  → Citizen's %mud-character receives death, respawns player in home room
  → Citizen's subscription to ~sneagan's world ends
  → Corpse persists on ~sneagan's world indefinitely (no timer)
  → Citizen re-enters ~sneagan's world via portal, uses waypoint, walks to corpse
  → Items only auto-return if host wipes the world

See DESIGN-gall-agent.md for full death penalty table, corpse system, and fast-travel waypoint spec.

Technical Concerns

Latency

Cross-ship communication via Ames adds latency. For a MUD this is mostly fine:

• Room descriptions, inventory, score — latency-tolerant
• Chat messages — latency-tolerant (people expect slight delay)
• Combat rounds (2-4 second ticks) — plenty of time for round-trip
• Real-time PvP (Achaea-style sub-second balance) — might be too tight

Mitigation: Design combat around 2-4 second ticks, not sub-second timing. This is the DikuMUD/Aardwolf model, not the Achaea model.

State Consistency

When a player is in a remote world:

• Player actions are pokes to the host
• Host processes and sends updates
• Race conditions: two players act simultaneously → host resolves in order received
• If host goes offline → players get disconnected from that world, return home

Scalability

How many visitors can one world host handle?

• Each visitor = one Ames subscription + poke processing
• Text MUDs are low-bandwidth — room descriptions are small
• Game tick processing scales with active visitors
• Estimate: A single ship could probably handle 50-200 concurrent visitors before performance degrades
• Scaling: Split world across multiple ships (continents on different hosts)

Offline Worlds

What happens when a world host’s ship goes down?

• Players in that world get disconnected
• They return to their home world automatically (client handles this)
• Character data is safe (lives on player’s ship)
• World-specific progress may need to be re-synced when host comes back
• This is actually better than traditional MUDs — in a traditional MUD, if the server goes down, everyone loses access. Here, only visitors to that specific world are affected.

Phase Plan

Phase 0: Foundation

• %mud-world agent on sneagan’s ship (rooms, mobs, items)
• Web UI via Eyre: room display, map panel, online users, status bar, command input
• Guest character support: create-and-play from browser, no Urbit required
• Basic commands: look, move, get, drop, inventory, say
• Guest character persistence (stored on host ship)
• SSE for real-time game output

Phase 1: Playable Single World

• Combat system (auto-attack + skills, 2-4 sec ticks)
• Character progression (XP, leveling, stats)
• Race and class selection at character creation
• Starter areas (levels 1-30, free for guests)
• Auto-quest system from quest masters
• NPC shops, basic economy (gold)
• Tutorial area
• Newbie channel + say
• Online users list with area-level locations
• This is the “try it in your browser” milestone

Phase 2: Urbit Citizen Support

• %mud-character agent on player’s ship (persistent character)
• Ames-based connection (citizens connect ship-to-ship)
• @p-authenticated players alongside guest players
• Citizen features: all channels, no level cap, persistent inventory
• Guest → Citizen upgrade path (claim your guest character)
• Home world: personal room on player’s ship with portal to sneagan’s world

Phase 3: Depth

• More areas (levels 30-100+)
• Remort/tier progression system
• Equipment system (wear, wield, enchant)
• Clan system
• Quest Points currency
• Area goals
• Builder OLC for sneagan’s world content

Phase 4: Multi-World Protocol

• Portal protocol: cross-ship world travel for citizens
• World directory / discovery
• Any ship can publish a world
• Character portability with trust/verification
• World metadata and ratings
• Tutorial teaches portal mechanic

Phase 5: Economy & Ecosystem

• Access control (free/paid tiers per world)
• Payment integration
• Web-based world builder tool
• World templates / starter kits
• Shared mob/item libraries
• Cross-world clans and social organizations

Open Questions

1. Character progression authority: Should progression be signed by the world where it was earned? How much do we trust remote character data?

2. Cross-world items: If I earn a sword in World A, can I bring it to World B? How does World B know the sword’s stats are legitimate? Does World B even support that item?

3. Cross-world communication: Should chat channels span worlds? If you’re in sneagan’s world and your friend is in someone else’s world, can you still talk?

4. World templates: Should we ship a “starter world” template that operators can customize? What’s in it?

5. Grief worlds: What stops someone from building a world designed to trap or exploit visitors? (Answer: @p reputation + ability to always portal home + community ratings)

6. Data format standardization: All worlds need to agree on character data format, portal protocol, trust verification. This is essentially an API standard / mark definition.

7. Combat across worlds: If two worlds have different combat rules, what happens when a player switches? Do they need to re-learn?

8. Shared NPCs/mobs: Could worlds share mob definitions? A “goblin” from the standard library behaves the same everywhere?

9. Guest storage limits: How many guest characters can a world host reasonably store? What’s the purge policy? Should hosts set a cap?

10. Guest abuse: Guests can create throwaway characters. Rate limiting by IP hash helps, but what about VPNs? Is the limited feature set (no gossip, level 30 cap) enough to make abuse not worth the effort?

11. Guest-to-citizen migration: When a guest claims their character with an @p, how does the data transfer? Does the host sign the character data and send it to the player’s ship? What about guest characters on multiple worlds?

12. Urbit onboarding: The MUD is an onramp to Urbit. Should we integrate Urbit planet purchasing / hosting setup into the conversion flow? Partner with a hosting provider?

13. Web UI framework: React via create-landscape-app? Or something lighter? The map panel and real-time updates need to be snappy. SSE vs WebSocket for the game feed.

The Vision

This isn’t just a MUD. It’s a protocol for interconnected text worlds running on a decentralized identity network.

Every Urbit ship becomes a potential game world. The network of worlds grows organically — some hobbyist experiments, some polished adventures, some social spaces, some PvP arenas. Players carry their identity and reputation across all of them.

sneagan’s world is the anchor — the first great destination, the proof that the system works. But the long-term value is the network itself.