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
# edit game.c   (optional: rename the output .elf via EE_BIN in the Makefile)

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 (3D), examples/life (Game of Life, the e_image_draw grid pattern), examples/jsport (a ported JS game).

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. AGENTS.md is the complete API, build, run, and conventions. An agent reads it, copies examples/template, and emits a game.
• A skill. skills/make-ps2-game scaffolds, builds, and verifies a game.
• A built-in verdict loop. make test builds the ELF, boots it headless, and prints RENDER: PASS/FAIL, so the loop is edit, 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.