Text Adventure Talk #2: How to write for Interactive Fiction and Parse Commands

As you would guess, the second most important part of a text adventure game is the writing , since it’s a game completely made of text (the first one is the coding, of course, otherwise it’s not a game). But the process of creating a game like that may seem quite overwhelming, especially if you lack the experience. And to create an environment with words can be a lot harder than creating one with 3D models, which are visible and allow the developer to show the player in a very clear way what kind of setting you’re trying to create. With text, the environment relies on the player’s imagination, and that’s where good writing makes a difference.

In this article, I will try to lend my experience to you about how to write your text adventure game, as a writer, game dev, and player of text-based games. I have touched on this subject briefly in my first text adventure article, but here I intend to dissect this topic further in case you need more clarification. And please remember that other devs may have different opinions; this is just things I learned in the development of my own games and analyzing classic and modern titles of the genre. Modern text adventure games often take some liberties with the classic structure (that will be the focus here), but you have first to know the rule to then break it, right?

Please, keep in mind that, in this article, I’m talking exclusively about writing, aiming at people that don’t have much experience writing fiction (or writing in general). I won’t be talking about any other aspect, like coding or sound. Those are topics for another time.

Everything I will say here applies to pretty much all kinds of text adventure sub-genres, like horror or fantasy, since I will be talking about the basics of Interactive Fiction writing. So let’s begin!

Disclaimer: I’ll be using a parser-type text adventure in my examples, but almost everything I say here applies to hyperlink-based games too (to know the difference, read this).

Starting out

So you have an idea of the plot and setting for your game, but how should you start actually writing it? If you are not familiar with the structure of a TA game, I highly recommend that you use a game engine made for IF (I talked about my favorite IF engines in the previous Text Adventure Talk) to develop your game, since they pretty much lay down all the structure for you, and make it easier for anyone to make a text-based game.

However, keep in mind that the executables of those engines have very limited customization options in regards to the appearance of the game. So if you don’t like how the game looks, you can make that version as a prototype, a base, so it’s easier for you to follow the structure during development, and then replicate it to another engine that will give you more artistic freedom. I did this with my first text adventure game, Family Dinner: made a prototype in Twine and then the final version in Construct 2.

In any case, you should start structuring your game with locations. A location is a specific area in the game to which the player can go, and that should contain items, documents, characters, or whatever you decide to put in it. For example, if your game is set inside a house, the locations would be its rooms. So the skeleton of your game should consist of many locations connected by commands.

Writing Locations

Each location should have, before anything, its name appearing on the screen, and beneath it a description for when the player enters it. The name is very important since that’s what keeps the player from getting completely confused and lost on the map. The description below it should be a complete “first look” of the room or area, and it’s usually the same text that should appear when the player uses the “look around” or “look room” command. The description should be quite straight forward, showing the visible exits of the location, along with the static objects (more on object types later) and characters that are visible and that can be interacted with. You should avoid mentioning very specific objects if the player is not supposed to interact with them in any way.

However, keeping it straight forward doesn’t mean making it boring. If you’re describing a living room, don’t write just “You are in a living room with a couch and a table”. Add a couple of lines that’ll give character to the room, like the decoration, if it’s old or modern-looking, if it’s clean or dirty, if it’s well-lit or dark, and so on. Remember that you need to set the atmosphere so the player’s imagination can do the rest.

Bedroom
The wind blows gently now that the storm is over, and the night looks calm through the window, to the east. The colorful sheets on your large bed are disturbed, and the brand new bedside table sits at its left. Your vintage desk sits against the west wall, right beside the matching wardrobe. A couple of framed movie posters and artistic photographs taken by yourself adorn the red walls.

Example of location description from one of my games in progress made in ADRIFT

That being said, the location description should not show every single thing that’s present in the location. For example, if your location has a bedside table with small objects upon it, don’t include those small objects in the room’s description. They should only appear in the bedside table’s description when the player decides to take a closer look at it.

Writing Objects

Objects also have descriptions that should appear when the player uses commands like “examine” or “look”. The same “rules” for the locations apply here: keep it focused, but add some character to it.

Static object: Anobject (usually big) that cannot be stored in the player’s inventory. But the player can probably move it (maybe to reveal a door or item, or anything you want), and definitely can interact with it by examining, opening and closing it (in the case of containers).

The bedside table I mentioned before is a good example of a static object, and it’s a piece of furniture that can be a container, if it has drawers, and it can also have objects placed upon it at the same time.

➢ look table
You saw this beautiful green bedside table on sale on a nearby store. It has a modern design and a single spacious drawer, but just now you realized the evil face serving as handle. You feel quite hesitant to touch it. A short table lamp rests upon the surface. The bedside table is currently closed. A metal hairpin is on the bedside table.

Example of object description made in ADRIFT

If your bedside table is a container, its description should mention if it’s open or closed. Once the player opens it (or if it’s already open), the description of the object should now tell the player the table is open and list the items present both inside it and upon it. Like this:

➢ open table
You open the bedside table. Inside the bedside table is your silver flashlight and a copper key.

➢ look bedside table
You saw this beautiful green bedside table on sale on a nearby store. It has a modern design and a single spacious drawer, but just now you realized the evil face serving as handle. You feel quite hesitant to touch it. A short table lamp rests upon the surface. The bedside table is currently open. A metal hairpin is on the bedside table, and inside are your silver flashlight and a copper key.

Example of object description made in ADRIFT

If the player takes all items from inside a container and it’s still open, the description should then inform the player the container is empty.

However, if your bedside table is not a container, you don’t need to include the drawers in the description. Remember that TA games are not as intuitive as 2D or 3D games, so you should avoid wasting the player’s time by leading them to try to interact with something that has no purpose.

Dynamic object: An object that can be stored in the player’s inventory. The player can also interact with it by examining, opening and closing it (in the case of containers, like bags or cases), and even by using it with other objects (in the case of keys and puzzle items). Those types of objects usually can’t be moved, though.

Its description should say (besides the obvious, like the name of the object) things like the approximate size (small, large), general appearance and state (new, old, rusty, broken, shiny, dirty) and some kind of subtle detail that suggests the purpose of the object (in case it’s an uncommon object, or if its purpose is not very clear at first).

A classic example of a dynamic object is a key. Its purpose is usually quite clear: you have to unlock a door or some kind of container with it. But what about a hairpin, for instance? The player might wonder what they are supposed to do with it, at first glance, but if you intended for it to be a sort of lockpick, you have to tell that to the player, although in a way that still would require some thinking on their part. Let’s use those two items as examples:

➢ look copper key
The tiny key is covered with a shiny layer of copper, and although it has been in your possession for many years, it seems brand new. Its round bow bears a flower engraving.

➢ look hairpin
A long hairpin made of metal, with a black plastic piece covering one of the pin’s ends. Some cheap diamond imitations adorn it. It’s still a bit dirty since you picked it up from the pavement and left it on the bedside table until you decide what to do with it, but it looks resistant. The sharp end could fit a very small hole.

Example of object descriptions made in ADRIFT

Matching a characteristic of the key with the lock that it goes to might be a nice move, so the player doesn’t have to test the key in every single lock they find. The same applies to the lockpick: some characteristic that tells the player what kind of locks it can open.

Writing Characters

As mentioned before, characters should be included in the locations’ descriptions, if any of them are present. And, just like the objects, the character’s presence in the location text should be described in a single, direct line that already gives some idea about the character (which is true for both NPCs and enemies). Still, you can also mention if they are sitting, standing, close to a window, or something like that. In the case of enemies, you should mention how many exits they’re blocking (more on that later).

Main Living Room
The large living room is opulent and silent. The tall windows allow for a clear view of the outside of the property. You see an archway to the east and a door to the north. The butler is here; he bows briefly in your direction with a courteous smile. A woman is sitting on an armchair, nearby, with a distracted expression on her face.

Example of a character mentioned in a location description made in ADRIFT

When the player uses a command to take a closer look at a character, just like an object, they should see a more detailed description.

NPCs: They are characters that are not (necessarily) hostile towards the player, and that can be usually found in specific locations, though they can also move to another one after some scripted event.The player can interact with them by looking at them or speaking to them (we will talk more about dialogue later), usually to learn some information or to trigger events, and also by giving or taking objects from them, if you choose to implement this mechanic.

Their description should say their name, their general appearance (if they’re tall or short, about their hair, eyes, and even approximate age), clothing (you can decide how specific you want to be in this topic, but try to keep it concise), the expression on their face or the impression that the player’s character might have of them (do they look serious? Reserved? Distracted? Mischievous? Gentle?), and their social status or occupation. Something that would define them in the context of the place or situation the player finds themselves in.

If you want your game to be extra immersive, you can create two different versions of the character’s location and detailed descriptions. The first one to appear before the player talks to the character for the first time (if the player’s character has never met the NPC before), and that contains only a first impression description, without their name. The second one would be following the structure I described you in the previous paragraph.

➢ look woman
A noble, reserved-looking woman, apparently in her fifties. She has dark hair and medium height, and her gray eyes seem to hide many secrets. The simplicity of her garments purposely fails to reflect the importance of her title and the size of her wealth.

Example of description before meeting the character

➢ look woman
The Baroness, Lady Lilac Aveniss, is a noble, reserved-looking woman, apparently in her fifties. She has dark hair and medium height, and her gray eyes seem to hide many secrets. The simplicity of her garments purposely fails to reflect the importance of her title and the size of her wealth. She is the last of a long and distinguished lineage, whose secluded and mysterious ways has generated many rumors and legends over the centuries.

Example of description after meeting the character

Enemy encounters: Enemies in TA games are usually placed as to block certain location exits (sometimes, they block all exits and prevent you from escaping), so the player can only go through them after they defeated that enemy. The player can usually interact with them by looking at them or attacking them with an object or weapon when the enemy is a type of monster or animal. But if the enemy is a human or any sort of sentient being, you can maybe allow the player to speak to them.

Their description should say their name or the type of creature they are, their appearance or mood (does the enemy look weak? Strong? Tired? Energetic? Wounded? Angry?), if they are carrying a weapon, or if they have claws or any other dangerous feature. Maybe you can add a bit of their backstory or the reason they are in that particular place.

>n
The Troll Room
This is a small room with passages to the east and south and a forbidding hole leading west. Bloodstains and deep scratches (perhaps made by an axe) mar the walls.
A nasty-looking troll, brandishing a bloody axe, blocks all passages out of the room.
Your sword has begun to glow very brightly.

Enemy encounter in Zork I

Writing Commands

This section only applies to the parser interface games. Hyperlink-based games cannot do that, since they don’t use text commands, but then again, creating a link is much easier than coding a text command.

As I said in the beginning, using an engine made for text adventure games makes the process of developing IF much easier in many ways. But the most convenient thing about IF engines, by far, is that they code many of the basic commands for you. I truly believe that, with some of those engines, you could make a complete game without having to code a single command (and I definitely intend to test that in the future), but you can also add more if you like. With a rather quick study of an IF engine, you would have an amazing understanding of all the commands you can use in your game.

However, let’s say you are a hardcore dev, and you want to do all the work yourself in another engine, and you want to know the best way to code your commands.

The first thing you need to understand is that it’s much more difficult for the player to navigate through a text adventure game; they don’t have a visual environment where they can simply press a button and move in whatever direction they want. In a 3D game, for example, you would have a default action button that would perform many different functions depending on the context they are used. For instance, if you press action in front of a character, the protagonist will speak to them, and if you press action in front of an item, the protagonist will grab the item, and so on.

In TA games, the player doesn’t have this luxury. They have to be very specific in every single action they want to perform, and they will need to type some of those commands many times during the playthrough. That’s why writing your commands in a very simple and intuitive way can be crucial to keep the player invested in the game, while also writing many variations of the same command. Different people say things in different ways, and the player can’t read the dev’s mind to know how exactly they should write a command. Some good practices are:

• Writing command variations with only the most essential words: if you are going to code “look at the table” also code “look at table”; 
• Writing abbreviated versions for the commands the player will be using many times, for instance: a common abbreviation of the “go north” command is “north” or just “n”.
• Writing many command variations to do the same thing. For example, the many words that can be used to get an item in your inventory: “take”, “get”, “pocket”, “grab”, etc.

So here is a list of commands for many different mechanics you can include in your game. Of course, that doesn’t mean you need to use all of them, but try to add as many variations as possible to the ones you do decide to use. And you can add other ones as well, the possibilities are endless! I’m already adding variations to some of them:

Movement:

• go [direction] | Example: go southgo to [location] | Example: go to kitchen
• go [location] | Example: go bathroom
• move [direction] | Example: move south
• move to [location] | Example: move to attic
• move [location] | Example: move basement
• [direction] | Example: south
• [direction initial] | Example: s
• climb [object] | Example: climb tree
• go up
• go down
• go inside [object] | Example: go inside closet
• get out of [object] | Example: get out of box
• lie on [object] | Example: lie on bed
• get off [object] | Example: get off bed
• sit on [object] | Example: sit on sofa
• get up 

Inspection:

• ook at [object] | Example: look at bed
• look [object] | Example: look document
• look around/la
• look room/lr
• look at [location] | Example: look at kitchen
• look [location] | Example: look living room
• look at [character] | Example: look at John
• look [character] | Example: look Catherine
• examine [object] | Example: examine knife
• examine [location] | Example: examine dining room
• examine [character] | Example: examine old lady

Acquiring Items:

• take the [object] | Example: take the gun
• take [object] | Example: take flashlight
• take [object] from [object] | Example: take bottle from bag
• get the [object] | Example: get the key
• get [object] | Example: get stone
• grab the [object] | Example: grab the flask
• grab [object] | Example: grab bottle
• pocket the [object] | Example: pocket the coin
• pocket [object] | Example: pocket jewelry

Moving Objects:

• move [object] | Example: move cabinet
• push [object] | Example: push chair
• pull [object] | Example: pull lever
• drag [object] | Example: drag carpet

Other Object Interactions:

• open [object] | Example: open chest
• close [object] | Example: close drawer
• use [object] | Example: use pencil
• use [object] on [object] | Example: use pencil on paper
• throw [object] | Example: throw ball
• throw [object] at [object] | Example: throw ball at statue
• read [object] | Example: read note
• drink [object] | Example: drink water
• eat [object] | Example: eat meat
• drop [object] | Example: drop cloth
• break [object] | Example: break glass
• wear [object] | Example: wear hat
• squeeze [object] | Example: squeeze fruit

Character Interactions:

• speak to [character] | Example: speak to maiden
• speak [character] | Example: speak Mr. Richards
• talk to [character] | Example: talk to butler
• talk [character] | Example: talk shopkeeper
• say [hello/hi] to [character] | Example: say hi to Keith
• say [hello/hi]
• say [goodbye/bye]
• ask about [subject] | Example: ask about safe key
• ask [character] about [subject] | Example: ask John about safe key
• tell [character] about [subject] | Example: tell Mary about monster
• attack [character] | Example: attack Lewis
• attack [character] with [object] | Example: attack ghoul with sword
• give [object] | Example: give key
• give [object] to [character] | Example: give key to Lucy
• take [object] | Example: take lantern
• take [object] from [character] | Example: take lantern from John

Other Gameplay Elements:

• inventory, inv, i: open the inventory
• map, m: open the map (if any)
• save, load, return: save/load progress
• help, h: open “help” section

“Invalid Command”

However, even if you follow every single good practice when writing commands and add as many variations as you can, you can’t possibly predict every single word the player will write. And they can make mistakes when typing too.

That’s why it’s recommended that you code a short message to appear when the player types something the game doesn’t recognize. There isn’t any strict rule for this part. You can adapt this message to the tone of your game (comedic, serious, weird), but some classic examples are “I beg your pardon?” and “Sorry, I didn’t understand that command”.

Actions

Every time the player performs an action that changes an object in some way, there needs to be a very brief text informing them that the action is complete and in what way it changed the object. Like activating a switch:

➢ turn on switch
You switch on the light switch.

Example of an action made in ADRIFT

Writing Documents

Something very important that sets text adventures apart from more common types of games, obviously, is that the player is reading all the time. Unlike many games, where you eventually come across documents that the player can choose not to read, if they want, the only way to play interactive fiction is by reading constantly.

With that in mind, you should try to display the information you want in that document as concise as possible. And, if the document is, for example, a page from a diary, try to incorporate the voice of the character that wrote it into the writing, so it’s not just another boring text the player has to read.

Dialogue

It’s hard to define a structure for dialogues because it depends a lot on the context of the conversation. Some advice that I can give on writing dialogue, in general, is to give somewhat unique voices to the characters, making a bit of each of their personalities appear during the conversations. Make it clear for the player who is saying what, and, a recurrent theme in this guide: avoid dialogues that go on for too long.

Something that is implemented frequently in classic-style TA games is active and passive dialogues.

Intro (active): A piece of dialogue that starts the conversation, appearing when the player speaks to the character in an introductory manner, saying “hello” or “hi” before asking something or talking about a specific subject. Usually only needs two lines, one for each character. Example:

➢ say hi to Anna
YOU: Hey, how are you doing?

ANNA: I’m fine. What do you want?

Example of dialogue made in ADRIFT

Intro (passive): A piece of dialogue that appears when the player asks something or talks about a specific subject with another character without starting the conversation beforehand. Only one line is needed, for the character the player is talking to. Once the player types the command to talk (ask or tell), this line will appear before the intended dialogue begins. Example:

➢ ask Anna about power outage
ANNA: What do you want?

YOU: What do you know about the power outage?

ANNA: Absolutely nothing.

Example of dialogue made in ADRIFT

Farewell (active): A piece of dialogue that ends the conversation, appearing when the player says “bye” or “farewell” during a conversation, before interacting with something else or leaving the location. Example:

➢ say bye to Anna
YOU: We can talk later, then.

ANNA: Ok. Bye.

Example of dialogue made in ADRIFT

Farewell (passive): A piece of dialogue that appears when the player interacts with something else or leaves the location before ending the conversation. Only one line is needed, for the character the player is talking to. Once the player types the command to perform an action, this line will appear before another brief line saying the intended action is completed. Example:

➢ go north
ANNA: Ok. Bye.

You move north.

Example of dialogue made in ADRIFT

Character Status

Here is another mechanic that you might be considering implementing if you’re a Zork fan, for instance. Your encounters with enemies can leave you with some collateral damage (even if you won) like a wound that can only be healed with items or after a specific number of moves, that limits the player’s performance in some way or just makes them less resistant.

>diagnose
You have a light wound, which will be cured after 26 moves.
You can be killed by one more light wound.

Character status system in Zork I

To check the protagonist’s status, the player usually has to use the “diagnose” or “look myself” command. The status text should tell the player how serious the effect is, how long it will last, and how much more damage the player can endure.

Introduction & End of Game

Those are texts that appear, respectively, when the player opens the game and when the player finishes it.

Introduction: Some classic TA games, once open, would start with an introduction text, consisting of the game’s name and some copyright information, followed straight away by the first location’s description. The game’s context and synopsis would be present in the game’s printed manual, as it was common back in the day. However, nowadays, with the fall of physical media and the rise of digital media, this practice has practically vanished, even among AAA games that are still being sold in physical copies. For indie titles, that was never an option.

But in other cases, that fit better in a modern TA game, the introduction text would contain the game’s name (if your game has a main menu, that’s not necessary), a text establishing the necessary info about the protagonist, like name, gender, occupation or social status (you can leave this part vague if you want the player to put themselves entirely in the character’s shoes, or if you want them to come up with a background for the character), and then setting the context of the story: where the protagonist is, why they are there and what’s their objective. As always, keep it concise and focus on the important details; if your story has a lot of details, you’ll be able to show them gradually in the game through dialogue, documents, etc.

Right below it, something that would really help modern players that have never touched a text adventure game before is to tell them how to access the “help” section (more on that later).

Remember that this is different from a synopsis. A synopsis has to be present on the game’s page, and it talks about the game in a different way (presenting the story in a more general way, as well as genre, mechanics, features, and things like that).

I Can’t Find My Glasses
What an inconvenience! A violent storm caused a power outage throughout the entire neighborhood, and it will probably take some time to be fixed. But wait… where are your glasses? You can’t go to sleep without them. I guess your comfy bed will have to wait for you a little longer.

Type “help” for further instructions.

Bedroom
Darkness is everywhere. The wind blows gently now that the storm is over. The only light present is dim, coming from the window, to the east. The few things you can see are your large bed and the brand new bedside table, to your left. You can’t see the door to the hallway, to the south… but you can barely make out a tall silhouette between you and the exit.

Example of introduction made in ADRIFT

End of game: This is the text that should appear when the player completes the main objective and wins the game. It should make it clear the player has won, and say what they have accomplished and what are the consequences of that. You can have multiple different End of Game texts if your game has more than one ending.

But below any End of Game text, the game should ask the player if they want to restart, load/restore a saved game, quit, or undo their last command (very classic structure). Or just tell them which key they should press to go to the main menu or the credits.

*** You have won ***
You find yourself in your room once again, safe and sound, ready to get some rest, and very glad that all the horrors you witnessed were merely a product of an active imagination and a bad sight.

Or were they?


Would you like to restart, restore a saved game, quit or undo the last command?

Example of end of the game made in ADRIFT

“Help” Section

Back in the day, the instructions and tips for the game would also be in the physical manual, and as time passed, they started to be implemented in the game itself.

In TA games, the player should be able to access this section at any moment (main menu and during the gameplay). Of course, you don’t have to put every single command and sentence possible in there. Otherwise, the player would spend more time reading it than playing the game. You should include the most vital commands (go, look, use, take, inventory, etc.), examples of sentences that can be used in the game, while also encouraging the player to try different ones. Let them know about features they can use in case they feel stuck, like the map or the “help” command itself.

Beta testers will help you a lot in this regard. Check the aspects they are having difficulty with and see if you can explain them better in the “help” screen.

Game Over

Here, you should tell the player that they lost, usually if they died somehow. So you should tell them how they died based on the action they performed or any kind of decision they made, and what are the consequences of that (very similar to the victory text). Once again, ask the player if they want to restart, load/restore a saved game, quit or undo their last command, or indicate a button take them back to the main menu. You can also give them a second chance and let them continue playing.

>give garlic
(to the cyclops)
The cyclops may be hungry, but there is a limit.
Someone carrying a large bag is casually leaning against one of the walls here. He does not speak, but it is clear from his aspect that the bag will be taken only over his dead body.
The thief comes in from the side, feints, and inserts the blade into your ribs. It appears that that last blow was too much for you. I’m afraid you are dead.

   ****  You have died  ****

Now, let’s take a look here… Well, you probably deserve another chance. I can’t quite fix you up completely, but you can’t have everything.

Game over screen from Zork I

And we are, at last, at the end! This was a long one, but when we are talking about writing in a game completely made from it, it gets complicated. Despite that, I hope this guide helped you in any way, whether you’re making a text adventure or any kind of game with a considerable amount of text. Be sure to comment if I forgot to mention anything, or if you have additional questions. Happy developing!