Getting Started

Getting Started with BlitEngine

Let's create your first game with BlitEngine! This guide will walk you through everything step-by-step.

Installation

BlitEngine is included with ModuOS. The files you need are:

• userland/BlitEngine.h - Header file
• userland/BlitEngine.c - Implementation
• userland/lib_NodGL.c - Graphics backend

Your First Program

Let's make a simple program that shows a green square you can move with WASD keys.

Step 1: Include BlitEngine

#include "BlitEngine.h"
#include "libc.h"

int md_main(long argc, char **argv) {
    // Your code here
    return 0;
}

Step 2: Initialize the Engine

int md_main(long argc, char **argv) {
    BlitEngine engine;
    
    if (blit_init(&engine) != 0) {
        printf("Failed to initialize BlitEngine!\n");
        return 1;
    }
    
    printf("BlitEngine initialized successfully!\n");
    printf("Screen: %dx%d\n", engine.screen_width, engine.screen_height);
    
    // Game code will go here
    
    blit_shutdown(&engine);
    return 0;
}

Step 3: Create a Sprite

// After blit_init...

// Create a 32x32 green square sprite
Sprite *player = blit_sprite_create_color(&engine, 32, 32, 0xFF00FF00);

if (!player) {
    printf("Failed to create sprite!\n");
    blit_shutdown(&engine);
    return 1;
}

Step 4: Add the Game Loop

// Player position
int x = 100, y = 100;

// Main game loop
while (blit_is_running(&engine)) {
    // Update input
    blit_update_input(&engine);
    
    // Clear screen to black
    blit_begin_frame(&engine, 0xFF000000);
    
    // Draw player
    blit_sprite_draw(&engine, player, x, y);
    
    // Show frame
    blit_end_frame(&engine);
}

Step 5: Add Movement Controls

while (blit_is_running(&engine)) {
    blit_update_input(&engine);
    
    // WASD controls
    if (blit_key_down(&engine, KEY_W)) y -= 3;
    if (blit_key_down(&engine, KEY_S)) y += 3;
    if (blit_key_down(&engine, KEY_A)) x -= 3;
    if (blit_key_down(&engine, KEY_D)) x += 3;
    
    // Keep player on screen
    if (x < 0) x = 0;
    if (y < 0) y = 0;
    if (x > engine.screen_width - 32) x = engine.screen_width - 32;
    if (y > engine.screen_height - 32) y = engine.screen_height - 32;
    
    // Draw
    blit_begin_frame(&engine, 0xFF000000);
    blit_sprite_draw(&engine, player, x, y);
    blit_end_frame(&engine);
}

Step 6: Clean Up

// After the game loop
blit_sprite_free(&engine, player);
blit_shutdown(&engine);
return 0;

Complete Program

Here's the full code:

#include "BlitEngine.h"
#include "libc.h"

int md_main(long argc, char **argv) {
    BlitEngine engine;
    
    if (blit_init(&engine) != 0) {
        printf("Failed to initialize BlitEngine!\n");
        return 1;
    }
    
    printf("My First BlitEngine Game!\n");
    printf("Use WASD to move, ESC to quit\n");
    
    // Create player sprite
    Sprite *player = blit_sprite_create_color(&engine, 32, 32, 0xFF00FF00);
    
    // Player position
    int x = 100, y = 100;
    
    // Game loop
    while (blit_is_running(&engine)) {
        blit_update_input(&engine);
        
        // ESC to quit
        if (blit_key_pressed(&engine, KEY_ESC)) {
            break;
        }
        
        // WASD movement
        if (blit_key_down(&engine, KEY_W)) y -= 3;
        if (blit_key_down(&engine, KEY_S)) y += 3;
        if (blit_key_down(&engine, KEY_A)) x -= 3;
        if (blit_key_down(&engine, KEY_D)) x += 3;
        
        // Keep on screen
        if (x < 0) x = 0;
        if (y < 0) y = 0;
        if (x > engine.screen_width - 32) x = engine.screen_width - 32;
        if (y > engine.screen_height - 32) y = engine.screen_height - 32;
        
        // Draw
        blit_begin_frame(&engine, 0xFF001020);
        blit_sprite_draw(&engine, player, x, y);
        blit_end_frame(&engine);
    }
    
    blit_sprite_free(&engine, player);
    blit_shutdown(&engine);
    
    printf("Thanks for playing!\n");
    return 0;
}

Building Your Game

Save your code as mygame.c and compile it:

# Compile your game
gcc -m64 -O2 -ffreestanding -nostdlib -c mygame.c -o mygame.o

# Compile BlitEngine
gcc -m64 -O2 -ffreestanding -nostdlib -c BlitEngine.c -o BlitEngine.o

# Link everything together
ld -T user.ld mygame.o BlitEngine.o lib_NodGL.a libc.a -o mygame.sqr

# Run it!
./mygame.sqr

Understanding the Code

BlitEngine Structure

BlitEngine engine;

This holds all the engine state: screen size, input, frame count, etc.

Initialization

blit_init(&engine);

Sets up graphics, opens input devices, gets screen resolution.

Game Loop Pattern

while (blit_is_running(&engine)) {
    // 1. Update input
    blit_update_input(&engine);
    
    // 2. Game logic (movement, collisions, etc.)
    
    // 3. Begin frame (clear screen)
    blit_begin_frame(&engine, clear_color);
    
    // 4. Draw everything
    
    // 5. End frame (show on screen)
    blit_end_frame(&engine);
}

This pattern runs 60 times per second (or as fast as your hardware allows).

Colors

Colors use ARGB format: 0xAARRGGBB

0xFF000000  // Black
0xFFFFFFFF  // White
0xFFFF0000  // Red
0xFF00FF00  // Green
0xFF0000FF  // Blue
0xFF001020  // Dark blue (nice background!)

Adding More Features

Multiple Sprites

Sprite *player = blit_sprite_create_color(&engine, 32, 32, 0xFF00FF00);
Sprite *enemy = blit_sprite_create_color(&engine, 24, 24, 0xFFFF0000);
Sprite *coin = blit_sprite_create_circle(&engine, 8, 0xFFFFFF00);

// Draw them all
blit_sprite_draw(&engine, player, px, py);
blit_sprite_draw(&engine, enemy, ex, ey);
blit_sprite_draw(&engine, coin, cx, cy);

Mouse Input

int mx = engine.input.mouse_x;
int my = engine.input.mouse_y;

if (blit_mouse_clicked(&engine, MOUSE_LEFT)) {
    printf("Clicked at %d, %d\n", mx, my);
}

Drawing Shapes

// Rectangle
blit_draw_rect(&engine, 50, 50, 100, 80, 0xFFFF0000);

// Circle
blit_draw_circle(&engine, 200, 200, 30, 0xFF00FF00);

// Line
blit_draw_line(&engine, 0, 0, 100, 100, 0xFFFFFFFF, 3);

// Text
blit_draw_text(&engine, "Hello!", 10, 10, 0xFFFFFFFF);

Collision Detection

// Check if player hit enemy
if (star_rects_overlap(px, py, 32, 32, ex, ey, 24, 24)) {
    printf("Player hit enemy!\n");
}

// Check if mouse clicked button
if (star_point_in_rect(mx, my, btn_x, btn_y, btn_w, btn_h)) {
    if (blit_mouse_clicked(&engine, MOUSE_LEFT)) {
        printf("Button clicked!\n");
    }
}

Common Mistakes

1. Forgetting to Update Input

// WRONG - Input won't work!
while (blit_is_running(&engine)) {
    // Missing: blit_update_input(&engine);
    
    if (blit_key_down(&engine, KEY_W)) { /* won't work */ }
}

// CORRECT
while (blit_is_running(&engine)) {
    blit_update_input(&engine);  // Always call first!
    
    if (blit_key_down(&engine, KEY_W)) { /* works! */ }
}

2. Not Freeing Sprites

// WRONG - Memory leak!
Sprite *sprite = blit_sprite_create_color(&engine, 32, 32, 0xFF00FF00);
// ... use sprite ...
blit_shutdown(&engine);  // sprite never freed!

// CORRECT
Sprite *sprite = blit_sprite_create_color(&engine, 32, 32, 0xFF00FF00);
// ... use sprite ...
blit_sprite_free(&engine, sprite);  // Clean up!
blit_shutdown(&engine);

3. Creating Sprites Every Frame

// WRONG - Very slow!
while (blit_is_running(&engine)) {
    Sprite *s = blit_sprite_create_color(&engine, 32, 32, 0xFF00FF00);  // BAD!
    blit_sprite_draw(&engine, s, x, y);
    blit_sprite_free(&engine, s);
}

// CORRECT - Create once!
Sprite *s = blit_sprite_create_color(&engine, 32, 32, 0xFF00FF00);
while (blit_is_running(&engine)) {
    blit_sprite_draw(&engine, s, x, y);  // Just draw it
}
blit_sprite_free(&engine, s);

Quick Reference

// Engine
blit_init(&engine);
blit_shutdown(&engine);
blit_update_input(&engine);
blit_begin_frame(&engine, color);
blit_end_frame(&engine);

// Sprites
Sprite *s = blit_sprite_create_color(&engine, w, h, color);
Sprite *c = blit_sprite_create_circle(&engine, radius, color);
blit_sprite_draw(&engine, sprite, x, y);
blit_sprite_free(&engine, sprite);

// Input
blit_key_down(&engine, KEY_W);
blit_key_pressed(&engine, KEY_SPACE);
blit_mouse_down(&engine, MOUSE_LEFT);
blit_mouse_clicked(&engine, MOUSE_LEFT);

// Drawing
blit_draw_rect(&engine, x, y, w, h, color);
blit_draw_circle(&engine, cx, cy, radius, color);
blit_draw_text(&engine, "text", x, y, color);

// Collision
star_rects_overlap(x1, y1, w1, h1, x2, y2, w2, h2);
star_point_in_rect(px, py, rx, ry, rw, rh);

Next Steps

Now that you know the basics:

1. Core Concepts - Deep dive into BlitEngine
2. Tutorial: Catch the Stars - Build a complete game
3. Using Entities - Advanced game objects
4. Example Games - Learn from working games

Happy game making! 🎮