How to create a 2D game with Python and the Arcade library

Learn how to get started with Arcade, an easy-to-use Python library for creating 2D video games.
575 readers like this.
2d arcade game sprite

Paul Vincent Craven. CC BY-SA 4.0

Python is an outstanding language for people learning to program, and perfect for anyone wanting to "get stuff done" and not spend heaps of time on boilerplate code. Arcade is a Python library for creating 2D video games that is easy to start using, and very capable as you gain experience. In this article, I will explain how to start using Python and Arcade to program video games.

I started development on Arcade after teaching students using the PyGame library. I taught in-person using PyGame for almost 10 years, and I developed ProgramArcadeGames.com to teach online. PyGame is great, but eventually I felt like I was wasting time having to cover for bugs that were never fixed.

I worried about teaching things like the event loop, which was no longer the way we code. I had a whole section in which I explained why the y-coordinates were reversed. Because PyGame was seldom updated and it is based on an old SDL 1 library, rather than something like more modern like OpenGL, I didn't hold a lot of hope for the future.

I wanted a library that was easier to use, more powerful, and used some of the new features of Python 3, like decorators and type-hinting. Arcade is it. And this is how to get started.

Installation

Arcade, like many other packages, is available via PyPi, which means you can install Arcade using the pip command (or the pipenv command). If you already have Python installed, you can likely just open up a command prompt on Windows and type:

pip install arcade

Or on MacOS and Linux type:

pip3 install arcade

For more detailed installation instructions, you can refer to the Arcade installation documentation.

Simple drawing

You can open a window and create simple drawings with just a few lines of code. Let's create an example that draws a smiley face like the figure below:

smile face image

The script below shows how you can use Arcade's drawing commands to do this. Note that you don't need to know how to use classes or even define functions. Programming with quick visual feedback is great for anyone who wants to start learning to program.

import arcade

# Set constants for the screen size
SCREEN_WIDTH = 600
SCREEN_HEIGHT = 600

# Open the window. Set the window title and dimensions (width and height)
arcade.open_window(SCREEN_WIDTH, SCREEN_HEIGHT, "Drawing Example")

# Set the background color to white.
# For a list of named colors see:
# http://arcade.academy/arcade.color.html
# Colors can also be specified in (red, green, blue) format and
# (red, green, blue, alpha) format.
arcade.set_background_color(arcade.color.WHITE)

# Start the render process. This must be done before any drawing commands.
arcade.start_render()

# Draw the face
x = 300
y = 300
radius = 200
arcade.draw_circle_filled(x, y, radius, arcade.color.YELLOW)

# Draw the right eye
x = 370
y = 350
radius = 20
arcade.draw_circle_filled(x, y, radius, arcade.color.BLACK)

# Draw the left eye
x = 230
y = 350
radius = 20
arcade.draw_circle_filled(x, y, radius, arcade.color.BLACK)

# Draw the smile
x = 300
y = 280
width = 120
height = 100
start_angle = 190
end_angle = 350
arcade.draw_arc_outline(x, y, width, height, arcade.color.BLACK, start_angle, end_angle, 10)

# Finish drawing and display the result
arcade.finish_render()

# Keep the window open until the user hits the 'close' button
arcade.run()

Using functions

Of course, writing code in the global context isn't good form. Thankfully improving your program by using functions is easy. Here we can see an example of a drawing a pine tree at a specific (x, y) location using a function:

def draw_pine_tree(x, y):
    """ This function draws a pine tree at the specified location. """
    
    # Draw the triangle on top of the trunk.
    # We need three x, y points for the triangle.
    arcade.draw_triangle_filled(x + 40, y,       # Point 1
                                x, y - 100,      # Point 2
                                x + 80, y - 100, # Point 3
                                arcade.color.DARK_GREEN)

    # Draw the trunk
    arcade.draw_lrtb_rectangle_filled(x + 30, x + 50, y - 100, y - 140,
                                      arcade.color.DARK_BROWN)

For the full example, see drawing with functions.

classes and functions

The more experienced programmer will know that modern graphics programs first load drawing information onto the graphics card, and then ask the graphics card to draw it later as a batch. Arcade supports this as well. Drawing 10,000 rectangles individually takes about 0.800 seconds. Drawing them as a batch takes less that 0.001 seconds.

The Window class

Larger programs will typically derive from the Window class, or use decorators. This allows a programmer to write code to handle drawing, updating, and handling input from the user. A template for a starting a Window-based program is below.

import arcade

SCREEN_WIDTH = 800
SCREEN_HEIGHT = 600


class MyGame(arcade.Window):
    """ Main application class. """

    def __init__(self, width, height):
        super().__init__(width, height)

        arcade.set_background_color(arcade.color.AMAZON)

    def setup(self):
        # Set up your game here
        pass

    def on_draw(self):
        """ Render the screen. """
        arcade.start_render()
        # Your drawing code goes here

    def update(self, delta_time):
        """ All the logic to move, and the game logic goes here. """
        pass


def main():
    game = MyGame(SCREEN_WIDTH, SCREEN_HEIGHT)
    game.setup()
    arcade.run()


if __name__ == "__main__":
    main()

The Window class has several methods that your programs can override to provide functionality to the program. Here are some of the most commonly used ones:

  • on_draw: All the code to draw the screen goes here.
  • update: All the code to move your items and perform game logic goes here. This is called about 60 times per second.
  • on_key_press: Handle events when a key is pressed, such as giving a player a speed.
  • on_key_release: Handle when a key is released, here you might stop a player from moving.
  • on_mouse_motion: This is called every time the mouse moves.
  • on_mouse_press: Called when a mouse button is pressed.
  • set_viewport: This function is used in scrolling games, when you have a world much larger than what can be seen on one screen. Calling set_viewport allows a programmer to set what part of that world is currently visible.

Sprites

Sprites are an easy way to create a 2D bitmapped object in Arcade. Arcade has methods that make it easy to draw, move, and animate sprites. You can also easily use sprites to detect collisions between objects.

Creating a sprite

Creating an instance of Arcade's Sprite class out of a graphic is easy. A programmer only needs the file name of an image to base the sprite off of, and optionally a number to scale the image up or down. For example:

SPRITE_SCALING_COIN = 0.2

coin = arcade.Sprite("coin_01.png", SPRITE_SCALING_COIN)

This code will create a sprite using the image stored in coin_01.png. The image will be scaled down to 20% of its original height and width.

sprites collecting coins

Sprite lists

Sprites are normally organized into lists. These lists make it easier to manage the sprites. Sprites in a list will use OpenGL to batch-draw the sprites as a group. The code below sets up a game with a player, and a bunch of coins for the player to collect. We use two lists, one for the player and one for the coins.

def setup(self):
    """ Set up the game and initialize the variables. """

    # Create the sprite lists
    self.player_list = arcade.SpriteList()
    self.coin_list = arcade.SpriteList()

    # Score
    self.score = 0

    # Set up the player
    # Character image from kenney.nl
    self.player_sprite = arcade.Sprite("images/character.png", SPRITE_SCALING_PLAYER)
    self.player_sprite.center_x = 50 # Starting position
    self.player_sprite.center_y = 50
    self.player_list.append(self.player_sprite)

    # Create the coins
    for i in range(COIN_COUNT):

        # Create the coin instance
        # Coin image from kenney.nl
        coin = arcade.Sprite("images/coin_01.png", SPRITE_SCALING_COIN)

        # Position the coin
        coin.center_x = random.randrange(SCREEN_WIDTH)
        coin.center_y = random.randrange(SCREEN_HEIGHT)

        # Add the coin to the lists
        self.coin_list.append(coin)

We can easily draw all the coins in the coin lists:

def on_draw(self):
    """ Draw everything """
    arcade.start_render()
    self.coin_list.draw()
    self.player_list.draw()

Detecting sprite collisions

The function check_for_collision_with_list allows us to see if a sprite runs into another sprite in a list. We can use this to see all the coins the player sprite is in contact with. Using a simple for loop, we can get rid of the coin from the game and increase our score.

def update(self, delta_time):
    # Generate a list of all coin sprites that collided with the player.
    coins_hit_list = arcade.check_for_collision_with_list(self.player_sprite, self.coin_list)

    # Loop through each colliding sprite, remove it, and add to the score.
    for coin in coins_hit_list:
        coin.kill()
        self.score += 1

For the full example, see collect_coins.py.

Game physics

Many games include some kind of physics. The simplest are top-down programs that prevent the player from walking through walls. Platformers add more complexity with gravity and platforms that move. Some games use a full 2D physics engine with mass, friction, springs, and more.

Top-down games

spring moving to walls

For simple top-down based games, an Arcade program needs a list of walls that the player (or anything else) can't move through. I usually call this wall_list. Then a physics engine is created in the Window class's setup code with:

self.physics_engine = arcade.PhysicsEngineSimple(self.player_sprite, self.wall_list)

The player_sprite is given a movement vector with its two attributes change_x and change_y. A simple example of doing this would be to have the player move with the keyboard. For example, this might be in the custom child of the Window class:

MOVEMENT_SPEED = 5

def on_key_press(self, key, modifiers):
    """Called whenever a key is pressed. """

    if key == arcade.key.UP:
        self.player_sprite.change_y = MOVEMENT_SPEED
    elif key == arcade.key.DOWN:
        self.player_sprite.change_y = -MOVEMENT_SPEED
    elif key == arcade.key.LEFT:
        self.player_sprite.change_x = -MOVEMENT_SPEED
    elif key == arcade.key.RIGHT:
        self.player_sprite.change_x = MOVEMENT_SPEED

def on_key_release(self, key, modifiers):
    """Called when the user releases a key. """

    if key == arcade.key.UP or key == arcade.key.DOWN:
        self.player_sprite.change_y = 0
    elif key == arcade.key.LEFT or key == arcade.key.RIGHT:
        self.player_sprite.change_x = 0

Although that code sets the player's speed, it doesn't move the player. In the update method of the Window class, calling physics_engine.update() will move the player, but not through walls.

def update(self, delta_time):
    """ Movement and game logic """

     self.physics_engine.update()

For a full example see sprite_move_walls.py.

Platformers

sprite tiled map

Moving to a side view platformer is rather easy. A programmer just needs to switch the physics engine to PhysicsEnginePlatformer and add in the gravity constant.

self.physics_engine = arcade.PhysicsEnginePlatformer(self.player_sprite,
                                                     self.wall_list, 
                                                     gravity_constant=GRAVITY)

You can use a program like Tiled to lay the tiles/blocks that make up your level.

For an example, see sprite_tiled_map.py.

For full 2D physics you can integrate the PyMunk library.

Learn by example

One of the best ways to learn is by example. The Arcade library has a long list of example programs that a person can draw on to create games. These examples each show a game concept that students have asked for in my classes or online over the years.

Running any of these demos is easy once Arcade has been installed. Each of the samples has a comment at the beginning of the program with a command you can type on the command-line to run the sample, for example:

python -m arcade.examples.sprite_moving_platforms

Summary

Arcade lets you start programming graphics and games with easy-to-understand code. Many new programmers have created great games not long after getting started. Give it a try!


To learn more, attend Paul Vincent Craven's talk, Easy 2D Game Creation With Arcade, at PyCon Cleveland 2018.

User profile image.
Paul Craven is the author of "Program Arcade Games with Python and Pygame", an on-line and in-print resource for learning to program. He is the primary maintainer of the Arcade Python game library for 2D graphics. Paul is also a professor at Simpson College in Iowa.

5 Comments

Great for open source game competition!

Tl;dr: in replacing PyGame you've managed to do precisely the same core mistake and made it too annoying to get your library up and running in at least what I think of as a sensible manner (subjective for sure).

First: Python 3.6 is a pain because it's so new, most distributions haven't even included 3.anything but at least getting 3.5.x up and running is fairly easy on most distributions as far as I know, but 3.6.? Compiling from source and wrestling with getting added bits and bobs and whatnot actually working? Who hasn't wasted far too many hours on stuff like that?

You're not helping yourself. This is the prefect mirror image of PyGame not supporting whatever Python people already have. In PyGame it's because PyGame is old (and broken) and in Arcade it's because the Python is too new. Same difference. Okay if you run in dedicated environments etc. but not for normal people at home wanting to take a peek and get right into it at minimal cost.

Second issue: pip, is it still a completely open and non-reviewed security issue as per the year-old report from that Czech intelligence agency? Should anyone be using pip at all?

Python lost the plot with pip. It's not your fault

Sorry for such negative issues in what is nothing but a drive-by comment using a mail address that is never being read (because Google is evil) but someone should point these things out and people usually don't, so for once I nudged my temporary JavaScript settings for opensource.com and commented.

Despite all that your actual library looks interesting, too bad I'm tired of hoops.

You are right that 3.6 is a pain to get up and running with some Linux distributions. With Windows, MacOS, and Ubuntu it will be default version for people doing a recent install. Not so much with Linux Mint or some other ones. I'll think about your comment seriously. I quite like the new print formatting, but it isn't used a lot in the code.

If you don't like pip, install Arcade using setup.py. I'm not quite sure what you are looking for here.

In reply to by A few bits sho… (not verified)

This looks amazing. I can't wait to try it.

I just installed it on Linux and will try it out very soon. It looks great. I like PyGame, but it *is* showing its age, so this is a hugely welcome development.

Wow, Paul, this library looks really promising. Last year I ran a Python class with 10-13 year olds and PyGame. Though it went well, I was occasionally frustrated by the limitations of the PyGame library and the confusing state of the docs. Can't wait to try out Arcade!

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.