Description
Your second project in CS 515-A is a text-based video game: players use text commands to explore a textual world. Text adventures were some of the first computer video games, offering an explorable world in narrative prose, full of puzzles, riddles, and mystery. Classics in the example include Colossal Cave Adventure
—from which the name ‘adventure game’ comes—or Zork
. The 1980s were the heyday of this style of game, evolving into visual puzzle games like Monkey Island
and Myst
and multi-user, combat-oriented games like MUDs
, which evolved into MMORPGs like EverQuest
. You can find games like our text adventure today on Twine
and the Interactive Fiction database
—people are definitely still thinking about text adventures, even though text is obviously not ‘mainstream’.
How are video games implemented?
A computer game in general has two parts: it’ll have an engine, which is the code that says how the game is played, and it’ll have assets, which are the data that the engine consumes. Assets describe the flavor or the structure of part of the game but not how the game is played. A large part of any video game will be assets—whether it’s a AAA shoot ’em up or a simple text adventure like this. In general, video games put as much into assets as possible, because that makes it easy for artists to work independently from the game engine. Typical assets in a text adventure are things like room names, room descriptions, how rooms connect, dialogue choices, and so on. To make a good text adventure you need to spend a bunch of time building a good engine for the game, but a good game will spend just as long (if not much longer) writing really good assets. In modern computer games, assets typically have small bits of code in them (Lua
is a popular choice) that the main game engine code runs—we’re not going to do anything so complicated as that, but even text adventures frequently have such features.
You’ll spend most of your time in this assignment implementing the game engine; we’ll additionally ask you to submit a game map that makes use of every (applicable) extension you implement.
What code do you have write?
We’d like you to implement the game engine. We specify precisely what that means below, but you’ll need to:
- load game maps (our only game asset)
- let the player play the game, i.e.,
- read input from the player
- parse the input as a command
- execute the command, updating the state of the game world accordingly
Your game engine will implement some baseline functionality along with “extensions”. We offer a list of possible extensions below; the list is not exhaustive, but to get credit for an extension you came up with, you must check with Prof. Greenberg first.
How do groups and extensions work?
You may work alone or in a group of two. The more people in your group, the more extensions you must implement:
| 1 person (working alone) | 3 extensions |
| 2 people | 5 extensions |
How do maps work?
Map files say what the world is. Here’s a sample, which we call loop.map:
[
{“name”: “A white room”,
“desc”: “You are in a simple room with white walls.”,
“exits”: { “north”: 1, “east”: 3 }
}
,
{“name”: “A blue room”,
“desc”: “This room is simple, too, but with blue walls.”,
“exits”: { “east”: 2, “south”: 0 }
}
,
{“name”: “A green room”,
“desc”: “You are in a simple room, with bright green walls.”,
“exits”: { “west”: 1, “south”: 3 },
“items”: []
}
,
{“name”: “A red room”,
“desc”: “This room is fancy. It’s red!”,
“exits”: { “north”: 2, “west”: 0 },
“items”: [“rose”]
}
]
A map is a JSON file
; the outermost part is a JSON list. Within the list are bunch of JSON objects, each one describing a room. The index a room appears at is its id. A room object has, at a minimum, three fields: name, the room’s name; desc, the room’s description; and exits, the exits from the room. A room might also have items, a list representing the items in that room. Depending on the extensions you implement, rooms may have other things, too. An object’s name and desc are both just strings. The exits should be another object, mapping exit names to room ids. Finally, a room’s items is a list of strings, each string describing an item in that room. A room might not have an items field. It’s worth noting that nowhere in the room object are we actually recording the room’s id.
A map is valid if every (a) every room has a name, desc, and exits of appropriate type, and (b) every exit points to a valid room id. It’s okay for the map to be disconnected, though
What does the game engine do?
The game engine actually plays the game! You can use as many Python files as you like; we’ll invoke your game by running:
python3 adventure.py [map filename]
You can access the command-line arguments in your code via sys.argv
.
After loading and checking that the given mapfile is valid, the player should be dropped into room 0. Here’s an example:
$ python3 adventure.py loop.map
> A white room
You are in a simple room with white walls.
Exits: north east
What would you like to do?
Notice the format: > followed by the title; a newline; the description; another newline; the exits (in the order they were given in JSON); another newline; and the prompt, What would you like to do?.
How do you play the game?
What does it mean to play? Text adventure games are a lot like a REPL: the world has some state and the player uses verbs to move through and modify the game world. You read the player’s input, parse it as a verb, execute the verb to update the game’s state, and then read more input.
In our simple model, the world state has two parts: the map and the world state. The map is described by the game asset, described above. The baseline world state is pretty simple: the player is in some location and has some inventory, i.e., items in their possession. In the baseline game, the room map is static, i.e., unchanging. Extensions can of course change that! But the world state is dynamic, i.e., constantly changing as the player issues commands.
The game starts with the map specified on the command line, with the player in room 0 and with an empty inventory, i.e., holding no items.
Your implementation will need to have three core parts:
- a loop that reads player input
- a parser that interprets player input as a verb (or issues an error message)
- implementations for each verb
There are many different ways to organize this code! Think carefully before you start.
We list the baseline verbs before, giving examples from loop.map. Note that case does not matter for any verbs, and arbitrary whitespace is allowed.
Verb: go
The go verb tries to go in a given direction. If there is no exit in that direction, go should give an error message. When a player successfully goes to a new room, you should show that room’s description.
> A white room
You are in a simple room with white walls.
Exits: north east
What would you like to do? go west
There’s no way to go west.
What would you like to do? go
Sorry, you need to ‘go’ somewhere.
What would you like to do? go north
You go north.
> A blue room
This room is simple, too, but with blue walls.
Exits: east south
What would you like to do? go south
You go south.
> A white room
You are in a simple room with white walls.
Exits: north east
What would you like to do? GO EAST
You go east.
> A red room
This room is fancy. It’s red!
Items: rose
Exits: north west
What would you like to do?
Verb: look
The look should show once again the the room that a person is in. The output of look is the same as what is shown when entering a new room or when starting the game.
> A white room
You are in a simple room with white walls.
Exits: north east
What would you like to do? look
> A white room
You are in a simple room with white walls.
Exits: north east
What would you like to do? go east
You go east.
> A red room
This room is fancy. It’s red!
Items: rose
Exits: north west
What would you like to do? look
> A red room
This room is fancy. It’s red!
Items: rose
Exits: north west
What would you like to do?
Verb: get and inventory
The get verb lets a player pick up items that are in the room. When a player says get [ITEM], if that item is in the room, the player will pick it up, the item will no longer be in the room but rather it will be in the player’s inventory. Trying to get things that aren’t there should produce an error message.
The inventory verb shows the player what they are carrying.
> A white room
You are in a simple room with white walls.
Exits: north east
What would you like to do? inventory
You’re not carrying anything.
What would you like to do? get rose
There’s no rose anywhere.
What would you like to do? go east
You go east.
> A red room
This room is fancy. It’s red!
Items: rose
Exits: north west
What would you like to do? get rose
You pick up the rose.
What would you like to do? inventory
Inventory:
rose
What would you like to do? go north
You go north.
> A green room
You are in a simple room, with bright green walls.
Exits: west south
What would you like to do? inventory
Inventory:
rose
What would you like to do? get rose
There’s no rose anywhere.
What would you like to do? get
Sorry, you need to ‘get’ something.
What would you like to do?
Verb: quit
The quit verb should exit the game. Sending an EOF (i.e., the user pressing Ctrl-D) should not end the game.
> A white room
You are in a simple room with white walls.
Exits: north east
What would you like to do? ^D
Use ‘quit’ to exit.
What would you like to do? quit
Goodbye!
Sending an interrupt should end the game immediately.
> A white room
You are in a simple room with white walls.
Exits: north east
What would you like to do? ^CTraceback (most recent call last):
…
KeyboardInterrupt
Extensions
In addition to the baseline functionality described above, you must implement three (3) extensions (if working alone) or five (5) extensions (if working in a group). We list six possibilities below, but these are not exhaustive. If you have an idea for a different extension, that’s great—but you must clear it with Prof. Greenberg first, or you won’t get credit for it. (We want to restrict possible extensions for three reasons: extensions should be appropriately scoped, i.e., not too hard or too easy; extensions should not interfere with baseline functionality; extensions should be tractable for the CAs to grade.)
Some of the extensions below offer some leeway in precisely how they behave. Have fun with it! But: extensions should not affect the baseline gameplay, i.e., they should not disrupt any of the baseline verbs and the core output of the game should not change. If you change baseline gameplay, you will likely fail some of our automated tests.
Abbreviations for verbs, directions, and items
It is common for text adventures to accept abbreviated forms of commands: for example, i might suffice to indicate inventory. It’s important that abbreviations only work when they are unambiguous: if you just typed g, would that indicate get or go? Such abbreviations are also useful for items and exits. Consider ambig.map:
[
{“name”: “A white room”, “desc”: “You are in a simple room with white walls.”,
“exits”: { “north”: 1, “northwest”: 2 }
}
,
{“name”: “A blue room”, “desc”: “This room is simple, too, but with blue walls.”,
“exits”: { “west”: 2, “south”: 0 }
}
,
{“name”: “A green room”, “desc”: “You are in a simple room, with bright green walls.”,
“exits”: { “east”: 1, “southeast”: 0 },
“items”: [“banana”, “bandana”, “bellows”, “deck of cards”]
}
]
Here’s an interaction in that map:
> A white room
You are in a simple room with white walls.
Exits: north northwest
What would you like to do? go n
Did you want to go north or northwest?
What would you like to do? go nort
Did you want to go north or northwest?
What would you like to do? go north
You go north.
> A blue room
This room is simple, too, but with blue walls.
Exits: west south
What would you like to do? go west
You go west.
> A green room
You are in a simple room, with bright green walls.
Items: banana, bandana, bellows, deck of cards
Exits: east southeast
What would you like to do? get deck
You pick up the deck of cards.
What would you like to do? get b
Did you want to get the banana, bandana or the bellows?
What would you like to do? get be
You pick up the bellows.
What would you like to do? get ban
Did you want to get the banana or the bandana?
What would you like to do? get band
You pick up the bandana.
What would you like to do? inv
Inventory:
bandana
bellows
deck of cards
What would you like to do?
For exits and commands, your matching should be prefix-based. Note that you sometimes the complete name of an exit (north) is a prefix of another valid exit (northwest)—it’s important that you’re able to use both exits. Items should be matchable based on any included string:
> A white room
You are in a simple room with white walls.
Exits: north northwest
What would you like to do? go northwest
You go northwest.
> A green room
You are in a simple room, with bright green walls.
Items: banana, bandana, bellows, deck of cards
Exits: east southeast
What would you like to do? get cards
You pick up the deck of cards.
What would you like to do?
A help verb
In complicated text adventures, it can be hard to keep track of what the verbs are. Having a help verb makes things easier for players.
In this extension, your help verb should tell players what the valid verbs are. We write … after verbs that expect a target of some kind:
> A white room
You are in a simple room with white walls.
Exits: north east
What would you like to do? help
You can run the following commands:
go …
get …
look
inventory
quit
help
What would you like to do?
To get full credit for this extension, your help verb must not simply be static text, but should be generated from the verbs that you have defined. That is, if you add a new command, it should somehow automaticallybe added to the help text. If you’re not sure what we mean mean, ask on #q-and-a on the Discord.
Directions become verbs
It’s common to be able to use an exit as a verb. That is, simply typing east instead of go east—or, if you’ve implemented abbreviations, typing e to go east.
It is important that these verbs don’t interfere with others, e.g., if you have a verb eat, it must be possible to both go east and to eat.
> A white room
You are in a simple room with white walls.
Exits: north east
What would you like to do? e
You go east.
> A red room
This room is fancy. It’s red!
Items: rose
Exits: north west
What would you like to do? s
There’s no way to go south.
What would you like to do? go west
You go west.
> A white room
You are in a simple room with white walls.
Exits: north east
What would you like to do?
To get full credit for this extension, you must support a way to give abbreviations for unusual exits, e.g., nwshould abbreviate northwest. How precisely you achieve this is up to you.
A drop verb
The drop verb is the opposite of get: take something from your inventory and put it down in the room. Just as get only lets you get items that are in the room, drop should only let you drop items that you already have.
> A white room
You are in a simple room with white walls.
Exits: north east
What would you like to do? go east
You go east.
> A red room
This room is fancy. It’s red!
Items: rose
Exits: north west
What would you like to do? get rose
You pick up the rose.
What would you like to do? look
> A red room
This room is fancy. It’s red!
Exits: north west
What would you like to do? go north
You go north.
> A green room
You are in a simple room, with bright green walls.
Exits: west south
What would you like to do? drop rose
You drop the rose.
What would you like to do? look
> A green room
You are in a simple room, with bright green walls.
Items: rose
Exits: west south
What would you like to do?
Locked doors
Make it possible for doors to be locked, requiring a certain item to unlock them. The precise set up of this is up to you: do you simply need to have the item, or do you add lock and unlock verbs for applicable doors? The details are up to you. You should (a) document your precise choices in your README.md, and (b) make sure that which doors are locked are represented in your asset, not in your game engine.
Winning and losing conditions
Make it possible to win (and possibly lose) the game. The precise set up of this is up to you: do you simply need to have some collection of items in a certain room, or do you need to use a special verb to trigger winning? For example, you might have a ‘boss room’: if you enter the boss room without both the sword and magic wand, you lose; if you enter it with both, you win. Here winning and losing should be indicated by special messages. The details are up to you. You should (a) document your precise choices in your README.md, and (b) make sure that what wins/loses the game is represented in your asset, not in your game engine. If you implement this option, please make sure to describe how to (and lose, if possible) in the README.md.
Interactions
Finally, many text adventures offer some form of interaction with the world or even other characters: dialog, combat, characters who move and make choices, and so on. If you are going to take this approach, you should make sure to scope things appropriately. For example, do just one of the following:
- Have a character who will trade one item for another. You might introduce talk and give
- Have a character who fights the player. You might introduce an attack Can the player win without finding a weapon or some other form of advantage?
- Have objects that demand custom verbs, e.g., a vending machine might need the user to push specific buttons or the player might need to pull a lever.
To get full credit, you must (a) introduce an interesting verb, that (b) has an effect on the world that no other verb does, and (c) the behavior is specified in your assets, not your game engine. The details are up to you. You should document your precise choices in your README.md. If you’re unsure about anything, please ask on #q-and-a in the Discord.
What do you submit?
You will need to submit three things:
- a md file including:
- the names and Stevens logins of your group members
- the URL of your public GitHub repo
- an estimate of how many hours you spent on the project
- a description of how you tested your code
- any bugs or issues you could not resolve
- an example of a difficult issue or bug and how you resolved
- a list of the extensions you’ve chosen to implement, with appropriate detail on them for the CAs to evaluate them (i.e., what are the new verbs/features, how do you exercise them, where are they in the map)
- a public GitHub repo with your code in it (which you can submit directly to GradeScope)
- we should be able to run your game by running `python3 adventure.py [map name]` in a the base directory of a clone of your repo
- a new map file that uses every extension (as applicable—help doesn’t affect the map)
After submission, we’re going to do two things: we’re going to run your code on a couple of maps of our own, that don’t make use of any extensions; and we’re going to follow the instructions in your README.md on the map that you provide. The first tests will be automated, making use of the core game logic—so it’s very important that you don’t change how things look! Your extensions cannot mess with a ‘vanilla’ map, which should play ‘normally’. You have to be very careful that your extensions do not alter the core gameplay!
