BPCore Engine Skill

Comprehensive guide for building Gameboy Advance games using the BPCore Engine Lua framework.

Overview

BPCore Engine (Blind jumP Core Engine) is a Lua game framework for GBA that combines C++ with embedded Lua, letting developers create games without C++ or compilers. Inspired by Pico-8 and Tic80, it's suited for small minigames given the GBA's limited resources: 240x160 screen, 16.78 MHz ARM7TDMI, and 256KB RAM for Lua/data.

The engine provides sprite rendering, tile-based graphics, entity management with collision, button input, UTF-8 text, audio, save/load via SRAM, and multiplayer through the link cable. The build system uses Lua to package resources into ROM.

API Reference

Entity Functions

Function	Signature	Description
ent()	ent()	Create entity, returns handle
entpos(e, x, y)	entpos(e, x, y)	Set position, returns self
entz(e, z)	entz(e, z)	Set Z-order (0-255), returns self
entspr(e, sprite, xflip, yflip)	entspr(e, sprite, xflip, yflip)	Set sprite and flips, returns self
entspd(e, x, y)	entspd(e, x, y)	Set movement speed, returns self
entslot(e, slot, value)	entslot(e, slot, value)	Store in slot, returns self
entslots(e, count)	entslots(e, count)	Allocate slots, returns self
entanim(e, start, len, rate)	entanim(e, start, len, rate)	Set animation
entag(e, tag)	entag(e, tag)	Set collision tag, returns self
enthb(e, ox, oy, w, h)	enthb(e, ox, oy, w, h)	Set hitbox, returns self
del(e, auto?)	del(e, [auto])	Delete entity
ents()	ents()	Get all entities table

Sprite & Tile Functions

Function	Signature	Description
txtr(layer_id, filename)	txtr(layer_id, filename)	Load texture from file
txtr(layer_id, ptr, len)	txtr(layer_id, ptr, len)	Load from pointer/length
file(filename)	file(filename)	Get file pointer/length
spr(sprite_id, x, y)	spr(sprite_id, x, y)	Draw sprite
spr(sprite_id, x, y, xflip, yflip)	spr(sprite_id, x, y, xflip, yflip)	Draw with flips
tile(layer_id, x, y, num?)	tile(layer_id, x, y, [num])	Draw/read tile
tilemap(f, layer, w, h, dx, dy, sx, sy)	tilemap(f, layer, w, h, dx, dy, sx, sy)	Load CSV tilemap
clear()	clear()	Clear sprites, VSync
display()	display()	Send sprites to display
fade(amount, color?, tl?, bg?)	fade(amount, [color], [tl], [bg])	Fade layers

Camera & Scroll

Function	Signature	Description
camera(x, y)	camera(x, y)	Set camera center
scroll(layer, x, y)	scroll(layer, x, y)	Set layer scroll
priority(s, bg, t0, t1)	priority(s, bg, t0, t1)	Set render priority

Collision

Function	Signature	Description
ecolle(e1, e2)	ecolle(e1, e2)	Check collision (bool)
ecoll(e, tag)	ecoll(e, tag)	Find tag matches (array)
enthb(e)	enthb(e)	Get hitbox (getter)

Input

Function	Signature	Description
btn(num)	btn(num)	Button held? (bool)
btnp(num)	btnp(num)	Button pressed? (bool)
btnnp(num)	btnnp(num)	Button released? (bool)

Graphics

Function	Signature	Description
print(text, x, y, fg?, bg?)	print(text, x, y, [fg], [bg])	Print to overlay

Audio

Function	Signature	Description
music(f, offset?)	music(f, [offset])	Play background music
sound(f, priority)	sound(f, priority)	Play sound effect

Memory

Function	Signature	Description
poke(addr, value)	poke(addr, value)	Write byte
poke4(addr, value)	poke4(addr, value)	Write 32-bit word
peek(addr)	peek(addr)	Read byte
peek4(addr)	peek4(addr)	Read 32-bit word
memput(addr, data)	memput(addr, data)	Write to memory
memget(addr, len?)	memget(addr, [len])	Read from memory

System

Function	Signature	Description
delta()	delta()	Microseconds since last call
sleep(frames)	sleep(frames)	Sleep N frames
startup_time()	startup_time()	Get boot time
fdog()	fdog()	Feed watchdog timer
log(msg)	log(msg)	Debug log
rline()	rline()	Get raster line
flimit(fps)	flimit(fps)	Set frame rate limit
next_script(filename)	next_script(filename)	Switch Lua script

Multiplayer

Function	Signature	Description
connect(timeout)	connect(timeout)	Connect (blocking)
disconnect()	disconnect()	Disconnect
send(data)	send(data)	Send message (max 11 bytes)
recv()	recv()	Receive message
send_iram(ptr)	send_iram(ptr)	Send from IRAM
recv_iram(ptr)	recv_iram(ptr)	Receive to IRAM

Layer IDs

ID	Layer	Size	Description
0	Overlay	32x32 tiles	Front, persistent
1	Tile Layer 1	64x64 tiles	Behind sprites, in front of tile_0
2	Tile Layer 0	64x64 tiles	Main background
3	Background	32x32 tiles	Back layer
4	Sprites	Dynamic	On-top sprites

Installation & Project Structure

Getting BPCoreEngine.gba

Important: BPCore Engine requires BPCoreEngine.gba base ROM with compiled C++ code and Lua interpreter. This is not a custom ROM you create.

Where to Obtain

1. Official Repository: Clone from GitHub

   git clone https://github.com/evanbowman/BPCore-Engine.git
   cd BPCore-Engine
   

2. Required Files: Repository contains:

   • BPCoreEngine.gba - Engine base ROM (~3.5 MB)
   • build.lua - Build script (Lua 5.3)
   • test/ - Example projects

3. Alternatives:

   • GitHub Releases may have pre-built GBA files
   • mGBA emulator includes BPCore version in some distributions

File Placement

your-project/
├── BPCoreEngine.gba          # Base ROM (required)
├── build.lua                  # Build script
├── manifest.lua               # Your manifest
├── overlay.bmp                # Text/UI tiles
├── tile0.bmp                  # Main background (64x64 tiles)
├── tile1.bmp                  # Foreground (64x64 tiles)
├── spritesheet.bmp           # Sprites (16x16)
├── music.raw                  # Music (mono 16kHz PCM)
├── sfx.wav                    # Sound effects
├── main.lua                   # Entry point
└── data.txt                   # Resources

Build Layout

./
├── src/
│   ├── main.lua              # Main loop
│   ├── game.lua              # Game logic
│   ├── menu.lua              # Menu
│   └── level1.csv            # Tilemap
├── assets/
│   ├── graphics/
│   │   ├── spritesheet.bmp
│   │   ├── tiles0.bmp
│   │   └── tiles1.bmp
│   ├── audio/
│   │   ├── music.raw
│   │   ├── jump.wav
│   │   └── coin.wav
│   └── tilemaps/
│       └── world.csv
├── build.lua                 # Build script
├── BPCoreEngine.gba          # Engine ROM
└── dist/
    └── yourgame.gba          # Output

Building Your ROM

Step 1: Create manifest.lua

local app = {
    name = "My Adventure",
    gamecode = "ABCD",
    makercode = "BC",
    tilesets = { "overlay.bmp", "tile0.bmp", "tile1.bmp" },
    spritesheets = { "spritesheet.bmp" },
    audio = { "music.raw", "jump.wav", "coin.wav" },
    scripts = { "main.lua", "game.lua", "menu.lua" },
    misc = { "level1.csv" }
}

return app

Step 2: Run build script

lua build.lua manifest.lua BPCoreEngine.gba output.gba

Step 3: Verify

Build checks manifest files exist, formats are valid, scripts readable, output ROM created (~3.5-4 MB).

Step 4: Test with mGBA

mGBA output.gba --log --memview

--log shows engine log() output, --memview opens memory viewer for debugging.

File Formats

BMP Tilesets: Indexed color (256 colors), tiles are 8x8 pixels. Overlay: 16x16 tiles, Tile_0/1: 32x32 tiles, Sprites: 8x8 sprites.

Audio: Mono 16kHz signed 8-bit PCM. Convert with FFmpeg:

ffmpeg -i input.mp3 -ar 16000 -ac 1 -f s8 output.raw

Tilemap CSV: Comma-separated tile indices, each row is one tile row. Tile indices start at 1 (0 = empty).

Deep Dives

Complex topics are split into reference files loaded on demand from ../SKILL.md:

• Save/Load to SRAM — Persistent storage patterns, checksums, marker bytes → references/save-load.md
• Multiplayer Link Cable Protocol — Packet formats, binary I/O, client-server sync → references/multiplayer.md
• Optimization & Camera — Sprite batching, entity pools, parallax scrolling → references/optimization.md
• Error Handling — Bounds checking, validation patterns → references/error-handling.md

Best Practices

• Memory management for sprites/tilemaps: Pre-allocate entity pools to avoid runtime allocation; batch stationary sprites to reduce redraw calls; keep tile updates minimal per frame.
• Managing SRAM save limits: SRAM is only 32KB—structure save data compactly; use checksums for corruption detection; validate save data before loading.
• Fixed-point math for GBA hardware: GBA lacks FPU—use fixed-point arithmetic (e.g., multiply by 256 for 8.8 format); avoid division where possible.
• Keeping entity update loops bounded: Process only active entities; use spatial partitioning for collision checks; cap entity count at 128.
• Using the link cable protocol carefully: Keep packets under 11 bytes; process recv() in a loop to clear queue; handle disconnects gracefully.

Troubleshooting

• Emulator vs hardware differences: mGBA is accurate but timing may differ; test on real hardware for final verification.
• Sprite flickering (too many sprites per scanline): GBA has 128 sprite slots but only ~10 visible per scanline; distribute sprites vertically.
• Audio channel conflicts: Only 3 sound channels + 1 music; prioritize important sounds using the priority parameter.
• Save data corruption: Always write checksums; verify marker byte (0x42) before loading; use atomic writes (write to temp, then commit).

References

• BPCore Engine GitHub Repository
• GBA Hardware Specifications
• Tonc GBA Tutorial
• GBA Programming Wiki
• mGBA Emulator

---

Summary

This skill covers BPCore Engine development for GBA:

• API Reference: 60+ functions with signatures
• Installation & Project Structure: BPCoreEngine.gba sources, build process
• Save/Load to SRAM: Persistent storage patterns
• Multiplayer Link Cable Protocol: Packet formats, binary I/O
• Optimization Patterns: Sprite batching, entity pools, audio mixing, state machines
• Camera & Scrolling: Parallax, bounds
• Error Handling: Validation, safe operations

Refer to official repository for updates.