bm — BareMetal Console & Game Engine

---

🚀 Overview

bm (BareMetal) is an open-source games console and development environment. It runs on the Raspberry Pi Zero W (main target, also the other Pi 1 boards) and on the PowKiddy RGB30 (make TARGET=rgb30) with no underlying operating system. The Pi Zero 2 W kernel (kernel7.img) is off in the default build.

Power on and the console boots straight into the games menu. Games are written in Lua 5.4, powered by a custom bare-metal runtime with 2D and 3D pipelines, V3D hardware rendering on the Pi, a polyphonic synthesizer, network multiplayer, and an on-device creative suite.

---

✨ Key Features

• True Bare Metal Architecture:
  • kernel.img (C, ARM assembly, and Lua 5.4) communicates directly with hardware registers. Size on 25 Oct 2026: about 4.5 MB for the Pi (kernel.img, with the editors built in) and about 2.3 MB for the RGB30 (kernel8.img).
  • No Linux kernel, background daemons, or OS scheduler: the 1 GHz core and the ARM share of the 512 MB RAM belong to your game frame (the share is read from the firmware: 448 MB with gpu_mem=64, see docs/HARDWARE.md).
• Hardware & Peripherals:
  • Video: HDMI output at 640×360, 480×270, 320×180, 256×256, 360×360 or 720×720 per cartridge, scaled up by the HDMI scaler (docs/RISOLUZIONI.md).
  • Audio: 8-voice polyphonic synthesizer with HDMI digital audio output.
  • Inputs: USB keyboards, gamepads and mice, and Bluetooth (up to 4 DualShock 4 controllers, a BLE keyboard, a mouse).
  • Connectivity: WiFi with HTTPS, local UDP multiplayer, and FAT32 SD card file system.
• Cartridge System (.bm):
  • A cartridge is one file in the bm/ folder of the SD card: Lua source, sprite sheets, tile maps, 3D meshes, skeletal animations and sound banks (docs/BM-FORMAT.md).
  • A .bm runs on the Pi Zero W and on the RGB30. Its header lists the kernels it runs on (the targets key in bm.info). A cartridge made for the other device shows a faded cover. The design is in docs/design/single-bm-and-adaptive-screen.md.
  • PICO-8 carts (.p8, .p8.png) play through the built-in nano8 cartridge.
• On-Console Creative Suite:
  • Code, draw, sculpt 3D models, rig skeletons, compose music, and test games directly on the console with no PC required.

local x = 320
function _update()                       -- 60 fps fixed update
  if btn(0) then x = x - 2 end           -- Left pad / arrow
  if btn(1) then x = x + 2 end           -- Right pad / arrow
end

function _draw()
  cls(0x102030)
  spr(1, x, 180)                         -- Draw sprite from cartridge sheet
end

---

⚡ Performance Highlights

Hardware target: Raspberry Pi Zero W (ARM1176 @ 1.0 GHz, VideoCore IV V3D GPU). All numbers are from the 3D Bench reports of 22 and 24 Oct 2026, at 640×360 RGB565, and show what one 60 fps frame (16.6 ms) holds. The full tables, with the report of each number, are in docs/PERF-BUDGET.md. RGB30: not verified on hardware with the current drivers.

Thing	One 60 fps frame holds
Map layer, opaque, full screen (8×8 tiles)	5 layers (3.08 ms each)
Sprites 16×16, ARM	2,574
Sprites 16×16, GPU in the 2D job	3,569 or more
Hero of 1,536 triangles, GPU with vertex shader	66
Spheres of 96 faces, GPU with vertex shader	783
Draw calls (one cube each), GPU with vertex shader	1,386
Hero sets with map, 2D and logic (herotris), GPU + vertex shader + queue	49,956 triangles (13.7 ms)
Hero Stress, 640×360, animated heroes	50 heroes, 52,992 triangles (59-60 fps)
Hero Stress, 1080p	24 heroes, 27,408 triangles (60 fps)

The same herotris scene on the ARM rasterizer holds 2,385 triangles (40.8 ms).

🚀 3D Engine & Architecture (bm3d & V3D Driver)

bm integrates bm3d (version 7.7 in src/gpu/version3d.h), a dual-path 3D engine:

• GPU Path (V3D Hardware - Default) (gpu3d): the V3D fills pixels with custom QPU assembly shaders (tools/qpuasm.py) at 811 Mpixel/s (full-screen render only). The vertex shader (gpu3d_vs, default 2) places the corners on the GPU. 4× MSAA is available (gpu3d_aa, off by default). The 2D draws in the same GPU job (gpu3d_2d, on by default).
• ARM Fallback Rasterizer (r3d): software rasterizer with per-face LOD, screen-door transparency, and planar shadows, used when the GPU is absent or in emulators.
• Settings > Screen shows two graphics rows: 3D of the games (gpu3d) and 3D on the ARM (r3d_fast). Every other graphics key is set in config.txt (docs/progress/v3d-flags.md).

🎯 Measure it yourself

• 3D Bench (C, in the kernel: Settings > System > Utilities on the Pi, the Dev tab on the RGB30, or the j key of the monitor) runs every 3D test with every driver and saves a report on the SD card (docs/BENCH3D.md).
• 3D Bench for the Market (carts/bench3d): a Lua edition. It has its own numbers, not comparable with the C bench.
• Hero Stress (carts/hero): a plaza with walking heroes. Change the hero count, the polygon level and the 3D options in real time, and read the cost.
• bm Web (carts/bmweb): 723 frames at 59.6 fps on the Pi Zero W, no late frame (report of 24 Oct, docs/PERF-BUDGET.md).

Older measurements (Sep-Oct 2026) stay as history in docs/GPU-BENCHMARK-REPORT.md, docs/PERFORMANCE.md and docs/STRESS.md. The tools they used (stress test, Texture Room, Stack bench, GPU test) were removed from the kernel on 24 Oct 2026.

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗