Introducing "The Adventure Game", an unoriginal title for a game I wrote for this November's "AWS Game Builder Challenge". It's a text based, open ended, RPG (role playing game), and while I mainly wrote it to experiment with some application architecture concepts, I found that I really enjoyed playing it, and so have a few others who have tried it out.

The game is designed as a base from which to experiment. Either through playing the game, or making some adjustments to the code. How far you go, is up to you, your interests and the time you have available.

This post is split in to several different sections. First I will outline the simple idea behind the game mechanics. Then I will walk through a level 100 of how to get the game up and running on your machine. I will then move on to a level 200 of how to make some adjustments, a level 300 of how the game state actually works, and finally a level 400 walk through of making a significant change to the game mechanics.

If you enjoy this post, please give it a 👍 up above! Thanks!

The Game Concept

The Adventure Game (UNLIKE its 1980's BBC TV Show namesake), is an RPG, with similar basic mechanics as DnD (Dungeons and Dragons). The game itself takes the role of a story teller (or a DM) and will guide you through a unique story each time you play. The decisions YOU make and what YOU choose to do will influence the narrative as much as the story telling game. If you decide to try and throw the game by doing weird and non-obvious actions (what my family called "Deadpooling" :) ) then that is on you, and what ever happens next happens. I suggest, as with any RPG you play, is to mostly go along with the spirit of the story teller, and have fun. During the game, when an action is taken, the story teller may choose to roll a dice (or many dice) to allow some randomness to decide your fate.

When you start the game, you choose the scenario, and off you go. I enjoy playing "Space Wars" inspired games, but the choice is yours. Here is a sample of some game play:

Note on Cost:

Running this project will incur costs that are NOT covered by AWS Free Tier (and may not be covered by AWS credits). This project makes use of generative models through Amazon Bedrock, and depending on which model is used, the size of prompts and the number of turns, the cost will vary. This project is not intended to be a cost effective way to run a game. Please review the Amazon Bedrock Pricing page for more details.

Note on Game Play (and Kids):

This game uses generative AI, and as such the game state may not be consistent or predictable. Caution should be used when playing this game, especially with sensitive topics or allowing children to play. It is not recommended to enter private information or allow children to play without adult supervision.

Getting Started

This game is written in Python, in simple text mode, so it can just run on your local machine, from the command line. The game uses AWS services specifically Amazon Bedrock for generative AI stuff, and if you want more detail on that, read this post to the end. If all you want to do is get started and play, then this is what you will need to do:

Setting Up Your Environment

1. Python Environment Setup

First, you'll need a Python environment that can work with AWS services. Here's how to set this up:

Install Python 3.8 or later if you haven't already. You can download it from python.org
We recommend using a virtual environment to keep things clean:

Activate your virtual environment:
On Windows:

On macOS/Linux:

2. AWS Setup and Security

Setting Up AWS Credentials

There are several ways to configure AWS credentials, but here's the most straightforward method for getting started:

Create an AWS IAM User:

Sign in to the AWS Console as an administrator
Go to IAM (Identity and Access Management)
Create a new IAM User
Enable "Programmatic access" to get access keys

Apply Least Privilege Access:

Create a custom policy that only allows access to Bedrock
Example minimal policy (save as JSON):

Attach this policy to your new IAM user

Get Your Credentials:

After creating the user, you'll receive an Access Key ID and Secret Access Key
Save these somewhere secure - you won't be able to see the Secret Access Key again

Configure Your Local Environment:

Enter your Access Key ID and Secret Access Key when prompted
Set your default region (e.g., us-east-1)
Set the output format to json

Security Notes:

Never commit AWS credentials to source control
Don't share your access keys
Consider using AWS IAM Identity Center (formerly AWS SSO) for enterprise environments
For production deployments, consider using IAM Roles instead of access keys
Regularly rotate your access keys
You can store credentials in environment variables if you prefer:

Alternative Setup Methods:

AWS CLI credentials file (~/.aws/credentials)
AWS IAM Identity Center
Environment variables
AWS SDK credential providers

3. AWS Bedrock Access

The game uses Amazon Bedrock for its AI storytelling. You'll need to:

Sign in to your AWS Console
Navigate to the Amazon Bedrock console
Click on "Model access" in the left navigation
Find and enable the language model. (Initially the game uses Anthropic's Claude 3.5 Haiku, but you can experiment with other models from Amazon Bedrock.)
Click "Save changes"

Note: You'll need an AWS account with appropriate permissions.

4. Get the Game Code

There are two ways to get the code:

Option 1: Clone with Git

If you have Git installed, you can clone the repository:

Option 2: Download ZIP File

If you're not familiar with Git:

Visit the game's GitHub page at https://github.com/build-on-aws/amazon-bedrock-adventure-game
Click the green "Code" button
Select "Download ZIP"
Extract the downloaded ZIP file to your preferred location
Open a terminal/command prompt and navigate to the extracted folder

5. Install Dependencies

With your virtual environment activated, open your command line terminal, change to the project folder and install all required packages:

This will install all necessary Python packages, including the AWS SDK (boto3) and other dependencies the game needs.

6. Run the Game

Now you're ready to play! Start the game by running:

Troubleshooting Common Issues

If you encounter errors:

Ensure your virtual environment is activated
Verify your AWS credentials are properly configured
Check that you have enabled the correct model in Amazon Bedrock
Make sure all dependencies installed correctly

How The Game Works (Level 100)

This game is a text adventure that uses AI to create an interactive story experience. While traditional text adventures use pre-written responses and fixed maps, this game creates the story dynamically using Amazon's Bedrock AI service. Here's a high-level overview of how it works:

The Basic Structure

The game maintains a "world" using a graph structure where rooms connect to each other
Each room can contain:
- Objects that can be picked up
- NPCs (Non-Player Characters) to interact with
- Descriptions of what you see
- Exits to other rooms

The Game Loop

You type in what you want to do (like "look around", "go north" or "slay the dragon!")
The AI interprets your command and decides what should happen
The AI uses an agent, and uses tools to:

Create or modify rooms
Move your character around
Add or remove objects
Control NPC

The AI's Role

The AI acts like a dungeon master in D&D - it:

Creates the story and environment
Controls how NPCs react to you
Decides what happens when you try to do something
Keeps track of what's possible and what isn't
Maintains a consistent world and story

Behind The Scenes

The game uses several key components:

A game state manager that tracks where everything is
A tool system that lets the AI modify the game world
Amazon Bedrock to provide the AI capabilities
A simple command-line interface for player interaction

The beauty of this design is that the game world can adapt and change based on your actions, creating a unique story each time you play. While traditional text adventures follow a script, this game creates the adventure as you go, responding to your choices in creative ways.

Making Simple Changes (Level 200)

When I first started building this game, I wanted to make sure that anyone could customize it, whether they could code or not. That's why one of my favorite features is the system prompt - it's just a text file that controls how the AI behaves, but it's surprisingly powerful. Think of it as the AI's personality and rulebook all rolled into one.

The Magic of the System Prompt

Open up system.txt in any text editor, and you'll find what looks like a set of instructions. This is where all the magic happens. It tells the AI everything from "you're a dungeon master" to specific rules about how it should describe scenes or handle player actions. The beauty of this setup is that you can completely transform your game just by editing this file.

Let me give you a practical example. Say you're tired of the standard way the game responds and you want the game to use the voice of a pirate no matter what the theme (a common request?). You don't need to touch any code - just find the writing style section in the system prompt and change:

Just like that, your game takes on a completely different tone. The same AI that was describing dragon-filled dungeons is now talking filled with 'arr me matty!'.

Experimenting with Game Feel

The system prompt isn't just about changing the writing style though. Want longer, more detailed descriptions? Find this section:

Or maybe you want to change how the game handles chance and skill checks:

You can even change how the game world is initially set up:

Making Changes Safely

Before you dive in and start editing, though, let me share some lessons I learned the hard way. First, always back up your original system.txt. It's easy to get carried away with changes and forget what the original looked like.

Start small - change one section at a time. The AI is pretty smart about following instructions, but it can sometimes interpret things in unexpected ways. I once tried to make the descriptions more detailed and accidentally ended up with a game that spent three paragraphs describing every doorknob.

Be specific in your instructions. Instead of saying "make it funnier," tell the AI exactly what kind of humor you want. And always check that your changes don't contradict other parts of the prompt - the AI will try to follow all instructions simultaneously, which can lead to some interesting but unintended results.

Getting Creative

Once you're comfortable with basic changes, you can start getting more creative. Add new sections to handle specific situations. Include examples of exactly how you want the AI to respond in certain situations. You can even create different system prompts for different genres or game styles.

Remember, the system prompt is essentially the AI's instruction manual - it will follow these guidelines religiously. This makes it an incredibly powerful tool for customizing your game without needing to understand the code behind it. Try adding in detail about the kind of theme you want, more than you type in at the start of the game. Whether you want to create a horror game, a space opera, or a romantic comedy, it's all possible just by editing this one file.

The only real limit is your imagination. Well, that and remembering to back up your files before you start experimenting!

Understanding the Agent Architecture (Level 300)

When I first started building this game, I could have gone the simple route - just keeping the game state in the AI's context window and letting it manage everything. But I wanted to build something more robust, something that could grow beyond simple text adventures. Let me walk you through what I built and why it matters.

The Three-Layer Architecture

At its heart, the game is built on three main components working together: an AI agent that makes decisions, a tool manager that executes those decisions, and a graph database that keeps track of everything. Think of it like a movie production - the AI is the director, the tools are the crew, and the graph is the set where everything happens.

The star of the show is the ConverseAgent. This is our director, taking in the player's input and deciding what should happen next. It talks directly to Amazon Bedrock, maintaining the conversation and figuring out what tools it needs to use to make things happen. Here's what that looks like in practice:

What does the code do? Use Amazon Q Developer installed in your IDE to explain the code. Once you have installed Amazon Q Developer and logged in with your AWS Builder ID, highlight any code you want to query, then right click and select "Amazon Q" > "Explain". Try is here, and try it on any code you want more information on!

But a director needs a crew, and that's where the ConverseToolManager comes in. Instead of letting the AI directly modify the game state (which could get messy), we give it a set of specific tools it can use. Each tool is like a specialist on our crew - one for creating rooms, another for moving players, another for handling objects. Here's how we set up one of these tools:

Finally, we have our set - the GameState. This is where everything gets interesting. Instead of trying to cram everything into the AI's context window (which has limits), we use a graph structure built with NetworkX. Rooms connect to other rooms, players can hold items, NPCs can be in locations - everything is represented as nodes and edges in this graph. It's like a web of relationships that can grow as complex as we need it to.

Why This Matters

You might be wondering why go to all this trouble. Why not just let the AI keep track of everything in its context? The answer becomes clear when you start pushing the boundaries of what's possible.

Imagine you're playing a massive open-world game. The AI's context window can only hold so much information - maybe a few rooms and some recent history. But our graph structure? It can hold an entire world. Players can leave items in one room, travel across the map, and come back to find everything exactly where they left it. The state persists independently of any conversation with the AI.

But it gets better. Because we're using tools with clear interfaces, we can have multiple AIs working with the same world. One AI could be controlling a shopkeeper while another manages the town guard. They're all working with the same consistent state, but each bringing their own personality and goals to the interaction.

Here's a tantalizing possibility:

The Experimental Frontier

This is where things get really interesting. The architecture I've built here is just the beginning - it's a foundation for experimentation. You could extend this in fascinating ways:

The graph structure is currently just stored in memory while you play, but it could be backed by a database, allowing persistent worlds that exist beyond single play sessions. You could add new types of relationships - maybe items could have magical connections, or rooms could shift based on time of day.

The tool system could be expanded with more complex behaviors. Imagine creating compound tools that execute multiple actions in sequence, or tools that have prerequisites and consequences. You could even have tools that generate new tools dynamically.

And the agent itself? It could be enhanced with memory systems, learning from past interactions. You could implement planning systems that let it think several moves ahead. Different agents could specialize in different aspects of the game world - one for combat, another for puzzles, another for character interaction.

This is why I find this architecture so exciting. It's not just about running a text adventure - it's about building a framework for experimentation with AI-driven interactive experiences. Every component is a hook for future expansion, every interface a door to new possibilities.

Adding Health (Level 400)

Let's make some changes to the game mechanics.

One fundamental element missing from our text adventure is the concept of health - that classic RPG mechanic that adds tension and consequences to our actions. Let's walk through how to add this to our game, building on the existing graph-based architecture.

Understanding What We're Building

We want to add a few key capabilities:

Track player health
Allow damage and healing
Let the AI use these mechanics in storytelling
Enable game-over scenarios

The nice thing about our graph structure is that we can add these properties to any entity - not just the player. This means the same system could track NPC health too.

Extending the GameState

First, let's add health tracking to our GameState class:

Registering the New Tools

Add these tools to your register_tools.py:

Updating the System Prompt

Add these instructions to your system prompt so the AI knows how to use the new mechanics:

Give it a try...

Work with the code examples above, test, experiment and see if it manages the health of the characters in a way that you want. What happens when the game ends? Do you want to add code that will stop the game? Or should you play on as a ghost? :)

Taking It Further

This basic health system opens up lots of possibilities:

Add armor that reduces damage
Create healing items and spells
Implement different damage types
Add status effects that modify health over time
Create NPCs with different health pools

Remember to handle edge cases:

What happens to items when a character dies?
Should some damage bypass armor?
How does healing work in combat vs. out of combat?

The beauty of using our graph structure is that health becomes just another property we can track and modify. Because it's stored in the graph, it persists between interactions and can be referenced by any tool or agent that needs it.

This implementation provides a solid foundation for adding more complex combat mechanics later. You could expand it to include mana for spells, stamina for actions, or even complex status effects building on this same pattern.

What's Next?

So there you have it - a text adventure game powered by AI that you can extend and modify to your heart's content. Whether you stick with the basics or dive into the advanced features, I hope this gives you a foundation to build something unique.

If you enjoyed this post, please give it a 👍 at the end! Thanks!

AWS Games Builder Challenge

Speaking of building something unique - this kind of project would be perfect for the AWS Games Builder Challenge! The challenge is all about exploring innovative ways to use AWS services in game development, and an AI-powered text adventure certainly fits the bill. Whether you use this code as a starting point or create something completely different, the challenge is a great opportunity to showcase your creativity.

Check out the AWS Games Builder Challenge here to learn more about participating. You can enter solo or as part of a team, and there are some amazing prizes up for grabs!

Get Involved!

I'd love to see what you create with this. The code is available on GitHub, and I'm particularly excited to see:

New system prompts that create unique game genres
Creative tool implementations
Interesting game mechanics
Novel uses of the graph structure
Fun game scenarios you create

Some Ideas to Get Started

Create a murder mystery where NPCs have complex relationships
Build a trading game with dynamic economies
Design a dungeon crawler with procedurally generated rooms
Make a diplomatic simulation where AI NPCs negotiate with each other
Build a survival game with resource management

Give it a Try

The beauty of this project is that it scales with your ambition. You can start by tweaking the system prompt to create your own adventure, then gradually add new features as you get comfortable with the code. The AI will adapt to whatever new tools and mechanics you add, often in surprising and delightful ways.

Stay in Touch

I'm always excited to see what people build with AI. If you create something cool or just want to chat about AI game development:

Find me on https://linkedin.com/in/mikegchambers
Share your creations using the tag “game-challenge” on https://community.aws
Let me know if you enter the AWS Games Builder Challenge!

Remember, the real magic of AI isn't just in what it can do out of the box - it's in how we can shape and direct it to create new experiences. This game is just one example of what's possible when we combine AI with traditional game mechanics and AWS services.

Now go forth and create some adventures! And if you're wondering if the AI made me write that last line... well, maybe it did, maybe it didn't. That's part of the fun, isn't it?

PS: And yes, I know you made it all the way to the end of this very long post. You're exactly the kind of person who might build something amazing with this. Can't wait to see what you create in the challenge!

Any opinions in this post are those of the individual author and may not reflect the opinions of AWS.

Site Terms, Privacy, and more.