Part 5 mini-project: Text Adventure

The biggest project yet. It uses every Part 5 idea — functions, lists, dictionaries, modules — to build a small text adventure: a player walks through rooms typing commands like go north and take torch.

What to build

A program that, when run:

  1. Drops the player into a starting room.
  2. Loops:
    • Prints the current room's description and any items in it.
    • Prompts for a command.
    • Carries out the command:
      • look — describe the current room again.
      • go <direction> — move through an exit (north, south, east, west, up, down).
      • take <item> — pick an item up off the floor.
      • inv — show what the player is carrying.
      • quit — stop the game.
  3. Wins when the player picks up the gold coin: print a victory message and exit.

Sample session:

-- Forest Path --
You are on a moss covered forest path. Birdsong drifts on the air.
Exits: north
> go north
-- Clearing --
A small clearing of wildflowers.
Items here: torch
Exits: east, south
> take torch
You pick up the torch.
> go east
-- Cave Entrance --
A cool, damp cave mouth opens to the east. A rope lies coiled on the floor.
Items here: rope
Exits: down, west
> quit
Goodbye.

File layout

Two Lua files sit side by side. Since main.lua loads world.lua with require, cd into their folder before running. To play the finished version:

cd projects/04-text-adventure/finished
lua main.lua

Files:

  • world.lua — exports the rooms table. Each room is a dictionary with name, description, exits, and items.
  • main.lua — the game loop and command functions.

Both versions live under projects/04-text-adventure/:

starter/
    world.lua
    main.lua
finished/
    world.lua
    main.lua

To work on the starter:

cd projects/04-text-adventure/starter
lua main.lua

Hints

  • The rooms table maps room id (a number) to a room. Exits map a direction to the id of the room it leads to. A room's items are a string list.

  • The player has two pieces of state: current_room_id (a number) and inventory (a list of strings).

  • To parse go north, split it into a verb and argument:

    local words = {}
for w in string.gmatch(input, "%S+") do
    table.insert(words, w)
end
local verb = words[1]
local arg = words[2]

  • The win check after a successful take is one if: was it the gold coin? If so, print the win message and break out of the main loop.

What you cannot use yet

  • Methods and self (chapter 26). Functions take the table they work on as a plain argument — take(item, room, inventory), not room:take(item).
  • Metatables (chapter 27). Plain tables and functions are enough.
  • Roblox APIs. Still pure terminal Lua.

A stretch (optional)

  • Add a read command for signs or letters.
  • Lock one exit until a specific item is carried (e.g. the gold coin is only reachable if the player has the torch).
  • Add an enemy that blocks an exit until the player uses a sword.

None of these are required to finish the project.

Done?

When you can walk through every room, pick up the items in order, and trigger the win on the gold coin, the project is complete. Move on to Chapter 26 — Methods and self, the first chapter that uses Roblox-style syntax directly.