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
Official Repository: Clone from GitHub
git clone https://github.com/evanbowman/BPCore-Engine.git
cd BPCore-Engine
Required Files: Repository contains:
BPCoreEngine.gba - Engine base ROM (~3.5 MB)
build.lua - Build script (Lua 5.3)
test/ - Example projects
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
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.
1---2name: bpcore-engine3description: Use when building GBA games with the BPCore Lua engine - entity, sprite and tilemap functions, SRAM save and load, link cable multiplayer protocol, camera and scrolling, or optimization patterns4metadata:5 source: https://skillmd.com/skills/mte90/bpcore-engine6 author: mte907 version: 2.0.08 tags:9 - lua10 - gba11 - game-engine12 - gameboy-advance13---1415# BPCore Engine Skill1617Comprehensive guide for building Gameboy Advance games using the BPCore Engine Lua framework.1819## Overview2021BPCore 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.2223The 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.2425## API Reference2627### Entity Functions2829| Function | Signature | Description |30|----------|-----------|-------------|31| `ent()` | `ent()` | Create entity, returns handle |32| `entpos(e, x, y)` | `entpos(e, x, y)` | Set position, returns self |33| `entz(e, z)` | `entz(e, z)` | Set Z-order (0-255), returns self |34| `entspr(e, sprite, xflip, yflip)` | `entspr(e, sprite, xflip, yflip)` | Set sprite and flips, returns self |35| `entspd(e, x, y)` | `entspd(e, x, y)` | Set movement speed, returns self |36| `entslot(e, slot, value)` | `entslot(e, slot, value)` | Store in slot, returns self |37| `entslots(e, count)` | `entslots(e, count)` | Allocate slots, returns self |38| `entanim(e, start, len, rate)` | `entanim(e, start, len, rate)` | Set animation |39| `entag(e, tag)` | `entag(e, tag)` | Set collision tag, returns self |40| `enthb(e, ox, oy, w, h)` | `enthb(e, ox, oy, w, h)` | Set hitbox, returns self |41| `del(e, auto?)` | `del(e, [auto])` | Delete entity |42| `ents()` | `ents()` | Get all entities table |4344### Sprite & Tile Functions4546| Function | Signature | Description |47|----------|-----------|-------------|48| `txtr(layer_id, filename)` | `txtr(layer_id, filename)` | Load texture from file |49| `txtr(layer_id, ptr, len)` | `txtr(layer_id, ptr, len)` | Load from pointer/length |50| `file(filename)` | `file(filename)` | Get file pointer/length |51| `spr(sprite_id, x, y)` | `spr(sprite_id, x, y)` | Draw sprite |52| `spr(sprite_id, x, y, xflip, yflip)` | `spr(sprite_id, x, y, xflip, yflip)` | Draw with flips |53| `tile(layer_id, x, y, num?)` | `tile(layer_id, x, y, [num])` | Draw/read tile |54| `tilemap(f, layer, w, h, dx, dy, sx, sy)` | `tilemap(f, layer, w, h, dx, dy, sx, sy)` | Load CSV tilemap |55| `clear()` | `clear()` | Clear sprites, VSync |56| `display()` | `display()` | Send sprites to display |57| `fade(amount, color?, tl?, bg?)` | `fade(amount, [color], [tl], [bg])` | Fade layers |5859### Camera & Scroll6061| Function | Signature | Description |62|----------|-----------|-------------|63| `camera(x, y)` | `camera(x, y)` | Set camera center |64| `scroll(layer, x, y)` | `scroll(layer, x, y)` | Set layer scroll |65| `priority(s, bg, t0, t1)` | `priority(s, bg, t0, t1)` | Set render priority |6667### Collision6869| Function | Signature | Description |70|----------|-----------|-------------|71| `ecolle(e1, e2)` | `ecolle(e1, e2)` | Check collision (bool) |72| `ecoll(e, tag)` | `ecoll(e, tag)` | Find tag matches (array) |73| `enthb(e)` | `enthb(e)` | Get hitbox (getter) |7475### Input7677| Function | Signature | Description |78|----------|-----------|-------------|79| `btn(num)` | `btn(num)` | Button held? (bool) |80| `btnp(num)` | `btnp(num)` | Button pressed? (bool) |81| `btnnp(num)` | `btnnp(num)` | Button released? (bool) |8283### Graphics8485| Function | Signature | Description |86|----------|-----------|-------------|87| `print(text, x, y, fg?, bg?)` | `print(text, x, y, [fg], [bg])` | Print to overlay |8889### Audio9091| Function | Signature | Description |92|----------|-----------|-------------|93| `music(f, offset?)` | `music(f, [offset])` | Play background music |94| `sound(f, priority)` | `sound(f, priority)` | Play sound effect |9596### Memory9798| Function | Signature | Description |99|----------|-----------|-------------|100| `poke(addr, value)` | `poke(addr, value)` | Write byte |101| `poke4(addr, value)` | `poke4(addr, value)` | Write 32-bit word |102| `peek(addr)` | `peek(addr)` | Read byte |103| `peek4(addr)` | `peek4(addr)` | Read 32-bit word |104| `memput(addr, data)` | `memput(addr, data)` | Write to memory |105| `memget(addr, len?)` | `memget(addr, [len])` | Read from memory |106107### System108109| Function | Signature | Description |110|----------|-----------|-------------|111| `delta()` | `delta()` | Microseconds since last call |112| `sleep(frames)` | `sleep(frames)` | Sleep N frames |113| `startup_time()` | `startup_time()` | Get boot time |114| `fdog()` | `fdog()` | Feed watchdog timer |115| `log(msg)` | `log(msg)` | Debug log |116| `rline()` | `rline()` | Get raster line |117| `flimit(fps)` | `flimit(fps)` | Set frame rate limit |118| `next_script(filename)` | `next_script(filename)` | Switch Lua script |119120### Multiplayer121122| Function | Signature | Description |123|----------|-----------|-------------|124| `connect(timeout)` | `connect(timeout)` | Connect (blocking) |125| `disconnect()` | `disconnect()` | Disconnect |126| `send(data)` | `send(data)` | Send message (max 11 bytes) |127| `recv()` | `recv()` | Receive message |128| `send_iram(ptr)` | `send_iram(ptr)` | Send from IRAM |129| `recv_iram(ptr)` | `recv_iram(ptr)` | Receive to IRAM |130131### Layer IDs132133| ID | Layer | Size | Description |134|----|-------|------|-------------|135| 0 | Overlay | 32x32 tiles | Front, persistent |136| 1 | Tile Layer 1 | 64x64 tiles | Behind sprites, in front of tile_0 |137| 2 | Tile Layer 0 | 64x64 tiles | Main background |138| 3 | Background | 32x32 tiles | Back layer |139| 4 | Sprites | Dynamic | On-top sprites |140141## Installation & Project Structure142143### Getting BPCoreEngine.gba144145**Important**: BPCore Engine requires `BPCoreEngine.gba` base ROM with compiled C++ code and Lua interpreter. This is **not** a custom ROM you create.146147#### Where to Obtain1481491. **Official Repository**: Clone from [GitHub](https://github.com/evanbowman/BPCore-Engine)150 ```bash151 git clone https://github.com/evanbowman/BPCore-Engine.git152 cd BPCore-Engine153 ```1541552. **Required Files**: Repository contains:156 - `BPCoreEngine.gba` - Engine base ROM (~3.5 MB)157 - `build.lua` - Build script (Lua 5.3)158 - `test/` - Example projects1591603. **Alternatives**:161 - GitHub Releases may have pre-built GBA files162 - mGBA emulator includes BPCore version in some distributions163164#### File Placement165166```167your-project/168├── BPCoreEngine.gba # Base ROM (required)169├── build.lua # Build script170├── manifest.lua # Your manifest171├── overlay.bmp # Text/UI tiles172├── tile0.bmp # Main background (64x64 tiles)173├── tile1.bmp # Foreground (64x64 tiles)174├── spritesheet.bmp # Sprites (16x16)175├── music.raw # Music (mono 16kHz PCM)176├── sfx.wav # Sound effects177├── main.lua # Entry point178└── data.txt # Resources179```180181### Build Layout182183```184./185├── src/186│ ├── main.lua # Main loop187│ ├── game.lua # Game logic188│ ├── menu.lua # Menu189│ └── level1.csv # Tilemap190├── assets/191│ ├── graphics/192│ │ ├── spritesheet.bmp193│ │ ├── tiles0.bmp194│ │ └── tiles1.bmp195│ ├── audio/196│ │ ├── music.raw197│ │ ├── jump.wav198│ │ └── coin.wav199│ └── tilemaps/200│ └── world.csv201├── build.lua # Build script202├── BPCoreEngine.gba # Engine ROM203└── dist/204 └── yourgame.gba # Output205```206207### Building Your ROM208209**Step 1**: Create `manifest.lua`210211```lua212local app = {213 name = "My Adventure",214 gamecode = "ABCD",215 makercode = "BC",216 tilesets = { "overlay.bmp", "tile0.bmp", "tile1.bmp" },217 spritesheets = { "spritesheet.bmp" },218 audio = { "music.raw", "jump.wav", "coin.wav" },219 scripts = { "main.lua", "game.lua", "menu.lua" },220 misc = { "level1.csv" }221}222223return app224```225226**Step 2**: Run build script227228```bash229lua build.lua manifest.lua BPCoreEngine.gba output.gba230```231232**Step 3**: Verify233234Build checks manifest files exist, formats are valid, scripts readable, output ROM created (~3.5-4 MB).235236**Step 4**: Test with mGBA237238```bash239mGBA output.gba --log --memview240```241242`--log` shows engine log() output, `--memview` opens memory viewer for debugging.243244### File Formats245246**BMP Tilesets**: Indexed color (256 colors), tiles are 8x8 pixels. Overlay: 16x16 tiles, Tile_0/1: 32x32 tiles, Sprites: 8x8 sprites.247248**Audio**: Mono 16kHz signed 8-bit PCM. Convert with FFmpeg:249```bash250ffmpeg -i input.mp3 -ar 16000 -ac 1 -f s8 output.raw251```252253**Tilemap CSV**: Comma-separated tile indices, each row is one tile row. Tile indices start at 1 (0 = empty).254255## Deep Dives256257Complex topics are split into reference files loaded on demand from `../SKILL.md`:258259- **Save/Load to SRAM** — Persistent storage patterns, checksums, marker bytes → [`references/save-load.md`](references/save-load.md)260- **Multiplayer Link Cable Protocol** — Packet formats, binary I/O, client-server sync → [`references/multiplayer.md`](references/multiplayer.md)261- **Optimization & Camera** — Sprite batching, entity pools, parallax scrolling → [`references/optimization.md`](references/optimization.md)262- **Error Handling** — Bounds checking, validation patterns → [`references/error-handling.md`](references/error-handling.md)263264## Best Practices265266- **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.267- **Managing SRAM save limits**: SRAM is only 32KB—structure save data compactly; use checksums for corruption detection; validate save data before loading.268- **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.269- **Keeping entity update loops bounded**: Process only active entities; use spatial partitioning for collision checks; cap entity count at 128.270- **Using the link cable protocol carefully**: Keep packets under 11 bytes; process recv() in a loop to clear queue; handle disconnects gracefully.271272## Troubleshooting273274- **Emulator vs hardware differences**: mGBA is accurate but timing may differ; test on real hardware for final verification.275- **Sprite flickering (too many sprites per scanline)**: GBA has 128 sprite slots but only ~10 visible per scanline; distribute sprites vertically.276- **Audio channel conflicts**: Only 3 sound channels + 1 music; prioritize important sounds using the priority parameter.277- **Save data corruption**: Always write checksums; verify marker byte (0x42) before loading; use atomic writes (write to temp, then commit).278279## References280281- [BPCore Engine GitHub Repository](https://github.com/evanbowman/BPCore-Engine)282- [GBA Hardware Specifications](https://problemkaputt.de/gbatek.htm)283- [Tonc GBA Tutorial](https://www.coranac.com/tonc/text/)284- [GBA Programming Wiki](https://gbadev.net/)285- [mGBA Emulator](https://mgba.io/)286287---288289## Summary290291This skill covers BPCore Engine development for GBA:292293- **API Reference**: 60+ functions with signatures294- **Installation & Project Structure**: BPCoreEngine.gba sources, build process295- **Save/Load to SRAM**: Persistent storage patterns296- **Multiplayer Link Cable Protocol**: Packet formats, binary I/O297- **Optimization Patterns**: Sprite batching, entity pools, audio mixing, state machines298- **Camera & Scrolling**: Parallax, bounds299- **Error Handling**: Validation, safe operations300301Refer to [official repository](https://github.com/evanbowman/BPCore-Engine) for updates.