NAME
Same::Boy - Game Boy and Game Boy Color emulator (SameBoy Core) for Perl
VERSION
Version 0.01
SYNOPSIS
use Same::Boy;
my $gb = Same::Boy->new(
model => 'cgb',
rom => 'game.gbc',
sample_rate => 44100,
);
for (1 .. 60) {
$gb->run_frame;
}
my ($w, $h) = $gb->dimensions; # 160, 144
my $frame = $gb->pixels; # packed 0x00RRGGBB words
my $audio = $gb->samples; # interleaved s16 L,R
$gb->press('a')->run_frame;
$gb->release('a');
# persistence
my $sram = $gb->save_battery; # cartridge save RAM
my $state = $gb->save_state; # full snapshot
$gb->load_state($state);DESCRIPTION
Same::Boy wraps the Core of SameBoy, a highly accurate Game Boy and Game Boy Color emulator, and exposes a Perl API for loading ROMs, stepping frames, reading video and audio, sending input, applying cheats, and saving/restoring state.
The SameBoy Core is vendored and compiled into the extension; there are no external library dependencies. SameBoy's own MIT-licensed open-source boot ROMs are embedded, so the emulator boots out of the box with no copyrighted files and no build time toolchain.
CONSTRUCTOR
new(%args)
my $gb = Same::Boy->new(model => 'cgb', rom => 'game.gbc');Options: model (one of dmg, mgb, sgb, sgb2, cgb; default cgb), rom and boot_rom (a path or a scalar reference of bytes), and sample_rate (enable audio at the given rate in Hz).
EXECUTION
run_frame
Run until the next V-Blank (one frame). Returns cycles executed.
run
Run a single Core step. Returns cycles executed.
reset
Reset the console.
set_clock_multiplier($multiplier)
Scale emulation speed (e.g. 2.0 for double speed).
set_turbo($on, $no_frame_skip)
Enable/disable turbo mode.
set_rtc_mode($mode)
Set real-time-clock behaviour for RTC cartridges (MBC3): sync_to_host or accurate.
INTROSPECTION
model
The model string passed to the constructor.
is_cgb / is_sgb
Booleans for the emulated hardware family.
rom_title
The cartridge's internal title (up to 16 chars).
rom_crc32
CRC-32 of the loaded ROM.
VIDEO
dimensions
Return ($width, $height) in pixels.
pixels
The current framebuffer: a packed string of native-endian uint32 words in 0x00RRGGBB form, $width * $height of them.
pixels_rgba
The current framebuffer as tightly-packed R,G,B,A bytes (alpha always 255), $width * $height * 4 of them. Ready to drop into a JavaScript ImageData buffer for canvas rendering.
set_color_correction($mode)
One of disabled, correct_curves, modern_balanced, modern_boost_contrast, reduce_contrast, low_contrast, modern_accurate.
set_dmg_palette($name)
For monochrome models, choose a built-in palette: grey, dmg, mgb, or gbl.
AUDIO
set_sample_rate($hz)
Enable audio capture at $hz (0 disables).
set_highpass_filter($mode)
One of off, accurate, remove_dc_offset.
samples
Return and clear captured audio as interleaved signed 16-bit little-endian left/right pairs. Call after run_frame.
INPUT
press($button) / release($button)
$button is one of up, down, left, right, a, b, start, select.
press_for_player / release_for_player($button, $player)
As above for SGB multiplayer ($player from 0).
set_key_mask($mask)
Set all buttons at once from an OR of the exportable KEY_* constants.
PERSISTENCE
save_battery / load_battery($src)
Cartridge battery-backed save RAM as bytes. save_battery returns undef if the cartridge has none. load_battery accepts a path or scalar ref.
save_battery_to_file($path) / load_battery_from_file($path)
save_state / load_state($src)
Full emulator snapshot (SameBoy BESS format). load_state croaks on error.
save_state_to_file($path) / load_state_from_file($path)
REWIND
set_rewind_length($seconds)
Allocate a rewind buffer of the given duration (0 disables).
rewind
Step back one rewind slot; returns true if a previous state was restored.
CHEATS
import_cheat($code, %opts)
Import a Game Genie or GameShark code. Options: description, enabled (default true). Returns true on success.
set_cheats_enabled($bool) / cheats_enabled
remove_all_cheats
AUTHOR
LNATION <email@lnation.org>
ACKNOWLEDGEMENTS
Emulation Core by Lior Halphon (SameBoy), used under the Expat (MIT) license. See LICENSE.SameBoy.
LICENSE AND COPYRIGHT
This software is Copyright (c) 2026 by LNATION.
This is free software, licensed under the Artistic License 2.0.