Build your Own AI - Part 2

Or Implementing Live Ops and In-App Artificial Intelligence

Date first published: 6th May 2024

Introduction

Hello and Welcome to this second article in the G-Man’s Streetwise Series on How to Build Your Own AI! My name is Graeme Clarke, software engineer, green computing pioneer, author and inventor.

If you missed the first article in this incredible series, you can find it right here. It will tell you that the point of this initiative is to build an AI that will increase user engagement in my own mobile adventure game, a Celtic Themed, Murder Mystery extravaganza called Otherworld Epic Adventure!

Today, I’m going to dive into the design of the software that makes up the AI, the data pipelines, (an essential element), and I’ll devote a quick word to the look and feel of the user interface.

I’m not going to touch on testing the system but before anyone starts throwing ripe fruit, you can find my thoughts on this subject right here in another of my Streetwise Articles: Designing For Test.

I also hope to impart some of my wisdom and experience in successfully building quality software systems over the last three decades. If you’re not interested in reading all my bemused ramblings but still want the good stuff, then keep an eye out for the HOT TIP callouts.

So read on or in the immortal words of Dave Lister: “Let's get out there and twat it!”

Recap – What Are We Trying To Achieve?

As we dig into the system design, it is essential to make sure that it ties back to the original business requirements enshrined in the Epics and Features written down in the first article. Don’t worry about going and reading it again, here is a recap. Otherworld is a big adventure game and players can quite easily wander around and get lost. This is why the first Feature is this:

We want to keep players engaged by providing hints and tips of what to do next.

The game has over two hundred points on the map that can be visited, (these are called Locations). There are also in excess of one hundred items, certain of which have to be actioned in particular ways and at the right location to solve puzzles and uncover the story. Some of the map locations are impossible to access without first going through others and of course, some are harder to find than others.

Basically, this Feature is still massive! It’s too much to try and develop at once and needs breaking down into some User Stories:

As a player wandering around Otherworld, I want a hint to tell me where to go next.
As a player unable to solve a puzzle I want a hint of what to do.
As a player interested in the plot I want to know if I’ve missed part of the story or where to find the next bit.

These must be prioritized and linked to the business value we want to achieve. Just like the Feature prioritization in Article 1, I’ve used a simple scoring system:

Table showing prioritization of Features

In Agile Software Development we want to do the minimum amount of work possible to achieve the maximum value. So, rather than try and boil the ocean and build everything at once, we’ll now focus on the design and development of a single User Story and see how it lands with the players. Besides, if the feedback is bad then we can always make changes later.

Section 1 – The Software Design or How On Earth Is This Actually Going To Work?

How It Will Actually Work is also called the Use Case. Many people think that in modern software development, User Stories have replaced Use Cases but in fact both of these are required. The User Story speaks to the value, (the Who, What And Why), whereas the Use Case addresses the How.

I’ve been around for a long time and while I haven’t played pool with planets I have certainly written just about every type of software you can think of. If I was to distill all my wisdom down to a single piece of advice it would be this.

Get the requirements right, and write the use case in clear language as this will save tons of rework and testing later on which are both time-consuming and expensive.

Many people also think that AI is the realm of Gandalf or Harry Potter and there is magic inside it that comes up with the result we’re looking for. Perhaps the AI is alive, reaching consciousness once the volume of data reaches a certain critical mass or it has somehow distilled the essence from the collective brains of those who invented it?

Some of these things may be true, (depending on your definition of alive), however, at its heart an AI is still just a series of algorithms acting on data with an ability for the system to learn and improve built-in. That’s why it's even more important for us to understand at a high level how the overall system will work.

Now we don’t need a wand, cauldron, or even some fancy markup language, we write this stuff in good old Anglo-Saxon. And here it is:

Use Case Show Direction Hint

If the player makes too many moves without visiting a Location the AI chooses the highest priority Location from those that are currently accessible:

Mandatory Locations are higher priority than optional locations.

Locations earlier in the Walkthrough Guide are higher priority than later ones.

Locations closer to the player are higher priority than ones further away.

The AI gives a hint for the right direction but makes the game easier by decreasing the number of moves required before the next hint is displayed.

When the player visits a Location, the AI removes its hints and adds new hints for any new Locations that can now be accessed. The AI makes the game harder by increasing the number of moves required before the next hint is displayed.

There will be a huge amount of input data flowing into the AI as the game is played. This includes the player's movements around the world, the items they pick up and the things they try and action. Some of the hints may not be useful so we will build in a feedback mechanism for the AI to learn what the player thinks of them.

Here are a few extra supporting use cases:

When the system displays a hint the player indicates if it is useful or not.
At any time, the player can request a hint be displayed regardless of the number of moves since the last hint.
The system continues to display the same hint until the player either visits the location or dismisses the hint. The next time the system displays the hint it changes the text based on the distance from the location and whether the hint has been displayed before.

What this should mean is that the more hints that are displayed the easier the game gets. Also, if the player visits Locations without hints the game should get harder.

In the Diving into the Detail section, we’ll look at the actual design of the software and what specific information we’ll feed into the AI brain. However, now we know how we want the system to work we need to also consider what data we’re going to capture to fulfil our business requirements.

Section 2: Useful Data and the Data Pipeline Design

“Call it extreme if you like, but I propose we hit it hard and fast with a major, and I mean major, leaflet campaign!”

A sterling suggestion from Arnold Rimmer

A sterling suggestion from Rimmsey on how to deal with Terrifying Alien Lifeforms but it will all fall apart without knowing exactly what message to hit it with.

And it’s the same for us, having the right data is essential to measuring the value that we get from the project. Here are some pieces of information that would be particularly useful for our first Feature:

Player retention – how frequently they return to the game.
Session duration – how long they play for.
Feedback on the usefulness of hints provided.

The first thing that’s needed is an effective mechanism to collect, store and analyse that data.

When this project was developed several years ago, the tool of choice was Microsoft App Centre which provided build, test, distribution and analytics for mobile apps, all in one place, (there were other tools available such as Google Firebase however the project was being coded in C# using Visual Studio and Azure DevOps so App Center was a natural selection).

Unfortunately, App Center will be deprecated as of March 2025 and although Microsoft have announced several alternatives, this series of articles is going to plough on and stick with App Center however I recommend you choose one of the others for your own projects.

Regardless of the tool, it will track the numbers over time and allow us to make sensible decisions about marketing and further updates to the game. Out of the box, App Centre provides us the following information illustrated in the screenshot below, (which has just been populated with a single piece of test data).

The number of Active Users at any time.
How frequently they play the game.
How long each user plays for.
What devices are being used.

This is going to provide exactly what we are looking for around player retention and session duration.

When it comes to the usefulness of the hints this information in particular can be taken directly from the Understanding and Knowledge within the AI that we’ll accumulate as the player moves around the Otherworld. Fortunately, App Center can also track any custom metrics we come up with. For example, in this screenshot, I’ve written out a few test numbers when the player completes a puzzle or finds a key location. These include amongst others:

The average number of moves before a useful hint is displayed.
The percentage of hints that are useful.
The percentage completion of the game.

Although App Center does a good job at collecting data, we need to combine that with information from the app stores, trend it over time and add extra analytics, especially those business value measurements we talked about before.

To do that we can take the data out of App Centre and feed it into Azure App Insights with analysis kindly provided by Power BI or even a Gen AI system like Chat GPT. The following diagram depicts the overall data flow through the system.

Section 3: The Look and Feel

Finally, before moving into this issue’s Diving into the Detail section and getting lost in the joy of software architecture, we should address the look and feel of the user interface. The AI interaction must fit in and come across as a natural part of the game

Otherworld does not have a complicated UI, as a retro adventure game it has text and photography to describe locations and items. All that is needed is a theme corresponding with the story behind the game. The game is a Celtic Murder Mystery set in the modern day that dips heavily into mythology and Irish history.

After a bit of research around these themes, I decided to go with a Raven.

Fun facts, (feel free to skip over if you only care about code):

The Raven features throughout Celtic, Norse and North American mythology where it is commonly associated with wisdom, war and death. In many legends, flocks of Ravens guard entrances to the Otherworld and will attack people who come too close.
The most famous story is of the legendary British king Bran the Blessed whose emblem was the Raven. Bran was mortally wounded in battle and after he died his head was cut off and buried in the hill where the Tower of London was later built. The head was placed to look out to sea and ward Britain from invasion. Bran’s ravens came and lived at the Tower and the legend tells that if they ever leave it will crumble and Britain will fall. To this day the Raven colony at the Tower of London is cared for by a dedicated officer of the Beefeater Guards.
Ravens are one of the most intelligent birds and recent studies conducted at the University of Vermont in Canada and St Andrews University in Scotland have shown that Ravens were capable of independent thought demonstrated by their ability to solve logic problems to win food by pulling on strings and pushing buttons.

Intelligent, can solve problems, and a key figure in Celtic mythology, the Raven sounds like the right avatar to represent our new AI.

Ideally, we want to minimize the amount of UI and reuse the existing controls and screens as much as possible because this will also reduce the amount of testing required. Therefore I plan to add a single button that will be highlighted when the AI wants to suggest a hint. This has the added benefit that the user can press it, at any time, to request advice.

This generates a few more use cases for the list:

If the Raven thinks a hint is important, it will display it automatically.
If the Raven thinks the hint is less important or doesn’t want to interrupt play, it will highlight the button and play a sound, (a Raven’s caw).
- The player taps the button to see the hint.
- If the player ignores the button, after a time the Raven will clear the highlight and the hint.
The player presses the button at any time and the Raven will display a hint.

Here is a knock-up of what the UI will look like. As you can see, the addition of a single button really minimizes the impact on the screen.

Screen shot from Otherworld with the Raven button highlighted

If the player needs a hint straightaway, they tap the Raven button. The additional screen that will be displayed can be constructed from the re-usable control library coded in the main part of the game. These controls have already been fully tested and we simply need to check that the correct information is being displayed.

Pressing the button allows the player to request a hint

Finally, the presence of this extra screen will allow additional functionality to be easily added later on that won’t impact the main part of the game.

Diving into the Detail

Today’s Diving into the Detail section is all about the software design and I’m going to present some of the class and flow diagrams that make up the architecture. A wee shout out to any die-hard architects reading this, I’m not showing the full design process and instead, these are some of the main excerpts from the overall architecture.

We derive the high-level class structure and relationships directly from the words and definitions contained in the use case description. Additional classes are then inferred by applying patterns such as Gang of Four.

In our case, the IBM AI structure can be treated as a specialized pattern for which extra classes can be added to the design. This will be the central part of the structure and used to collect, manage and update data within the system.

Creating the Class Structure

Step 1: The AI Brain

The list of classes we need is taken directly from the IBM model presented in the last article. These are:

The DataCollector harvests data generated by gameplay.
The Understanding holds this data in context.
The Knowledge is everything that has been learned by the system.
The Reasoner uses the Knowledge and Understanding to answer questions, specifically whether we should display a hint to the player and what hint should that be.
The Reaction Collector retrieves feedback from the player to enable the system to learn.

The DataCollector and the ReactionCollector interact with the rest of the system and are coloured in blue.

Step 2: Use Case Classes

To make our use case work, we’ll need additional classes. Here is a slightly abridged version of the Use Case text with keywords underlined.

If the player makes too many moves without visiting a Location the AI chooses the highest priority Location from those that are currently accessible:

Mandatory Locations are higher priority than optional Locations.

Locations earlier in the Walkthrough Guide are higher priority than later ones.

Locations closer to the player are higher priority than ones further away.

The AI gives a hint for the right direction and makes the game easier by decreasing the number of moves required before the next hint is displayed.

The underlined terms become elements in our structure. Inserting the relationships we get a structure that looks like this:

Here are a few notes on the diagram

In the final solution, hints and tips will need to be associated with Items not just with Locations. That’s why there’s a base Hint class with direction, puzzle, or whatever other types of hint we want, derived from it. We’ve also inferred a HintController class to manage the use case. Just like the hint, we’ll need derived versions for direction and puzzle hints.
The Location class is included with the original game and we’re unable to derive from it. Additional functionality and data have therefore been attached to the existing Location object using the LocationMetadata shown in red which acts similarly to the Decorator GOF pattern.
The content of the hints that will be displayed is different for each location. These are encapsulated within classes derived from the metadata and examples for the Caravan, Derelict House and Secret Lair locations are shown in the diagram in orange. It is the job of the AI to determine what type of hint and which one is appropriate.
The WalkthroughGuide enumeration coloured in brown lists the locations in order of priority with an Optional default entry.

Although some of these terms have turned into classes, others we can place as data items directly within the Understanding. Here is a list of the Understanding’s properties which will record the data we need as well as the accumulated data within the Knowledge.

Properties contained in the Knowledge and Understanding

Step 3: Integration with the Original Game

And finally, we’ll connect together these classes, the AI brain, and the existing parts of the original Otherworld game. The classes in yellow are those ones that come from the main game, in particular:

The main source of input into the DataCollector is the InputController which informs us whenever the player makes a move, actions an item, or makes any other form of input.
The ReactionCollector receives feedback directly from the player who is represented by the LiveOpsUI object. It is used to ask questions or display messages to the user and then pass back the responses.

Flow of Events

With the main class structure in place, we now need to consider the flow of events through the system and, in particular, those flows where the AI will accumulate the Knowledge and Understanding that it will use to decide whether to display a hint or not.

1. Recording Any Move

In this sequence, we need to record that a move was made which will update data within the Understanding. We assume here that the player has moved but not arrived at a key Location, so, they may or may not require a hint. You can see in the diagram that the data collector records the move and then updates the information contained within the Understanding.

The design then asks the Reasoner to think whether a hint is required or not.

2. Arriving at a Key Location

When the player arrives at a Location, the system will no longer need to display a hint about it, so this information will need to be recorded as well.

You can see in the diagram below that once again it’s the DataCollector that registers the fact that the player has arrived at the location and then updates the Understanding of the AI which is that information in context. The Knowledge of the system, (i.e. what is learned so far), is also updated

3. Feedback on a Hint

Finally, one of the most essential flows is when the player gives feedback on a hint. This is extremely important as without an indication of the usefulness of the hint then the AI will never actually learn, the design is fortunately very simple and follows roughly the same pattern.

Note that instead of being registered by the DataCollector, it's picked up by the ReactionCollector and fed into the Understanding. Once again we are forced to update our Knowledge based on the new feedback.

Now that we have a visualization of those classes we need and what their methods will do we're ready to finally start coding!

Summary

If you’ve not got experience with software architecture you might be thinking that it's taken a long time to put these designs and diagrams together? Nothing could be further from the truth. With a decent design tool, many of these take only seconds to draw up and I believe that performing this exercise is essential to visualize what is in fact quite a complex system before we start typing in the code.

Speaking of which, the third and final article in this series will deal with just that, the coding and implementation of the system including the data pipelines, the logging framework and how in practice data flows through the system.

To make the next article particularly class we want as much data in the system as possible. So after you’re finished reading why not play Otherworld yourself and help generate some? The price has been reduced to only 99p which is as cheap as it's possible to make it on Apple. The complete Walk Through Guide which contains solutions to all the puzzles is also available at only 99p!!

Click a link or scan the QR code to get these treasures now!

That's it for today and thanks for reading. Smoke Me a Kipper and we’ll be back in the next article!