Welcome to Text Adventure Game, a friendly game engine for making interactive text stories, while learning the basics of programming along the way!
With a plain text file, you can create your own dynamic story driven adventure. Define rooms that change with events, characters to talk to, and conversations that evolve with the story. You can even customize the theme with your own colors, or change the default game text to match your language or style of speech. After you define your game in an .ini file, you can run the engine with it, and bring your text adventure game to life!
(Click to see table of contents)
To run the game, first install or download text-adventure-game, then create an .ini file describing your game world, or use the example file below.
(Click to read detailed instructions)
-
Right-click the
.zipfile and select Extract All.... -
- Right-click the link → Save link as...
-
Move
example.iniinto the folder where you extracted the game. -
Open the Start Menu, type
cmd, and press Enter to open Command Prompt. -
Navigate to the folder where you extracted the files:
cd path\to\your\download\folder
-
Run the game:
text-adventure-game.exe -f example.ini
-
Open Finder, then double-click the
.tar.gzto extract the app. -
- Control-click the link → Download Linked File As...
-
Move
example.iniinto the folder with the game binary. -
Open Terminal (use Spotlight with
⌘ + Space, then type “Terminal”). -
Navigate to your Downloads folder:
cd ~/Downloads
-
macOS blocks running unsigned apps by default. To fix this:
-
Run:
chmod +x text-adventure-game
-
Then attempt to run it:
./text-adventure-game -f example.ini
-
If macOS blocks it, go to System Settings → Privacy & Security, scroll down, and click "Allow Anyway".
-
Then try running it again.
-
-
Extract it using your file manager, or run:
tar -xzf text-adventure-game-x86_64-unknown-linux-musl.tar.gz
-
- Right-click the link → Save Link As...
-
Move
example.inito the same folder as the extracted binary. -
Open your terminal and navigate to that folder:
cd ~/Downloads
-
Make the game executable:
chmod +x text-adventure-game
-
Run the game:
./text-adventure-game -f example.ini
On Linux or macOS, open a terminal and run:
text-adventure-game -f path/to/your/game.iniOn Windows, open Command Prompt from the Start menu and run:
text-adventure-game.exe -f path\to\your\game.iniJust download and unzip the file for your OS below.
| Platform | Link |
|---|---|
| 🐧 Linux (musl) | Download |
| 🪟 Windows | Download |
| 🍎 macOS | Download |
🛠️ After downloading, extract the archive. Then double-click the executable or run it from the terminal as shown above.
Try this example.ini demo game. Right-click the link and choose “Save Link As…” to save it.
Read about the development process for this project on Y = Code!
Every game is defined in a single .ini file, a simple, old-school format that's easy to read and edit. This file is divided into sections that describe a part of your game world: the title screen, theme, rooms, characters, and more. You can add comments with semicolons ; to provide context within your file.
As an enhancement to the .ini file format, Text Adventure Game adds support for multi-line strings. Simply wrap your text block in triple quotes """ and you can you extend it as far as you like. For example:
description="""
A cold wind blows.
You see your breath.
"""The root (unnamed) section must define the following fields:
title=The Game Title
greeting=Welcome to your next adventure!
credits=Thanks for playing!
start_room=StartingRoomtitle: Displayed at game launch.greeting: Displayed when the game begins.credits: Displayed when the game ends.start_room: TheTitleid of the room the player begins in.
[Theme]
title = Red
heading = Green
background = #FF3344
text = #FFFFFF
highlight = RGB(10, 50, 10)
highlight_text = Blue
subdued = GrayDefines colors for the UI. Most valid CSS colors should work, including RGB, hex codes, and common color name strings.
Allows you to override built-in strings (e.g., “Talk”, “Do”, “Go”) for localization to different langauges or stylistic changes.
[Language]
characters_found = You look around and see:
exits_found = You can exit in these directions:
talk = Talk
interact = Interact
go_somewhere = Go someplace?
end_game = End the game?
choose_exit = Get out of here?
cancel_exit = Don't leave
choose_chat = Talk to:
cancel_chat = Nevermind
choose_response = You say:
cancel_response = ...
choose_action = You decide to:
cancel_action = Nevermind
action_failed = That didn't work
continue_game = Keep Going?
press_q_to_quit = The letter q is for quit!Each entity section starts with one of the following headers:
[Room:RoomName][Room:RoomName|variant](see Variants below)[Character:CharacterName][Dialogue:dialogue_id][Dialogue:dialogue_id|variant](see Variants below)[Response:response_id][Item:item_id][Action:action_id]
| Type | Syntax | Example |
|---|---|---|
Title |
CamelCase | StartingRoom |
Identifier |
snake_case | the_ring |
The engine will prettify names when shown to players:
StartingRoom→ Starting Roomthe_ring→ The Ring
Only rooms and character names use Title syntax. Everything else is an Identifier.
Some entities can have variants to reflect dynamic changes (e.g., after an event):
[Room:Basement|rubble]
description=The basement is filled with rubble.The default variant is the one with no |variant suffix. All entities that have variants must include a default. Variants use Identifier syntax.
Each room must define:
[Room:Basement]
description=A cold, damp basement.
exits=north:LivingRoom,east:SecretLab
characters=CuriousCalvin
actions=open_cratedescription: Text shown when entering the room.exits: (Optional) Comma-separated list of directions and destinations. Each direction is separated from the destination room name by a colon:.characters: (Optional) Comma-separated list of characters present.actions: (Optional) Comma-separated list of actions available.
If a room has no exits, the game ends when the player enters it!
[Character:NeighborFrank]
start_dialogue=hellostart_dialogue: The ID of the dialogue shown when the player talks to this character.
[Dialogue:hello]
text=Hi there!
responses=wave,goodbyeDialogues show text and present a list of responses. They can have variants to show different text based on game state.
text: Text spoken by the character.responses: (Optional) Comma-separated list of response IDs. If omitted, the chat ends immediately.
[Dialogue:hello|rude]
text=Go away!
responses=shrug
requires=has_item:the_ringUse the optional requires attribute to conditionally show dialogue variants. Supported conditions:
has_item:item_idroom_variant:RoomName|variant
If no requirements match, the default variant (no |variant) is shown.
[Response:wave]
text=You wave back.
leads_to=goodbyetext: This text appears as a selectable menu option.leads_to: (Optional) The next dialogue ID. If not specified, the chat ends.
requires works the same way as for dialogue, but responses do not have variants.
[Item:the_ring]
description=A mysterious golden ring.Items can be given to or taken from the player via actions.
Actions are powerful tools for changing the state of your game. They can move the player, give or take items, swap things out, or even end the game. All by modifying other entities in response to what the player does.
Here are some example actions:
[Action:pull_lever]
change_room=WoodShed->closed
description=You pull the hefty lever and hear a satisfying clunk! Immediately, the lights go out, and the lever seizes in place.
[Action:pay_bribe]
take_item=silver_coin
description=You give away your last coin begrudgingly.
[Action:unlock_chest]
replace_item=key->ring
description=You unlock the chest and discover a golden ring!
[Action:pickup_key]
give_item=key
description=You pick up the dingy key on the floor.
[Action:beam_me_up]
teleport_to=Enterprise
required=silver_coin
description=Scotty teleports you aboard the ship!
[Action:push_the_red_button]
sequence=pickup_key,unlock_chest,beam_me_up
required=golden_ticket
description=You don't quite know what just happened, but you are now on a spaceship with a ring in your hand!You can define several types of actions:
ChangeRoom: Updates the to a specified variant.GiveItem: Adds items to the player's inventory.TakeItem: Removes items from the player's inventory.ReplaceItem: Swaps one item for another.Teleport: Instantly moves the player to a different room.Sequence: Chains together multiple actions in order.
The actions Teleport, Sequence, and ChangeRoom include an optional required field. If specified, the required item must be in the player's inventory to perform the action. Additionally, when that action is completed, that item is then removed from the player's inventory.
Actions make your game feel alive. For example, suppose an event requires that characters move between rooms. You can combine a ChangeRoom and a Sequence to update multiple rooms at once, switching them to a variant where those characters are in new locations.
Furthermore, if you need to trigger a conversation, a single GiveItem action can do . Since dialogues and responses are switched by room variants and items in the players inventory, giving the player an item can open up new dialogue options. Additionally, if you want to end the game at any point, can use the Teleport action to send the player to a room with no exits, as that ends the game.
Actions aren’t just mechanics, they are key to telling a dynamic story.