Space Swirls is an interactive multiplayer space shooter game designed for the MZAPO educational board. Players navigate spaceships through space and battle each other by firing projectiles and utilizing randomly generated power-ups.
📄 Click here to see User Manual
This project is built to run directly on the physical MZAPO board or locally via an emulator.
Before running the game on the physical board, you must add the required SSH private key to your SSH agent for password-less authentication:
ssh-add ~/.ssh/mzapo-root-key
(Note: The exact path to the key may vary depending on your local setup. On lab computers, the key is typically located at /opt/zynq/ssh-connect/mzapo-root-key).
To cross-compile the game for the ARM architecture, transfer it to the board, and execute it automatically in one step, run:
make TARGET_IP=192.168.223.xxx run
(Replace xxx with the actual IP address of your MZAPO board).
If you are connecting from outside the lab network (e.g., from home or via Eduroam), you must route the connection through the university's gateway using ProxyJump:
make TARGET_IP=192.168.223.xxx SSH_OPTIONS="-o ProxyJump=harvaane@postel.felk.cvut.cz" run
To compile the game for your local machine using the SDL-based emulator, use the EMUL=1 flag:
make EMUL=1
Once compiled, you must first start the emulator backend in the background, followed by the game executable:
./emulator/emul &
./game
To remove all compiled object files, dependencies, and executables, run:
make clean
The application is modularized into several key components to separate game logic from hardware interactions and visual rendering.
main.c/main.h: The core engine. Contains the primary game loop (while(1)), context initialization, and state machine transitions (Menus vs. Playing state).main_phys.c/main_phys.h: The physics and collision engine. Handles vector mathematics and updates movement logic utilizing precomputed trigonometric tables for optimal performance on the ARM processor.input_processing.c/input_processing.h: Fetching and processing hardware input. Translates raw knob data into rotation offsets, single clicks (shooting/pausing), and double clicks (activating power-ups).collision_logic.c/collision_logic.h: Handles circular collision detection between ships, projectiles, and power-up entities.bounds_check.c/bounds_check.h: Checking player, projectile and ship angle bounds to keep entities inside the active screen area.led_handling.c/led_handling.h: The peripheral controller. Translates the players' remaining lives to the 32-bit LED strip and assigns power-up statuses to the side RGB LEDs.
main_visuals.c/main_visuals.h: The rendering engine. Maps game objects to the PARLCD display buffer. Responsible for drawing 2D sprites, applying hit-effect color filters, and rendering text fonts.menus_handling.c/menus_handling.h: The UI layer. Manages the rendering and logic of the Main Menu, Pause Menu, and Game Over screens.
blue_player.h,red_player.h,power_ups.h, etc.: Data storage headers containing static arrays of pixel data for animations in RGB565 format.font_prop14x16.c,font_rom8x16.c,font_types.h: Font definitions and typographical structures required for rendering text strings on the display.
mzapo_parlcd.c/.h: Low-level driver for parallel data transfer to the MZAPO LCD display.mzapo_phys.c/.h: Handles the mapping of physical hardware peripheral addresses into the virtual memory space.mzapo_regs.h: Contains definitions of register offsets for I/O operations on the MZAPO board.