Welcome to Gama documentation

Welcome to the official documentation for the Gama game engine!

This documentation is designed to help you get started with creating your own games using Gama, especially if you are a beginner in C programming.

You can get started right-away(if you have your pc) with a tutorial or documentation.

Installation

To use gama, the easiest way is to install the gama command line tool to easily get started building projects.

Linux Installation

Linux debian binaries are available at the gama releases page. Download the archive then install with apt.

sudo apt install path/to/debian/archive.deb

This will install gama and required development libraries like glfw, then you can use gama via gama command on your terminal.

─>$ gama
2025/08/26 01:31:15 open gama.yml: no such file or directory
Gama wraps along the whole project of creating, running and packaging
 your apps using gama.h.

Usage:
  gama [command]

Available Commands:
  build       Build the applicaiton
  completion  Generate the autocompletion script for the specified shell
  create      Create a new gama project
  font        Manage project fonts
  help        Help about any command
  package     A brief description of your command
  run         Run the built binaries

Flags:
      --config string   config file (default is $HOME/.gama.yaml)
  -h, --help            help for gama
  -t, --toggle          Help message for toggle

Use "gama [command] --help" for more information about a command.

Windows installation

You can install on windows using the windows installer at the releases page. Follow the setup to install gama user wide.

Introducing the gama tool

The gama tool manages and creates gama projects.

Creating a project

To create projects, gama create is the key. It takes as arguments the project name, and optionally the template you want to use.

─>$ gama create --help
Create is a command to create or start a new utility.

 Use:
 gama create <name>

 It creates a new directory called <name> and initializes the
 project in it.

Usage:
  gama create <name> [flags]

Aliases:
  create, init, initialize

Examples:
gama create helloWorld

Flags:
  -h, --help              help for create
  -n, --name string       The name of the project you want to create
  -t, --template string   The starter template (default "skeleton")

Global Flags:
      --config string   config file (default is $HOME/.gama.yaml)

To create a project called myApp with the default template:

gama create myApp

To specify a template like pong, at a -t <templatename> to the command:

gama create myApp -t pong

Building your project

To build a project from your terminal:

Open your terminal, like cmd, kitty, or windows terminal
Change to your project root(The folder you created) using cd my/project/path on linux or powershell or dir my/project/path on windows.
Run the build command gama build

To build the project run gama build, this will create a folder in build/ and your executable application will be in that folder.

[!NOTE] You may not run the executable inside the build folder, as it will have errors trying to find your app files. to run your project after building: run gama run. To build and run your project directly, run gama build -r this is what you want most of the case.

Building for windows, ... on linux

Building for windows on linux required winegcc installed, on ubuntu run, install it with apt(sudo apt install winegcc), and to run a windows project you need wine command intalled, once that's done, simply add -w to the build or run commands to build for windows.

Tutorials

A few tutorials to help you grab how gama works. Most of should be available in templates when you create a new project.

Building a Pong Game (AI generated)

This tutorial will guide you through creating a classic Pong game from scratch using the Gama engine. This is a great project for beginners as it covers all the fundamental concepts of game development in a simple and easy-to-understand way.

Prerequisites

Before you begin, make sure you have the following installed:

A C compiler (like GCC)
The gama command-line tool

1. Setting Up Your Project

First, let's create a new project. Open your terminal and run:

gama create mypong

This will create a new directory called mypong with a basic project structure.

2. The `main.c` File

Navigate into your new project directory and open the src/main.c file. This is the entry point for your game. You will see three main functions:

init(App *app): Called once when your application starts.
create(App *app): Called after the application window has been created.
shutdown(App *app): Called when the application is about to close.

Let's start by setting a title for our game window in the init function:

// src/main.c
#include "../assets/gama/gama.h"

void init(App *app) {
    SetAppTitle(app, "Gama Pong");
}

void create(App *app) {}
void shutdown(App *app) {}

3. Setting up the Game Scene

For Pong, we only need one scene. We can set this up directly in our main.c file. We'll define the functions for our scene and then assign them in the create function.

// src/main.c
#include "../assets/gama/gama.h"

// Forward declarations for our scene functions
void gameCreate(Scene *scene);
void gameUpdate(Scene *scene, double theta);
void gameRender(Scene *scene);
void gameKey(Scene *scene, KeyEvent *e);

void init(App *app) {
    SetAppTitle(app, "Gama Pong");
}

void create(App *app) {
    Scene *gameScene = createScene(app);
    gameScene->create = gameCreate;
    gameScene->update = gameUpdate;
    gameScene->render = gameRender;
    gameScene->onkey = gameKey;
    gameScene->background = BLACK;
    showScene(app, gameScene);
}

void shutdown(App *app) {}

// ... implementations of gameCreate, gameUpdate, etc. will go here ...

4. Creating the Game Objects

We need two paddles and a ball. These will be Shape objects. Let's declare them as global variables and initialize them in gameCreate.

// ... after #include
Shape leftPaddle, rightPaddle, ball;

void gameCreate(Scene *scene) {
    // Left Paddle
    createRectangle(&leftPaddle, at(-0.9, 0), at(0.05, 0.3), WHITE);

    // Right Paddle
    createRectangle(&rightPaddle, at(0.9, 0), at(0.05, 0.3), WHITE);

    // Ball
    createCircle(&ball, at(0, 0), 0.025, WHITE);
    setShapeVelocity(&ball, at(0.5, 0.5)); // Give the ball some initial speed
}

A Note on the Coordinate System

Gama uses a 2D Cartesian coordinate system where the center of the screen is (0, 0). The x-axis ranges from -1.0 (left edge) to 1.0 (right edge), and the y-axis ranges from -1.0 (bottom edge) to 1.0 (top edge).

5. Rendering the Game

Now, let's draw our shapes in the gameRender function.

void gameRender(Scene *scene) {
    renderShape(&leftPaddle);
    renderShape(&rightPaddle);
    renderShape(&ball);
}

If you run the game now (gama build -r) which builds your projet and runs it, you should see the paddles and the ball, but nothing is moving yet.

6. Moving the Paddles

We need to handle keyboard input to move the paddles. We'll do this in the gameKey function.

void gameKey(Scene *scene, KeyEvent *e) {
    double paddleSpeed = 1.0;
    if (e->key == KeyW) {
        setShapeVelocity(&leftPaddle, at(0, paddleSpeed));
    }
    if (e->key == KeyS) {
        setShapeVelocity(&leftPaddle, at(0, -paddleSpeed));
    }
    if (e->key == KeyUp) {
        setShapeVelocity(&rightPaddle, at(0, paddleSpeed));
    }
    if (e->key == KeyDown) {
        setShapeVelocity(&rightPaddle, at(0, -paddleSpeed));
    }
}

7. The Game Loop and Frame-Rate Independence

Now we need to update the positions of our objects in gameUpdate. This function is the heart of our game's logic and is called on every frame.

This function receives a theta parameter, which is the time in seconds that has passed since the last frame (also known as delta time). It is crucial to use theta in your movement calculations to ensure your game runs at the same speed on all computers, regardless of their frame rate. This is called frame-rate independence.

void gameUpdate(Scene *scene, double theta) {
    updateShape(&leftPaddle, theta);
    updateShape(&rightPaddle, theta);
    updateShape(&ball, theta);

    // Stop paddles at the window edges
    if (shapeTop(&leftPaddle) > 1.0 || shapeBottom(&leftPaddle) < -1.0) {
        setShapeVelocity(&leftPaddle, at(0, 0));
    }
    if (shapeTop(&rightPaddle) > 1.0 || shapeBottom(&rightPaddle) < -1.0) {
        setShapeVelocity(&rightPaddle, at(0, 0));
    }
}

Run the game now, and you should be able to move the paddles!

8. Collision and Bouncing

Let's make the ball bounce off the walls and the paddles. The bounceShape function is perfect for this. It works by inverting the velocity of a shape on a given axis. For example, bounceShape(&ball, 0, 1.0) will not change the x-velocity but will invert the y-velocity, making the ball bounce vertically.

void gameUpdate(Scene *scene, double theta) {
    // ... (previous code from gameUpdate)

    // Ball bouncing off top and bottom walls
    if (shapeTop(&ball) > 1.0 || shapeBottom(&ball) < -1.0) {
        bounceShape(&ball, 0, 1.0);
    }

    // Ball bouncing off paddles
    if (rectsCollide(getShapePosition(&ball), at(0.05, 0.05), getShapePosition(&leftPaddle), leftPaddle.size) ||
        rectsCollide(getShapePosition(&ball), at(0.05, 0.05), getShapePosition(&rightPaddle), rightPaddle.size)) {
        bounceShape(&ball, 1.0, 0);
    }

    // Scoring and resetting the ball
    if (shapeLeft(&ball) < -1.0 || shapeRight(&ball) > 1.0) {
        setShapePosition(&ball, at(0, 0));
        setShapeVelocity(&ball, at(0.5, 0.5)); // Reset ball speed
    }
}

9 Adding text

For gama to be able to show text to your users, it needs a font. Add the Ubuntu-R.ttf font(which comes with gama) using:

gama font add Ubuntu-R.ttf

This will create the new file in your assets/fonts/Ubuntu-R.ttf your app can now use for rendering text. You can view other available fonts with gama font list.

9. Adding Scoring

Let's add scoring. We'll need a font and two text objects.

// ... after shape declarations
Font *font;
Text *leftScoreText, *rightScoreText;
int leftScore = 0, rightScore = 0;

void gameCreate(Scene *scene) {
    // ... (paddle and ball creation)

    font = loadFont("assets/fonts/Ubuntu-R.ttf"); // the font you just added
    leftScoreText = createTextNulled("0", font, at(-0.1, 0.8));
    rightScoreText = createTextNulled("0", font, at(0.1, 0.8));
}

void gameRender(Scene *scene) {
    // ... (render shapes)
    renderText(leftScoreText);
    renderText(rightScoreText);
}

void updateScore() {
    char scoreStr[10];
    sprintf(scoreStr, "%d", leftScore); // put the score text in scoreStr with printf like formating
    setTextNulled(leftScoreText, scoreStr); // set the text to the new string
    sprintf(scoreStr, "%d", rightScore);
    setTextNulled(rightScoreText, scoreStr);
}

Now we will add logic so that if the ball exits the screen(passes behind a paddl) then it is one point for the other user, and the ball returns to the middle of the scene(at(0, 0))

// In gameUpdate, modify the scoring logic:
// ...
    if (shapeLeft(&ball) < -1.0) { // Right player scores
        rightScore++;
        updateScore();
        setShapePosition(&ball, at(0, 0));
    }
    if (shapeRight(&ball) > 1.0) { // Left player scores
        leftScore++;
        updateScore();
        setShapePosition(&ball, at(0, 0));
    }
// ...

10. Game Over and Restarting

Let's add a simple game over condition. The first player to reach 5 points wins.

// ... after score variables
Text *gameOverText;
int gameOver = 0; // 0 for playing, 1 for game over

void gameCreate(Scene *scene) {
    // ...
    gameOverText = createTextNulled("", font, at(0, 0));
    gameOverText->fontsize = 0.2;
    gameOverText->color = RED;
}

void resetGame() {
    leftScore = 0;
    rightScore = 0;
    updateScore();
    setShapePosition(&ball, at(0, 0));
    setShapeVelocity(&ball, at(0.5, 0.5));
    setTextNulled(gameOverText, "");
    gameOver = 0;
}

// In gameKey, add a restart key:
void gameKey(Scene *scene, KeyEvent *e) {
    // ... (paddle movement)
    if (e->key == KeyR && gameOver) {
        resetGame();
    }
}

// In gameUpdate, check for game over:
void gameUpdate(Scene *scene, double theta) {
    if (gameOver) return; // Don't update the game if it's over

    // ... (rest of the update logic)

    if (leftScore >= 5) {
        setTextNulled(gameOverText, "Left Player Wins!\nPress R to Restart");
        gameOver = 1;
    }
    if (rightScore >= 5) {
        setTextNulled(gameOverText, "Right Player Wins!\nPress R to Restart");
        gameOver = 1;
    }
}

// In gameRender, draw the game over text:
void gameRender(Scene *scene) {
    // ... (render shapes and scores)
    if (gameOver) {
        renderText(gameOverText);
    }
}

11. Conclusion

You now have a complete, working Pong game with a scoring and game over system! This tutorial has covered the basics of creating a game in Gama. From here, you can try to add more features, like a main menu, sound effects, or increasing ball speed over time.

Guides

Packaging your app

Once you've got something convincing you may want to share your app with others, and need a something you could give them to run, a few packaging methods are available.

Packaging as zip (linux and windows)

To package your app as a zip file, run gama package zip(gama package zip -w for wine on linux). This creates a new zip file named with your app name and version and you can share to others.

Installing required libraries(linux)

For windows users, that should work very easy, with windows 7, just need to unzip the folder and run the {projectName}.exe file. But on linux the person who runs the app should make sure to have a few libraries installed:

sudo apt install libglfw3 libxi libxxf86vm

Then you should be able to run this.

[!TODO] Reduce these libraries to strict necessary.

[!WARNING] Running on another linux machine has not been tested yet.

Other packaging methods

Packaging as linux .deb archive and windows setup using nsis is planned... But not yet implemented until then hope this method is okay.

Gama.h

Here is a more indepth but hand-written documentation about gama.h

The base

The base of the gama application is these simple three methods. You must specify them for your app to run.

When your app starts to when it stops, gama runs these few methods.

`void init(App* app)`

This is the first method which gama calls. This method is intended to comfigure your just-created app, verify files or configuration before your app windows shows and even binding events directly to your app instead of a scene. You should not start loading fonts or creating objects here, it is strictly meant for initializing your application.

init() receives [The App] as only argument, since obviously it is meant to set it up.

Example:

void init(App* app) {
  setAppTitle(app, "Hello world");
  setAppSize(app, 500, 500);
}

`void create(App* app)`

Create shapes, scenes, fonts, and every thing else here. Create runs after the init and when your app opengl context has already been initialized, This is why it is only safe to create fonts, images and shapres here.

It is also in this that your are going to create and show The scene.

API Reference

[!NOTE] This reference is generated with AI.

This is a comprehensive reference for the Gama game engine's API.

`app.h`

This file provides the core application management functionalities.

`struct sApp` or simply `App`

Represents your game application.

Fields:

char *title: The title of the application window.
unsigned int width: The width of the application window in pixels.
unsigned int height: The height of the application window in pixels.
void (*onclick)(struct sApp *, MouseClickEvent *): A function pointer that is called when a mouse click event occurs.
void (*onkey)(struct sApp *, KeyEvent *): A function pointer that is called when a key event occurs.
Scene *scene: A pointer to the currently active scene.

`App *GamaCreateApp()`

Creates and initializes a new App structure with default values.

Returns:

A pointer to the newly created App.

`void showScene(App app, Scene s)`

Switches the currently active scene in the application. If there was a previous scene, it is destroyed.

Parameters:

App *app: A pointer to your application.
Scene *s: The new scene to be displayed.

`void SetAppTitle(App app, char title)`

Sets the title of the application window.

Parameters:

App *app: A pointer to your application.
char *title: The new title for the window.

Color col: The color to clear the screen with.

`drawshape.h`

Provides functions for drawing basic geometric shapes.

`void drawRectangle(double x, double y, double width, double height, Color color)`

Draws a rectangle centered at (x, y).

Parameters:

double x: The x-coordinate of the center of the rectangle.
double y: The y-coordinate of the center of the rectangle.
double width: The width of the rectangle.
double height: The height of the rectangle.
Color color: The color of the rectangle.

`void drawCircle(double cx, double cy, double radius, Color color)`

Draws a circle centered at (cx, cy).

Parameters:

double cx: The x-coordinate of the center of the circle.
double cy: The y-coordinate of the center of the circle.
double radius: The radius of the circle.
Color color: The color of the circle.

`events.h`

Defines the structures for handling user input events.

`struct MouseClickEvent`

Represents a mouse click event.

Fields:

double x: The x-coordinate of the mouse click (from -1.0 to 1.0).
double y: The y-coordinate of the mouse click (from -1.0 to 1.0).
int button: The mouse button that was clicked (e.g., GLFW_MOUSE_BUTTON_LEFT).
int down: 1 if the button was pressed, 0 if it was released.

`enum Key`

An enumeration of all the keyboard keys that can be detected by Gama.

Examples: KeyLeft, KeyRight, KeySpace, KeyEnter, KeyA, KeyB, etc.

`struct KeyEvent`

Represents a keyboard event.

Fields:

Key key: The key that was pressed or released.

`image.h`

This file provides functions for loading and manipulating images.

`struct Image`

Represents an image.

Fields:

unsigned int width: The width of the image in pixels.
unsigned int height: The height of the image in pixels.
unsigned char *data: A pointer to the raw pixel data of the image.
unsigned int texture_id: The OpenGL texture ID for the image.

`Image openImageFile(Image img, const char *path)`

Loads an image from a file.

Parameters:

Image *img: A pointer to an Image struct to load the data into.
const char *path: The path to the image file.

Returns:

A pointer to the loaded Image, or NULL on failure.

`Image *newImage()`

Allocates memory for a new Image struct.

Returns:

A pointer to the new Image.

`Image *createImage(unsigned int width, unsigned int height)`

Creates a new blank Image with the specified dimensions.

Parameters:

unsigned int width: The width of the new image.
unsigned int height: The height of the new image.

Returns:

A pointer to the new Image.

`Image cropImage(const Image img, unsigned int startx, unsigned int starty, unsigned int width, unsigned int height)`

Creates a new Image by cropping a section of an existing image.

Parameters:

const Image *img: The image to crop from.
unsigned int startx: The starting x-coordinate of the crop.
unsigned int starty: The starting y-coordinate of the crop.
unsigned int width: The width of the cropped image.
unsigned int height: The height of the cropped image.

Returns:

A pointer to the new cropped Image.

`void drawImage(Image *image, double x, double y, double w, double h)`

Draws an image to the screen.

Parameters:

Image *image: The image to draw.
double x: The x-coordinate of the top-left corner.
double y: The y-coordinate of the top-left corner.
double w: The width to draw the image.
double h: The height to draw the image.

`void freeImage(Image *image)`

Frees the memory used by an Image.

Parameters:

Image *image: The image to free.

`scene.h`

This file provides the structure and functions for managing scenes.

`struct sScene`

Represents a scene in the game.

Fields:

SpriteList sprites: A list of sprites in the scene.
ShapeList shapes: A list of shapes in the scene.
Color background: The background color of the scene.
struct sApp *app: A pointer to the application.
void (*create)(struct sScene *): Function pointer called when the scene is created.
void (*update)(struct sScene *, double): Function pointer called every frame to update the scene.
void (*render)(struct sScene *): Function pointer called every frame to render the scene.
void (*destroy)(struct sScene *): Function pointer called when the scene is destroyed.
void (*onclick)(struct sScene *, MouseClickEvent *): Function pointer for mouse click events.
void (*onkey)(struct sScene *, KeyEvent *): Function pointer for key events.

`Scene createScene(struct sApp app)`

Creates a new, empty scene.

Parameters:

struct sApp *app: A pointer to the application.

Returns:

A pointer to the new Scene.

`void addShapeToScene(Scene scene, Shape shape)`

Adds a shape to the scene.

Parameters:

Scene *scene: The scene to add the shape to.
Shape *shape: The shape to add.

`void addSpriteToScene(Scene scene, Sprite sprite)`

Adds a sprite to the scene.

Parameters:

Scene *scene: The scene to add the sprite to.
Sprite *sprite: The sprite to add.

`shape.h`

This file provides everything needed to create and manage shapes.

`enum ShapeType`

An enum to represent the type of a shape.

Values:

RectangleShape
CircleShape

`struct Shape`

Represents a geometric shape.

Fields:

ShapeType type: The type of the shape.
Vector *pos: The position and movement vector of the shape.
Pos *size: The size of the shape (for rectangles).
Color color: The color of the shape.
double radius: The radius of the shape (for circles).

`Shape createRectangle(Shape s, Pos pos, Pos size, Color col)`

Initializes a Shape structure as a rectangle.

Parameters:

Shape *s: A pointer to the Shape to initialize.
Pos *pos: The position of the rectangle.
Pos *size: The size of the rectangle.
Color col: The color of the rectangle.

Returns:

A pointer to the initialized Shape.

`Shape createCircle(Shape s, Pos *pos, double radius, Color col)`

Initializes a Shape structure as a circle.

Parameters:

Shape *s: A pointer to the Shape to initialize.
Pos *pos: The position of the circle.
double radius: The radius of the circle.
Color col: The color of the circle.

Returns:

A pointer to the initialized Shape.

Shape Helpers

Physics and Position

void setShapeVelocity(Shape *s, Pos *vel): Sets the velocity of a shape.
Pos *getShapeVelocity(Shape *s): Gets the velocity of a shape.
Pos *getShapePosition(Shape *s): Gets the position of a shape.
void setShapePosition(Shape *s, Pos *pos): Sets the position of a shape.
Pos *getShapeAcceleration(Shape *s): Gets the acceleration of a shape.
void setShapeAcceleration(Shape *s, Pos *acc): Sets the acceleration of a shape.

Collision and Bouncing

double shapeTop(Shape *s): Returns the y-coordinate of the top edge of a shape.
double shapeBottom(Shape *s): Returns the y-coordinate of the bottom edge of a shape.
double shapeLeft(Shape *s): Returns the x-coordinate of the left edge of a shape.
double shapeRight(Shape *s): Returns the x-coordinate of the right edge of a shape.
void bounceShape(Shape *s, double x, double y): Inverts the velocity of a shape on the x or y axis, simulating a bounce. A value of 0.0 for x or y means no bounce on that axis.

`sprite.h`

This file provides everything needed to create and manage animated sprites.

`struct Sprite`

Represents a sprite.

Fields:

Vector *pos: The position and movement vector of the sprite.
Pos *size: The size of the sprite.
unsigned int length: The number of frames in the sprite sheet.
Image **images: An array of images representing the frames of the sprite.
float fps: The speed of the animation in frames per second.
... and other internal animation fields.

`Sprite createSprite(const char path, unsigned int width, unsigned int height, Pos pos, Pos size)`

Creates a new sprite from a sprite sheet image.

Parameters:

const char *path: The path to the sprite sheet image.
unsigned int width: The width of a single frame in the sprite sheet.
unsigned int height: The height of a single frame in the sprite sheet.
Pos *pos: The initial position of the sprite.
Pos *size: The size to render the sprite.

Returns:

A pointer to the new Sprite.

`void setSpriteAnimation(Sprite s, unsigned int length, unsigned int animation, unsigned int fps)`

Sets a custom animation sequence for a sprite.

Parameters:

Sprite *s: The sprite to animate.
unsigned int length: The number of frames in the animation sequence.
unsigned int *animation: An array of frame indices for the animation.
unsigned int fps: The speed of the animation in frames per second.

Sprite Helpers

Physics and Position

void setSpriteVelocity(Sprite *s, Pos *vel): Sets the velocity of a sprite.
Pos *getSpriteVelocity(Sprite *s): Gets the velocity of a sprite.
Pos *getSpritePosition(Sprite *s): Gets the position of a sprite.
void setSpritePosition(Sprite *s, Pos *pos): Sets the position of a sprite.
Pos *getSpriteAcceleration(Sprite *s): Gets the acceleration of a sprite.
void setSpriteAcceleration(Sprite *s, Pos *acc): Sets the acceleration of a sprite.

Collision and Bouncing

double spriteTop(Sprite *s): Returns the y-coordinate of the top edge of a sprite.
double spriteBottom(Sprite *s): Returns the y-coordinate of the bottom edge of a sprite.
double spriteLeft(Sprite *s): Returns the x-coordinate of the left edge of a sprite.
double spriteRight(Sprite *s): Returns the x-coordinate of the right edge of a sprite.
void bounceSprite(Sprite *s, double x, double y): Inverts the velocity of a sprite on the x or y axis.
float bounceSpriteUnder(Sprite *s, double pos, double bounce, double maxSpeed): A specialized bounce function that simulates a bounce when a sprite hits a floor at a certain y-position.
int rectsCollide(Pos *pa, Pos *sa, Pos *pb, Pos *sb): Checks if two rectangles collide.
int spriteTouchesSprite(Sprite *a, Sprite *b): Checks if two sprites are colliding.

char *text: The text string to render.
double fontsize: The size of the font.
Font *font: The font to use.
Vector *pos: The position of the text.
Color color: The color of the text.