PyBadge Face Invaders

Face Invaders is an arcade game built for the Adafruit PyBadge, which features personalized 'face' objects that the player can dodge and destroy.

The game recreates the arcade classic Asteroids, giving players control over a physics-based ship to thrust, turn, and shoot. The goal is to earn a high score by eliminating waves of incoming objects that destroy the ship on contact.

For a fun experience, the typical asteroid game sprites are replaced with custom-created face sprites. This adds a playful twist to the gameplay, as players are now maneuvering around the floating faces of friends, family, or even themselves.

Additional Face Invaders features include:

• Frame Rate Optimization - Time-based movement calculations are used to update object positions each frame, providing consistent movement speeds regardless of frame processing time.
• High Score System - After earning a new high score, players are prompted to enter their initials to be added to the high scores list. These scores are saved and persist between games.
• Pixel-based Hit Detection - Collisions between the ship, bullets, and faces are calculated on a per-pixel basis (as opposed to hitboxes) to ensure accurate hits between objects.
• Brightness and Volume Control - Users can alter the brightness of the display and volume of the speakers within the game's Options menu.
• Sound Effects - Retro arcade sound effects are played for thrusting, shooting, collisions, and more.

The game is coded with CircuitPython and desigend to run on the Adafruit PyBadge or PyBadge LC.

Game graphics are drawn on the PyBadge's 1.8" display, and sounds are played from the board's onboard or connected speaker. Each of the eight input buttons are used to control the game's ship or navigate menus.

Setup Instructions

Below are instructions for installing and running Face Invaders on the Adafruit PyBadge. These instructions assume working knowledge of PyBadge hardware, CircuitPython, and the image-editing software GIMP.

Board Configuration

The PyBadge must first be configured with the correct version of CircuitPython and required libraries to execute the game's CircuitPython code.

1. Connect the PyBadge to a computer via a USB cable.

This connection powers the board and opens file access to the PyBadge's onboard storage drive, listed as CIRCUITPYTHON on the connected computer.

2. Install CircuitPython version 10.x

While multiple versions of CircuitPython exist, this project requires the features available in version 10.x or higher.

Follow the CircuitPython Installation Guide to download and install version 10.x (currently available as the latest development release) on the PyBadge.

3. Install the required libraries

For the project code to perform complex actions like loading images or controlling audio, it requires additional code from several Adafruit libraries.

Follow the CircuitPython Libraries Guide to install the following libraries from the Adafruit CircuitPython Library Bundle (version 10.x) into the lib directory on the CIRCUITPYTHON drive:

• adafruit_display_shapes/
• adafruit_display_text/
• adafruit_imageload/
• neopixel.mpy

With these steps complete, the PyBadge is properly configured to run the Face Invaders game code and is ready for the game to be installed.

Game Installation

To install Face Invaders, its game files (CircuitPython scripts, image sprites, and audio files) must be downloaded and copied onto the PyBadge.

1. Browse to the Face Invaders GitHub repository. Click "Code", then "Download ZIP", and unzip the downloaded pybadge-face-invaders-main.zip file.

2. From the unzipped directory, copy the following files and subdirectory into the CIRCUITPYTHON drive:

• boot.py
• code.py
• face_invaders/

On board startup, boot.py executes and enables write permission on the PyBadge's drive, which is required for saving the game's high scores.

When the board resets (including on startup), code.py executes to launch the game and run the main processing loop that handles player inputs, advances the game, and updates the display.

All game code and assets are stored in the face_invaders/ directory. These files build the game's visual graphics and audio effects, calculate object positions and interactions, and update the game state.

3. Reset the PyBadge by powering it off and on or pressing the RESET button.

This power cycling or hard reset is required to ensure the boot.py script executes prior to playing the game.

After completing the installation steps, the default version of Face Invaders is now playable on the PyBadge.

This version includes all the gameplay features, but uses placeholder sprites as the floating faces that the player interacts with.

Create Personalized Sprites

Add personalized faces to the game by replacing the default face sprites stored in the Face Invaders game files.

New sprites must be created that are cropped and centered on a subject's face, and match the required format. Copying these sprites onto the PyBadge to overwrite the existing ones will automatically include them in the game.

1. Open the reference image in GIMP

With GIMP open, click File -> Open and select an image that features the personalized subject's face.

2. Crop the image

Within the tools, click the Rectangle Select tool. Check the Fixed option, and select Aspect Ratio from the dropdown. Enter 1:1.2 as the ratio value.

Drag a rectangular selection around the face within the image, resizing and positioning it to tightly border the top and bottom of the face.

Click Image -> Crop to Selection to crop the image to just the face.

3. Isolate the face

Erase any background image content and isolate the face against a black backdrop. This creates a dark border for the sprite that will blend into the game's space environment.

From the menu, select Layer -> Transparency -> Add Alpha Channel to add a transparent channel to the image.

Next, click the Color Picker and select Black as the foreground color. Select Layer -> New Layer, and for Fill select Foreground Color. Click OK.

Within the Layers menu, select the newly created layer and drag it below the face image layer, then re-select the face image layer.

From the tools, select the Eraser Tool and carefully erase all of the image content surrounding the face, exposing the black background underneath.

Finally, select Layer -> Merge Down from the menu to combine the image and background layers into a single layer.

4. Duplicate the image

Create a duplicate of the isolated face image by selecting Image -> Duplicate from the menu.

A virtual copy of the image and its layers is opened in a new tab, allowing for edits to be made to this copy while preserving the original for later use.

5. Resize the image

Working in the duplicated image tab, resize the image to the game's required dimensions by selecting Image -> ScaleImage from the menu.

Set the Width value to 40 and the Height value to 48, and click Scale.

6. Format Image Colors

Create a transparency key by setting the image background to a unique color and positioning it first within the image colormap. The game code identifies this color within the face sprites and makes them transparent when displayed.

Click the Color Picker tool and select a bright green color, then use the Pencil Tool to color all of the background pixels this color.

From the menu, select Image -> Mode -> Indexed. In the Colormap menu, select Generate optimum palette and set the maximum number of colors to 128, then click Convert.

Next, select Colors -> Map -> Set Colormap. Click and drag the green background color to the first position in the mapping, and click OK.

7. Export Image as Bitmap

CircuitPython can only load and display bitmap images. Export the image in this format by selecting File -> Export As from the menu.

Click the CIRCUITPYTHON drive within the file selector, then navigate into the face_invaders/img directory. Select face_large.bmp, then click Export then Replace to overwrite the default face sprite file.

8. Repeat the process for remaining sprites

The above steps replaced the game's default large face sprite with the newly created personalized one. Complete these steps again to replace the game's medium and small face sprites.

Starting with the isolated face image from step 3, repeat steps 4 through 7 twice more to resize, reformat, and export these sprite versions:

• Medium: Resize to 30x36 pixels and replace face_medium.bmp
• Small: Resize to 20x24 pixels and replace face_small.bmp

After replaceing the three default sprites, the personalized version of Face Invaders is now complete and playable on the PyBadge.

PyBadge Case

An optional final step is to enclose the PyBadge in a 3D-printed case that features a d-pad input. This case provides a traditional handheld look and feel that matches the arcade style of the game.

Follow the PyBadge Protective Case with D-pad project guide for instructions on how to print and assemble this case.