rubyboy 1.5.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22c8e1f0094ec086f0e7130e6c79623d0e9385c718f0724ca2773c101ff3b976
-  data.tar.gz: 49adde27b593ef7bf8bf3f874160922ed7994388960db71f5757b2cbf033735f
+  metadata.gz: '09e12943a26b3089da7e75f3a26a0994dd71c1a748b63c840c49c3772502b625'
+  data.tar.gz: c37fdfa6182bb28cbca6ffe5438670860e0e6c10e32b581509dbfca28e12f70d
 SHA512:
-  metadata.gz: 48abbc79e8dde1e691f3f76a2736ad909b29af549c3c3b6a99eedd16a5b832f8b84bfb810ed4115483e116f5acbd50e1b07ec333e61778dc82433293f36a8401
-  data.tar.gz: dcf874037cd1d133687e3a99c5aeb36d97cd8a8f356514bb97b40eec57184b3bed7bd003538925fce18875d13d8bd37e1f50ffdd646568b5fbc351925f710a5a
+  metadata.gz: 35c057be65b5b1143d870d6db5d8a0b769074e42c10281680b411e1d348f2b8b5109ff12dcddae3ca3b803b6a379fff4f7343fd0e16b111e25686d25d5468861
+  data.tar.gz: 900d258e730fdd03f23b508d1ff4cfd3e80b738ebf0c9ce49e6a064faeb0456a01be84bab269d62f59bcb7895d25b1dfeb08d41a2d39c0fabce4b52427d63a91

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [1.6.0] - 2026-10-04
+
+- Add battery-backed saves and hardware-oriented save states
+- Fix MBC1 ROM bank mapping, external RAM size and RAM banking
+- Fix audio drop-outs and APU sample-rate drift
+- Support Spinel compilation and fix SDL event allocation
+- Add --frames, --unlimited and --no-audio player options
+- Add benchmark warmup, SDL rendering and JSON output
+- Disable VSync for rendered benchmarks and require SDL 2.0.18 or higher
+- Update JSON and development dependencies for recent Ruby versions
+
 ## [1.5.1] - 2025-02-16
 
 - Optimize Cartridge::Mbc1 and Bus

data/README.md

@@ -15,7 +15,7 @@ A Game Boy emulator written in Ruby
 </div>
 
 ## Requirements
-[SDL2](https://wiki.libsdl.org/SDL2/Installation)
+[SDL2](https://wiki.libsdl.org/SDL2/Installation) 2.0.18 or higher.
 
 ## Installation
 
@@ -47,6 +47,62 @@ If bundler is not being used to manage dependencies, install the gem by executin
 | `U`   | Select |
 | `I`   | Start  |
 
+## Bounded execution
+
+The player accepts `--frames N` to stop after N completed frames, `--no-audio`
+to disable audio output while continuing APU emulation, and `--unlimited` to
+disable real-time synchronization:
+
+```sh
+bundle exec ruby --yjit -Ilib exe/rubyboy --frames 600 --unlimited --no-audio lib/roms/tobu.gb
+```
+
+Normal playback remains synchronized to real time with audio enabled.
+`--unlimited` alone still permits audio queue backpressure; use `--no-audio`
+for maximum speed. These player options retain keyboard input and battery save
+loading/writing. Use the benchmark below for comparisons with a fixed start state.
+
+## Benchmarking
+
+Run a headless benchmark with an explicit warmup before each measured trial:
+
+```sh
+bundle exec ruby --yjit -Ilib exe/rubyboy-bench \
+  --rom-path lib/roms/tobu.gb --frames 1500 --warmup-frames 1500 --count 5 --json
+```
+
+Add `--render` to include SDL drawing, with audio output and VSync disabled.
+No environment variable is required; the benchmark overrides the VSync setting
+for its renderer, including `SDL_RENDER_VSYNC=1`:
+
+```sh
+bundle exec ruby --yjit -Ilib exe/rubyboy-bench \
+  --rom-path lib/roms/tobu.gb --frames 1500 --warmup-frames 1500 --count 5 --render --json
+```
+
+Both modes run the same CPU, timer, PPU and APU frame processing. Each trial
+starts with a fresh emulator, ignores battery saves, accepts no game input and
+runs without real-time synchronization or audio output. Initialization, warmup
+and display cleanup are excluded from the measured duration. Warmup advances
+the machine state by the requested number of frames in both modes. The defaults
+are 3 trials, 1500 measured frames and no warmup; counts and measured frames must
+be positive, and warmup frames may be zero.
+
+Without `--json`, the command prints each trial's duration and aggregate FPS.
+With `--json`, stdout contains one JSON document with individual durations/FPS,
+aggregate FPS, runtime identity and execution conditions. Aggregate FPS is the
+total measured frame count divided by the sum of measured durations. Closing
+the window before a trial finishes aborts the benchmark with a nonzero exit
+status instead of reporting a result for that incomplete trial.
+
+For comparisons, use the same source revision, ROM, frame counts, warmup,
+window/display settings and SDL render driver. Normal playback retains its
+existing VSync setting. Rendered FPS measures frame
+processing and SDL drawing calls; it does not count distinct frames visible on
+the monitor. Measure performance without recording, then use a separate
+`--render --count 1` run for a reference recording. Preserve elapsed real time
+when converting the recording to GIF so that speed differences remain visible.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/sacckey/rubyboy. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/sacckey/rubyboy/blob/main/CODE_OF_CONDUCT.md).

data/exe/rubyboy

@@ -4,16 +4,29 @@
 require 'rubyboy'
 require 'optparse'
 
+frames = nil
+realtime = true
+audio = true
+
 begin
   OptionParser.new do |opts|
     opts.banner = "Usage: #{File.basename($PROGRAM_NAME)} ROM_PATH"
 
+    opts.on('--frames N', 'Exit after N frames (positive integer)') do |value|
+      value = Integer(value)
+      raise OptionParser::InvalidArgument, 'frames must be a positive integer' unless value > 0
+
+      frames = value
+    end
+    opts.on('--unlimited', 'Disable real-time synchronization') { realtime = false }
+    opts.on('--no-audio', 'Disable audio output while keeping APU emulation') { audio = false }
+
     opts.on('-h', '--help', 'Displays this help') do
       puts opts
       exit
     end
   end.parse!
-rescue OptionParser::ParseError => e
+rescue OptionParser::ParseError, ArgumentError => e
   puts e.message
   puts "Usage: #{File.basename($PROGRAM_NAME)} ROM_PATH"
   exit 1
@@ -28,4 +41,4 @@ else
   puts 'YJIT is not available in this environment.'
 end
 
-Rubyboy::Emulator.new(rom_path).start
+Rubyboy::Emulator.new(rom_path, audio:).start(frames:, realtime:)

data/exe/rubyboy-bench

@@ -10,12 +10,24 @@ begin
   OptionParser.new do |opts|
     opts.banner = "Usage: #{File.basename($PROGRAM_NAME)} [options]"
 
-    opts.on('--count COUNT', Integer, 'Number of counts for the benchmark') do |count|
-      options[:count] = count
+    opts.on('--count COUNT', Integer, 'Number of trials for the benchmark') do |count|
+      options[:count] = Integer(count)
     end
 
-    opts.on('--frames FRAMES', Integer, 'Number of frames to process') do |frames|
-      options[:frames] = frames
+    opts.on('--frames FRAMES', Integer, 'Number of measured frames per trial') do |frames|
+      options[:frames] = Integer(frames)
+    end
+
+    opts.on('--warmup-frames FRAMES', Integer, 'Number of unmeasured warmup frames per trial (default: 0)') do |frames|
+      options[:warmup_frames] = Integer(frames)
+    end
+
+    opts.on('--render', 'Draw each frame without audio output or realtime synchronization') do
+      options[:render] = true
+    end
+
+    opts.on('--json', 'Output benchmark results and runtime information as JSON') do
+      options[:json] = true
     end
 
     opts.on('--rom-path ROM_PATH', String, 'Path to the ROM file') do |rom_path|
@@ -27,17 +39,24 @@ begin
       exit
     end
   end.parse!
-rescue OptionParser::ParseError => e
-  puts e.message
-  puts "Usage: #{File.basename($PROGRAM_NAME)} --count NUM --frames NUM --rom-path FILEPATH"
+rescue OptionParser::ParseError, ArgumentError => e
+  warn e.message
+  warn "Usage: #{File.basename($PROGRAM_NAME)} --count NUM --frames NUM --rom-path FILEPATH"
   exit 1
 end
 
-puts "Ruby: #{RUBY_VERSION}"
-if defined?(RubyVM::YJIT)
-  puts "YJIT: #{RubyVM::YJIT.enabled?}"
-else
-  puts 'YJIT is not available in this environment.'
+unless options[:json]
+  puts "Ruby: #{RUBY_VERSION}"
+  if defined?(RubyVM::YJIT)
+    puts "YJIT: #{RubyVM::YJIT.enabled?}"
+  else
+    puts 'YJIT is not available in this environment.'
+  end
 end
 
-Rubyboy::Bench.new.run(**options)
+begin
+  Rubyboy::Bench.new.run(**options)
+rescue ArgumentError, Rubyboy::Bench::WindowClosed => e
+  warn e.message
+  exit 1
+end

data/lib/bench.rb

@@ -1,27 +1,82 @@
 # frozen_string_literal: true
 
+require 'json'
 require_relative 'rubyboy/emulator_headless'
 
 module Rubyboy
   class Bench
-    def run(count: 3, frames: 1500, rom_path: 'lib/roms/tobu.gb')
-      time_sum = 0
+    class WindowClosed < StandardError; end
+
+    def run(count: 3, frames: 1500, rom_path: 'lib/roms/tobu.gb', warmup_frames: 0, render: false, json: false)
+      validate_integer(:count, count, 1)
+      validate_integer(:frames, frames, 1)
+      validate_integer(:warmup_frames, warmup_frames, 0)
+      require_relative 'rubyboy/lcd' if render
 
+      trials = []
+      time_sum = 0
       count.times do |i|
-        emulator = Rubyboy::EmulatorHeadless.new(rom_path)
-        frame_count = 0
+        time = run_trial(rom_path, frames, warmup_frames, render)
+        elapsed_seconds = time / 1_000_000_000.0
+        trials << { trial: i + 1, frames:, elapsed_seconds:, fps: frames / elapsed_seconds }
+        puts "#{i + 1}: #{elapsed_seconds} sec" unless json
+        time_sum += time
+      end
+
+      result = {
+        schema_version: 1,
+        rom_path: File.expand_path(rom_path),
+        count:,
+        frames:,
+        warmup_frames:,
+        render:,
+        runtime:,
+        conditions: { apu: true, audio_output: false, realtime_sync: false, vsync: render ? false : nil, input: false, save: false },
+        trials:,
+        total_frames: frames * count,
+        elapsed_seconds: time_sum / 1_000_000_000.0,
+        fps: frames * count * 1_000_000_000.0 / time_sum
+      }
+      puts(json ? JSON.generate(result) : "FPS: #{result[:fps]}")
+      result
+    end
+
+    private
+
+    def validate_integer(name, value, minimum)
+      return if value.is_a?(Integer) && value >= minimum
+
+      requirement = minimum == 0 ? 'a nonnegative integer' : 'a positive integer'
+      raise ArgumentError, "#{name} must be #{requirement}"
+    end
+
+    def run_trial(rom_path, frames, warmup_frames, render)
+      emulator = Rubyboy::EmulatorHeadless.new(rom_path)
+      lcd = Rubyboy::Lcd.new(vsync: false) if render
+      begin
+        run_frames(emulator, lcd, warmup_frames)
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
-        while frame_count < frames
-          emulator.step
-          frame_count += 1
-        end
-        time = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) - start_time
-        puts "#{i + 1}: #{time / 1_000_000_000.0} sec"
+        run_frames(emulator, lcd, frames)
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) - start_time
+      ensure
+        lcd&.close_window
+      end
+    end
 
-        time_sum += time
+    def run_frames(emulator, lcd, frames)
+      frame_count = 0
+      while frame_count < frames
+        raise WindowClosed, 'Benchmark stopped because the window was closed.' if lcd&.window_should_close?
+
+        emulator.step
+        lcd&.draw(emulator.framebuffer)
+        frame_count += 1
       end
+    end
 
-      puts "FPS: #{frames * count * 1_000_000_000.0 / time_sum}"
+    def runtime
+      yjit_enabled = defined?(RubyVM::YJIT) ? RubyVM::YJIT.enabled? : false
+      { engine: RUBY_ENGINE, version: RUBY_VERSION, description: RUBY_DESCRIPTION, platform: RUBY_PLATFORM, yjit_enabled: }
     end
   end
 end

data/lib/rubyboy/apu.rb

@@ -7,13 +7,24 @@ require_relative 'apu_channels/channel4'
 
 module Rubyboy
   class Apu
+    # APU samples are pushed to SDL at 48 kHz (must match Rubyboy::Audio::SAMPLE_RATE).
+    # The CPU runs at 4_194_304 Hz, so the real divisor is 87.3813...
+    # The previous implementation used `>= 87` which effectively ran the sampler
+    # at ~48_210 Hz — a 0.4% drift that slowly over-filled the SDL audio queue
+    # and triggered the clear-on-overflow in Audio#queue, producing audible gaps
+    # in BGM. We fix this with a fixed-point accumulator that targets the exact
+    # ratio: every step adds `cycles * SAMPLE_RATE` and we emit one sample
+    # whenever the accumulator reaches CPU_CLOCK_HZ.
+    CPU_CLOCK_HZ = 4_194_304
+    SAMPLE_RATE = 48_000
+
     attr_reader :samples
 
     def initialize
       @nr50 = 0
       @nr51 = 0
       @cycles = 0
-      @sampling_cycles = 0
+      @sampling_accumulator = 0
       @fs = 0
       @samples = Array.new(1024, 0.0)
       @sample_idx = 0
@@ -25,7 +36,7 @@ module Rubyboy
 
     def step(cycles)
       @cycles += cycles
-      @sampling_cycles += cycles
+      @sampling_accumulator += cycles * SAMPLE_RATE
 
       @channel1.step(cycles)
       @channel2.step(cycles)
@@ -43,8 +54,8 @@ module Rubyboy
         @fs = (@fs + 1) % 8
       end
 
-      if @sampling_cycles >= 87
-        @sampling_cycles -= 87
+      if @sampling_accumulator >= CPU_CLOCK_HZ
+        @sampling_accumulator -= CPU_CLOCK_HZ
 
         left_sample = (
           @nr51[7] * @channel4.dac_output +

data/lib/rubyboy/audio.rb

@@ -22,14 +22,22 @@ module Rubyboy
     end
 
     def queue(buffer)
-      # sleep(0.001) while SDL.GetQueuedAudioSize(@device) > 8192
-
-      SDL.ClearQueuedAudio(@device) if SDL.GetQueuedAudioSize(@device) > 8192
+      # Block until the SDL audio queue has drained enough to accept another
+      # buffer. The previous implementation called SDL.ClearQueuedAudio here
+      # instead, which dropped the entire queue whenever the emulator ran ahead
+      # of real time — that produced audible pops/gaps in BGM (most noticeable
+      # in Pokemon-style tracks). Blocking here costs a tiny bit of frame
+      # budget but keeps audio continuous.
+      sleep(0.001) while SDL.GetQueuedAudioSize(@device) > 8192
 
       buf_ptr = FFI::MemoryPointer.new(:float, buffer.size)
       buf_ptr.put_array_of_float(0, buffer)
 
       SDL.QueueAudio(@device, buf_ptr, buffer.size * buf_ptr.type_size)
     end
+
+    def clear_queue
+      SDL.ClearQueuedAudio(@device)
+    end
   end
 end

data/lib/rubyboy/cartridge/mbc1.rb

@@ -3,6 +3,9 @@
 module Rubyboy
   module Cartridge
     class Mbc1
+      ROM_BANK_SIZE = 0x4000
+      RAM_BANK_SIZE = 0x2000
+
       def initialize(rom, ram)
         @rom = rom
         @ram = ram
@@ -15,19 +18,13 @@ module Rubyboy
       def read_byte(addr)
         case (addr >> 12)
         when 0x0, 0x1, 0x2, 0x3
-          @rom.data[addr]
+          @rom.data[rom_offset(addr)] || 0xff
         when 0x4, 0x5, 0x6, 0x7
-          @rom.data[addr + ((@rom_bank - 1) << 14)]
+          @rom.data[rom_offset(addr)] || 0xff
         when 0xa, 0xb
-          if @ram_enable
-            if @ram_banking_mode
-              @ram.eram[addr - 0xa000 + (@ram_bank << 11)]
-            else
-              @ram.eram[addr - 0xa000]
-            end
-          else
-            0xff
-          end
+          return 0xff unless @ram_enable
+
+          @ram.eram[ram_offset(addr)] || 0xff
         end
       end
 
@@ -43,15 +40,30 @@ module Rubyboy
         when 0x6, 0x7
           @ram_banking_mode = value & 0x01 == 0x01
         when 0xa, 0xb
-          if @ram_enable
-            if @ram_banking_mode
-              @ram.eram[addr - 0xa000 + (@ram_bank << 11)] = value
-            else
-              @ram.eram[addr - 0xa000] = value
-            end
-          end
+          return unless @ram_enable
+
+          offset = ram_offset(addr)
+          @ram.eram[offset] = value if offset < @ram.eram.size
         end
       end
+
+      private
+
+      def rom_offset(addr)
+        bank =
+          if addr < ROM_BANK_SIZE
+            @ram_banking_mode ? (@ram_bank << 5) : 0
+          else
+            (@ram_bank << 5) | @rom_bank
+          end
+
+        ((bank * ROM_BANK_SIZE) + (addr & (ROM_BANK_SIZE - 1))) % @rom.data.size
+      end
+
+      def ram_offset(addr)
+        bank = @ram_banking_mode ? @ram_bank : 0
+        (addr - 0xa000) + (bank * RAM_BANK_SIZE)
+      end
     end
   end
 end

data/lib/rubyboy/emulator.rb

@@ -4,49 +4,74 @@ module Rubyboy
   class Emulator
     CPU_CLOCK_HZ = 4_194_304
     CYCLE_NANOSEC = 1_000_000_000 / CPU_CLOCK_HZ
+    SAVE_STATE_KEYS = [
+      SDL::SDL_SCANCODE_1,
+      SDL::SDL_SCANCODE_2,
+      SDL::SDL_SCANCODE_3,
+      SDL::SDL_SCANCODE_4,
+      SDL::SDL_SCANCODE_5,
+      SDL::SDL_SCANCODE_6,
+      SDL::SDL_SCANCODE_7,
+      SDL::SDL_SCANCODE_8,
+      SDL::SDL_SCANCODE_9,
+      SDL::SDL_SCANCODE_0
+    ].freeze
 
-    def initialize(rom_path)
+    def initialize(rom_path, audio: true)
+      @rom_path = rom_path
       rom_data = File.open(rom_path, 'r') { _1.read.bytes }
-      rom = Rom.new(rom_data)
-      ram = Ram.new
-      mbc = Cartridge::Factory.create(rom, ram)
-      interrupt = Interrupt.new
-      @ppu = Ppu.new(interrupt)
-      @timer = Timer.new(interrupt)
-      @joypad = Joypad.new(interrupt)
+      @rom = Rom.new(rom_data)
+      @ram = Ram.new(@rom)
+      @mbc = Cartridge::Factory.create(@rom, @ram)
+      @interrupt = Interrupt.new
+      @ppu = Ppu.new(@interrupt)
+      @timer = Timer.new(@interrupt)
+      @joypad = Joypad.new(@interrupt)
       @apu = Apu.new
-      @bus = Bus.new(@ppu, rom, ram, mbc, @timer, interrupt, @joypad, @apu)
-      @cpu = Cpu.new(@bus, interrupt)
+      @bus = Bus.new(@ppu, @rom, @ram, @mbc, @timer, @interrupt, @joypad, @apu)
+      @cpu = Cpu.new(@bus, @interrupt)
       @lcd = Lcd.new
-      @audio = Audio.new
+      @audio = audio ? Audio.new : nil
+      @prev_save_state_keys = Array.new(SAVE_STATE_KEYS.size, 0)
+      @save_file = @rom.battery? ? SaveFile.new(default_save_path(rom_path)) : nil
+      load_save_file
     end
 
-    def start
-      SDL.InitSubSystem(SDL::INIT_KEYBOARD)
+    def start(frames: nil, realtime: true)
+      raise ArgumentError, 'frames must be a positive integer' unless frames.nil? || (frames.is_a?(Integer) && frames > 0)
 
-      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
-      elapsed_machine_time = 0
-      catch(:exit_loop) do
-        loop do
-          elapsed_real_time = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) - start_time
-          while elapsed_real_time > elapsed_machine_time
-            cycles = @cpu.exec
-            @timer.step(cycles)
-            @audio.queue(@apu.samples) if @apu.step(cycles)
-            if @ppu.step(cycles)
-              @lcd.draw(@ppu.buffer)
-              key_input_check
-              throw :exit_loop if @lcd.window_should_close?
-            end
+      begin
+        SDL.InitSubSystem(SDL::INIT_KEYBOARD)
 
-            elapsed_machine_time += cycles * CYCLE_NANOSEC
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) if realtime
+        elapsed_machine_time = 0
+        frame_count = 0
+        catch(:exit_loop) do
+          loop do
+            elapsed_real_time = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) - start_time if realtime
+            while !realtime || elapsed_real_time > elapsed_machine_time
+              cycles = @cpu.exec
+              @timer.step(cycles)
+              @audio.queue(@apu.samples) if @apu.step(cycles) && @audio
+              if @ppu.step(cycles)
+                @lcd.draw(@ppu.buffer)
+                key_input_check
+                frame_count += 1
+                throw :exit_loop if frames && frame_count >= frames
+                throw :exit_loop if @lcd.window_should_close?
+              end
+
+              elapsed_machine_time += cycles * CYCLE_NANOSEC if realtime
+            end
           end
         end
+      rescue StandardError => e
+        puts e.to_s[0, 100]
+        raise e
+      ensure
+        @lcd.close_window
+        save_save_file
       end
-      @lcd.close_window
-    rescue StandardError => e
-      puts e.to_s[0, 100]
-      raise e
     end
 
     def bench(frames)
@@ -65,17 +90,106 @@ module Rubyboy
       Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) - start_time
     end
 
+    def save_state(slot: nil, path: nil)
+      state_path = path || slot_path(slot)
+      return false unless StateFile.write(state_path, rom: @rom) { hardware_state }
+
+      puts "Saved state to #{state_path}"
+      true
+    end
+
+    def load_state(slot: nil, path: nil)
+      state_path = path || slot_path(slot)
+      return false unless StateFile.read(state_path, rom: @rom) { |state| restore_hardware_state(state) }
+
+      @audio&.clear_queue
+      puts "Loaded state from #{state_path}"
+      true
+    end
+
     private
 
+    def default_save_path(rom_path)
+      dir = File.dirname(rom_path)
+      base = File.basename(rom_path, '.*')
+      File.join(dir, "#{base}.sav")
+    end
+
+    def slot_path(slot)
+      raise ArgumentError, 'slot must be between 0 and 9' unless (0..9).cover?(slot)
+
+      dir = File.dirname(@rom_path)
+      base = File.basename(@rom_path, '.*')
+      File.join(dir, "#{base}.state#{slot}")
+    end
+
+    def hardware_state
+      {
+        schema: 'game_boy_console_and_cartridge',
+        console: {
+          cpu: @cpu.hardware_state,
+          ram: @ram.hardware_state,
+          ppu: @ppu.hardware_state,
+          apu: @apu.hardware_state,
+          timer: @timer.hardware_state,
+          interrupt: @interrupt.hardware_state,
+          joypad: @joypad.hardware_state
+        },
+        cartridge: @mbc.hardware_state
+      }
+    end
+
+    def restore_hardware_state(state)
+      console = state.fetch(:console)
+      @cpu.restore_hardware_state(console.fetch(:cpu))
+      @ram.restore_hardware_state(console.fetch(:ram))
+      @ppu.restore_hardware_state(console.fetch(:ppu))
+      @apu.restore_hardware_state(console.fetch(:apu))
+      @timer.restore_hardware_state(console.fetch(:timer))
+      @interrupt.restore_hardware_state(console.fetch(:interrupt))
+      @joypad.restore_hardware_state(console.fetch(:joypad))
+      @mbc.restore_hardware_state(state.fetch(:cartridge))
+    end
+
+    def load_save_file
+      return unless @save_file
+
+      bytes = @save_file.read(@ram.eram.size)
+      return unless bytes
+
+      @ram.eram.replace(bytes)
+      puts "Loaded save from #{@save_file.path}"
+    end
+
+    def save_save_file
+      return unless @save_file
+
+      puts "Saved to #{@save_file.path}" if @save_file.write(@ram.eram)
+    end
+
     def key_input_check
       SDL.PumpEvents
       keyboard = SDL.GetKeyboardState(nil)
       keyboard_state = keyboard.read_array_of_uint8(229)
 
+      check_state_save_keys(keyboard_state)
       direction = (keyboard_state[SDL::SDL_SCANCODE_D]) | (keyboard_state[SDL::SDL_SCANCODE_A] << 1) | (keyboard_state[SDL::SDL_SCANCODE_W] << 2) | (keyboard_state[SDL::SDL_SCANCODE_S] << 3)
       action = (keyboard_state[SDL::SDL_SCANCODE_K]) | (keyboard_state[SDL::SDL_SCANCODE_J] << 1) | (keyboard_state[SDL::SDL_SCANCODE_U] << 2) | (keyboard_state[SDL::SDL_SCANCODE_I] << 3)
       @joypad.direction_button(15 - direction)
       @joypad.action_button(15 - action)
     end
+
+    def check_state_save_keys(keyboard_state)
+      shift = keyboard_state[SDL::SDL_SCANCODE_LSHIFT] > 0
+      SAVE_STATE_KEYS.each_with_index do |key, index|
+        pressed = keyboard_state[key]
+        next unless pressed > 0 && @prev_save_state_keys[index] == 0
+
+        slot = index == 9 ? 0 : index + 1
+        shift ? load_state(slot:) : save_state(slot:)
+      ensure
+        @prev_save_state_keys[index] = pressed
+      end
+    end
   end
 end

data/lib/rubyboy/emulator_headless.rb

@@ -16,7 +16,7 @@ module Rubyboy
     def initialize(rom_path)
       rom_data = File.open(rom_path, 'r') { _1.read.bytes }
       rom = Rom.new(rom_data)
-      ram = Ram.new
+      ram = Ram.new(rom)
       mbc = Cartridge::Factory.create(rom, ram)
       interrupt = Interrupt.new
       @ppu = Ppu.new(interrupt)
@@ -27,6 +27,10 @@ module Rubyboy
       @cpu = Cpu.new(bus, interrupt)
     end
 
+    def framebuffer
+      @ppu.buffer
+    end
+
     def step
       loop do
         cycles = @cpu.exec