diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | README.md | 98 | ||||
| -rwxr-xr-x | gbctl | 2 | ||||
| -rw-r--r-- | src/main.c | 152 |
4 files changed, 198 insertions, 55 deletions
@@ -5,3 +5,4 @@ *.sav roms/ compile_commands.json +/bios/ @@ -17,14 +17,37 @@ over 2 s (~108×). Terminal resize (`SIGWINCH`) triggers a full repaint. ```sh make -./build/gbc path/to/rom.gb # interactive -./build/gbc rom.gb --test 30 # run 30s, log serial to stderr (test roms) -./build/gbc rom.gb --shot 60 out.ppm # run 60 frames, dump a PPM screenshot -./build/gbc rom.gb --sixel 3 # sixel graphics output at 3x zoom -./build/gbc rom.gb --sock # open a control/debug socket (/tmp/gbc.sock) -./build/gbc rom.gb --headless # no video; serial <-> stdio (OS console) +./build/gbc path/to/rom.gb # interactive (ROM is the final argument) +./build/gbc --test 30 rom.gb # run 30s, log serial to stderr (test roms) +./build/gbc --shot 60 out.ppm rom.gb # run 60 frames, dump a PPM screenshot +./build/gbc --sixel 3 rom.gb # sixel graphics output at 3x zoom +./build/gbc --sixel 3 --chrome rom.gb # ...wrapped in a Game Boy body/frame +./build/gbc --bios rom.gb # boot through the BIOS before the game +./build/gbc --sock rom.gb # open a control/debug socket (/tmp/gbc.sock) +./build/gbc --headless rom.gb # no video; serial <-> stdio (OS console) +./build/gbc --help # full option list ``` +### Boot ROM / BIOS (`--bios`) + +By default the emulator skips the boot ROM and starts the cartridge directly +with the documented post-boot register state. Pass `--bios [path]` to instead +run a real boot ROM first, so you get the authentic power-on animation (the +Nintendo logo drop, and on a CGB the color splash + chime) before control is +handed to the game: + +```sh +./build/gbc --bios roms/pky.gbc # defaults to bios/gbc_bios.bin +./build/gbc --bios path/to/boot.bin roms/pky.gbc +./build/gbc --bios --sixel 3 --chrome roms/pky.gbc # boot inside the shell +``` + +The boot ROM is mapped over low memory (with the CGB header hole at +`0x0100-0x01FF` where the cartridge shows through) and unmaps itself when the +ROM writes `0xFF50`, exactly like hardware. A 256-byte image boots as DMG; a +2304-byte image (like the bundled `bios/gbc_bios.bin`) boots as CGB — which +also colorizes plain DMG games via the boot ROM's compatibility palette. + ### Headless serial console (`--headless`) For bring-up and debugging of an OS/monitor running on the emulated Game Boy, @@ -39,10 +62,10 @@ Emulation is paced to native speed by default; add `--uncapped` to run flat out. Because it's plain stdio it pipes and scripts cleanly: ```sh -./build/gbc os.gb --headless # interactive byte console -./build/gbc os.gb --headless --uncapped # as fast as possible -printf 'ls\n' | ./build/gbc os.gb --headless # feed input, capture output -./build/gbc os.gb --headless | tee session.log +./build/gbc --headless os.gb # interactive byte console +./build/gbc --headless --uncapped os.gb # as fast as possible +printf 'ls\n' | ./build/gbc --headless os.gb # feed input, capture output +./build/gbc --headless os.gb | tee session.log ``` The serial console model matches what a GB program expects: write the byte to @@ -60,8 +83,8 @@ mlterm, Contour, recent iTerm2, etc.) pass `--sixel [scale]` to render true pixels instead of half-blocks: ```sh -./build/gbc rom.gb --sixel # default 2x zoom (320×288 pixels) -./build/gbc rom.gb --sixel 4 # 4x zoom +./build/gbc --sixel rom.gb # default 2x zoom (320×288 pixels) +./build/gbc --sixel 4 rom.gb # 4x zoom ``` Each frame builds a per-frame palette from the framebuffer (≤256 entries — 4 @@ -71,6 +94,39 @@ run-length encoding. `scale` is an integer pixel zoom (1–6). Sixel frames are sent in full (no inter-frame diffing), so combine with `--frameskip` on slower terminals. +#### Game Boy chrome + +Add `--chrome` (sixel only) to draw a DMG-style **sl0pboy** handheld around the +LCD — screen bezel with accent stripe, power LED, silk-screened branding +(`sl0pboy` logo, `DOT MATRIX WITH STEREO SOUND`, button labels), a D-pad, A/B +buttons, Start/Select and a speaker grille. The controls light up while the +matching button is held, so it doubles as an on-screen input display: + +```sh +./build/gbc --sixel 3 --chrome rom.gb +``` + +The shell is drawn with flat colors so it adds only a handful of palette +entries. It composites into a larger canvas (240×342 px before scaling), so a +given `scale` produces a proportionally bigger image than the bare LCD. + +#### LCD palette (`--palette`) + +By default the LCD shows the game's true colors (the greenish DMG shades, or +full CGB color). Pass `--palette NAME` to remap every LCD pixel to a 4-shade +palette by luminance for the classic monochrome-LCD look — this even greens +out full-color CGB games for that retro vibe: + +```sh +./build/gbc --sixel 3 --chrome --palette dmg rom.gb # classic DMG-01 pea green +./build/gbc --sixel 3 --green rom.gb # alias for --palette dmg +./build/gbc --palette gray rom.gb # GB-Pocket grayscale +``` + +Names: `dmg`/`green` (the iconic `#9bbc0f` pea-green ramp) and `pocket`/`gray` +(grayscale). The recolor applies to every render path — half-block, sixel and +chrome — and only touches the LCD, not the drawn shell. + ### Speed & frame skipping The emulator always advances every Game Boy frame at the correct rate, so @@ -80,9 +136,9 @@ frame skipping — the machine keeps running in real time while the terminal is refreshed less often: ```sh -./build/gbc rom.gb --frameskip 2 # emulate 60 fps, draw every 3rd frame (20 fps) -./build/gbc rom.gb --fps 120 # run the game at 2x speed -./build/gbc rom.gb --uncapped # run as fast as possible (turbo) +./build/gbc --frameskip 2 rom.gb # emulate 60 fps, draw every 3rd frame (20 fps) +./build/gbc --fps 120 rom.gb # run the game at 2x speed +./build/gbc --uncapped rom.gb # run as fast as possible (turbo) ``` | Flag | Meaning | @@ -119,7 +175,7 @@ can send true key-**release** events, so it gives deterministic input for scripting and automated testing. ```sh -./build/gbc rom.gb --fifo /tmp/gbc.fifo & +./build/gbc --fifo /tmp/gbc.fifo rom.gb & echo 'a' > /tmp/gbc.fifo # momentary tap of A echo 'start' > /tmp/gbc.fifo # tap Start echo '+left' > /tmp/gbc.fifo # press and HOLD Left @@ -153,7 +209,7 @@ pushes asynchronous events when execution stops. Connect any line-oriented client: ```sh -./build/gbc rom.gb --sock /tmp/gbc.sock & +./build/gbc --sock /tmp/gbc.sock rom.gb & socat - UNIX-CONNECT:/tmp/gbc.sock # interactive # or: nc -U /tmp/gbc.sock ``` @@ -190,7 +246,7 @@ or decimal; **memory bytes are hex** (so `read` output feeds straight back into ### Video capture & input replay (demo GIFs) -Capture the RGB framebuffer to a flat file and turn it into a GIF: +Capture the displayed frame to a flat file and turn it into a GIF: ``` ./gbctl record start /abs/out.gbv 2 # capture 1 of every 2 frames (~30fps) @@ -199,6 +255,12 @@ Capture the RGB framebuffer to a flat file and turn it into a GIF: python3 tools/gbgif.py out.gbv out.gif --scale 3 ``` +Recording captures exactly what's on screen: if the emulator was started with +`--palette` and/or `--chrome`, those are baked into the capture (the `.gbv` +header records the resulting dimensions, so e.g. chrome frames are 240×362 and +`gbgif.py` picks that up automatically). `--shot` screenshots honor the same +options. Start without them for the bare 160×144 true-color LCD. + Drive the ROM from a **synthesized input movie** instead of live input, for reproducible demos. A movie is a text file of `<frames> [buttons...]` lines (`a b start select up down left right`; none/`-` = released); the emulator @@ -200,7 +200,7 @@ def cmd_spawn(argv): if "TMUX" not in os.environ: die("not inside tmux; gbctl spawn needs a tmux session") - cmd = [BIN, rom, "--sock", sock_path] + emu_args + cmd = [BIN, "--sock", sock_path] + emu_args + [rom] # ROM is the final arg # exec via a shell wrapper so the pane stays around & shows a title shell_cmd = "printf '\\033]2;gbc %s\\007'; exec %s" % ( os.path.basename(rom), " ".join(_shquote(c) for c in cmd)) @@ -44,15 +44,59 @@ static u8 keys_mask(const char *keys, int frame) { } } +static void print_usage(FILE *out, const char *prog) { + fprintf(out, +"usage: %s [options] <rom>\n" +"\n" +"Emulate a Game Boy / Game Boy Color ROM. The ROM path is the final\n" +"argument; all options precede it.\n" +"\n" +"display:\n" +" --sixel [scale] sixel graphics output; scale = pixel zoom 1-6 (def 2)\n" +" --chrome draw a Game Boy body around the LCD (sixel display)\n" +" --palette NAME recolor the LCD: dmg|green (pea green), pocket|gray\n" +" --green alias for --palette dmg\n" +" --frameskip N draw 1 of every (N+1) frames\n" +"\n" +"speed:\n" +" --fps N emulation speed cap in frames/sec (default 59.73)\n" +" --uncapped run as fast as possible (alias: --turbo)\n" +"\n" +"boot:\n" +" --bios [path] run a boot ROM first (default bios/gbc_bios.bin)\n" +"\n" +"control channels:\n" +" --fifo [path] button-input named pipe (default /tmp/gbc.fifo)\n" +" --sock [path] control/debug socket (default /tmp/gbc.sock)\n" +"\n" +"headless & testing:\n" +" --headless no video; wire serial <-> stdio (OS console)\n" +" --test [seconds] run N seconds then exit, logging serial (default 30)\n" +" --shot N [file] run N frames, write a PPM screenshot (default shot.ppm)\n" +" --keys STR scripted button taps: u d l r a b s(elect) e(start) .\n" +"\n" +" -h, --help show this help and exit\n", + prog); +} + int main(int argc, char **argv) { - if (argc < 2) { - fprintf(stderr, "usage: %s <rom> [--test seconds] [--sixel [scale]] " - "[--frameskip n] [--fps n] [--uncapped] [--fifo [path]] " - "[--sock [path]] [--headless]\n", - argv[0]); + const char *prog = argv[0]; + // --help / -h anywhere on the line wins. + for (int i = 1; i < argc; i++) + if (!strcmp(argv[i], "-h") || !strcmp(argv[i], "--help")) { + print_usage(stdout, prog); + return 0; + } + if (argc < 2) { print_usage(stderr, prog); return 1; } + + // The ROM is the final argument; everything before it is an option. + const char *rom = argv[argc - 1]; + if (rom[0] == '-') { + fprintf(stderr, "%s: no ROM specified (it must be the final argument)\n\n", + prog); + print_usage(stderr, prog); return 1; } - const char *rom = argv[1]; bool test = false; double seconds = 30.0; int shot_frames = -1; @@ -63,41 +107,76 @@ int main(int argc, char **argv) { int frameskip = 0; // draw 1 of every (frameskip+1) frames bool sixel = false; // use sixel graphics output int sixel_scale = 2; // integer pixel zoom for sixel + bool chrome = false; // draw a Game Boy body around the LCD (sixel) + const char *palette = NULL; // LCD recolor: dmg/green, pocket/gray, or off bool headless = false; // no video; serial <-> stdio (OS debug console) + const char *bios_path = NULL; // boot ROM to run before the cartridge const char *keys = NULL; // scripted button taps for testing (u d l r a b s e .) - for (int i = 2; i < argc; i++) { - if (!strcmp(argv[i], "--test")) { + + // Parse options in argv[1 .. argc-2]; the final argument is the ROM and is + // excluded here so options with optional values never swallow it. + for (int i = 1; i < argc - 1; i++) { + const char *a = argv[i]; + // A value is available only if the next token is still within the + // option range (not the ROM) and isn't itself an option. + bool has_val = (i + 1 < argc - 1) && argv[i+1][0] != '-'; + if (!strcmp(a, "--test")) { test = true; - if (i + 1 < argc) seconds = atof(argv[++i]); - } else if (!strcmp(argv[i], "--shot")) { - if (i + 1 < argc) shot_frames = atoi(argv[++i]); - if (i + 1 < argc && argv[i+1][0] != '-') shot_path = argv[++i]; - } else if (!strcmp(argv[i], "--keys")) { - if (i + 1 < argc) keys = argv[++i]; - } else if (!strcmp(argv[i], "--fifo")) { - fifo_path = (i + 1 < argc && argv[i+1][0] != '-') - ? argv[++i] : "/tmp/gbc.fifo"; - } else if (!strcmp(argv[i], "--sock") || !strcmp(argv[i], "--socket")) { - sock_path = (i + 1 < argc && argv[i+1][0] != '-') - ? argv[++i] : "/tmp/gbc.sock"; - } else if (!strcmp(argv[i], "--fps")) { - if (i + 1 < argc) target_fps = atof(argv[++i]); - } else if (!strcmp(argv[i], "--frameskip")) { - if (i + 1 < argc) frameskip = atoi(argv[++i]); - } else if (!strcmp(argv[i], "--sixel")) { + if (has_val) seconds = atof(argv[++i]); + } else if (!strcmp(a, "--shot")) { + if (!has_val) { fprintf(stderr, "%s: --shot needs a frame count\n", prog); return 1; } + shot_frames = atoi(argv[++i]); + if ((i + 1 < argc - 1) && argv[i+1][0] != '-') shot_path = argv[++i]; + } else if (!strcmp(a, "--keys")) { + if (!has_val) { fprintf(stderr, "%s: --keys needs a value\n", prog); return 1; } + keys = argv[++i]; + } else if (!strcmp(a, "--fifo")) { + fifo_path = has_val ? argv[++i] : "/tmp/gbc.fifo"; + } else if (!strcmp(a, "--sock") || !strcmp(a, "--socket")) { + sock_path = has_val ? argv[++i] : "/tmp/gbc.sock"; + } else if (!strcmp(a, "--fps")) { + if (!has_val) { fprintf(stderr, "%s: --fps needs a value\n", prog); return 1; } + target_fps = atof(argv[++i]); + } else if (!strcmp(a, "--frameskip")) { + if (!has_val) { fprintf(stderr, "%s: --frameskip needs a value\n", prog); return 1; } + frameskip = atoi(argv[++i]); + } else if (!strcmp(a, "--sixel")) { sixel = true; - if (i + 1 < argc && argv[i+1][0] != '-') sixel_scale = atoi(argv[++i]); - } else if (!strcmp(argv[i], "--uncapped") || !strcmp(argv[i], "--turbo")) { + if (has_val) sixel_scale = atoi(argv[++i]); + } else if (!strcmp(a, "--chrome")) { + chrome = true; + } else if (!strcmp(a, "--palette")) { + palette = has_val ? argv[++i] : "dmg"; + } else if (!strcmp(a, "--green")) { + palette = "dmg"; + } else if (!strcmp(a, "--uncapped") || !strcmp(a, "--turbo")) { target_fps = 0; - } else if (!strcmp(argv[i], "--headless")) { + } else if (!strcmp(a, "--headless")) { headless = true; + } else if (!strcmp(a, "--bios") || !strcmp(a, "--boot")) { + bios_path = has_val ? argv[++i] : "bios/gbc_bios.bin"; + } else { + fprintf(stderr, "%s: unknown option '%s'\n\n", prog, a); + print_usage(stderr, prog); + return 1; } } if (frameskip < 0) frameskip = 0; GB *gb = calloc(1, sizeof(GB)); if (cart_load(&gb->cart, rom) != 0) { free(gb); return 1; } + if (bios_path && gb_load_bootrom(gb, bios_path) != 0) { + cart_free(&gb->cart); free(gb); return 1; + } gb_reset(gb); + if (bios_path) + fprintf(stderr, "booting through BIOS: %s\n", bios_path); + + // Display/capture options that also affect screenshots and video recording, + // so set them before the --shot / recording paths. (--sixel below is purely + // a live-display concern.) + if (palette) render_set_palette(palette); + if (chrome) render_set_chrome(true); if (test) { gb->serial_log = true; @@ -161,11 +240,10 @@ int main(int argc, char **argv) { } if (raw_tty) tcsetattr(STDIN_FILENO, TCSANOW, &saved_tio); if (shot_frames >= 0) { // --headless --shot FILE: dump final LCD + int cw, ch; const u8 *cap = render_capture_frame(gb, &cw, &ch); FILE *pf = fopen(shot_path, "wb"); - fprintf(pf, "P6\n%d %d\n255\n", SCREEN_W, SCREEN_H); - for (int y = 0; y < SCREEN_H; y++) - for (int x = 0; x < SCREEN_W; x++) - fwrite(gb->ppu.fb[y][x], 1, 3, pf); + fprintf(pf, "P6\n%d %d\n255\n", cw, ch); + fwrite(cap, 1, (size_t)cw * ch * 3, pf); fclose(pf); } cart_free(&gb->cart); free(gb); return 0; @@ -173,11 +251,10 @@ int main(int argc, char **argv) { if (shot_frames >= 0) { for (int f = 0; f < shot_frames; f++) run_frame(gb); + int cw, ch; const u8 *cap = render_capture_frame(gb, &cw, &ch); FILE *pf = fopen(shot_path, "wb"); - fprintf(pf, "P6\n%d %d\n255\n", SCREEN_W, SCREEN_H); - for (int y = 0; y < SCREEN_H; y++) - for (int x = 0; x < SCREEN_W; x++) - fwrite(gb->ppu.fb[y][x], 1, 3, pf); + fprintf(pf, "P6\n%d %d\n255\n", cw, ch); + fwrite(cap, 1, (size_t)cw * ch * 3, pf); fclose(pf); fprintf(stderr, "wrote %s after %d frames\n", shot_path, shot_frames); cart_free(&gb->cart); free(gb); return 0; @@ -198,6 +275,9 @@ int main(int argc, char **argv) { sock_path); } if (sixel) render_set_sixel(true, sixel_scale); + if (chrome && !sixel) + fprintf(stderr, "note: --chrome only affects live display in --sixel mode " + "(it still applies to --shot / recordings)\n"); term_init(); // The emulator always advances every GB frame at the paced native rate so |