Top Python Game Engines

Like many people, maybe you wanted to write video games when you first learned to code. But were those games like the games you played? Maybe there was no Python when you started, no Python games available for you to study, and no game engines to speak of. With no real guidance or framework to assist you, the advanced graphics and sound that you experienced in other games may have remained out of reach.

Now, there’s Python, and a host of great Python game engines available. This powerful combination makes crafting great computer games much easier than in the past. In this tutorial, you’ll explore several of these game engines, learning what you need to start crafting your own Python video games!

By the end of this article, you’ll:

Understand the pros and cons of several popular Python game engines
See these game engines in action
Understand how they compare to stand-alone game engines
Learn about other Python game engines available

To get the most out of this tutorial, you should be well-versed in Python programming, including object-oriented programming. An understanding of basic game concepts is helpful, but not necessary.

Ready to dive in? Click the link below to download the source code for all the games that you’ll be creating:

Get Source Code: Click here to get the source code you’ll use to try out Python game engines.

Python Game Engines Overview

Game engines for Python most often take the form of Python libraries, which can be installed in a variety of ways. Most are available on PyPI and can be installed with pip. However, a few are available only on GitHub, GitLab, or other code sharing locations, and they may require other installation steps. This article will cover installation methods for all the engines discussed.

Python is a general purpose programming language, and it’s used for a variety of tasks other than writing computer games. In contrast, there are many different stand-alone game engines that are tailored specifically to writing games. Some of these include:

These stand-alone game engines differ from Python game engines in several key aspects:

Language support: Languages like C++, C#, and JavaScript are popular for games written in stand-alone game engines, as the engines themselves are often written in these languages. Very few stand-alone engines support Python.
Proprietary scripting support: In addition, many stand-alone game engines maintain and support their own scripting languages, which may not resemble Python. For example, Unity uses C# natively, while Unreal works best with C++.
Platform support: Many modern stand-alone game engines can produce games for a variety of platforms, including mobile and dedicated game systems, with very little effort. In contrast, porting a Python game across various platforms, especially mobile platforms, can be a major undertaking.
Licensing options: Games written using a stand-alone game engine may have different licensing options and restrictions, based on the engine used.

So why use Python to write games at all? In a word, Python. Using a stand-alone game engine often requires you to learn a new programming or scripting language. Python game engines leverage your existing knowledge of Python, reducing the learning curve and getting you moving forward quickly.

There are many game engines available for the Python environment. The engines that you’ll learn about here all share the following criteria:

They’re relatively popular engines, or they cover aspects of gaming that aren’t usually covered.
They’re currently maintained.
They have good documentation available.

For each engine, you’ll learn about:

Installation methods
Basic concepts, as well as assumptions that the engine makes
Major features and capabilities
Two game implementations, to allow for comparison

Where appropriate, you should install these game engines in a virtual environment. Full source code for the games in this tutorial is available for download at the link below and will be referenced throughout the article:

Get Source Code: Click here to get the source code you’ll use to try out Python game engines.

With the source code downloaded, you’re ready to begin.

Remove ads

Pygame

When people think of Python game engines, the first thought many have is Pygame. In fact, there’s already a great primer on Pygame available at Real Python.

Written as a replacement for the stalled PySDL library, Pygame wraps and extends the SDL library, which stands for Simple DirectMedia Layer. SDL provides cross-platform access to your system’s underlying multimedia hardware components, such as sound, video, mouse, keyboard, and joystick. The cross-platform nature of both SDL and Pygame means that you can write games and rich multimedia Python programs for every platform that supports them!

Pygame Installation

Pygame is available on PyPI, so after creating and activating a virtual environment, you can install it using the appropriate pip command:

Shell
      
(venv) $ python -m pip install pygame

Once that’s done, you can verify the installation by running an example that comes with the library:

Shell
      
(venv) $ python -m pygame.examples.aliens

Now that you’ve installed Pygame, you can begin using it right away. If you run into problems during installation, then the Getting Started guide outlines some known issues and possible solutions for all platforms.

Basic Concepts

Pygame is organized into several different modules, which provide abstracted access to your computer graphics, sound, and input hardware. Pygame also defines numerous classes, which encapsulate concepts that aren’t hardware dependent. For example, drawing is done on Surface objects, whose rectangular limits are defined by their Rect object.

Every game utilizes a game loop to control game play. This loop iterates constantly as the game progresses. Pygame provides methods and functions to implement a game loop, but it doesn’t provide one automatically. The game author is expected to implement the functionality of a game loop.

Each iteration of the game loop is called a frame. Every frame, the game performs four vital actions:

Processing user input. User input in Pygame is handled using an event model. Mouse and keyboard input generate events, which can be read and handled, or ignored as you see fit. Pygame itself doesn’t provide any event handlers.
Updating the state of game objects. Game objects can be represented using any Pygame data structure or special Pygame class. Objects such as sprites, images, fonts, and colors can be created and extended in Python to provide as much state information as necessary.
Updating the display and audio output. Pygame provides abstract access to display and sound hardware. The display, mixer, and music modules allow game authors flexibility in game design and implementation.
Maintaining the speed of the game. Pygame’s time module allows game authors to control the game speed. By ensuring each frame completes within a specified time limit, game authors can ensure the game runs similarly on different hardware.

You can see these concepts come together in a basic example.

Basic Application

This basic Pygame program draws a few shapes and some text on the screen:

The code for this sample can be found below and in the downloadable materials:

Python
      
    
"""
Basic "Hello, World!" program in Pygame

This program is designed to demonstrate the basic capabilities
of Pygame. It will:
- Create a game window
- Fill the background with white
- Draw some basic shapes in different colors
- Draw some text in a specified size and color
- Allow you to close the window
"""

# Import and initialize the pygame library
import pygame

pygame.init()

# Set the width and height of the output window, in pixels
WIDTH = 800
HEIGHT = 600

# Set up the drawing window
screen = pygame.display.set_mode([WIDTH, HEIGHT])

# Run until the user asks to quit
running = True
while running:

    # Did the user click the window close button?
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    # Fill the background with white
    screen.fill((255, 255, 255))

    # Draw a blue circle with a radius of 50 in the center of the screen
    pygame.draw.circle(screen, (0, 0, 255), (WIDTH // 2, HEIGHT // 2), 50)

    # Draw a red-outlined square in the top-left corner of the screen
    red_square = pygame.Rect((50, 50), (100, 100))
    pygame.draw.rect(screen, (200, 0, 0), red_square, 1)

    # Draw an orange caption along the bottom in 60-point font
    text_font = pygame.font.SysFont("any_font", 60)
    text_block = text_font.render(
        "Hello, World! From Pygame", False, (200, 100, 0)
    )
    screen.blit(text_block, (50, HEIGHT - 50))

    # Flip the display
    pygame.display.flip()

# Done! Time to quit.
pygame.quit()

Despite its humble aspirations, even this basic Pygame program requires a game loop and event handlers. The game loop begins on line 27 and is controlled by the running variable. Setting this variable to False will end the program.

Event handling begins on line 30 with an event loop. Events are retrieved from a queue using pygame.event.get() and are processed one at a time during every loop iteration. In this case, the only event being handled is the pygame.QUIT event, which is generated when the user closes the game window. When this event is processed, you set running = False, which will eventually end the game loop and the program.

Pygame provides various methods for drawing basic shapes, such as circles and rectangles. In this sample, a blue circle is drawn on line 38, and a red square is drawn on lines 41 and 42. Note that drawing a rectangle requires you to create a Rect object first.

Drawing text on the screen is a little more involved. First, on line 45, you select a font and create a font object. Using that font on lines 46 to 48, you call the .render() method. This creates a Surface object containing the text rendered in the specified font and color. Finally, you copy Surface to the screen using the .blit() method on line 49.

The end of the game loop occurs on line 52, when everything that was previously drawn is shown on the display. Without this line, nothing would be displayed.

To run this code, use the following command:

Shell
      
(venv) $ python pygame/pygame_basic.py

You should see a window appear with the image shown above. Congratulations! You just ran your first Pygame program!

Remove ads

Advanced Application

Of course, Pygame was designed to write games in Python. To explore the capabilities and requirements of an actual Pygame game, you’ll examine a game written in Pygame with the following details:

The player is a single sprite on the screen, controlled by moving the mouse.
At regular intervals, coins appear on the screen one by one.
As the player moves over each coin, it disappears and the player is awarded ten points.
As the game progresses, coins are added more quickly.
The game ends when there are more than ten coins visible on the screen.

When done, the game will look something like this:

The complete code for this game can be found in the downloaded materials and below:

Python
      
    
"""
Complete Game in Pygame

This game demonstrates some of the more advanced features of
Pygame, including:
- Using sprites to render complex graphics
- Handling user mouse input
- Basic sound output
"""

# Import and initialize the pygame library
import pygame

# To randomize coin placement
from random import randint

# To find your assets
from pathlib import Path

# For type hinting
from typing import Tuple

# Set the width and height of the output window, in pixels
WIDTH = 800
HEIGHT = 600

# How quickly do you generate coins? Time is in milliseconds
coin_countdown = 2500
coin_interval = 100

# How many coins can be on the screen before you end?
COIN_COUNT = 10

# Define the Player sprite
class Player(pygame.sprite.Sprite):
    def __init__(self):
        """Initialize the player sprite"""
        super(Player, self).__init__()

        # Get the image to draw for the player
        player_image = str(
            Path.cwd() / "pygame" / "images" / "alien_green_stand.png"
        )
        # Load the image, preserve alpha channel for transparency
        self.surf = pygame.image.load(player_image).convert_alpha()
        # Save the rect so you can move it
        self.rect = self.surf.get_rect()

    def update(self, pos: Tuple):
        """Update the position of the player

        Arguments:
            pos {Tuple} -- the (X,Y) position to move the player
        """
        self.rect.center = pos

# Define the Coin sprite
class Coin(pygame.sprite.Sprite):
    def __init__(self):
        """Initialize the coin sprite"""
        super(Coin, self).__init__()

        # Get the image to draw for the coin
        coin_image = str(Path.cwd() / "pygame" / "images" / "coin_gold.png")

        # Load the image, preserve alpha channel for transparency
        self.surf = pygame.image.load(coin_image).convert_alpha()

        # The starting position is randomly generated
        self.rect = self.surf.get_rect(
            center=(
                randint(10, WIDTH - 10),
                randint(10, HEIGHT - 10),
            )
        )

# Initialize the Pygame engine
pygame.init()

# Set up the drawing window
screen = pygame.display.set_mode(size=[WIDTH, HEIGHT])

# Hide the mouse cursor
pygame.mouse.set_visible(False)

# Set up the clock for a decent frame rate
clock = pygame.time.Clock()

# Create a custom event for adding a new coin
ADDCOIN = pygame.USEREVENT + 1
pygame.time.set_timer(ADDCOIN, coin_countdown)

# Set up the coin_list
coin_list = pygame.sprite.Group()

# Initialize the score
score = 0

# Set up the coin pickup sound
coin_pickup_sound = pygame.mixer.Sound(
    str(Path.cwd() / "pygame" / "sounds" / "coin_pickup.wav")
)

# Create a player sprite and set its initial position
player = Player()
player.update(pygame.mouse.get_pos())

# Run until you get to an end condition
running = True
while running:

    # Did the user click the window close button?
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

        # Should you add a new coin?
        elif event.type == ADDCOIN:
            # Create a new coin and add it to the coin_list
            new_coin = Coin()
            coin_list.add(new_coin)

            # Speed things up if fewer than three coins are on-screen
            if len(coin_list) < 3:
                coin_countdown -= coin_interval
            # Need to have some interval
            if coin_countdown < 100:
                coin_countdown = 100

            # Stop the previous timer by setting the interval to 0
            pygame.time.set_timer(ADDCOIN, 0)

            # Start a new timer
            pygame.time.set_timer(ADDCOIN, coin_countdown)

    # Update the player position
    player.update(pygame.mouse.get_pos())

    # Check if the player has collided with a coin, removing the coin if so
    coins_collected = pygame.sprite.spritecollide(
        sprite=player, group=coin_list, dokill=True
    )
    for coin in coins_collected:
        # Each coin is worth 10 points
        score += 10
        # Play the coin collected sound
        coin_pickup_sound.play()

    # Are there too many coins on the screen?
    if len(coin_list) >= COIN_COUNT:
        # This counts as an end condition, so you end your game loop
        running = False

    # To render the screen, first fill the background with pink
    screen.fill((255, 170, 164))

    # Draw the coins next
    for coin in coin_list:
        screen.blit(coin.surf, coin.rect)

    # Then draw the player
    screen.blit(player.surf, player.rect)

    # Finally, draw the score at the bottom left
    score_font = pygame.font.SysFont("any_font", 36)
    score_block = score_font.render(f"Score: {score}", False, (0, 0, 0))
    screen.blit(score_block, (50, HEIGHT - 50))

    # Flip the display to make everything appear
    pygame.display.flip()

    # Ensure you maintain a 30 frames per second rate
    clock.tick(30)

# Done! Print the final score
print(f"Game over! Final score: {score}")

# Make the mouse visible again
pygame.mouse.set_visible(True)

# Quit the game
pygame.quit()

Sprites in Pygame provide some basic functionality, but they’re designed to be subclassed rather than used on their own. Pygame sprites don’t have images associated with them by default, and they can’t be positioned on their own.

To properly draw and manage the player and the coins on-screen, a Player class is created on lines 35 to 55, and a Coin class on lines 58 to 75. When each sprite object is created, it first locates and loads the image it’ll display, saving it in self.surf. The self.rect property positions and moves the sprite on the screen.

Adding coins to the screen at regular intervals is done with a timer. In Pygame, events are fired whenever a timer expires, and game creators can define their own events as integer constants. The ADDCOIN event is defined on line 90, and the timer fires the event after coin_countdown milliseconds on line 91.

Since ADDCOIN is an event, it needs to be handled in an event loop, which happens on lines 118 to 134. The event creates a new Coin object and adds it to the existing coin_list. The number of coins on-screen is checked. If there are fewer than three, then coin_countdown is reduced. Finally, the previous timer is stopped, and a new one starts.

As the player moves, they collide with coins, collecting them as they do. This removes each collected coin from the coin_list automatically. This also updates the score and plays a sound.

Player movement occurs on line 137. Collisions with coins on the screen are checked on lines 140 to 142. The dokill=True parameter removes the coin from the coin_list automatically. Finally, lines 143 to 147 update the score and play the sound for each coin collected.

The game ends when the user either closes the window, or when there are more than ten coins on the screen. Checking for more than ten coins is done on lines 150 to 152.

Because Pygame sprites have no built-in knowledge of an image, they also don’t know how to draw themselves on the screen. The game author needs to clear the screen, draw all the sprites in the correct order, draw the on-screen score, then .flip() the display to make everything appear. That all happens on lines 155 to 170.

Pygame is a very powerful and well-established library, but it has its drawbacks. Pygame makes game authors work to get their results. It’s up to the game author to implement basic sprite behavior and implement key game requirements such as game loops and basic event handlers. Next up, you’ll see how other game engines deliver similar results while reducing the amount of work you have to do.

Pygame Zero

There are many things Pygame does well, but others where its age is evident. For game-writing beginners, a better option can be found in Pygame Zero. Designed for education, Pygame Zero is guided by a simple set of principles aimed at being perfect for young and beginning programmers:

Make it accessible: Everything is designed for beginning programmers.
Be conservative: Support the common platform and avoid experimental features.
Just work: Make sure everything works without a lot of fuss.
Minimize runtime costs: If something might fail, fail early.
Error clearly: Nothing’s worse than not knowing why something went wrong.
Document well: A framework is only as good as its docs.
Minimize breaking changes: Upgrading shouldn’t require rewriting your game.

The documentation for Pygame Zero is very accessible for beginning programmers, and it includes a complete step-by-step tutorial. Further, the Pygame Zero team recognizes that many beginning programmers start coding with Scratch, so they provide a tutorial demonstrating how to migrate a Scratch program to Pygame Zero.

Remove ads

Pygame Zero Installation

Pygame Zero is available on PyPI, and you can install it like any other Python library on Windows, macOS, or Linux:

Shell
      
(venv) $ python -m pip install pgzero

Pygame Zero, as its name suggests, is built on Pygame, so this step also installs Pygame as a dependent library. Pygame Zero is installed by default on the Raspberry Pi platform, on Raspbian Jessie or a later release.

Basic Concepts

Pygame Zero automates many things that programmers have to do manually in Pygame. By default, Pygame Zero provides the game creator:

A game loop, so there’s no need to write one
An event model to handle drawing, update, and input handling
Uniform image, text, and sound handling
A usable sprite class and useful animation methods for user sprites

Because of these provisions, a basic Pygame Zero program can be very short:

Python
      
    
"""
Basic "Hello, World!" program in Pygame Zero

This program is designed to demonstrate the basic capabilities
of Pygame Zero. It will:
- Create a game window
- Fill the background with white
- Draw some basic shapes in different colors
- Draw some text in a specified size and color
"""

# Import pgzrun allows the program to run in Python IDLE
import pgzrun

# Set the width and height of your output window, in pixels
WIDTH = 800
HEIGHT = 600

def draw():
    """Draw is called once per frame to render everything on the screen"""

    # Clear the screen first
    screen.clear()

    # Set the background color to white
    screen.fill("white")

    # Draw a blue circle with a radius of 50 in the center of the screen
    screen.draw.filled_circle(
        (WIDTH // 2, HEIGHT // 2), 50, "blue"
    )

    # Draw a red-outlined square in the top-left corner of the screen
    red_square = Rect((50, 50), (100, 100))
    screen.draw.rect(red_square, (200, 0, 0))

    # Draw an orange caption along the bottom in 60-point font
    screen.draw.text(
        "Hello, World! From Pygame Zero!",
        (100, HEIGHT - 50),
        fontsize=60,
        color="orange",
    )

# Run the program
pgzrun.go()

Pygame Zero recognizes that the constants WIDTH and HEIGHT on lines 16 and 17 refer to the size of the window and automatically uses those dimensions to create it. Plus, Pygame Zero provides a built-in game loop and calls the draw() function defined on lines 19 to 43 once per frame to render the screen.

Because Pygame Zero is based on Pygame, some shape drawing code is inherited. You can see the similarities in drawing the circle on line 29 and the square on lines 34 to 35:

However, text drawing is now a single function call on lines 38 to 43, rather than three separate functions.

Pygame Zero also provides basic window-handling code, so you can close the window by clicking the appropriate close button, without requiring an event handler.

You can find code demonstrating some of Pygame Zero’s basic capabilities in the downloadable materials:

Get Source Code: Click here to get the source code you’ll use to try out Python game engines.

Running Pygame Zero programs is done from the command line using the command:

Shell
      
(venv) $ python pygame_zero/pygame_zero_basic.py

Running this command will start your Pygame Zero game. You should see a window appear with basic shapes and your Pygame Zero greeting.

Sprites and Images

Sprites are called Actors in Pygame Zero, and they have a few characteristics which require some explanation:

Pygame Zero provides the Actor class. Each Actor has, at minimum, an image and a position.
All images used in a Pygame Zero program must be located in a subfolder called ./images/, and be named using lowercase letters, numbers, and underscores only.
Images are referenced using only the base name of the image. For example, if your image is called alien.png, you reference it in your program as "alien".

Because of these built-in features of Pygame Zero, drawing sprites on the screen requires very little code:

Python
      
    
alien = Actor("alien")
alien.pos = 100, 56

WIDTH = 500
HEIGHT = alien.height + 20

def draw():
    screen.clear()
    alien.draw()

Now you’ll break this small sample down line by line:

Line 1 creates the new Actor object, giving it the name of the image to draw.
Line 2 sets the initial x and y position of the Actor.
Lines 4 and 5 set the size of the Pygame Zero window. Notice that HEIGHT is based on the .height attribute of the sprite. This value comes from the height of the image used to create the sprite.
Line 9 draws the sprite by calling .draw() on the Actor object. This draws the sprite image on the screen at the location provided by .pos.

You’ll use these techniques in a more advanced game next.

Remove ads

Advanced Application

To demonstrate the difference between the game engines, you’ll revisit the same advanced game that you saw in the Pygame section, now written using Pygame Zero. As a reminder, the key details of that game are:

The player is a single sprite on the screen, controlled by moving the mouse.
At regular intervals, coins appear on the screen one by one.
As the player moves over each coin, it disappears and the player is awarded ten points.
As the game progresses, coins are added more quickly.
The game ends when there are more than ten coins visible on the screen.

This game should look and behave identically to the Pygame version demonstrated earlier, with only the window title bar betraying the Pygame Zero origin:

You can find the complete code for this sample in the downloaded materials and below:

Python
      
    
"""
Complete game in Pygame Zero

This game demonstrates some of the more advanced features of
Pygame Zero, including:
- Using sprites to render complex graphics
- Handling user input
- Sound output

"""

# Import pgzrun allows the program to run in Python IDLE
import pgzrun

# For type-hinting support
from typing import Tuple

# To randomize coin placement
from random import randint

# Set the width and height of your output window, in pixels
WIDTH = 800
HEIGHT = 600

# Set up the player
player = Actor("alien_green_stand")
player_position = WIDTH // 2, HEIGHT // 2
player.center = player_position

# Set up the coins to collect
COIN_COUNT = 10
coin_list = list()

# Set up a timer to create new coins
coin_countdown = 2.5
coin_interval = 0.1

# Score is initially zero
score = 0

def add_coin():
    """Adds a new coin to playfield, then
    schedules the next coin to be added
    """
    global coin_countdown

    # Create a new coin Actor at a random location
    new_coin = Actor(
        "coin_gold", (randint(10, WIDTH - 10), randint(10, HEIGHT - 10))
    )

    # Add it to the global coin list
    coin_list.append(new_coin)

    # Decrease the time between coin appearances if there are
    # fewer than three coins on the screen.
    if len(coin_list) < 3:
        coin_countdown -= coin_interval

    # Make sure you don't go too quickly
    if coin_countdown < 0.1:
        coin_countdown = 0.1

    # Schedule the next coin addition
    clock.schedule(add_coin, coin_countdown)

def on_mouse_move(pos: Tuple):
    """Called whenever the mouse changes position

    Arguments:
        pos {Tuple} -- The current position of the mouse
    """
    global player_position

    # Set the player to the mouse position
    player_position = pos

    # Ensure the player doesn't move off the screen
    if player_position[0] < 0:
        player_position[0] = 0
    if player_position[0] > WIDTH:
        player_position[0] = WIDTH

    if player_position[1] < 0:
        player_position[1] = 0
    if player_position[1] > HEIGHT:
        player_position[1] = HEIGHT

def update(delta_time: float):
    """Called every frame to update game objects

    Arguments:
        delta_time {float} -- Time since the last frame
    """
    global score

    # Update the player position
    player.center = player_position

    # Check if the player has collided with a coin
    # First, set up a list of coins to remove
    coin_remove_list = []

    # Check each coin in the list for a collision
    for coin in coin_list:
        if player.colliderect(coin):
            sounds.coin_pickup.play()
            coin_remove_list.append(coin)
            score += 10

    # Remove any coins with which you collided
    for coin in coin_remove_list:
        coin_list.remove(coin)

    # The game is over when there are too many coins on the screen
    if len(coin_list) >= COIN_COUNT:
        # Stop making new coins
        clock.unschedule(add_coin)

        # Print the final score and exit the game
        print(f"Game over! Final score: {score}")
        exit()

def draw():
    """Render everything on the screen once per frame"""

    # Clear the screen first
    screen.clear()

    # Set the background color to pink
    screen.fill("pink")

    # Draw the remaining coins
    for coin in coin_list:
        coin.draw()

    # Draw the player
    player.draw()

    # Draw the current score at the bottom
    screen.draw.text(
        f"Score: {score}",
        (50, HEIGHT - 50),
        fontsize=48,
        color="black",
    )

# Schedule the first coin to appear
clock.schedule(add_coin, coin_countdown)

# Run the program
pgzrun.go()

Creating the player Actor is done on lines 26 to 28. The initial position is the center of the screen.

The clock.schedule() method handles creating coins at regular intervals. This method takes a function to call and the number of seconds to delay before calling that function.

Lines 41 to 65 define the add_coin() function that will be scheduled. It creates a new coin Actor at a random location on lines 48 to 50 and adds it to a global list of visible coins.

As the game progresses, coins should appear more and more quickly, but not too quickly. Managing the interval is done on lines 57 to 62. Because clock.schedule() will only fire a single time, you schedule another call on line 65.

Mouse movement is processed in the on_mouse_move() event handler on lines 67 to 87. The mouse position is captured and stored in a global variable on line 76. Lines 79 to 87 ensure this position is never off the screen.

Storing the player position in a global variable is a convenience that simplifies the code and focuses allows you to focus on the capabilities of Pygame Zero. Your design choices may differ in more complete games.

The update() function defined on lines 89 to 122 is called once per frame by Pygame Zero. You use this to move Actor objects and update the state of all your game objects. The position of the player Actor is updated to track the mouse on line 98.

Collisions with coins are handled on lines 102 to 113. If the player has collided with a coin, then the coin is added to coin_remove_list, the score is incremented, and a sound is played. When all the collisions have been processed, you remove the coins which were added to coin_remove_list on lines 112 to 113.

After coin collisions are handled, you check to see if there are still too many coins on the screen on line 116. If so, the game is over, so you stop creating new coins, print the final score, and end the game on lines 118 to 122.

Of course, all this updating needs to be reflected on the screen. The draw() function on lines 124 to 146 is called after update() once per frame. After clearing the screen and filling it with a background color on lines 128 and 131, the player Actor and all the coins are drawn on lines 134 to 138. The current score is the last thing drawn on lines 141 to 146.

The Pygame Zero implementation used 152 lines of code to deliver the same game as 182 lines of Pygame code. While these line counts are comparable, the Pygame Zero version is arguably cleaner, more modular, and possibly easier to understand and code than the Pygame version.

Of course, there’s always one more way to write a game.

Arcade

Arcade is a modern Python framework for crafting games with compelling graphics and sound. Object-oriented by design, Arcade provides game authors with a modern set of tools for crafting great Python game experiences.

Designed by Professor Paul Craven from Simpson College in Iowa, USA, Arcade is built on top of the pyglet windowing and multimedia library. It provides a set of improvements, modernizations, and enhancements that compare favorably with both Pygame and Pygame Zero:

Supports modern OpenGL graphics
Supports Python 3 type hinting
Has support for frame-based animated sprites
Incorporates consistent command, function, and parameter names
Encourages separation of game logic from display code
Requires less boilerplate code
Provides well-maintained and up-to-date documentation, including several tutorials and complete Python game examples
Has built-in physics engines for top-down and platform games

Arcade is under constant development, is well supported in the community, and has an author who’s very responsive to issues, bug reports, and potential fixes.

Remove ads

Arcade Installation

To install Arcade and its dependencies, use the appropriate pip command:

Shell
      
(venv) $ python -m pip install arcade

Complete installation instructions based on your platform are available for Windows, macOS, and Linux. You can even install arcade directly from source if you’d prefer.

Basic Concepts

Everything in Arcade occurs in a window that’s created with a user-defined size. The coordinate system assumes that the origin (0, 0) is located in the lower-left corner of the screen, with the y-coordinates increasing as you move up. This is different from many other game engines, which place (0, 0) in the upper left and increase the y-coordinates moving down.

At its heart, Arcade is an object-oriented library. While it’s possible to write Arcade applications procedurally, its real power is revealed when you create fully object-oriented code.

Arcade, like Pygame Zero, provides a built-in game loop and a well-defined event model, so you end up with very clean and readable game code. Also like Pygame Zero, Arcade provides a powerful sprite class which aids rendering, positioning, and collision detection. In addition, Arcade sprites can be animated by providing multiple images.

The code for a basic Arcade application listed below is provided in the tutorial’s source code as arcade_basic.py:

Python
      
    
"""
Basic "Hello, World!" program in Arcade

This program is designed to demonstrate the basic capabilities
of Arcade. It will:
- Create a game window
- Fill the background with white
- Draw some basic shapes in different colors
- Draw some text in a specified size and color
"""

# Import arcade allows the program to run in Python IDLE
import arcade

# Set the width and height of your output window, in pixels
WIDTH = 800
HEIGHT = 600

# Classes
class ArcadeBasic(arcade.Window):
    """Main game window"""

    def __init__(self, width: int, height: int, title: str):
        """Initialize the window to a specific size

        Arguments:
            width {int} -- Width of the window
            height {int} -- Height of the window
            title {str} -- Title for the window
        """

        # Call the parent class constructor
        super().__init__(width, height, title)

        # Set the background window
        arcade.set_background_color(color=arcade.color.WHITE)

    def on_draw(self):
        """Called once per frame to render everything on the screen"""

        # Start rendering
        arcade.start_render()

        # Draw a blue circle with a radius of 50 in the center of the screen
        arcade.draw_circle_filled(
            center_x=WIDTH // 2,
            center_y=HEIGHT // 2,
            radius=50,
            color=arcade.color.BLUE,
            num_segments=50,
        )

        # Draw a red-outlined square in the top-left corner of the screen
        arcade.draw_lrtb_rectangle_outline(
            left=50,
            top=HEIGHT - 50,
            bottom=HEIGHT - 100,
            right=100,
            color=arcade.color.RED,
            border_width=3,
        )

        # Draw an orange caption along the bottom in 60-point font
        arcade.draw_text(
            text="Hello, World! From Arcade!",
            start_x=100,
            start_y=50,
            font_size=28,
            color=arcade.color.ORANGE,
        )

# Run the program
if __name__ == "__main__":
    arcade_game = ArcadeBasic(WIDTH, HEIGHT, "Arcade Basic Game")
    arcade.run()

To run this code, use the following command:

Shell
      
(venv) $ python arcade/arcade_basic.py

This program draws a few shapes and some text on the screen, as in the basic examples previously shown:

As mentioned above, Arcade programs can be written as fully object-oriented code. The arcade.Window class is designed to be subclassed by your games, as shown on line 20. Calling super().__init() on line 33 ensures the game window is set up properly.

Arcade calls the .on_draw() event handler defined on lines 38 to 70 once per frame to render everything to the screen. This method starts with a call to .start_render(), which tells Arcade to prepare the window for drawing. This is comparable to the pygame.flip() call required at the end of the Pygame drawing step.

Each of the basic shape-drawing methods in Arcade starts with draw_* and requires a single line to complete. Arcade has built-in drawing support for numerous shapes.

Arcade comes loaded with hundreds of named colors in the arcade.color package, but you’re also free to pick your own colors using RGB or RGBA tuples.

Advanced Application

To show how Arcade is different from other game engines, you’ll see the same game from before, now implemented in Arcade. As a reminder, here are the key details of the game:

The player is a single sprite on the screen, controlled by moving the mouse.
At regular intervals, coins appear on the screen one by one.
As the player moves over each coin, it disappears and the player is awarded ten points.
As the game progresses, coins are added more quickly.
The game ends when there are more than ten coins visible on the screen.

Again, the game should act the same as the previous examples:

The code for the full Arcade game listed below is provided in the downloadable materials as arcade_game.py:

Python
      
    
"""
Complete game in Arcade

This game demonstrates some of the more advanced features of
Arcade, including:
- Using sprites to render complex graphics
- Handling user input
- Sound output
"""

# Import arcade allows the program to run in Python IDLE
import arcade

# To randomize coin placement
from random import randint

# To locate your assets
from pathlib import Path

# Set the width and height of your game window, in pixels
WIDTH = 800
HEIGHT = 600

# Set the game window title
TITLE = "Arcade Sample Game"

# Location of your assets
ASSETS_PATH = Path.cwd() / "assets"

# How many coins must be on the screen before the game is over?
COIN_COUNT = 10

# How much is each coin worth?
COIN_VALUE = 10

# Classes
class ArcadeGame(arcade.Window):
    """The Arcade Game class"""

    def __init__(self, width: float, height: float, title: str):
        """Create the main game window

        Arguments:
            width {float} -- Width of the game window
            height {float} -- Height of the game window
            title {str} -- Title for the game window
        """

        # Call the super class init method
        super().__init__(width, height, title)

        # Set up a timer to create new coins
        self.coin_countdown = 2.5
        self.coin_interval = 0.1

        # Score is initially zero
        self.score = 0

        # Set up empty sprite lists
        self.coins = arcade.SpriteList()

        # Don't show the mouse cursor
        self.set_mouse_visible(False)

    def setup(self):
        """Get the game ready to play"""

        # Set the background color
        arcade.set_background_color(color=arcade.color.PINK)

        # Set up the player
        sprite_image = ASSETS_PATH / "images" / "alien_green_stand.png"
        self.player = arcade.Sprite(
            filename=sprite_image, center_x=WIDTH // 2, center_y=HEIGHT // 2
        )

        # Spawn a new coin
        arcade.schedule(
            function_pointer=self.add_coin, interval=self.coin_countdown
        )

        # Load your coin collision sound
        self.coin_pickup_sound = arcade.load_sound(
            ASSETS_PATH / "sounds" / "coin_pickup.wav"
        )

    def add_coin(self, dt: float):
        """Add a new coin to the screen, reschedule the timer if necessary

        Arguments:
            dt {float} -- Time since last call (unused)
        """

        # Create a new coin
        coin_image = ASSETS_PATH / "images" / "coin_gold.png"
        new_coin = arcade.Sprite(
            filename=coin_image,
            center_x=randint(20, WIDTH - 20),
            center_y=randint(20, HEIGHT - 20),
        )

        # Add the coin to the current list of coins
        self.coins.append(new_coin)

        # Decrease the time between coin appearances, but only if there are
        # fewer than three coins on the screen.
        if len(self.coins) < 3:
            self.coin_countdown -= self.coin_interval

            # Make sure you don't go too quickly
            if self.coin_countdown < 0.1:
                self.coin_countdown = 0.1

            # Stop the previously scheduled call
            arcade.unschedule(function_pointer=self.add_coin)

            # Schedule the next coin addition
            arcade.schedule(
                function_pointer=self.add_coin, interval=self.coin_countdown
            )

    def on_mouse_motion(self, x: float, y: float, dx: float, dy: float):
        """Processed when the mouse moves

        Arguments:
            x {float} -- X Position of the mouse
            y {float} -- Y Position of the mouse
            dx {float} -- Change in x position since last move
            dy {float} -- Change in y position since last move
        """

        # Ensure the player doesn't move off-screen
        self.player.center_x = arcade.clamp(x, 0, WIDTH)
        self.player.center_y = arcade.clamp(y, 0, HEIGHT)

    def on_update(self, delta_time: float):
        """Update all the game objects

        Arguments:
            delta_time {float} -- How many seconds since the last frame?
        """

        # Check if you've picked up a coin
        coins_hit = arcade.check_for_collision_with_list(
            sprite=self.player, sprite_list=self.coins
        )

        for coin in coins_hit:
            # Add the coin score to your score
            self.score += COIN_VALUE

            # Play the coin sound
            arcade.play_sound(self.coin_pickup_sound)

            # Remove the coin
            coin.remove_from_sprite_lists()

        # Are there more coins than allowed on the screen?
        if len(self.coins) > COIN_COUNT:
            # Stop adding coins
            arcade.unschedule(function_pointer=self.add_coin)

            # Show the mouse cursor
            self.set_mouse_visible(True)

            # Print the final score and exit the game
            print(f"Game over! Final score: {self.score}")
            exit()

    def on_draw(self):
        """Draw everything"""

        # Start the rendering pass
        arcade.start_render()

        # Draw the coins
        self.coins.draw()

        # Draw the player
        self.player.draw()

        # Draw the score in the lower-left corner
        arcade.draw_text(
            text=f"Score: {self.score}",
            start_x=50,
            start_y=50,
            font_size=32,
            color=arcade.color.BLACK,
        )

if __name__ == "__main__":
    arcade_game = ArcadeGame(WIDTH, HEIGHT, TITLE)
    arcade_game.setup()
    arcade.run()

The object-oriented nature of Arcade allows you to quickly implement different levels by separating the initialization of the game from the initialization of each different level. The game is initialized in the .__init__() method on lines 40 to 63, while levels are set up and can be restarted using the separate .setup() method on lines 65 to 85. This is a great pattern to use even for games that have a single level, like this one.

Sprites are defined by creating an object of the class arcade.Sprite, and providing the path to an image. Arcade supports pathlib paths, which eases the creation of the player sprite on lines 72 to 75.

Creating new coins is handled on lines 78 to 80, which call arcade.schedule() to call the self.add_coin() method at regular intervals.

The .add_coin() method defined on lines 87 to 120 creates a new coin sprite at a random location and adds it to a list to simplify drawing as well as collision handling later.

To move the player using the mouse, you implement the .on_mouse_motion() method on lines 122 to 134. The arcade.clamp() method ensures the player’s center coordinates are never off the screen.

Checking for collisions between the player and the coin is handled in the .on_update() method on lines 144 to 156. The arcade.check_for_collision_with_list() method returns a list of all the sprites in the list that have collided with the specified sprite. The code walks through that list, incrementing the score and playing a sound effect before removing each coin from play.

The .on_update() method also checks if there are too many coins on the screen on lines 159 to 168. If so, it ends the game.

This Arcade implementation is just as readable and well structured as the Pygame Zero code, although it took over 27% more code, with 194 lines written. The longer code may be worth it, as Arcade offers many more features not demonstrated here, such as:

Animated sprites
Several built-in physics engines
Support for third-party game maps
Updated particle and shader systems

New game authors coming from Python Zero will find Arcade similar in structure while offering more powerful and extensive features.

Remove ads

adventurelib

Of course, not every game requires a colorful player moving on the screen, avoiding obstacles, and killing bad guys. Classic computer games like Zork showed off the power of good storytelling while still providing a great gaming experience. Crafting these text-based games, also called interactive fiction, can be difficult in any language. Luckily for the Python programmer, there’s adventurelib:

adventurelib provides basic functionality for writing text-based adventure games, with the aim of making it easy enough for young teenagers to do. (Source)

It’s not just for teenagers, though! adventurelib is great for anyone who wants to write a text-based game without having to also write a natural language parser to do so.

adventurelib was created by the folks behind Pygame Zero, and it tackles more advanced computer science topics such as state management, business logic, naming and references, and set manipulation, to name a few. This makes it a great next step for educators, parents, and mentors helping young people learn computer science through the creation of games. It’s also great for broadening your own game-coding skills.

adventurelib Installation

adventurelib is available on PyPI and can be installed using the appropriate pip command:

Shell
      
(venv) $ python -m pip install adventurelib

adventurelib is a single file, so it can also be downloaded from the GitHub repo, saved in the same folder as your game, and used directly.

Basic Concepts

To learn the basics of adventurelib, you’ll see a small game with three rooms and a key to unlock a door to the final room below. The code for this sample game is provided in the downloadable materials in adventurelib_basic.py:

Python
      
    
"""
Basic "Hello, World!" program in adventurelib

This program is designed to demonstrate the basic capabilities
of adventurelib. It will:
- Create a basic three-room world
- Add a single inventory item
- Require that inventory item to move to the final room
"""

# Import the library contents
import adventurelib as adv

# Define your rooms
bedroom = adv.Room(
    """
You are in your bedroom. The bed is unmade, but otherwise
it's clean. Your dresser is in the corner, and a desk is
under the window.
"""
)

living_room = adv.Room(
    """
The living room stands bright and empty. The TV is off,
and the sun shines brightly through the curtains.
"""
)

front_porch = adv.Room(
    """
The creaky boards of your front porch welcome you as an
old friend. Your front door mat reads 'Welcome'.
"""
)

# Define the connections between the rooms
bedroom.south = living_room
living_room.east = front_porch

# Define a constraint to move from the bedroom to the living room
# If the door between the living room and front porch door is locked,
# you can't exit
living_room.locked = {"east": True}

# None of the other rooms have any locked doors
bedroom.locked = dict()
front_porch.locked = dict()

# Set the starting room as the current room
current_room = bedroom

# Define functions to use items
def unlock_living_room(current_room):

    if current_room == living_room:
        print("You unlock the door.")
        current_room.locked["east"] = False
    else:
        print("There is nothing to unlock here.")

# Create your items
key = adv.Item("a front door key", "key")
key.use_item = unlock_living_room

# Create empty Bags for room contents
bedroom.contents = adv.Bag()
living_room.contents = adv.Bag()
front_porch.contents = adv.Bag()

# Put the key in the bedroom
bedroom.contents.add(key)

# Set up your current empty inventory
inventory = adv.Bag()

# Define your movement commands
@adv.when("go DIRECTION")
@adv.when("north", direction="north")
@adv.when("south", direction="south")
@adv.when("east", direction="east")
@adv.when("west", direction="west")
@adv.when("n", direction="north")
@adv.when("s", direction="south")
@adv.when("e", direction="east")
@adv.when("w", direction="west")
def go(direction: str):
    """Processes your moving direction

    Arguments:
        direction {str} -- which direction does the player want to move
    """

    # What is your current room?
    global current_room

    # Is there an exit in that direction?
    next_room = current_room.exit(direction)
    if next_room:
        # Is the door locked?
        if direction in current_room.locked and current_room.locked[direction]:
            print(f"You can't go {direction} --- the door is locked.")
        else:
            current_room = next_room
            print(f"You go {direction}.")
            look()

    # No exit that way
    else:
        print(f"You can't go {direction}.")

# How do you look at the room?
@adv.when("look")
def look():
    """Looks at the current room"""

    # Describe the room
    adv.say(current_room)

    # List the contents
    for item in current_room.contents:
        print(f"There is {item} here.")

    # List the exits
    print(f"The following exits are present: {current_room.exits()}")

# How do you look at items?
@adv.when("look at ITEM")
@adv.when("inspect ITEM")
def look_at(item: str):

    # Check if the item is in your inventory or not
    obj = inventory.find(item)
    if not obj:
        print(f"You don't have {item}.")
    else:
        print(f"It's an {obj}.")

# How do you pick up items?
@adv.when("take ITEM")
@adv.when("get ITEM")
@adv.when("pickup ITEM")
def get(item: str):
    """Get the item if it exists

    Arguments:
        item {str} -- The name of the item to get
    """
    global current_room

    obj = current_room.contents.take(item)
    if not obj:
        print(f"There is no {item} here.")
    else:
        print(f"You now have {item}.")
        inventory.add(obj)

# How do you use an item?
@adv.when("unlock door", item="key")
@adv.when("use ITEM")
def use(item: str):
    """Use an item, consumes it if used

    Arguments:
        item {str} -- Which item to use
    """

    # First, do you have the item?
    obj = inventory.take(item)
    if not obj:
        print(f"You don't have {item}")

    # Try to use the item
    else:
        obj.use_item(current_room)

if __name__ == "__main__":
    # Look at the starting room
    look()

    adv.start()

To run this code, use the following command:

Shell
      
(venv) $ python adventurelib/adventurelib_basic.py

Text-based games rely heavily on parsing user input to drive the game forward. adventurelib defines the text that a player types as a command and provides the @when() decorator to define commands.

A good example of a command is the look command defined on lines 113 to 125. The @when("look") decorator adds the text look to a list of valid commands and connects it to the look() function. Whenever the player types look, adventurelib will call the look() function.

Commands are case-insensitive when typed by the player. The player can type look, LOOK, Look, or even lOOk, and adventurelib will find the correct command.

Multiple commands can all use the same function, as seen with the go() function on lines 78 to 110. This function is decorated with nine separate commands, allowing the player several different ways to move around the game world. In the game play example below, the commands south, east, and north are all used, but each results in the same function being called:

Sometimes the commands that a player types are directed at a specific item. For example, the player may want to look at a particular thing or go in a specific direction. The game designer can capture additional command context by specifying capitalized words in the @when() decorator. These are treated as variable names, and the text that the player types in their place are the values.

This can be seen in the look_at() function on lines 128 to 137. This function defines a single string parameter called item. In the @when() decorators defining the look at and inspect commands, the word ITEM acts as a placeholder for any text following the command. This text is then passed to the look_at() function as the item parameter. For example, if the player types look at book, then the parameter item will get the value "book".

The strength of a text-based game relies on the descriptiveness of its text. While you can and should certainly use print() functions, printing numerous lines of text in response to user commands can introduce difficulties spanning text over multiple lines and determining line breaks. adventurelib eases this burden with the say() function, which works well with triple-quoted multiline strings.

You can see the say() function in action on line 118 in the look() function. Whenever the player types look, the say() function outputs the description of the current room to the console.

Of course, your commands need places to occur. adventurelib provides the Room class to define different areas of your game world. Rooms are created by providing a description of the room, and they can be connected to other rooms by using the .north, .south, .east, and .west properties. You can also define custom properties that apply to either the entire Room class or individual objects.

The three rooms in this game are created on lines 15 to 35. The Room() constructor accepts a description as a string, or in this case, as a multiline string. Once you’ve created the rooms, then you connect them on lines 38 to 39. Setting bedroom.south to living_room implies that living_room.north will be bedroom. adventurelib is smart enough to make this connection automatically.

You also create a constraint on line 44 to indicate a locked door between the living room and the front porch. Unlocking this door will require the player to locate an item.

Text-based games often feature items which must be collected to open new areas of the game or to solve certain puzzles. Items can also represent non-player characters with whom the player can interact. adventurelib provides the Item class to define both collectable items and non-player characters by their names and aliases. For example, the alias key refers to the front door key:

On line 63, you define the key used to unlock the door between the living room and the front porch. The Item() constructor takes one or more strings. The first is the default or full name of the item, and it’s used when printing the name of the item. All other names are used as aliases so the player doesn’t have to type the full name of the item.

The key doesn’t just have a name and aliases. It also has an intended use, which is defined on line 64. key.use_item refers to a function that will be called when a player tries to use the item by typing "use key". This function is called in the use() command handler defined on lines 159 to 175.

Collections of items, such as the player’s inventory or items on the ground in a room, can be stored in a Bag object. You can add items to the bag, remove items from the bag, and inspect the bag’s contents. Bag objects are iterable in Python, so you can also use in to test if something is in the bag and loop over the bag’s contents in a for loop.

Four different Bag objects are defined on lines 67 to 75. Each of the three rooms has a Bag to hold items in the room, and the player also has a Bag to hold their inventory of items they pick up. The key item is placed in its starting location in the bedroom.

Items are added to the player’s inventory by the get() function defined on lines 140 to 156. When the player types get key, you attempt to take() the item from the room’s contents bag on line 151. If the key is returned, it’s also removed from the room’s contents. You then add the key to the player’s inventory on line 156.

Remove ads

Advanced Application

Of course, there’s much more to adventurelib. To show off its other capabilities, you’ll craft a more involved text adventure with the following backstory:

You live in a small, quiet hamlet.
Recently, your neighbors have begun complaining of missing livestock.
As a member of a night patrol, you notice a broken fence and a trail leading away from it.
You decide to investigate, armed only with a wooden practice sword.

The game has several areas to describe and define:

Your small, quiet hamlet
The trail leading away from the field
A nearby village where you can buy a better weapon
A side path leading to a wizard who can enchant your weapon
A cave containing the giant who has been taking your livestock

There are several items to collect, such as weapons and food, and characters with which to interact. You also need a basic battle system to allow you to fight the giant and win the game.

All of the code for this game is listed below, and can be found in the downloaded materials:

Get Source Code: Click here to get the source code you’ll use to try out Python game engines.

To keep things organized, you break your game into different files:

adventurelib_game_rooms.py defines the rooms and areas.
adventurelib_game_items.py defines the items and their attributes.
adventurelib_game_characters.py defines the characters with which you can interact.
adventurelib_game.py pulls everything together, adds commands, and starts the game.

Python
      
    
"""
Complete game written in adventurelib

This program is designed to demonstrate the capabilities
of adventurelib. It will:
- Create a large world in which to wander
- Contain several inventory items
- Set contexts for moving from one area to another
- Require some puzzle-solving skills
"""

# Import the library contents
# from adventurelib import *
import adventurelib as adv

# Import your rooms, which imports your items and characters
import adventurelib_game_rooms

import adventurelib_game_items

# For your battle sequence
from random import randint

# To allow you to exit the game
import sys

# Set the first room
current_room = adventurelib_game_rooms.home
current_room.visited = False

# How many HP do you have?
hit_points = 20

# How many HP does the giant have?
giant_hit_points = 50

# Your current inventory
inventory = adv.Bag()

# Some basic item commands
@adv.when("inventory")
@adv.when("inv")
@adv.when("i")
def list_inventory():
    if inventory:
        print("You have the following items:")
        for item in inventory:
            print(f"  - {item.description}")
    else:
        print("You have nothing in your inventory.")

@adv.when("look at ITEM")
def look_at(item: str):
    """Prints a short description of an item if it is either:
    1. in the current room, or
    2. in our inventory

    Arguments:
        item {str} -- the item to look at
    """

    global inventory, current_room

    # Check if the item is in the room
    obj = current_room.items.find(item)
    if not obj:
        # Check if the item is in your inventory
        obj = inventory.find(item)
        if not obj:
            print(f"I can't find {item} anywhere.")
        else:
            print(f"You have {item}.")
    else:
        print(f"You see {item}.")

@adv.when("describe ITEM")
def describe(item: str):
    """Prints a description of an item if it is either:
    1. in the current room, or
    2. in your inventory

    Arguments:
        item {str} -- the item to look at
    """

    global inventory, current_room

    # Check if the item is in the room
    obj = current_room.items.find(item)
    if not obj:
        # Check if the item is in your inventory
        obj = inventory.find(item)
        if not obj:
            print(f"I can't find {item} anywhere.")
        else:
            print(f"You have {obj.description}.")
    else:
        print(f"You see {obj.description}.")

@adv.when("take ITEM")
@adv.when("get ITEM")
@adv.when("pickup ITEM")
@adv.when("pick up ITEM")
@adv.when("grab ITEM")
def take_item(item: str):
    global current_room

    obj = current_room.items.take(item)
    if not obj:
        print(f"I don't see {item} here.")
    else:
        print(f"You now have {obj.description}.")
        inventory.add(obj)

@adv.when("eat ITEM")
def eat(item: str):
    global inventory

    # Make sure you have the thing first
    obj = inventory.find(item)

    # Do you have this thing?
    if not obj:
        print(f"You don't have {item}.")

    # Is it edible?
    elif obj.edible:
        print(f"You savor every bite of {obj.description}.")
        inventory.take(item)

    else:
        print(f"How do you propose we eat {obj.description}?")

@adv.when("wear ITEM")
@adv.when("put on ITEM")
def wear(item: str):
    global inventory

    # Make sure you have the thing first
    obj = inventory.find(item)

    # Do you have this thing?
    if not obj:
        print(f"You don't have {item}.")

    # Is it wearable?
    elif obj.wearable:
        print(f"The {obj.description} makes a wonderful fashion statement!")

    else:
        print(
            f"""This is no time for avant garde fashion choices!
            Wear a {obj.description}? Really?"""
        )

# Some character-specific commands
@adv.when("talk to CHARACTER")
def talk_to(character: str):
    global current_room

    char = current_room.characters.find(character)

    # Is the character there?
    if not char:
        print(f"Sorry, I can't find {character}.")

    # It's a character who is there
    else:
        # Set the context, and start the encounter
        adv.set_context(char.context)
        adv.say(char.greeting)

@adv.when("yes", context="elder")
def yes_elder():
    global current_room

    adv.say(
        """
    It is not often one of our number leaves, and rarer still if they leave
    to defend our Home. Go with our blessing, and our hope for a successful
    journey and speedy return. To help, we bestow three gifts.

    The first is one of knowledge. There is a blacksmith in one of the
    neighboring villages. You may find help there.

    Second, seek a wizard who lives as a hermit, who may be persuaded to
    give aid. Be wary, though! The wizard does not give away his aid for
    free. As he tests you, remember always where you started your journey.

    Lastly, we don't know what dangers you may face. We are peaceful people,
    but do not wish you to go into the world undefended. Take this meager
    offering, and use it well!
    """
    )
    inventory.add(adventurelib_game_items.wooden_sword)
    current_room.locked_exits["south"] = False

@adv.when("thank you", context="elder")
@adv.when("thanks", context="elder")
def thank_elder():
    adv.say("It is we who should thank you. Go with our love and hopes!")

@adv.when("yes", context="blacksmith")
def yes_blacksmith():
    global current_room

    adv.say(
        """
        I can see you've not a lot of money. Usually, everything here
        if pretty expensive, but I just might have something...

        There's this steel sword here, if you want it. Don't worry --- it
        doesn't cost anything! It was dropped off for repair a few weeks
        ago, but the person never came back for it. It's clean, sharp,
        well-oiled, and will do a lot more damage than that
        fancy sword-shaped club you've got. I need it gone to clear some room.

        If you want, we could trade even up --- the wooden sword for the
        steel one. I can use yours for fire-starter. Deal?
        """
    )
    adv.set_context("blacksmith.trade")

@adv.when("yes", context="blacksmith.trade")
def trade_swords_yes():
    print("Great!")
    inventory.take("wooden sword")
    inventory.add(adventurelib_game_items.steel_sword)

@adv.when("no", context="blacksmith.trade")
def trade_swords_no():
    print("Well, that's all I have within your budget. Good luck!")
    adv.set_context(None)

@adv.when("yes", context="wizard")
def yes_wizard():
    global current_room

    adv.say(
        """
    I can make your weapon more powerful than it is, but only if
    you can answer my riddle:

    What has one head...
        One foot...
            But four legs?
    """
    )

    adv.set_context("wizard.riddle")

@adv.when("bed", context="wizard.riddle")
@adv.when("a bed", context="wizard.riddle")
def answer_riddle():
    adv.say("You are smarter than you believe yourself to be! Behold!")

    obj = inventory.find("sword")
    obj.bonus = 2
    obj.description += ", which glows with eldritch light"

    adv.set_context(None)
    current_room.locked_exits["west"] = False

@adv.when("fight CHARACTER", context="giant")
def fight_giant(character: str):

    global giant_hit_points, hit_points

    sword = inventory.find("sword")

    # The player gets a swing
    player_attack = randint(1, sword.damage + 1) + sword.bonus
    print(f"You swing your {sword}, doing {player_attack} damage!")
    giant_hit_points -= player_attack

    # Is the giant dead?
    if giant_hit_points <= 0:
        end_game(victory=True)

    print_giant_condition()
    print()

    # Then the giant tries
    giant_attack = randint(0, 5)
    if giant_attack == 0:
        print("The giant's arm whistles harmlessly over your head!")
    else:
        print(
            f"""
            The giant swings his mighty fist,
            and does {giant_attack} damage!
            """
        )
        hit_points -= giant_attack

    # Is the player dead?
    if hit_points <= 0:
        end_game(victory=False)

    print_player_condition()
    print()

def print_giant_condition():

    if giant_hit_points < 10:
        print("The giant staggers, his eyes unfocused.")
    elif giant_hit_points < 20:
        print("The giant's steps become more unsteady.")
    elif giant_hit_points < 30:
        print("The giant sweats and wipes the blood from his brow.")
    elif giant_hit_points < 40:
        print("The giant snorts and grits his teeth against the pain.")
    else:
        print("The giant smiles and readies himself for the attack.")

def print_player_condition():

    if hit_points < 4:
        print("Your eyes lose focus on the giant as you sway unsteadily.")
    elif hit_points < 8:
        print(
            """
            Your footing becomes less steady
            as you swing your sword sloppily.
            """
        )
    elif hit_points < 12:
        print(
            """
            Blood mixes with sweat on your face
            as you wipe it from your eyes.
            """
        )
    elif hit_points < 16:
        print("You bite down as the pain begins to make itself felt.")
    else:
        print("You charge into the fray valiantly!")

def end_game(victory: bool):
    if victory:
        adv.say(
            """
        The giant falls to his knees as the last of his strength flees
        his body. He takes one final swing at you, which you dodge easily.
        His momentum carries him forward, and he lands face down in the dirt.
        His final breath escapes his lips as he succumbs to your attack.

        You are victorious! Your name will be sung for generations!
        """
        )

    else:
        adv.say(
            """
        The giant's mighty fist connects with your head, and the last
        sound you hear are the bones in your neck crunching. You spin
        and tumble down, your sword clattering to the floor
        as the giant laughs.
        Your eyes see the giant step towards you, his mighty foot
        raised to crash down on you.
        Oblivion takes over before you experience anything else...

        You have been defeated! The giant is free to ravage your town!
        """
        )

    sys.exit()

@adv.when("flee", context="giant")
def flee():
    adv.say(
        """
    As you turn to run, the giant reaches out and catches your tunic.
    He lifts you off the ground, grabbing your dangling sword-arm
    as he does so. A quick twist, and your sword tumbles to the ground.
    Still holding you, he reaches his hand to your throat and squeezes,
    cutting off your air supply.

    The last sight you see before blackness takes you are
    the rotten teeth of the evil grin as the giant laughs
    at your puny attempt to stop him...

    You have been defeated! The giant is free to ravage your town!
    """
    )

    sys.exit()

@adv.when("goodbye")
@adv.when("bye")
@adv.when("adios")
@adv.when("later")
def goodbye():

    # Are you fighting the giant?
    if adv.get_context() == "giant":
        # Not so fast!
        print("The giant steps in front of you, blocking your exit!")

    else:
        # Close the current context
        adv.set_context(None)
        print("Fare thee well, traveler!")

# Define some basic commands
@adv.when("look")
def look():
    """Print the description of the current room.
    If you've already visited it, print a short description.
    """
    global current_room

    if not current_room.visited:
        adv.say(current_room)
        current_room.visited = True
    else:
        print(current_room.short_desc)

    # Are there any items here?
    for item in current_room.items:
        print(f"There is {item.description} here.")

@adv.when("describe")
def describe_room():
    """Print the full description of the room."""
    adv.say(current_room)

    # Are there any items here?
    for item in current_room.items:
        print(f"There is {item.description} here.")

# Define your movement commands
@adv.when("go DIRECTION")
@adv.when("north", direction="north")
@adv.when("south", direction="south")
@adv.when("east", direction="east")
@adv.when("west", direction="west")
@adv.when("n", direction="north")
@adv.when("s", direction="south")
@adv.when("e", direction="east")
@adv.when("w", direction="west")
def go(direction: str):
    """Processes your moving direction

    Arguments:
        direction {str} -- which direction does the player want to move
    """

    # What is your current room?
    global current_room

    # Is there an exit in that direction?
    next_room = current_room.exit(direction)
    if next_room:
        # Is the door locked?
        if (
            direction in current_room.locked_exits
            and current_room.locked_exits[direction]
        ):
            print(f"You can't go {direction} --- the door is locked.")
        else:
            # Clear the context if necessary
            current_context = adv.get_context()
            if current_context == "giant":
                adv.say(
                    """Your way is currently blocked.
                    Or have you forgotten the giant you are fighting?"""
                )
            else:
                if current_context:
                    print("Fare thee well, traveler!")
                    adv.set_context(None)

                current_room = next_room
                print(f"You go {direction}.")
                look()

    # No exit that way
    else:
        print(f"You can't go {direction}.")

# Define a prompt
def prompt():
    global current_room

    # Get possible exits
    exits_string = get_exits(current_room)

    # Are you in battle?
    if adv.get_context() == "giant":
        prompt_string = f"HP: {hit_points} > "
    else:
        prompt_string = f"({current_room.title}) > "

    return f"""({exits_string}) {prompt_string}"""

def no_command_matches(command: str):
    if adv.get_context() == "wizard.riddle":
        adv.say("That is not the correct answer. Begone!")
        adv.set_context(None)
        current_room.locked_exits["west"] = False
    else:
        print(f"What do you mean by '{command}'?")

def get_exits(room):
    exits = room.exits()

    exits_string = ""
    for exit in exits:
        exits_string += f"{exit[0].upper()}|"

    return exits_string[:-1]

# Start the game
if __name__ == "__main__":
    # No context is normal
    adv.set_context(None)

    # Set the prompt
    adv.prompt = prompt

    # What happens with unknown commands
    adv.no_command_matches = no_command_matches

    # Look at your starting room
    look()

    # Start the game
    adv.start()

Python
      
    
"""
Rooms for the adventurelib game
"""

# Import the library contents
import adventurelib as adv

# Import your items as well
import adventurelib_game_items

# And your characters
import adventurelib_game_characters

# Create a subclass of Rooms to track some custom properties
class GameArea(adv.Room):
    def __init__(self, description: str):

        super().__init__(description)

        # All areas can have locked exits
        self.locked_exits = {
            "north": False,
            "south": False,
            "east": False,
            "west": False,
        }
        # All areas can have items in them
        self.items = adv.Bag()

        # All areas can have characters in them
        self.characters = adv.Bag()

        # All areas may have been visited already
        # If so, you can print a shorter description
        self.visited = False

        # Which means each area needs a shorter description
        self.short_desc = ""

        # Each area also has a very short title for the prompt
        self.title = ""

# Your home
home = GameArea(
    """
You wake as the sun streams in through the single
window into your small room. You lie on your feather bed which
hugs the north wall, while the remains of last night's
fire smolders in the center of the room.

Remembering last night's discussion with the council, you
throw back your blanket and rise from your comfortable
bed. Cold water awaits you as you splash away the night's
sleep, grab an apple to eat, and prepare for the day.
"""
)
home.title = "Home"
home.short_desc = "This is your home."

# Hamlet
hamlet = GameArea(
    """
From the center of your small hamlet, you can see every other
home. It doesn't really even have an official name --- folks
around here just call it Home.

The council awaits you as you approach. Elder Barron beckons you
as you exit your home.
"""
)
hamlet.title = "Hamlet"
hamlet.short_desc = "You are in the hamlet."

# Fork in road
fork = GameArea(
    """
As you leave your hamlet, you think about how unprepared you
really are. Your lack of experience and pitiful equipment
are certainly no match for whatever has been stealing
the villages livestock.

As you travel, you come across a fork in the path. The path of
the livestock thief continues east. However, you know
the village of Dunhaven lies to the west, where you may
get some additional help.
"""
)
fork.title = "Fork in road"
fork.short_desc = "You are at a fork in the road."

# Village of Dunhaven
village = GameArea(
    """
A short trek up the well-worn path brings you the village
of Dunhaven. Larger than your humble Home, Dunhaven sits at
the end of a supply route from the capitol. As such, it has
amenities and capabilities not found in the smaller farming
communities.

As you approach, you hear the clang-clang of hammer on anvil,
and inhale the unmistakable smell of the coal-fed fire of a
blacksmith shop to your south.
"""
)
village.title = "Village of Dunhaven"
village.short_desc = "You are in the village of Dunhaven."

# Blacksmith shop
blacksmith_shop = GameArea(
    """
As you approach the blacksmith, the sounds of the hammer become
clearer and clearer. Passing the front door, you head towards
the sound of the blacksmith, and find her busy at the furnace.
"""
)
blacksmith_shop.title = "Blacksmith Shop"
blacksmith_shop.short_desc = "You are in the blacksmith shop."

# Side path away from fork
side_path = GameArea(
    """
The path leads away from the fork to Dunhaven. Fresh tracks of
something big, dragging something behind it, lead away to the south.
"""
)
side_path.title = "Side path"
side_path.short_desc = "You are standing on a side path."

# Wizard's Hut
wizard_hut = GameArea(
    """
The path opens into a shaded glen. A small stream wanders down the
hills to the east and past an unassuming hut. In front of the hut,
the local wizard Trent sits smoking a long clay pipe.
"""
)
wizard_hut.title = "Wizard's Hut"
wizard_hut.short_desc = "You are at the wizard's hut."

# Cave mouth
cave_mouth = GameArea(
    """
The path from Trent's hut follows the stream for a while before
turning south away from the water. The trees begin closing overhead,
blocking the sun and lending a chill to the air as you continue.

The path finally terminates at the opening of a large cave. The
tracks you have been following mix and mingle with others, both
coming and going, but all the same. Whatever has been stealing
your neighbor's livestock lives here, and comes and goes frequently.
"""
)
cave_mouth.title = "Cave Mouth"
cave_mouth.short_desc = "You are at the mouth of large cave."

# Cave of the Giant
giant_cave = GameArea(
    """
You take a few tentative steps into the cave. It feels much warmer
and more humid than the cold sunless forest air outside. A steady
drip of water from the rocks is the only sound for a while.

You begin to make out a faint light ahead. You hug the wall and
press on, as the light becomes brighter. You finally enter a
chamber at least 20 meters across, with a fire blazing in the center.
Cages line one wall, some empty, but others containing cows and
sheep stolen from you neighbors. Opposite them are piles of the bones
of the creatures unlucky enough to have already been devoured.

As you look around, you become aware of another presence in the room.
"""
)
giant_cave.title = "Cave of the Giant"
giant_cave.short_desc = "You are in the giant's cave."

# Set up the paths between areas
home.south = hamlet
hamlet.south = fork
fork.west = village
fork.east = side_path
village.south = blacksmith_shop
side_path.south = wizard_hut
wizard_hut.west = cave_mouth
cave_mouth.south = giant_cave

# Lock some exits, since you can't leave until something else happens
hamlet.locked_exits["south"] = True
wizard_hut.locked_exits["west"] = True

# Place items in different areas
# These are just for flavor
home.items.add(adventurelib_game_items.apple)
fork.items.add(adventurelib_game_items.cloak)
cave_mouth.items.add(adventurelib_game_items.slug)

# Place characters where they should be
hamlet.characters.add(adventurelib_game_characters.elder_barron)
blacksmith_shop.characters.add(adventurelib_game_characters.blacksmith)
wizard_hut.characters.add(adventurelib_game_characters.wizard_trent)
giant_cave.characters.add(adventurelib_game_characters.giant)

Python
      
    
"""
Items for the adventurelib Game
"""

# Import the adventurelib library
import adventurelib as adv

# All items have some basic properties
adv.Item.color = "undistinguished"
adv.Item.description = "a generic thing"
adv.Item.edible = False
adv.Item.wearable = False

# Create your "flavor" items
apple = adv.Item("small red apple", "apple")
apple.color = "red"
apple.description = "a small ripe red apple"
apple.edible = True
apple.wearable = False

cloak = adv.Item("wool cloak", "cloak")
cloak.color = "grey tweed"
cloak.description = (
    "a grey tweed cloak, heavy enough to keep the wind and rain at bay"
)
cloak.edible = False
cloak.wearable = True

slug = adv.Item("slimy brown slug", "slug")
slug.color = "slimy brown"
slug.description = "a fat, slimy, brown slug"
slug.edible = True
slug.wearable = False

# Create the real items you need
wooden_sword = adv.Item("wooden sword", "sword")
wooden_sword.color = "brown"
wooden_sword.description = (
    "a small wooden practice sword, not even sharp enough to cut milk"
)
wooden_sword.edible = False
wooden_sword.wearable = False
wooden_sword.damage = 4
wooden_sword.bonus = 0

steel_sword = adv.Item("steel sword", "sword")
steel_sword.color = "steely grey"
steel_sword.description = (
    "a finely made steel sword, honed to a razor edge, ready for blood"
)
steel_sword.edible = False
steel_sword.wearable = False
steel_sword.damage = 10
steel_sword.bonus = 0

Python
      
    
"""
Characters for the adventurelib Game
"""

# Import the adventurelib library
import adventurelib as adv

# All characters have some properties
adv.Item.greeting = ""
adv.Item.context = ""

# Your characters
elder_barron = adv.Item("Elder Barron", "elder", "barron")
elder_barron.description = """Elder Barron, a tall distinguished member
of the community. His steely grey hair and stiff beard inspire confidence."""
elder_barron.greeting = (
    "I have some information for you. Would you like to hear it?"
)
elder_barron.context = "elder"

blacksmith = adv.Item("Alanna Smith", "Alanna", "blacksmith", "smith")
blacksmith.description = """Alanna the blacksmith stands just 1.5m tall,
and her strength lies in her arms and heart"""
blacksmith.greeting = (
    "Oh, hi! I've got some stuff for sale. Do you want to see it?"
)
blacksmith.context = "blacksmith"

wizard_trent = adv.Item("Trent the Wizard", "Trent", "wizard")
wizard_trent.description = """Trent's wizardly studies have apparently
aged him past his years, but they have also preserved his life longer than
expected."""
wizard_trent.greeting = (
    "It's been a long time since I've had a visitor? Do you seek wisdom?"
)
wizard_trent.context = "wizard"

giant = adv.Item("hungry giant", "giant")
giant.description = """Almost four meters of hulking brutish strength
stands before you, his breath rank with rotten meat, his mangy hair
tangled and matted"""
giant.greeting = "Argh! Who dares invade my home? Prepare to defend yourself!"
giant.context = "giant"

You can start this game with the following command:

Shell
      
(venv) $ python adventurelib/adventurelib_game.py

After defining the backstory, you mapped out the different game areas and the paths which the player uses move between them:

Each area has various properties associated with it, including:

Items and characters that are in that area
Some exits that are locked
A title, a short description, and a longer description
An indication of whether the player has been in this area or not

To ensure that each area has its own instance of each of these properties, you create a subclass of Room called GameArea in adventurelib_game_rooms.py on lines 15 to 41. Items in each room are held in a Bag object called items, while characters are stored in characters, defined on lines 28 and 31. Now you can create GameArea objects, describe them, and populate them with unique items and characters, which are all imported on lines 9 and 12.

Some game items are required to finish the game, while others are just there for flavor and to add interest. Flavor items are identified and placed on lines 192 to 194, followed by characters on lines 197 to 200.

All of your game items are defined in adventurelib_game_items.py as objects of type Item(). Game items have properties that define them, but because you’ve used the Item base class, some basic universal properties are added to the class on lines 9 to 12. These properties are used when the item is created. For example, the apple object is created on lines 15 to 19 and defines each of the universal properties when it is created.

Some items, however, have specific properties unique to the item. For example, the wooden_sword and steel_sword items need properties to track the damage they do and any magical bonuses they carry. Those are added on lines 43 to 44 and 53 to 54.

Interacting with characters helps drive the game story forward and often gives the player a reason to explore. Characters in adventurelib are created as Item objects, and for this game are defined in adventurelib_game_characters.py.

Each character, like each item, has universal properties associated with it, such as a long description and the greeting used when the player encounters it for the first time. These properties are declared on lines 9 and 10, and they’re defined for each character when the character is created.

Of course, if you have characters, then it makes sense for the player to talk to and interact with them. It’s often a good idea to know when you’re interacting with a character, and when you’re just in the same game area with one.

This is done by using an adventurelib concept called a context. Contexts allow you to turn on different commands for different situations. They also allow certain commands to behave differently, and they track additional information about actions that the player may have taken.

When the game starts, there’s no context set. As the player progresses, they first encounter Elder Barron. When the player types "talk to elder", the context is set to elder.context, which in this case is elder.

Elder Barron’s greeting ends with a yes or no question to the player. If the player types "yes", then the command handler on line 173 in adventurelib_game.py is triggered, which is defined as @when("yes", context="elder"), as shown below:

Later, when the player is talking to the blacksmith, a second level of context is added to reflect that they’re engaged in a possible weapon trade. Lines 203 to 233 define the discussion with the blacksmith, which includes the offer of a weapons trade. A new context is defined on line 222, which allows the same "yes" command to be used elegantly in multiple ways.

You can also check the context in a command handler. For example, the player cannot simply leave the fight with the giant by ending the conversation. The "goodbye" command handler defined on lines 389 to 403 checks if the player is in the "giant" context, which is entered when they start fighting the giant. If so, they’re not allowed to stop the conversation — it’s a fight to the death!

You can also ask questions of the player requiring a specific answer. When the player talks to the wizard Trent, they’re asked to solve a riddle. An incorrect answer will end the interaction. While the correct answer is handled with the command handler on lines 252 to 262, one of the nearly infinite wrong answers won’t match any handler.

Commands with no matches are handled by the no_command_matches() function on lines 497 to 503. You leverage this to handle incorrect answers to the wizard’s riddle by checking for the wizard.riddle context on line 498. Any incorrect answer to the riddle will result in the wizard ending the conversation. You connect this to adventurelib on line 523 by setting adventurelib.no_command_matches to your new function.

You can customize the prompt shown to the player by writing a function that returns the new prompt. Your new prompt is defined on lines 483 to 495 and connected to adventurelib on line 520.

Of course, there’s always more that you could add. Creating a complete text adventure game is challenging, and adventurelib makes sure the the main challenge lies in painting a picture with words.

Remove ads

Ren’Py

The modern descendant of the pure text adventure is the visual novel, which highlights the storytelling aspect of the game, limiting player interactions while adding visuals and sound to heighten the experience. Visual novels are the graphic novels of the game world — modern, innovative, and extremely compelling to create and consume.

Ren’Py is a tool based on Pygame and designed specifically to create visual novels. Ren’Py takes its name from the Japanese word for romantic love and provides tools and a framework for crafting compelling visual novels.

To be fair, Ren’Py is not strictly a Python library that you can pip install and use. Ren’Py games are created using the Ren’Py Launcher, which comes with the full Ren’Py SDK. This launcher also features a game editor, although you can edit your game in your editor of choice. Ren’Py also features its own scripting language for game creation. However, Ren’Py is based on Pygame, and it’s extendable using Python, which warrants its appearance here.

Ren’Py Installation

As mentioned, Ren’Py requires not only the SDK, but also the Ren’Py Launcher. These are packaged together in a single unit, which you need to download.

Knowing which package to download and how to install it depends on your platform. Ren’Py provides installers and instructions for Windows, macOS, and Linux users:

After the package is installed, you can navigate to the folder containing the SDK then run the Ren’Py Launcher. Windows users should use renpy.exe, while macOS and Linux users should run renpy.sh. This will start the Ren’Py Launcher for the first time:

This is where you’ll start new Ren’Py projects, work on existing projects, and set overall preferences for Ren’Py.

Basic Concepts

Ren’Py games start as new projects in the Ren’Py Launcher. Creating one will set up the proper file and folder structure for a Ren’Py game. After the project is set up, you can use your own editor to write your game, although the Ren’Py Launcher is required to run the game:

Ren’Py games are contained in files called scripts. Don’t think of Ren’Py scripts as you would shell scripts. They’re more analogous to scripts for plays or television shows. Ren’Py scripts have the extension .rpy and are written in the Ren’Py language. Your game can consist of as many scripts as you like, which are all stored in the game/ subfolder of your project folder.

When you create a new Ren’Py project, the following scripts are created for you to use and update:

gui.rpy, which defines the look of all UI elements used in your game
options.rpy, which defines changeable options to customize your game
screens.rpy, which defines the styles used for dialogue, menus, and other game output
script.rpy, which is where you start writing your game

To run the sample games from the downloaded materials for this tutorial, you’ll use the following process:

Start the Ren’Py Launcher.
Click Preferences, then Projects Directory.
Change the Projects Directory to the renpy folder in the repository that you downloaded.
Click Return to return to the main Ren’Py Launcher page.

You’ll see basic_game and giant_quest_game in the Projects list on the left. Select the one that you wish to run, then click Launch Project.

For this example, you’ll only modify the script.rpy file for basic_game. The complete code for this game can be found in the downloaded materials, as well as below:

Text

 1# The script of the game goes in this file.
 2
 3# Declare characters used by this game. The color argument colorizes the
 4# name of the character.
 5
 6define kevin = Character("Kevin", color="#c8ffc8")
 7define mom = Character("Mom", color="#c8ffff")
 8define me = Character("Me", color="#c8c8ff")
 9
10# The game starts here.
11
12label start:
13
14    # Some basic narration to start the game
15
16    "You hear your alarm going off, and your mother calling to you."
17
18    mom "It's time to wake up. If I can hear your alarm,
19    you can hear it to - let's go!"
20
21    "Reluctantly you open your eyes."
22
23    # Show a background.
24
25    scene bedroom day
26
27    # This shows the basic narration
28
29    "You awaken in your bedroom after a good night's rest. 
30    Laying there sleepily, your eyes wander to the clock on your phone."
31
32    me "Yoinks! I'm gonna be late!"
33
34    "You leap out of bed and quickly put on some clothes.
35    Grabbing your book bag, you sprint for the door to the living room."
36
37    scene hallway day
38
39    "Your brother is waiting for you in the hall."
40
41    show kevin normal
42
43    kevin "Let's go, loser! We're gonna be late!"
44
45    mom "Got everything, honey?"
46
47    menu:
48        "Yes, I've got everything.":
49            jump follow_kevin
50
51        "Wait, I forgot my phone!":
52            jump check_room
53
54label check_room:
55
56    me "Wait! My phone!"
57
58    kevin "Whatever. See you outside!"
59
60    "You sprint back to your room to get your phone."
61
62    scene bedroom day
63
64    "You grab the phone from the nightstand and sprint back to the hall."
65
66    scene hallway day
67
68    "True to his word, Kevin is already outside."
69
70    jump outside
71
72label follow_kevin:
73
74    kevin "Then let's go!"
75
76    "You follow Kevin out to the street."
77
78label outside:
79
80    scene street
81
82    show kevin normal
83
84    kevin "About time you got here. Let's Go!"
85
86    # This ends the game
87    return

Labels define entry points into your story, and are often used to start new scenes and provide alternate paths through the story. All Ren’Py games start running at the line label start:, which can appear in any script you choose. You can see this on line 12 of script.rpy.

You can also use labels to define background images, set up transitions between scenes, and control the appearance of characters. In the sample, a second scene starts on line 54 with the line label check_room:.

Text enclosed in double-quotes on a line is called a say statement. A single string on a line is treated as narration. Two strings get treated as dialogue, identifying a character first and then providing the line that they’re speaking.

At the beginning of the game, narration is seen on line 16, which sets the scene. Dialogue is provided on line 18, when your mom calls to you.

You can define characters by simply naming them in the story. However, you can also define characters at the top of your script. You can see this on lines 6 to 8, where you, your brother Kevin, and your mom are defined. The define statement initializes the three variables as Characters, giving them a display name, followed by a text color used to display the name.

Of course, this is a visual novel, so it makes sense that Ren’Py would have a way to handle images. Like Pygame Zero, Ren’Py requires that all images and sounds used in the game reside in specific folders. Images are found in the game/images/ folder, and sounds are in the game/audio/ folder. In the game script, you refer to them by filename without any file extension.

Line 25 shows this in action, when you open your eyes and see your bedroom for the first time. The scene keyword clears the screen, then displays the bedroom day.png image. Ren’Py supports the JPG, WEBP, and PNG image formats.

You can also display characters on the screen using the show keyword and the same naming convention for the image. Line 41 shows a picture of your brother Kevin, stored as kevin normal.png.

Of course, it’s not much of a game if you can’t make decisions to affect the outcome. In Ren’Py, players make choices from a menu presented to them in the course of the game. The game reacts by jumping to predefined labels, changing character images, playing sounds, or taking other actions as necessary.

A basic choice in this sample is shown on lines 47 to 52, where you realize you’ve forgotten your phone. In a more complete story, this choice may have consequences later.

Of course, you can do much more with Ren’Py. You can control transitions between scenes, have characters enter and leave scenes in specific ways, and include sound and music for your game. Ren’Py also supports writing more complex Python code, including using Python data types and making direct Python function calls. Now take a closer look at these capabilities in a more advanced application.

Remove ads

Advanced Application

To show the depth of Ren’Py, you’ll implement the same game as you did for adventurelib. As a reminder, here’s the basic design of that game:

You live in a small, quiet hamlet.
Recently, your neighbors have begun complaining of missing livestock.
As a member of a night patrol, you notice a broken fence and a trail leading away from it.
You decide to investigate, armed only with a wooden practice sword.

The game has several areas to define and provide images for. For example, you’ll need images and definitions for your small, quiet hamlet, the trail leading away from the field, a nearby village where you can buy a better weapon, a side path leading to a wizard who can enchant your weapon, and the cave containing the giant who has been taking your livestock.

There are also a few characters to define and provide images for. You need a blacksmith who can give you a better weapon, a wizard who can enchant your weapon, and the giant whom you need to defeat.

For this example, you’ll create four separate scripts:

script.rpy, which is where the game starts
town.rpy, which contains the story of the nearby village
path.rpy, which contains the path between villages
giant.rpy, which contains the logic for the giant battle

You can create the wizard encounter as an independent exercise.

The complete code for this game can be found in the downloaded materials at renpy_sample/giant_quest/ and is also available below:

Text

 1#
 2# Complete game in Ren'Py
 3# 
 4# This game demonstrates some of the more advanced features of
 5# Ren'Py, including:
 6# - Multiple sprites
 7# - Handling user input
 8# - Selecting alternate outcomes
 9# - Tracking score and inventory
10# 
11
12## Declare characters used by this game. The color argument colorizes the
13## name of the character.
14define player = Character("Me", color="#c8ffff")
15define smith = Character("Miranda, village blacksmith", color="#99ff9c")
16define wizard = Character("Endeavor, cryptic wizard", color="#f4d3ff")
17define giant = Character("Maull, terrifying giant", color="#ff8c8c")
18
19## Images used in the game
20# Backgrounds
21image starting path = "BG10a_1280.jpg"
22image crossroads = "BG19a01_1280.jpg"
23
24# Items
25image wooden sword = "SwordWood.png"
26image steel sword = "Sword.png"
27image enchanted sword = "SwordT2.png"
28
29## Default settings
30# What is the current weapon?
31default current_weapon = "wooden sword"
32
33# What is the weapon damage?
34# These change when the weapon is upgraded or enchanted
35default base_damage = 4
36default multiplier = 1
37default additional = 0
38
39# Did they cross the bridge to town?
40default cross_bridge = False
41
42# You need this for the giant battle later
43
44init python:
45    from random import randint
46
47# The game starts here.
48
49label start:
50
51    # Show the initial background.
52
53    scene starting path
54    with fade
55
56    # Begin narration
57
58    "Growing up in a small hamlet was boring, but reliable and safe. 
59    At least, it was until the neighbors began complaining of missing
60    livestock. That's when the evening patrols began."
61
62    "While on patrol just before dawn, your group noticed broken fence
63    around a cattle paddock. Beyond the broken fence,
64    a crude trail had been blazed to a road leading away from town."
65
66    # Show the current weapon
67    show expression current_weapon at left
68    with moveinleft
69
70    "After reporting back to the town council, it was decided that you
71    should follow the tracks to discover the fate of the livestock.
72    You picked up your only weapon, a simple wooden practice sword,
73    and set off."
74
75    scene crossroads
76    with fade
77
78    show expression current_weapon at left
79
80    "Following the path, you come to a bridge across the river."
81
82    "Crossing the bridge will take you to the county seat,
83    where you may hear some news or get supplies.
84    The tracks, however, continue straight on the path."
85
86    menu optional_name:
87        "Which direction will you travel?"
88
89        "Cross the bridge":
90            $ cross_bridge = True
91            jump town
92        "Continue on the path":
93            jump path
94
95    "Your quest is ended!"
96
97    return

Text

  1##
  2## Code for the interactions in town
  3##
  4
  5## Backgrounds
  6image distant town = "4_road_a.jpg"
  7image within town = "3_blacksmith_a.jpg"
  8
  9# Characters
 10image blacksmith greeting = "blacksmith1.png"
 11image blacksmith confused = "blacksmith2.png"
 12image blacksmith happy = "blacksmith3.png"
 13image blacksmith shocked = "blacksmith4.png"
 14
 15label town:
 16
 17    scene distant town
 18    with fade
 19
 20    show expression current_weapon at left
 21
 22    "Crossing the bridge, you stride away from the river along a
 23    well worn path. The way is pleasant, and you find yourself humming
 24    a tune as you break into a small clearing."
 25
 26    "From here, you can make out the county seat of Fetheron.
 27    You feel confident you can find help for your quest here."
 28
 29    scene within town
 30    with fade
 31
 32    show expression current_weapon at left
 33
 34    "As you enter town, you immediately begin seeking the local blacksmith.
 35    After asking one of the townsfolk, you find the smithy on the far
 36    south end of town. You approach the smithy,
 37    smelling the smoke of the furnace long before you hear
 38    the pounding of hammer on steel."
 39
 40    player "Hello! Is the smith in?"
 41
 42    smith "Who wants to know?"
 43
 44    show blacksmith greeting
 45
 46    "The blacksmith appears from her bellows.
 47    She greets you with a warm smile."
 48
 49    smith "Oh, hello! You're from the next town over, right?"
 50
 51    menu:
 52        "Yes, from the other side of the river.":
 53            show blacksmith happy
 54
 55            smith "I thought I recognized you. Nice to see you!"
 56
 57        "Look, I don't have time for pleasantries, can we get to business?":
 58            show blacksmith shocked
 59
 60            smith "Hey, just trying to make conversation"
 61
 62    smith "So, what can I do for you?"
 63
 64    player "I need a better weapon than this wooden thing."
 65
 66    show blacksmith confused
 67
 68    smith "Are you going to be doing something dangerous?"
 69
 70    player "Have you heard about the missing livestock in town?"
 71
 72    smith "Of course. Everyone has. What do you know about it?"
 73
 74    player "Well, I'm tracking whatever took them from our town."
 75
 76    smith "Oh, I see. So you want something better to fight with!"
 77
 78    player "Exactly! Can you help?"
 79
 80    smith "I've got just the thing. Been working on it for a while,
 81    but didn't know what to do with it. Now I know."
 82
 83    "Miranda walks back past the furnace to a small rack.
 84    On it, a gleaming steel sword rests.
 85    She picks it up and walks back to you."
 86
 87    smith "Will this do?"
 88
 89    menu:
 90        "It's perfect!":
 91            show blacksmith happy
 92
 93            smith "Wonderful! Give me the wooden one -
 94            I can use it in the furnace!"
 95
 96            $ current_weapon = "steel sword"
 97            $ base_damage = 6
 98            $ multiplier = 2
 99
100        "Is that piece of junk it?":
101            show blacksmith confused
102
103            smith "I worked on this for weeks.
104            If you don't want it, then don't take it."
105
106    # Show the current weapon
107    show expression current_weapon at left
108
109    smith "Anything else?"
110
111    player "Nope, that's all."
112
113    smith "Alright. Good luck!"
114
115    scene distant town
116    with fade
117
118    show expression current_weapon at left
119
120    "You make your way back through town.
121    Glancing back at the town, you wonder if
122    you can keep them safe too."
123
124    jump path

Text

 1##
 2## Code for the interactions in town
 3##
 4
 5## Backgrounds
 6image path = "1_forest_a.jpg"
 7image wizard hut = "BG600a_1280.jpg"
 8
 9# Characters
10image wizard greeting = "wizard1.png"
11image wizard happy = "wizard2.png"
12image wizard confused = "wizard3.png"
13image wizard shocked = "wizard4.png"
14
15label path:
16
17    scene path
18    with fade
19
20    show expression current_weapon at left
21
22    "You pick up the tracks as you follow the path through the woods."
23
24    jump giant_battle

Text

  1##
  2## Code for the giant battle
  3##
  4
  5## Backgrounds
  6image forest = "forest_hill_night.jpg"
  7
  8# Characters
  9image giant greeting = "giant1.png"
 10image giant unhappy = "giant2.png"
 11image giant angry = "giant3.png"
 12image giant hurt = "giant4.png"
 13
 14# Text of the giant encounter
 15label giant_battle:
 16
 17    scene forest
 18    with fade
 19
 20    show expression current_weapon at left
 21
 22    "As you follow the tracks down the path, night falls.
 23    You hear sounds in the distance:
 24    cows, goats, sheep. You've found the livestock!"
 25
 26    show giant greeting
 27
 28    "As you approach the clearing and see your villages livestock,
 29    a giant appears."
 30
 31    giant "Who are you?"
 32
 33    player "I've come to get our livestock back."
 34
 35    giant "You and which army, little ... whatever you are?"
 36
 37    show giant unhappy
 38
 39    "The giant bears down on you - the battle is joined!"
 40
 41python:
 42
 43    def show_giant_condition(giant_hp):
 44        if giant_hp < 10:
 45            renpy.say(None, "The giant staggers, his eyes unfocused.")
 46        elif giant_hp < 20:
 47            renpy.say(None, "The giant's steps become more unsteady.")
 48        elif giant_hp < 30:
 49            renpy.say(
 50                None, "The giant sweats and wipes the blood from his brow."
 51            )
 52        elif giant_hp < 40:
 53            renpy.say(
 54                None,
 55                "The giant snorts and grits his teeth against the pain.",
 56            )
 57        else:
 58            renpy.say(
 59                None,
 60                "The giant smiles and readies himself for the attack.",
 61            )
 62
 63    def show_player_condition(player_hp):
 64        if player_hp < 4:
 65            renpy.say(
 66                None,
 67                "Your eyes lose focus on the giant as you sway unsteadily.",
 68            )
 69        elif player_hp < 8:
 70            renpy.say(
 71                None,
 72                "Your footing becomes less steady as you swing your sword sloppily.",
 73            )
 74        elif player_hp < 12:
 75            renpy.say(
 76                None,
 77                "Blood mixes with sweat on your face as you wipe it from your eyes.",
 78            )
 79        elif player_hp < 16:
 80            renpy.say(
 81                None,
 82                "You bite down as the pain begins to make itself felt.",
 83            )
 84        else:
 85            renpy.say(None, "You charge into the fray valiantly!")
 86
 87    def fight_giant():
 88
 89        # Default values
 90        giant_hp = 50
 91        player_hp = 20
 92        giant_damage = 4
 93
 94        battle_over = False
 95        player_wins = False
 96
 97        # Keep swinging until something happens
 98        while not battle_over:
 99
100            renpy.say(
101                None,
102                "You have {0} hit points. Do you want to fight or flee?".format(
103                    player_hp
104                ),
105                interact=False,
106            )
107            battle_over = renpy.display_menu(
108                [("Fight!", False), ("Flee!", True)]
109            )
110
111            if battle_over:
112                player_wins = False
113                break
114
115            # The player gets a swing
116            player_attack = (
117                randint(1, base_damage + 1) * multiplier + additional
118            )
119            renpy.say(
120                None,
121                "You swing your {0}, doing {1} damage!".format(
122                    current_weapon, player_attack
123                ),
124            )
125            giant_hp -= player_attack
126
127            # Is the giant dead?
128            if giant_hp <= 0:
129                battle_over = True
130                player_wins = True
131                break
132
133            show_giant_condition(giant_hp)
134
135            # Then the giant tries
136            giant_attack = randint(0, giant_damage)
137            if giant_attack == 0:
138                renpy.say(
139                    None,
140                    "The giant's arm whistles harmlessly over your head!",
141                )
142            else:
143                renpy.say(
144                    None,
145                    "The giant swings his mighty fist, and does {0} damage!".format(
146                        giant_attack
147                    ),
148                )
149                player_hp -= giant_attack
150
151            # Is the player dead?
152            if player_hp <= 0:
153                battle_over = True
154                player_wins = False
155
156            show_player_condition(player_hp)
157
158        # Return who died
159        return player_wins
160
161    # fight_giant returns True if the player wins.
162    if fight_giant():
163        renpy.jump("player_wins")
164    else:
165        renpy.jump("giant_wins")
166
167label player_wins:
168
169    "The giant's eyes glaze over as he falls heavily to the ground.
170    The earth shakes as his bulk lands face down,
171    and his death rattle fills the air."
172
173    hide giant
174
175    "You are victorious! The land is safe from the giant!"
176
177    return
178
179label giant_wins:
180
181    "The giant takes one last swing, knocking you down.
182    Your vision clouds, and you see the ground rising to meet you.
183    As you slowly lose consciousness, your last vision is
184    the smiling figure of the giant as he advances on you."
185
186    "You have lost!"
187
188    return

As in the previous example, you define Character() objects before the script begins on lines 14 to 17 of script.rpy.

You can also define background or character image objects for later use. Lines 21 to 27 define several images which you refer to later, both to use as backgrounds and to display as items. Using this syntax allows you to assign shorter and more descriptive internal names for images. Later, you’ll see how they’re displayed.

You also need to track the capabilities of the equipped weapon. This is done on lines 31 to 37, using default variable values, which you’ll use during the giant battle later.

To indicate which weapon is enabled, you show the image as an expression. Ren’Py expressions are small images displayed in the corners of the game window and are used to show a wide variety of information. For this game, you use an expression to show the weapon using show expression first on lines 67 and 68.

The show command has a number of modifiers documented. The with moveinleft modifier causes the current_weapon image to slide onto the screen from the left. Also, it’s important to remember that every time scene changes, the entire screen is cleared, requiring you to show the current weapon again. You can see that on lines 75 to 78.

When you enter the town in town.rpy, you meet the blacksmith, who greets you:

The blacksmith offers you the opportunity to upgrade your weapon. If you choose to do so, then you update the values for current_weapon and the weapon stats. This is done on lines 93 to 98.

Lines that begin with the $ character are interpreted by Ren’Py as Python statements, allowing you to write arbitrary Python code as necessary. Updating the current_weapon and weapon stats is done using three Python statements on lines 96 to 98, which change the values of the the default variables that you defined at the top of script.rpy.

You can also define a large block of Python code using a python: section, as shown in giant.rpy starting on line 41.

Lines 43 to 61 contain a helper function to show the condition of the giant, based on the giant’s remaining hit points. It uses the renpy.say() method to output narration back to the main Ren’Py window. A similar helper function to show the player’s condition is seen on lines 63 to 85.

The battle is controlled by fight_giant() on lines 87 to 159. The game loop is implemented on line 98 and is controlled by the battle_over variable. Player choices of fight or flee are displayed using the renpy.display_menu() method.

If the player fights, then a random amount of damage is done on lines 116 to 118, and the giant’s hit points are adjusted. If the giant is still alive, then they get to attack in a similar fashion on lines 136 to 149. Note that the giant has a chance to miss, while the player always hits. The fight continues either until the player or the giant has zero hit points or until the player flees:

It’s important note that this code is very similar to the code that you used in the adventurelib battle. This shows how you can drop full Python code into your Ren’Py games without needing to translate it into Ren’Py script.

There’s much more to Ren’Py than what you’ve tried out here. Consult the Ren’Py documentation for more complete details.

Remove ads

Other Notable Python Game Engines

These five engines are only a small sampling of the many different Python game engines available. There are dozens of others available, and a few are worth noting here:

Wasabi 2D is developed by the team behind Pygame Zero. It’s a modern framework built on moderngl that automates rendering, provides coroutines for animation effects, has built-in particle effects, and uses an event-driven model for game play.
cocos2d is a framework designed for coding cross-platform games. Sadly, cocos2d-python hasn’t been updated since 2017.
Panda 3D is an open-source framework for creating 3D games and 3D renderings. Panda 3D is portable across platforms, supports multiple asset types, connects out of the box with numerous third-party libraries, and provides built-in pipeline profiling.
Ursina is built on top of Panda 3D and provides a dedicated game development engine that simplifies many aspects of Panda 3D. Well supported and well documented, Ursina is under active development at the time of this writing.
PursuedPyBear is billed as an educational library. It boasts a scene management system, frame-based animated sprites which can be paused, and a low barrier to entry. Documentation is sparse, but help is only a GitHub discussion away.

New Python game engines are created every day. If you find one that suits your needs and wasn’t mentioned here, please sing its praises in the comments!

Sources for Game Assets

Often, creating game assets is the biggest issue facing game authors. Large video game companies employ teams of artists, animators, and musicians to design the look and sound of their games. Solo game developers with a background in coding may find this aspect of game development daunting. Luckily, there are many different sources for game assets available. Here are some that were vital in locating assets for the games in this tutorial:

OpenGameArt.org hosts a wide variety of game art, music, backgrounds, icons, and other assets for both 2D and 3D games. Artists and musicians list their assets for download, which you can download and use in your games. Most assets are freely available, and licensing terms may apply to many of them.
Kenney.nl hosts a set of free and paid assets, many of which can be found nowhere else. Donations are always welcome to support the free assets, which are all licensed for use in commercial games.
Itch.io is a marketplace for digital creators focused on independent game development. Here you can find digital assets for just about any purpose, both free and paid, along with complete games. Individual creators control their own content here, so you’re always working directly with talented individuals.

Most assets available from third-parties carry licensing terms dictating the proper and allowable use of the assets. As the user of these assets, it’s your responsibility to read, understand, and comply with the licensing terms as defined by the asset owner. If you have questions or concerns about those terms, please consult a legal professional for assistance.

All of the assets used in the games referenced in this article conform to their respective licensing requirements.

Conclusion

Congratulations, great game design is now within your reach! Thanks to Python and a buffet of highly capable Python game engines, you can create quality computer games much more easily than before. In this tutorial, you’ve explored several such game engines, learning the information that you need to start crafting your own Python video games!

By now, you’ve seen some of the top Python game engines in action, and you’ve:

Explored the pros and cons of several popular Python game engines
Experienced how they compare to stand-alone game engines
Learned about other Python game engines available

If you’d like to review the code for the games in this tutorial, you can do so by clicking the link below:

Get Source Code: Click here to get the source code you’ll use to try out Python game engines.

Now you can choose the best Python game engine for your purpose. So what are you waiting for? Get out there and write some games!

What Do You Think?

Rate this article:

What’s your #1 takeaway or favorite thing you learned? How are you going to put your newfound skills to use? Leave a comment below and let us know.

Commenting Tips: The most useful comments are those written with the goal of learning from or helping out other students. Get tips for asking good questions and get answers to common questions in our support portal.

Looking for a real-time conversation? Visit the Real Python Community Chat or join the next “Office Hours” Live Q&A Session. Happy Pythoning!