NAME

Same::Boy::Terminal - playable truecolor terminal frontend for Same::Boy

SYNOPSIS

use Same::Boy::Terminal;

my $term = Same::Boy::Terminal->new(
    rom_path => 'game.gbc',
    scale    => 1,
    model    => 'cgb',
);

my $had_battery = $term->run;
print "saved battery to ${\ $term->sav_path}\n" if $had_battery;

DESCRIPTION

Same::Boy::Terminal renders the 160x144 Game Boy screen into a truecolor terminal using Unicode upper-half-block characters (one cell = two vertically stacked pixels) and drives Same::Boy from raw-mode keyboard input. It has no GUI dependencies.

Battery-backed cartridge RAM is loaded from <rom_path>.sav at start and flushed back on every exit path (quit, Ctrl-C, SIGTERM, terminal close). Save states are written to and read from <rom_path>.state.

A truecolor terminal is required; a wide one (>= 160 columns) for scale 1, or use scale => 2 (80 columns).

ATTRIBUTES

rom_path

Path to the ROM to load. Required.

scale

Integer downscale factor for the display (default 1). Values below 1 are treated as 1.

model

Game Boy model passed to Same::Boy (default cgb).

sav_path / state_path

Derived from rom_path (.sav and .state suffixes).

METHODS

run

Enter raw mode and run the emulator loop until the user quits. Restores the terminal and flushes battery RAM on exit. Returns true if the cartridge had battery-backed RAM.

Controls

Arrow keys / WASD .. D-pad        z .. B        x / space .. A
Enter .. Start                    \ .. Select
[ .. save state   ] .. load state
- / = .. slower / faster          r .. reset     q .. quit

AUTHOR

LNATION <email@lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under the Artistic License 2.0.