Building a game with Amazon Q Developer: Writing some game server documentation
When the code is looking cryptic, Amazon Q Developer Agent is here to help
Nathan Peck
Amazon Employee
Published May 1, 2024
In the previous article I introduced a generative AI game that I have been working on. In that article I talked about using Amazon Q Developer to help me build a core Vue component for the front end web client for the game. But I was hiding a little secret, which was that I had already started on the backend server for the game some time ago!
Of course, as with any non trivial project, the larger the project gets and the more things there are to do on the project, the more likely it is that you’ll lose track of what you were working on. In this case, I had thrown together a quick prototype of a WebSocket server that basically ties together a collection of LLM prompts and two AWS services:
- Amazon Bedrock - Provides my game server with generative AI powered responses to my game’s prompts
- Amazon DynamoDB - A serverless backend store for all the game’s state
The game server allows the game client to initiate game actions over WebSocket protocol. The game server then dispatches prompts to Amazon Bedrock and waits for the response to come back. When the model is done answering a prompt, the game server updates the player’s game state in DynamoDB, and then pushes updates back down to the game client.
This is a great architecture for a generative AI game, because many of the LLM backed prompts can take at least ten to fifteen seconds to finish answering the prompt. If I implemented the game server as a traditional HTTP API, then the game server would need to keep track of many long running requests, and I would have to deal with the problem of HTTP requests timing out. A server built on the WebSocket protocol can keep a single open connection to each game client, and then push game info back down the client the moment that info is ready for the client.
But I had a problem: my initial prototype was thrown together in a hurry, and I did not write any documentation for it. After taking a break for a few weeks to work on the Amazon Q Developer launch I had completely forgotten many aspects of how my game server worked, what commands I should expect it to answer to, and even what format the responses were.
As I sat there with my IDE open, and a cryptic looking block of code in front of me, I realized that I really needed to document how this thing works.
Luckily, I have Amazon Q Developer Agent to help!
I opened the Amazon Q chat window in my IDE and typed
/dev . This tells Amazon Q Developer that I want it to read all the code files in my project, and instead of answering inline in the chat, construct a code diff that can be applied to my project.My command to Amazon Q was:
/dev Write a README.md file in the /server directory, which describes the WebSocket format of the server
Amazon Q started out by collecting my code files and coming up with a plan. Amazon Q asked me to review the plan first:
From the plan I could see that Amazon Q had already understood a few key concepts:
- the game server accepts commands from a client
- the game server responds to the client with various responses
- it has started to collect a list of commands that it has noticed, such as
fetch inventory,disassemble item, etc
I approved this plan, and Amazon Q started executing on the plan.
Amazon Q took about two minutes to produce results for the plan, but this was fine because it allowed me to tab out of my IDE and catch up on some email, respond to Slack messages, etc.
I don’t know about you, but after lots of time spent writing in interpreted languages I’m pretty excited to revisit the world of the legendary XKCD 303, with a modern twist of course:
A couple minutes later Amazon Q came back with a code diff that I could click on to preview right there in the IDE:
I was actually quite surprised with how good the
README.md file was as a starting point. Amazon Q broke the file into two main sections: one section for client to server messages, and one section for server to client messages. While there were a few small mistakes in the example message formats, I was able to use this README.md as a strong starting point, then make minor changes as I noticed mismatches between the auto generated docs and the real message formats.In this case I can’t blame Amazon Q Developer Agent for getting some of the example message formats wrong, because most of the game server message format is itself something that is generated by an LLM model on the Amazon Bedrock side. For example, one of my prompts currently looks like this:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
export const repairItem = function (persona, repairItem, components) {
return `
I want to repair a broken item. The following document describes my skills,
and available tools:
${JSON.stringify(persona)}
I plan to repair the following item:
${JSON.stringify(repairItem)}
I will use the following components for the repair:
${JSON.stringify(components)}
Write a JSON document with following structure:
story - A short paragraph about how I repair the item. I should only attempt
repairs that are reasonable given the repair components, and my skills.
item
item.name
item.description - A description of the appearance of the item
item.weight - weight of item
item.value - Value of the item should increase only if successful repairs are made
item.color - human readable
item.materials - array of material types
item.damage - A short description of the condition of the item`;
}The JSON response from the game server is therefore mostly a generated response that is not directly found anywhere in my game server code base. Predicting that response format requires deriving it by reading the prompt embedded in my code. Amazon Q Developer Agent did a decent job at this, and while it got a few fields wrong I was able to fix those pretty easily.
One of my key takeaways from working with generative AI as part of my code development cycle is that good documentation is key. Just like when working with a human developer, if you write good documentation then the AI agent will be able to generate better and more accurate code. Fortunately, even if you don’t have great docs yet you can get there by using Amazon Q Developer Agent to help generate doc strings, documentation examples, and other key documentation artifacts that can then be utilized by subsequent feature development workflows.
At this time the first pass of generated documentation was not 100% accurate, however it still saved me a massive amount of time on writing the docs from scratch. I would estimate that the generated docs were at least 80% of the way there, and the final 20% took another 15 minutes or so to validate for accuracy. Best of all, this documentation will make future feature development passes by Amazon Q Developer Agent even smoother!
I highly recommend trying out Amazon Q Developer Agent in your IDE. There is a free tier that doesn’t even require an AWS account. All you need is an AWS Builder ID. Find more on getting started with Amazon Q in the Developer Center.
Any opinions in this post are those of the individual author and may not reflect the opinions of AWS.