FlipperZero Game Engine (Video Game Engine)

FlipperZero Game Engine (Video Game Engine)

Overview

The FlipperZero Game Engine is a git submodule that you can include in your own Flipper Zero application. Because it is a sub-module, you should clone applications that use the engine using the git clone --recursive option (or --recurse-submodules).

The engine is located at https://github.com/flipperdevices/flipperzero-game-engine and typically people create a submodule in an engine directory.

The game engine contains two main parts:

• Game engine for playing games
  • Game has a bunch of Level* objects; described by LevelBehavior
  • Level has a bunch of Entity* objects (e.g. player, ball, coin, wall, etc. entity); described by EntityDescription
  • Entity can have a rectangular or circular collider
  • Sprite (.png transformed to .fxbm image) can be loaded and rendered to Canvas
  • Vector (x & y position) and APIs for manipulating the vector
  • GameManager for getting InputState, switching Level, loading Sprite objects, showing frames-per-second, overall game context, etc.
• Sensor library for accessing the Video Game Module
  • Pitch : Assuming screen facing up & IR port facing left, then pitch is the tilt Left(+) / Right(-)
  • Roll : Assuming screen facing up & IR port facing left, then roll is the GPIO ports Down(+) / GPIO ports Up(-)
  • Yaw : Assuming screen facing up & IR port facing left, then yaw is Counter-Clockwise(+) / Clockwise(-)

Existing Games

The game engine was used by the Air Arkanoid game.

I wrote the Air Labyrinth game using the game engine.

JBlanked wrote Flip World game using the game engine.

There is also an example game using the game engine. This example only has one level and does not leverage the Video Game Module for motion.

Adding to your project

To add the submodule to your project, you typically run the following command in the same directory as your application.fam file.

git submodule add https://github.com/flipperdevices/flipperzero-game-engine.git engine

IMU (Inertial Measurement Unit)

If you have a Video Game Module (VGM) attached to your Flipper Zero you can access the orientation in your application. You need all of the code under the sensors folder, but it has no other dependencies.

Your application will need to #include "sensors/imu.h"

You can then call: Imu* imu = imu_alloc(); to obtain an Imu* object. When you call this method, it will try to acquire the IMU connected to the VGM (using pins 2-7, plus power [3v3] and GND). If it detects the module, it will also do a calibration. For best results, you should have the device in the expected orientation and not moving during this time.

Calling bool imu_present = imu_present(imu); will return true if the IMU was present during the allocation call, otherwise it will return false. NOTE: If you are running custom firmware on the Video Game Module, it is possible that the onboard PI may be using the IMU and will be unavailable to the Flipper Zero.

To get orientation data...

float pitch = imu_pitch_get(imu);
float roll = imu_roll_get(imu);
float yaw = imu_yaw_get(img);

When you are done with the IMU, you should release the resource using imu_free(imu);.

Creating a game

Create a submodule for the engine. See Adding to your project for commands.

Entry point

The engine\main.c file defines an entry point of game_app. Your application.fam file should set the entry point using entry_point="game_app",.

Game

You application should #include "engine/engine.h"

The engine\engine.h declares extern const Game game; which will get executed by the game engine. You must define the game variable in your game, setting all of the properties.

The engine\engine.h defines the Game structure as:

typedef struct {
    float target_fps;
    bool show_fps;
    bool always_backlight;
    void (*start)(GameManager* game_manager, void* context);
    void (*stop)(void* context);
    size_t context_size;
} Game;

• target_fps : The number of frames per second to try to render. A value of 30 is probably a good starting point.
• show_fps : Useful for debugging to see the actual frames per second. Typically set to false.
• always_backlight : Set to true so the screen is always visible while playing the game.
• start : Callback that should add the levels & allocate Imu* object
• stop : Callback that should free Imu* object
• context_size : Set to sizeof( your context structure ). The context will be allocated for you and passed to your start and stop methods.

The Air Arkanoid game uses the following in their game.c file:

void game_start(GameManager* game_manager, void* ctx);
void game_stop(void* ctx);

// The various levels that are created.
typedef struct {
    Level* menu;
    Level* settings;
    Level* game;
    Level* message;
} Levels;

// Settings that are saved on SD card.
typedef struct {
    bool sound;
    bool show_fps;
} Settings;

// Game (App) related data
typedef struct {
    Imu* imu; // VGM data
    bool imu_present; // cache of imu_present(imu)
    Levels levels; // All of the levels in the game
    Settings settings; // Settings associated with game (like sound)
    NotificationApp* app; // For sound/vibrate
    GameManager* game_manager; // Used to set showing/hiding fps info
} GameContext;

const Game game = {
    .target_fps = 30, // Update screen 30 frames per second
    .show_fps = false, // Don't display the current frames per second
    .always_backlight = true, // Keep screen on so it is easy to see
    .start = game_start, // Callback that should add the levels & allocate Imu* object
    .stop = game_stop, // Callback that should free Imu* object
    .context_size = sizeof(GameContext), // Context for storing Game related data.
};