How to create a style guide for your MUD

Updated
A headshot of Andruid, shaded blue.
By Andruid

Writer, roleplayer, storyteller, and nerd who tries to live by Bill and Ted wisdom, i.e. "Be excellent to each other." 

Table of Contents

    Creating a multi-user dungeon (MUD) can be a fun and rewarding experience, but without a clear set of guidelines, areas may end up inconsistent with each other and the game’s intended theme.

    This is especially true if the game has multiple builders working on their own areas independently.

    As I mentioned in my post on writing excellent room descriptions, consistency – and proofreading! – are important for creating a polished game that players will understand while moving from one area to the next.

    If your game doesn’t already have a style guide, today’s post is for you. I’ll be walking you through the steps of creating a style guide that will not only be unique to your game but right for your audience.

    What is a builder’s style guide?

    A builder’s style guide is a set of rules that MUD builders follow when creating new rooms and areas for a text-based game. It includes guidelines for things like room titles, description length, and what sort of things should go in a room description.

    The style guide can also include guidelines for creating objects, NPCs, scripts, crafts, and other common content.

    Is a style guide necessary?

    A style guide can vastly improve the quality of a text-based game and is an important tool for getting tribal knowledge out of one or two people’s heads and into a format that other builders can follow.

    If you already have (or someday plan to have) more than one builder working on their own projects, I highly recommend a style guide.

    Who should create the style guide?

    The game’s Head Builder is generally the one who creates and maintains the style guide. The Head Builder is often responsible for reviewing and approving new building projects, teaching other builders the ropes, and creating their own content for the game.

    If the game doesn’t have a Head Builder yet, the responsibility may fall to the head admin or implementor – or whoever is willing to put in the work.

    It could even be a team effort, with the group as a whole working on the document and agreeing on its contents. It’s up to you to decide what’s best for your game.

    What should go in your MUD Builder’s Style Guide

    Below are some of the things you’ll want to address in your style guide, including sections for rooms, objects, and NPCs.

    Depending on the nature of the game, you may also want to add sections for mobprogs, quests, crafts, or other features builders will be able to edit or expand over time.

    For now, let’s take a look at the essentials:

    1. Rooms

    A stone archway and path leading into mist-covered mountains.

    When a builder first gets started, they’re often assigned a task to create some number of rooms – possibly even a whole area.

    Rooms are generally easier to manipulate than objects, mobs, or scripts, and so they tend to be a good place to start. They also provide an outlet for expressing one’s creativity and imagination.

    When writing up a section for rooms in your style guide, you’ll want to find a balance between freedom and structure, particularly if your builders are volunteers.

    What I mean by that is if your rules are super strict, builders will feel constrained – maybe even turned off altogether.

    On the other hand, if you don’t have at least some guidelines, they could end up feeling lost or unsure of what’s expected of them, or they may end up building out rooms in a way that aren’t consistent with your vision for the game.

    Room names

    The room name (also called a “room title”) is often the first thing players read. Sometimes, it’s the only thing players read, so it’s a good idea to put a little bit of thought into how it should display.

    For example, should your room names use title case, start case, or sentence case?

    Actually, games sometimes enforce start case, which means that when a room name is printed to the screen, the underlying code ensures that the first letter in each word is capitalized regardless of how the name was actually entered by the builder or saved to the database.

    This is one way that code can be used to enforce the style guide and keep things consistent, but it does come with a tradeoff: by enforcing a specific case, you won’t be able to allow exceptions without coding in additional settings, etc.

    Again, it’s a balance between providing freedom and structure.

    Example guidelines for room names
    • Room names should be 3-6 words in length
    • No decorative borders or ASCII art
    • Don’t start the name with ‘A’ or ‘The’ unless it’s part of a proper noun

    Note: Code can also be used to enforce things like the length of room names by printing an error message when a builder tries to save a room name that is longer than what is allowed.

    Room descriptions

    Considerations for room descriptions include things like:

    • description length
    • tone and style
    • content

    One question you might be wondering is, “What’s the ideal length for a room description?” This is not an uncommon question for new game implementors and builders.

    In fact, the ideal/desired description length will really depend on your target audience.

    For example, in a hack-and-slash or PvP game without a roleplay focus, players may generally prefer shorter room descriptions that convey the important stuff without a lot of descriptive prose.

    On the other hand, in a roleplaying game with a strong emphasis on immersive storytelling, longer descriptions might be the accepted norm.

    Ideal description length will also vary by personal preference, which means that no matter what you do, you probably won’t please everyone, and that’s okay.

    I recommend that you choose something that works for you and your target playerbase and go from there.

    Example guidelines for room description length

    When adding length to your Style Guide, you can lay it out in a few different ways depending on how your game handles room descriptions:

    • Number of lines (appropriate if room descriptions are automatically formatted to a specific width, such as the standard 80 characters)
    • Number of characters or words
    • Number of sentences

    For example:

    • Rooms descs should be 5-8 lines long
    • Rooms descs should be 25-50 words long
    • Rooms descs should be 2-4 sentences in length
    Example guidelines for tone, style, and content

    I already talk a bit about tone and style in my post on writing excellent room descriptions, so I’ll just cut straight to some example guidelines:

    • Avoid using the second person (“you”)
    • Complete sentences only
    • Don’t reference current events or pop culture
    • Don’t include descriptions of weather (applicable if the code will print a line about current weather conditions)
    • Don’t assume that the PC will react or feel a certain way when they enter the room, e.g. no writing: “Your heart swells with joy when you see the tiny kitten.”
    • It’s okay to write about insects and small animals but no large beasts or threats

    Also, just like with weather conditions, you should let your builders know if you prefer code to handle things like smells and sounds based on characters’ stats and senses.

    Finally, it’s worth spelling out what the limit should be on graphic descriptions of things like blood and gore, torture devices, evidence of substance abuse, or anything else that might be triggering to players or inappropriate for your target playerbase.

    Word processors and quotation marks

    A quick note about something that could be frustrating for you later if you don’t know about it ahead of time:

    Some text editors and word processors, such as Google Docs, MS Word, and Notion will handle quotation marks differently than others. In these programs, quotation marks and apostrophes become curly as you type, automatically curving toward the text they’re surrounding.

    Because of this, they’re sometimes also referred to as “smart quotes.”

    Here’s an example screenshot from a sentence written in Google Docs (you can also test this yourself):

    Example of curly quotation marks from Google Docs.

    And now here’s the same sentence typed into Sublime Text:

    Example of straight quotation marks from Sublime Text.

    Notice how in the first example, the quotation marks are curved or curly.

    If you try to copy content with smart quotes and paste it into your game, the game may not handle those curly quotation marks correctly.

    If you find this is true for your game, you may want to ask your builders to write descriptions in a code editing software like Sublime Text before copying them over (Notepad++ or Grammarly will also work). This will prevent the marks from disappearing when entered into the game’s editor.

    Tip: If your builders write their room descriptions in Grammarly first, the content is less likely to have typos by the time it enters your game.

    Accessibility considerations

    Before moving on to objects, I’d like to take a moment to talk about accessibility. In particular, there are two common issues to consider when it comes to rooms:

    • ASCII art
    • use of color

    Your sighted builders might be tempted to add ASCII art to their descriptions, but unless you have a method for hiding ASCII for screen reader users, I really don’t recommend it.

    To a screen reader user, ASCII art will sound like a confusing, garbled mess – not helpful at all.

    Similarly, if your builders use color as a visual cue (e.g. to highlight secrets or interesting details), your non-sighted users will be at an unfair disadvantage unless you code in a way to call attention to those features audibly.

    However you decide to handle these issues – whether via code improvements or builder guidelines, I recommend including a section in your style guide on accessibility.

    An accessibility section can be a useful teaching tool to bring your builders on the same page and ensure a universally good experience for everyone who plays your game.

    Quote by Niamh pulled from the body of the post.
    One of my favorite quotes by Niamh in “Building a better MUD for screen reader users“, April 17, 2022.

    2. Objects

    A blacksmith hammering a blade against an anvil.

    Once you’re done with the section on rooms, you’ll be in a good position to add one for objects.

    Most long-time admins are probably familiar with the bloat and chaos that can happen if you don’t keep an eye on what objects your builders are adding to the game. 😅

    Make sure you give your builders some guidance around things like:

    • use of color (see note on accessibility above)
    • naming conventions for objects
    • required descriptions, style, and length
    • whether it’s okay to base objects on real-life items or events
    • whether it’s okay to create joke/humor objects, or whether there’s some topics you’d like your builders to avoid (e.g. sex toys or Spencer’s gifts)
    • limits on how graphic or gruesome object descriptions can be

    For example, if your intended playerbase includes families, you may want to steer your builders away from creating objects that are inappropriate for kids or young teens.

    Tip: It’s much better to be upfront and explicit about what adult content is allowed, rather than to have to clean up inappropriate objects and misunderstandings later after the damage has already been done.

    3. Mobs / mobiles / NPCs

    Photo of a Ren Faire musician strumming a lute-like instrument.

    Many of the style guide recommendations for rooms and objects also apply to mobs and mobprogs:

    • use of color
    • naming conventions
    • required descriptions, style, and length
    • whether it’s okay to model NPCs on celebrities, fictional characters from books or movies, etc.
    • what kinds of humor are okay for NPC dialogue
    • what topics are off-limits or should be avoided

    Again, your builder’s style guide isn’t just a place to talk about spelling and grammar.

    Make sure you’re giving your builders clear guidelines when it comes to adult language and themes, too.

    That said, spelling and grammar can be important for accessibility reasons – not just for making your game seem more polished.

    Screen readers use punctuation and capitalization as cues when interpreting text-to-speech, which means that appropriate use of punctuation at the end of sentences, use of quotation marks, and use of caps in NPC dialogue can all make a difference in how your non-sighted users experience your game.

    Something to think about as you lay out your guidelines.

    Tip: Having a screen reader user on your staff team can help you catch problems early, set good guidelines, and build in accessibility from the get-go. For examples, check out my interviews with admins from Alter Aeon and Alter Epoch.

    Where should the MUD style guide live?

    There’s no hard or fast rule, but the style guide should be published in a place that is a) searchable, and b) accessible to both sighted and non-sighted builders.

    Some admins prefer to use a wiki, others prefer to keep the guide in-game as part of the game’s help system.

    Other options include forums, a password-protected website, or a document in an online text editor.

    If you’re not sure what would best suit your builders, there’s no harm in asking – they can help you sort out the various pros and cons.

    What else do builders need?

    Often, a style guide is part of a larger set of documents dedicated to building (sometimes referred to as a “Builder’s Manual”).

    Although this blog post is focused on the style aspect, the technical guide is also very important and will probably be the piece your builders are most interested in when they first get started.

    After all, the technical guide is what will help them express their creativity and bring their ideas to life!

    Make sure your builders have the tools they need to complete their projects. This means having clear technical instructions for creating rooms (i.e. the commands required), objects, mobs, and especially mobprogs.

    One of the most important reasons to shore up your building documents is the same as why you should have a good help system: if you don’t, you’ll end up answering the same questions over and over, which isn’t the most efficient use of your time.

    For an example of a holistic building guide with both stylistic and technical considerations, check out “On Writing Areas” by Morrn. It’s a web-based supplemental manual created for Dawn of Ages.

    Mobprog scripting and technical help

    And lastly, a quick note on mobprogs. Mobprogs can be one of the toughest things for a new builder to learn if they don’t have previous coding or scripting experience.

    Be sure to provide your builders with some solid examples, as well as do’s and don’ts – just like you would with your style guide.

    For example, in the mobprog guide for Cleft of Dimensions, there’s a link to several examples, plus sections dedicated to definitions and troubleshooting.

    You can find a few more examples of technical guides here:

    While I didn’t cover every example and scenario, I hope this post provided you with at least a few ideas and some food for thought.

    If there’s a specific topic you’d like me to cover in a future post, feel free to reach out! Contact info on my About page and in the footer. 👇