Build PlayStation 2 games in one C file. Tiny, readable C. One header, ~20 core functions, 2D and 3D. The entire engine fits on a single page ( AGENTS.md), so an AI agent (or you) can write, build, and run a real PS2 game from one read. Builds with the open
ps2dev
toolchain; runs in the Play! emulator (no BIOS needed) and on
real PS2 hardware.
a 60fps 3D cellular automaton, running on a PlayStation 2
Cyclic CA | Reaction-diffusion | Physarum (slime mold) | Multi-neighborhood CA | Gray-Scott coral | 3D cellular automaton |
Six of the sixteen systems in the showcase app ( emergent-systems-ps2), all real PS2 output.
#include "engine.h"
typedef struct { int x, y; } Game;
static void init (void *s, Ctx *c){ Game *g=s; g->x=160; g->y=120; }
static void update(void *s, Ctx *c){ Game *g=s; if (ctx_is_held(c,BTN_LEFT)) g->x--; }
static void render(void *s, Ctx *c){ Game *g=s; e_rect(c, g->x,g->y, 12,12, 255,90,90); }
int main(void){
static Game g;
Scene sc = { .state=&g, .init=init, .update=update, .render=render };
app_run(config_default(), &sc); /* engine owns the loop, GS, pad, timing */
}
3D is three calls:
e3d_begin(c, yaw, pitch);
for (...) e3d_voxel(x,y,z, r,g,b);
e3d_end(c);
1. Toolchain (one time, no sudo):
tools/bootstrap.sh # downloads the prebuilt ps2dev toolchain
Export the PS2DEV
/ PS2SDK
/ GSKIT
PATH
lines it prints.
2. Make your game:
cp -r examples/template mygame
cd mygame
3. Build, run, test:
make # -> game.elf (a genuine MIPS R5900 / Emotion Engine executable)
make run # boot it in the Play! emulator
make test # build -> boot headless -> prints "RENDER: PASS|FAIL" + exit code
4. Play it for real: copy game.elf
to a USB stick / memory card and launch it on a PlayStation 2 via FMCB or wLaunchELF.
Examples: examples/template (2D),
examples/spin3d
examples/life
e_image_draw
grid pattern), (a ported JS game).
examples/jsport
Don't want to think about make
? Use the bundled forge
CLI:
./forge doctor # check your toolchain is ready
./forge new mygame # scaffold a new game in ./mygame
./forge build # compile the game in this folder -> .elf
./forge run # build + boot it in the emulator
./forge test # build + boot headless + print RENDER: PASS/FAIL
./forge play spin3d # build + run a bundled example
./forge gui # open a web dashboard to browse + preview games
forge gui
serves a local dashboard (http://localhost:8090) that lists every
example and, on click, builds it, boots it headless, and shows the actual
rendered PS2 frame plus a PASS/FAIL verdict. The fastest way to see what the
engine does. (The headless preview/test needs Play!
, Xvfb
, and a Python with
mss
Pillow
; on a remote box, tunnel the port: ssh -L 8090:localhost:8090 <host>
.)
2D: filled rects, an alpha-tested font atlas (e_text
), rotated quads,
textured sprites, a dynamic framebuffer blit (e_image_draw
, for cellular
automata / software renderers), and a hardware scissor.
3D: a software voxel renderer (e3d_*
), depth-sorted, one blit, 60fps. Plus D-pad/button input and ADPCM sound effects.
Full API + conventions on one page: .
AGENTS.md
One contract. is the complete API, build, run, and conventions. An agent reads it, copiesAGENTS.md
examples/template
, and emits a game.A skill. scaffolds, builds, and verifies a game.skills/make-ps2-game
A built-in verdict loop.make test
builds the ELF, boots it headless, and printsRENDER: PASS/FAIL
, so the loop isedit, one command, verdict, no eyeballing.
Most agent-made games are HTML5-canvas or p5.js. Include engine/canvas.h and the calls line up nearly 1:1:
cv_fill(90,200,255); cv_rect(x,y,8,8); // ctx.fillStyle + ctx.fillRect
cv_text(8,8,"SCORE"); // ctx.fillText
if (cv_key(BTN_LEFT)) x--; // keyIsDown(LEFT_ARROW)
Full mapping table + a worked example: PORTING.md and the
port-js-to-ps2
skill.emergent-systems-ps2: sixteen cellular automata / emergent systems (the GIFs above), including a 60fps 3D one, running on real PS2 hardware.
PRs welcome. See CONTRIBUTING.md for the build setup, the one-file-game convention, the
make test
verdict, and code style (notably: no em dashes). CI builds every example on each push.Engine code: MIT. Built on PS2SDK and gsKit (ps2dev): their licenses apply to them.