This is an introductory tutorial for anyone interested in building their own AI to play in a game. All you need to start is some familiarity with programming in Python. This is part 1 of a series originally published on the Coder One blog.

We'll be using a custom game environment called Dungeons and Data Structures. It's inspired by the classic NES game Bomberman, but with some variations. This game was used for an AI game competition called the AI Sports Challenge organized by Coder One.

In this first part of the tutorial series, we'll cover:

• Installing and setting up the Dungeons and Data Structures AI game environment
• The starter kit for building our bot
• Getting familiar with the AI game environment

No fancy algorithms or ML just yet. We'll start off simple, and build on our bot with more advanced strategies as part of this series. (If you're more interested in the area of reinforcement learning, check out this introductory tutorial to reinforcement learning using OpenAI Gym).

Game overview

In Dungeons and Data Structures, your goal is to either be:

• The last bot standing, or
• The bot with the most points by the end of the game.

You can take away an opponent's HP and earn points by using bombs to destroy wooden and ore (green) blocks. For a full description of the game rules, you can check the Dungeons and Data Structures Game Documentation.

Getting Started

First, let's install the game environment.

You can do that by heading over to the Dungeons and Data Structures Repo, and downloading the package coderone-challenge-dungeon-0.1.6.tar.gz from the Releases page.

Install it by navigating to the working directory containing the package you just downloaded, and run in your terminal:

pip install coderone-challenge-dungeon-0.1.6.tar.gz

To check that your installation is working, run:

python -m coderone.dungeon.main --interactive coderone.dungeon.agent

You should see a window similar to this pop up:

Press ENTER to un-pause the game. You'll be able to play as the knight, using the arrow keys ↑ / ↓ / ← / → and SPACE to place a bomb. You're playing against the default agent provided in the game (which does nothing but stand still). Close the window when you're done.

Setting up our starter agent

To create your own bot that interacts with this game, create a file in your working directory called my_agent.py. In this file, paste the following:

import random

class Agent:

    def __init__(self):
        '''
        Place any initialization code for your agent here (if any)
        '''
        pass

    def next_move(self, game_state, player_state):
        '''
        This method is called each time your Agent is required to choose an action
        '''

        ###### CODE HERE ######

        # a list of all the actions your Agent can choose from
        actions = ['','u','d','l','r','p']

        # randomly choosing an action
        action = random.choice(actions)

        ###### END CODE ######

        return action

The full template is also available here.

At a high level, the job of your my_agent.py script is to:

1. Define a class called Agent containing a method next_move
2. Define next_move such that it can accept game information on each tick, stored in the variables game_state and player_state
3. Have next_move return an output action which can take the form of a string representing one of the valid game moves:
   • '': do nothing
   • u, d, l, r : up, down, left, right (respectively)
   • p: place bomb

This basic starter agent will randomly choose an action from the list of those available.

Now save your file, and run in your terminal:

coderone-dungeon --watch --interactive my_agent

This will load up the game, and allow you to play against the bot whose behavior we defined in my_agent.py.

Here are some additional details on the earlier command we ran in the terminal:

--watch loads the game in a format where you can make live changes to your code.

--interactive allows you to play the game as well.

my_agent is the name of your bot's Python script that you want to play against.

Note: you will need at least two agents for the game to start. In the code above, my_agent is Player 1 (Wizard) and you are Player 2 (Knight). You can also try:

# play your agent against itself
coderone-dungeon --watch my_agent my_agent 

Feel free to play around with the starter code (e.g. try making a bot that only moves up).

Getting familiar with the game Environment

In the previous section, we mentioned that your bot receives two inputs: game_state and player_state. These variables contain information about the game environment and your player respectively. They both contain some useful information (a full list is available in the Game Documentation), but the most important ones for now are:

game_state:

• size: the size of the Game Map in the form (cols, rows) - i.e. (12,10) for a 12x10 map
• bombs: a list of all the current positions of bombs placed

player_state:

• location: the current location co-ordinates of your player in the form (x,y)
• ammo: the amount of ammo you have

Below are some examples of use cases for these properties, given game_state and player_state. Have a go at filling in the code yourself, and checking them against the provided answers.

# get your Agent's current location
my_agents_location = pass     ### CHANGE THIS

Link to solution

# get the number of columns and rows of the Game Map
cols = pass     ### CHANGE THIS
rows = pass     ### CHANGE THIS

Link to solution

# print the location of all the bombs placed on the Game Map
list_of_bombs = pass   ### CHANGE THIS

for bomb in list_of_bombs:
    print(f"Bomb at x: {None} y: {None}")         ### Change 'None'

Link to solution

In addition to properties, game_state also contains some useful methods. The ones we'll use in this tutorial are:

• entity_at(location): returns the entity/object at the specified location
• is_in_bounds(location): returns True or False depending on whether the specified location is actually within the Game Map (within the 12x10 grid)
• is_occupied(location): returns True or False depending on whether that block is occupied by another object or not

Some more example use cases are provided below.

# return the entity at co-ordinate (1,1)
entity_at_1_1 = pass   ### CHANGE THIS

Link to solution

# is the co-ordinate (12,11) within the boundaries of the game?
is_in_bounds = pass   ### CHANGE THIS

Link to solution

# is the co-ordinate (4,2) occupied?
is_occupied = pass   ### CHANGE THIS

Link to solution

Next Steps

Feel free to try playing around with the environment and building your own agent! Otherwise check out Part 2 below.

If you've got any questions or feedback, feel free to let me know in the comments below.

Thanks for reading 🙌

P.S. If you're interested in supporting this project, follow us on Product Hunt!