MUD Writing Craft

Reference guide for writing room descriptions, NPC dialogue, item text, and building areas for text-based games. Compiled from builder guides, MUD style documents, and community knowledge.

1. Room Description Writing

Voice, Tense, and Perspective

The standard for MUD room descriptions is third person, present tense, with no direct references to the player. This is the single most universally agreed-upon rule across MUD building communities.

Do not:

You are standing in a dimly lit tavern. You notice a fire crackling
in the hearth.

Do:

A dimly lit tavern stretches out beneath smoke-darkened rafters.
A fire crackles in a stone hearth along the eastern wall.

The “you” perspective breaks in multiple contexts: when a player is scrying from afar, when they’re sitting rather than standing, or when the room description is viewed from an adjacent room. Third-person descriptions remain accurate regardless of how the player encounters the text.

Similarly, never dictate player actions or emotions. “The sight takes your breath away” assumes a reaction the player hasn’t chosen. “A vista sprawling enough to take one’s breath away” leaves that to them.

Length

There is no universal right answer — length depends on audience.

The Discworld MUD recommends 50-80 words per room. CircleMUD’s builder manual suggests most rooms should be under 6 lines, with the average around 3-4. If a description takes more than a few seconds to parse, most players will skip it entirely.

Unless a room is plot-critical or a major landmark, err on the side of brevity.

Sensory Details

Good room descriptions engage more than sight. The five senses framework:

• Sight: Lighting, colors, visual features at both close and far range
• Sound: Water, wind, crowd noise, machinery, birdsong, silence
• Smell: Distinguish “odor” (negative), “aroma” (positive), “scent” (neutral)
• Touch: Temperature, humidity, ground texture, air quality
• Taste: Salt spray, metallic tang, dust — often pairs with smell

Weak:

The forest is dark and gloomy.

Strong:

Hardly any light filters through the dense forest canopy, creating
wells of shadow amid the trees' craggy trunks. The air hangs heavy
with the smell of wet loam and rotting leaves.

The first tells. The second shows. “Show, don’t tell” is the foundational writing principle for MUD descriptions.

Conveying Atmosphere Through Word Choice

Words carry emotional weight beyond their literal meaning. Use this deliberately:

• “Cozy” instead of “small” (warmth vs. confinement)
• “Looms” instead of “stands” (menace vs. neutral)
• “Dangles” instead of “hangs” (precariousness)
• “Meanders” instead of “goes” (laziness, tranquility)

Active verbs create more vivid imagery than passive constructions. “A shelf dangles from the north wall by a single rusted nail” works harder than “There is a shelf on the north wall.”

Position modifiers close to what they modify: “The river slowly meanders eastward through the village” flows better than “The river meanders through the village slowly to the east.”

Day/Night Variations

Some MUDs implement dynamic descriptions that change with time of day. The Discworld MUD handles this through layered description lines:

• A weather line reports temperature, season, time of day, wind, cloud cover, and precipitation
• Ambient lines change based on context — crowd density on streets, what’s underfoot in forests, atmosphere in buildings
• Transitions happen in stages: morning arrives first as a weather-line change, then a few minutes later the sun rises with the sky beginning to lighten

If your engine supports it, consider at minimum:

• Day vs. night lighting descriptions
• Dawn/dusk transitional text
• Weather-dependent atmosphere lines
• Seasonal variation for outdoor rooms

If it doesn’t, write descriptions that are time-neutral: “Torches line the walls” works day or night, while “Sunlight streams through the windows” does not.

Common Mistakes

1. Describing mobs in room text. If you write “A grizzled blacksmith hammers at his anvil” as part of the room description, it persists after the blacksmith is killed. Use the mob’s own long description instead.

2. Mentioning nouns without examinable details. If the description references a fountain, players will try to look at the fountain. Always add extra descriptions (add_items, extra descs) for every noun you mention — including nouns within those extra descriptions.

3. Using relative directions. “The path stretches ahead” and “to your left” assume the player entered from a specific direction. Use cardinal directions: “The path continues north” or “A door stands in the western wall.”

4. Command hints in descriptions. “You can BUY and SELL items here” breaks immersion. If you need to convey shop functionality, use an in-world sign: “A chalkboard behind the counter lists prices in a cramped hand.”

5. Color abuse. Color in room descriptions is distracting, inconsistent across clients, and inaccessible to screen readers. The general consensus is: don’t use it, or use it extremely sparingly.

6. Boring hallways. Hallways are tedious to write and traverse. Either skip them (connect rooms directly) or give them a dual purpose — a noticeboard, a window with a view, accumulated memorabilia.

7. Repetitive uniform rooms. When an area demands many similar rooms (forest paths, dungeon corridors), vary the minor details room by room. Different moss patterns, a particular root formation, a shaft of light, water stains.

Examples of Good Room Descriptions

Tavern interior (exploration-focused):

The Broken Drum
Sawdust crunches underfoot in this low-ceilinged taproom, its
rafters blackened by decades of pipe smoke and tallow. Battered
tables crowd the floor in no discernible pattern, each one bearing
the scars of old knife games. A long oak bar runs along the south
wall, its surface worn smooth by a thousand sliding tankards.

Wilderness (action-focused, shorter):

Rocky Streambed
A shallow stream cuts through loose grey stone here, its water
clear enough to reveal the gravel bottom. The banks rise steeply
to the north and south.

Dungeon (atmospheric):

Dank Cellblock
Water seeps down the walls in thin rivulets, pooling in the
cracks between uneven flagstones. Three iron-barred cells line the
eastern wall, their doors hanging open on rusted hinges. The air
tastes of copper and old stone.

2. NPC/Mob Descriptions and Behavior

Short vs. Long Descriptions

Mobs typically have multiple text fields:

Short descriptions should be a noun phrase without a period — they get inserted into sentences like “The city guard hits you with his pike” or “You give the gold coin to the city guard.”

Long descriptions appear in room listings. They should be one line, ending with a period. Write them as if describing what you’d see glancing at the room. Avoid starting every mob with “A [creature] is here” — vary the structure.

Examine text is where you paint the full picture.

Making NPCs Feel Alive

The Discworld guide for NPC descriptions emphasizes deriving physical traits from function:

• A blacksmith displays muscled forearms and old burn scars
• A veteran bears a short-cropped head and a thin scar across one cheek
• A noble carries herself with practiced posture and manicured hands
• A street urchin has dirt-caked fingernails and quick, darting eyes

Consider what a character’s daily life does to their body. This is more compelling than a list of generic features.

Avoid describing clothing on NPCs if your game allows theft — players stripping the mob’s gear will create contradictions with a description that mentions a “fine silk doublet.”

Dialogue Systems

NPC dialogue generally falls into three categories:

Keyword-triggered speech: The NPC responds to specific words in player speech. A quest-giver might respond to “quest,” “help,” or “task.” Keep keyword lists comprehensive — accept synonyms and variations.

Speech triggers with pattern matching: More sophisticated systems use regex or wildcard matching. The NPC listens for patterns in say, tell, or whisper commands and responds contextually.

Ambient dialogue: Unprompted statements the NPC makes on a timer or random trigger. These don’t require player interaction and build atmosphere passively.

Mob Echo Messages (Random Acts)

Echo messages are the simplest and most effective way to make a world feel lived-in. They’re random messages broadcast to the room at intervals.

Types of echo messages:

• Say (NPC speaks): The barkeep mutters, 'Another quiet night.'
• Emote (NPC acts): The cat stretches languorously across the windowsill.
• Room echo (environmental): A cold draft rattles the shutters.

Implementation varies by codebase but typically uses a random trigger with a probability weight. A rand_prog with a value of 5 means approximately a 5% chance per mob pulse of firing. Keep probabilities low (2-8%) — NPCs that chatter every few seconds become annoying rather than immersive.

Good echo messages:

The old woman rocks slowly in her chair, humming a tuneless melody.
The blacksmith pauses to wipe sweat from his brow with a soot-stained rag.
A rat scurries along the base of the wall and vanishes into a crack.
The guard shifts his weight and stifles a yawn.

Bad echo messages:

The guard guards the area.
The shopkeeper is here.
Nothing happens.

Schedule-Based Behavior

More advanced NPCs change behavior based on in-game time:

• A shopkeeper opens the store at dawn and closes at dusk
• A guard patrols during the day and sleeps in the barracks at night
• A priest leads prayers at specific hours
• A farmer works the fields by day and drinks at the tavern by night

This creates the illusion of routine and a world that continues without the player.

3. Item Descriptions

Equipment Descriptions

Like mobs, items have multiple text fields:

Ground descriptions (long desc) should imply the item is on the ground or otherwise at rest. “A battered shield leans against the wall” is better than “A battered shield.”

Examine Text

This is your chance to reward the curious player. A good examine description includes:

• Physical details (material, craftsmanship, condition, size)
• History hints (wear patterns, inscriptions, maker’s marks)
• Functional clues (a blade that “hums faintly” might be magical)

Example:

This longsword has seen better days. The leather wrapping on the
hilt is worn thin, exposing the wire beneath, and several nicks
mark the fuller. But the edge remains keen, and the steel carries
a faint bluish sheen that is hard to dismiss as mere reflection.
Etched into the crossguard in tiny letters: 'Forged in Kael-Dur.'

One paragraph is usually enough. Resist writing an essay — let the player’s imagination do work.

Identifying Magical Items Through Description

A well-designed MUD uses description as the first tier of item identification, before any identify spell or skill:

Unidentified (what the player sees):

• Unusual material: “The ring is carved from a single piece of bone, yet it is warm to the touch.”
• Strange behavior: “The blade hums faintly when drawn from its scabbard.”
• Exceptional quality: “Despite its apparent age, the chainmail shows not a single spot of rust.”
• Inscriptions and runes: “Strange symbols are etched along the flat of the blade, glowing faintly in dim light.”

After identification (revealed stats and lore):

• Full stat bonuses
• Lore / origin story
• Usage instructions for activated abilities

The progression from “this seems unusual” to “I know exactly what this does” is itself a form of gameplay.

Common Item Description Pitfalls

• Don’t reference the player: “You see a fine sword” — just describe the sword
• Don’t describe the stats: “This armor gives +5 defense” — let the identify system handle mechanics
• Don’t break genre: no modern items in medieval settings without explicit genre justification
• Keep it physical: describe what the item looks, feels, smells, and sounds like, not what it “does”

4. Area Building Methodology

Phase 1: Concept

Before writing a single room, answer these questions:

1. Theme: What is this place? A haunted monastery? A bustling port? A goblin warren?
2. Level range: Who is this area for? Levels 1-10? 50-80? Groups only?
3. Narrative purpose: What story does this area tell? What happened here?
4. Geography: Where does it fit in the world? What’s nearby? How do players reach it?
5. Mood: Dark and threatening? Whimsical? Mundane? Melancholy?
6. Size: How many rooms? (First-time builders on Aardwolf are limited to 50 rooms/mobs/objects — a reasonable starting cap.)

Write a short pitch — two or three sentences that capture the essence. If you can’t summarize it concisely, the concept needs sharpening.

Phase 2: Map and Layout

Map on paper first. Graph paper works well. Sketch the layout before touching any builder tools. This prevents the common trap of building room-by-room and ending up with a sprawling mess.

Design principles:

• Ensure directional consistency: Moving east then immediately west should return to the same room. Violations of this break player trust.
• Use cardinal directions: N/S/E/W plus NE/NW/SE/SW plus up/down. Diagonals prevent a grid-like feel and create more natural-feeling geography.
• Include loops: One-way dead-end corridors force tedious backtracking. Create circular paths so players can explore without constant retreating.
• Provide shortcuts: For large areas, include teleportation, secret passages, or fast-travel options to reduce traversal tedium.
• Avoid pure mazes: If you must include a maze, make it small and provide an alternate solution (a guide NPC, visual markers, a logical pattern). “The point is not to make it hard and boring.”
• Give every room a purpose: “Barring a few junctions and corridors, there should be something out of the ordinary about every room.” Approximately four interactive elements per room produces rich, explorable content.
• Vary room density: Tight corridors for tension, open spaces for relief. Architecture shapes the player’s emotional state.

Phase 3: Mob Placement

Place mobs BEFORE writing descriptions — this ensures descriptions and population are coherent.

• Match mob difficulty to the area’s level range
• Place stronger mobs deeper in / harder to reach
• Use wandering mobs sparingly — they add dynamism but can frustrate players if a high-level mob wanders into a low-level zone
• Not every mob needs to be hostile: shopkeepers, quest-givers, ambient townsfolk, and neutral animals all build world texture
• Vary mob types within the area to prevent combat monotony
• Give key mobs unique echo messages and dialogue triggers

Phase 4: Item and Loot Placement

• Items should logically belong in their locations (weapons in an armory, not a bakery — unless there’s a story reason)
• Match item power to the area’s level range
• Don’t pile all the best loot in one room — distribute rewards to encourage full exploration
• Include non-combat items: readable books, keys, quest objects, food, flavor items
• Consider load rates for rare items — not everything should be guaranteed
• “Nobody likes to fight the most difficult mobile on the MUD and get nothing for doing it” — but don’t overreward either

Phase 5: Goal / Quest Design

Principles from the quest design literature:

Player Rights (the non-negotiables):

• No sudden death without warning or hints
• Hints must be understandable before solving the puzzle
• The quest must be winnable without trial-and-error deaths
• No hidden prerequisites (needing an item from 30 minutes ago that can’t be re-obtained)
• Don’t close off areas permanently without warning
• Accept command synonyms — if “look inside box” finds nothing but “search box” works, that’s unfair
• Limit luck-based solutions

Design principles:

• Don’t make finding the quest itself be a big puzzle — clues can be obscure but they MUST exist somewhere
• Don’t assume the player knows the MUD or will automatically try unusual commands
• Multi-step solutions are more satisfying than single-action puzzles
• Support multiple valid approaches when possible
• Quest completion should unlock new areas or content, not just grant tokens
• Make reward items interesting through function (tools, spells) rather than just symbolic value

Structure:

• Use a three-act structure: prologue (setup, 8-10 rooms max), middle game, end game
• Map puzzle dependencies — create a lattice showing which puzzles depend on others to avoid bottlenecks
• Balance breadth (many simultaneous puzzles) against depth (linear chains) — pure extremes of either feel wrong
• Ensure quests remain completable even when items are lost

Phase 6: Testing and QA

A builder checklist before submission:

• Walk every path — confirm all exits are bidirectional (unless intentionally one-way)
• Verify every noun mentioned in descriptions has an extra description / add_item
• Spellcheck all descriptions (use an external editor if OLC doesn’t have one)
• Grammar check — complete sentences, consistent tense
• Kill every mob — ensure combat works and loot drops correctly
• Complete every quest path — confirm solvability
• Test as a level-appropriate character — not as an immortal
• Check mob respawn behavior — does everything repopulate correctly?
• Read room descriptions sequentially along common paths — do they flow or feel repetitive?
• Verify shops function (buy/sell prices, inventory)
• Have someone else playtest blind — watch for confusion, missed clues, boring stretches
• Check accessibility — avoid relying on color alone, minimize ASCII art, ensure screen readers can parse descriptions

Show your work to other builders and accept feedback. Iterative improvement with fresh eyes consistently produces better areas.

5. Environmental Storytelling

Environmental storytelling is the art of arranging details so they imply a narrative without explicit exposition. In a graphical game, it’s a knocked-over chair and a bloodstain. In a MUD, it’s all in the text.

Stories Through Room Descriptions

Instead of telling the player “this village was raided,” show the evidence:

Charred Homestead
Little remains of what was once a thatched cottage. The stone
foundation walls still stand, blackened by fire, but the roof has
collapsed inward. A child's wooden horse lies in the dooryard,
half-buried in ash.

The player infers the raid. The wooden horse implies a family. No exposition needed.

Techniques:

• Contrast: Describe what something once was alongside what it is now. “Faded banners hang in tatters from rusted brackets” tells you this place was once maintained.
• Absence: What’s missing tells a story. An empty sword rack, a room with furniture but no inhabitants, a library with empty shelves.
• Damage patterns: The specificity of damage implies cause. Claw marks differ from sword cuts differ from blast damage.
• Time markers: Cobwebs, dust thickness, plant overgrowth, rust — these tell the player how long ago something happened.

Using Item Placement to Imply Events

Items in a room can tell a story the description doesn’t:

• A half-eaten meal on a table implies interrupted activity
• A bloodstained dagger beside a locked chest implies theft gone wrong
• A stack of unsent letters implies someone who never left
• Discarded armor along a path implies a retreating army
• A single boot at a river’s edge implies… something

The key is suggestiveness. Don’t explain what happened — let the player construct the narrative from evidence. When players piece together a story from clues, they remember it far more vividly than if they’d been told directly.

Progressive Discovery

Layer information so that deeper exploration reveals more of the story:

Layer 1 — Room description: Surface-level observation. “A study lined with bookshelves. Papers are scattered across the desk.”

Layer 2 — Extra descriptions: Looking at the papers reveals they’re written in a frantic hand. Looking at the bookshelves shows gaps where volumes have been pulled out hastily.

Layer 3 — Item examination: A crumpled letter on the floor mentions a “breach in the lower ward.” A tome left open on the desk is a treatise on binding rituals.

Layer 4 — NPC interaction: The scholar’s ghost, found in the basement, speaks of what he tried to contain.

Each layer rewards increased engagement. Casual players get atmosphere. Thorough players get story. Obsessive players get lore.

The Five Environmental Storytelling Techniques

Applied to MUDs:

1. Spatial design: The layout itself tells stories. A throne room at the end of increasingly opulent hallways. A dungeon that descends deeper and gets wetter. A city where the houses get smaller as you move from the center.

2. Narrative props: Objects that reflect unseen events. Bloodstains, broken furniture, abandoned tools, discarded personal items.

3. Item descriptions: “Write item texts that imply more than they explain.” A blood-stained robe. A blade with notches. A locket containing a portrait of someone the player might recognize.

4. NPC/mob placement: What creatures inhabit a space tells you what the space is. Rats in an abandoned granary. Undead in a battlefield. Bandits on a trade road. The transition from one mob type to another marks territorial boundaries.

5. Safe zone violations: Breaking established patterns. If taverns have always been safe, an attacked tavern creates immediate narrative tension without a word of exposition.

6. Style Guides from Notable MUDs

Discworld MUD — Ten Commandments of Descriptions

The most widely cited MUD writing reference. Summarized:

1. No “you.” Remove all direct references to the player.
2. Don’t dictate actions. Describe the environment; don’t tell players what they decide to do.
3. Don’t freeze dynamic things. Don’t describe movable objects or NPCs in static room text — use mob echoes and room messages instead.
4. No relative directions. Use cardinal directions, not “ahead” or “to your left.”
5. Proper English. Write numbers as words (at least up to twenty), use complete sentences with verbs, maintain consistent spelling standards (Discworld uses British English).
6. Visual clarity. Double-space between sentences for fixed-width readability. Avoid color in descriptions.
7. Describe every noun. If you mention it, add an examinable entry for it. Reward exploration with humor and detail in these entries.
8. Don’t describe NPCs in room text. NPCs are separate objects with their own descriptions.
9. No command hints. Don’t write “type BUY to purchase.” Use in-world signs if you need to convey functionality.
10. Have fun writing. Enthusiasm shows. But stay in-theme — don’t break immersion with excessive silliness.

Additional Discworld standards:

• Target length: 50-80 words per room description
• Use emotionally resonant words to build atmosphere
• Use active verbs over passive constructions
• Avoid repeating prominent words within a description
• Visualize the room before writing it — close your eyes and see it first

Discworld — NPC Description Guide

From the Ankh-Morpork domain guide:

• Derive physical traits from function (a blacksmith’s burn scars, a veteran’s short hair and old wounds)
• Consider origin, social class, and occupation as visible markers
• Avoid describing clothing (it can be stolen)
• Focus on what makes this NPC distinct from every other NPC
• Keep descriptions static — don’t describe one-time events
• Avoid hallways; when unavoidable, give them dual purpose

Aardwolf MUD — Builder Rules

Key standards:

• No copyrighted material — areas cannot be based on existing games, books, or movies
• Areas are exclusive to Aardwolf once loaded on the main port
• One active area per builder at a time
• First-time builders limited to 50 rooms/mobs/objects
• Builders may not use knowledge of their own areas to benefit themselves or friends on the main port
• No sharing speedwalks or quest solutions
• Two months of inactivity = area archived (restored once only)
• Follow provided guidelines for rooms, objects, mobs, and programs — non-compliant areas won’t be released
• Lua scripting is available and encouraged for atmosphere and challenge variety

CircleMUD — Builder’s Manual Philosophy

• Treat area creation like writing a book: plot, descriptive writing, memorable people and places
• Plan on paper before building
• Match objects and monsters to the intended audience’s level
• Don’t deliberately build unbalanced areas — “letting the players balance the area” is not a strategy
• Invest in rich, detailed descriptions
• Structure areas around plotlines, whether complex or simple
• Add non-combat elements: non-functional NPC traders, puzzles, special procedures
• Show your work to others and accept feedback

Cleft of Dimensions — Building Guide

• Five or six lines per room description is usually plenty
• Maintain a single color for clarity; highlight specific words sparingly
• Remain objective in tone — avoid telling readers what to feel
• Add extra descriptions to reward thorough players
• Include keywords from both short and long descriptions in mob keyword lists
• Use the Formulator application for statistical balance
• Hidden naming conventions (e.g., +sslash for slashing weapons, =legs for leg armor) enable later searching and categorization

Advent of the Mists — Room Guidelines

• Third person, no “you”
• General crowd descriptions fine; specific NPC descriptions not
• End room descriptions with directional information for each visible direction
• Extra descriptions for important nouns
• Capitalize first word and all major words in room titles
• No color in descriptions or titles (except designated newbie areas)
• No impossible escape routes or mazes near newbie areas

Writing-Games.org — Style Guide Framework

A comprehensive template for creating your own MUD style guide:

Rooms section should cover:

• Name length (3-6 words), capitalization rules
• Description target length (lines, words, or sentences)
• Tone requirements
• Second-person restrictions
• Smart quote warnings (use plain text editors)

Objects section should cover:

• Naming conventions
• Description requirements and length
• Appropriateness guidelines
• Material and theme restrictions

NPCs section should cover:

• Dialogue style and humor levels
• Character modeling restrictions
• Grammar and punctuation (important for screen reader accessibility)

Accessibility requirements:

• ASCII art sounds like “confusing, garbled mess” to screen readers
• Color-usage protocols shouldn’t disadvantage non-sighted players
• Pair style guidelines with technical building instructions

7. Tools and Workflows

OLC (Online Creation)

OLC is the standard in-game building system for Diku/Merc-derived MUDs. It allows builders to edit world data while the game is running, without requiring a restart.

Core OLC editors:

• REDIT — Room editor (descriptions, exits, flags, extra descs)
• MEDIT — Mobile/mob editor (stats, descriptions, behavior)
• OEDIT — Object editor (stats, descriptions, type, values)
• MPEDIT — Mob program editor (scripted behavior)
• AEDIT — Area editor (metadata, level ranges, resets)
• HEDIT — Help file editor

Typical workflow:

1. Get assigned a vnum range from the head builder
2. Use REDIT to create rooms and link exits
3. Use MEDIT to create mobs
4. Use OEDIT to create objects
5. Use AEDIT/ZEDIT to set up resets (what spawns where on area repopulation)
6. Use MPEDIT to add mob programs for dialogue and behavior
7. Save and test

The description editor within OLC is usually a simple line editor. Use .h for help within the editor. .a aborts changes. Most support basic formatting commands.

External Editors

Many builders prefer writing descriptions in external editors and pasting them in:

• Write in a plain text editor (vim, VS Code, Notepad++) to avoid smart quotes and special characters from word processors
• Word processors like Google Docs or Word introduce curly quotes, em-dashes, and other characters that break in MUD clients
• Use a fixed-width font (monospace) while writing to see how text will actually display
• Keep lines under 76-80 characters to prevent awkward wrapping in most MUD clients
• Copy from external editor, enter OLC edit mode, paste into the client

Some codebases provide web-based editing interfaces (“creweb” systems) that let builders edit area files through a browser. Others expose shell access so builders can use vim or similar directly on the server.

Mapping Tools

• MUD Map — Standalone mapping tool supporting 10 directions, grid and free-form layouts
• AVAE (Ack!Mud Visual Area Editor) — Visual area editor for Ack-derived MUDs
• MZF Editor — Area file editor with documentation
• Graph paper — Still the most recommended starting point; sketch before you build

Collaborative Building

For multi-builder areas:

• Divide the area into sub-sections, each assigned to one builder
• Maintain a shared style guide so descriptions feel consistent across sections
• The head builder or area lead reviews all sections for coherence
• Use consistent naming conventions for vnums, keywords, and hidden tags
• Communicate about shared elements (NPCs that appear in multiple rooms, through-lines in the narrative)
• On Aardwolf, unauthorized access to another builder’s area results in immediate loss of builder status — clear boundaries matter

Modern Development Workflows

For contemporary MUD engines (Evennia, Ranvier, etc.):

• Area data stored as code or structured data files (YAML, JSON, Python)
• Standard version control (git) for all area content
• Code review workflows for new areas
• Automated testing possible for room connectivity, exit symmetry, and description validation
• Modern text editors with syntax highlighting for area files
• Collaborative development through branches and pull requests
• No in-game OLC needed — everything managed through the development environment

Area File Formats

Traditional Diku/Merc area files are structured plaintext:

• *.wld — Room definitions
• *.mob — Mobile definitions
• *.obj — Object definitions
• *.shp — Shop definitions
• *.zon / *.are — Zone metadata and reset commands

Each file ends with $ for parser recognition. Every entity is identified by a vnum (virtual number), unique within its category. New areas require: copying files to the correct directory, updating index files, and running syntax-checking mode before deployment.

Appendix: Quick Reference Checklist

Room Description Checklist

• Third person, present tense, no “you”
• 3-5 lines / 50-80 words (adjust per style guide)
• At least two senses engaged (not just sight)
• Active verbs, emotionally resonant word choices
• Cardinal directions only, no relative directions
• No mobs or movable objects described in room text
• Extra descriptions for every mentioned noun
• No command hints or syntax references
• No color (or extremely minimal)
• Spellchecked, grammar-checked, proofread

NPC Checklist

• Keywords cover all reasonable targeting words
• Short description is a noun phrase (no period)
• Long description is one line, varies from “X is here” pattern
• Examine text derives traits from function/occupation
• No clothing described (if theft is possible)
• At least 2-3 echo messages for ambient behavior
• Echo probability set low (2-8%)
• Dialogue triggers for relevant keywords

Item Checklist

• Keywords cover all reasonable names
• Short description is a noun phrase
• Long description implies the item is at rest
• Examine text includes physical details and subtle clues
• Magical items show hints before formal identification
• No stat references in description text
• No player references (“you see”)

Area Checklist

• Concept documented (theme, level range, story, mood)
• Map sketched before building
• All exits bidirectional (unless intentionally one-way)
• Mob difficulty matches level range
• Loot matches level range and is distributed across the area
• Quests are solvable without trial-and-error
• Quests have visible clues somewhere in the area
• Tested at appropriate character level (not as immortal)
• Peer reviewed by at least one other builder
• Accessibility verified

Sources

• Discworld MUD — Ten Commandments of Descriptions
• Discworld MUD — Guide for Writing Descriptions (Elera)
• Discworld MUD — Writer’s Block
• Discworld MUD Wiki — Description Line (Room)
• Writing-Games.org — How Long Should Room Descriptions Be
• Writing-Games.org — How to Create a Style Guide for Your MU*
• Writing-Games.org — How to Write Room Descriptions: Tips and Examples
• CircleMUD Builder’s Manual — Introduction
• CircleMUD Builder’s Manual — Mechanics of World Building
• Aardwolf MUD — The Building Rules
• Aardwolf MUD — Building Page
• Aardwolf MUD — Description Editor
• Cleft of Dimensions — Building Guide
• Cleft of Dimensions — Mprog Compendium
• Advent of the Mists — Room Guidelines
• Lysator — How to Make Good Quests
• MudBytes.net — Forum and Resources
• MUD Area Building Software and Links
• MUD Wiki — Online Creation
• MUD Wiki — Mobile
• Keewano — 5 Environmental Storytelling Techniques
• Roleplayingtips.com — Write More Engaging Room Descriptions
• MUD Map User Manual