gemba 0.1.0

data/lib/gemba/core.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Gemba
+  # GBA emulator core wrapping libmgba's mCore API.
+  #
+  # Core loads a GBA ROM, emulates one frame at a time, and provides
+  # access to the video and audio output buffers. Pair with
+  # {Teek::SDL2::Renderer} for display and {Teek::SDL2::AudioStream}
+  # for sound.
+  #
+  # @example Run a frame and grab pixels
+  #   core = Gemba::Core.new("game.gba")
+  #   core.run_frame
+  #   pixels = core.video_buffer   # 240*160*4 bytes RGBA
+  #   core.destroy
+  class Core
+
+    # @!method initialize(rom_path, save_dir = nil)
+    #   Load a GBA ROM and initialize the emulator core.
+    #   Detects the platform (GBA/GB/GBC) from the file extension,
+    #   allocates video and audio buffers, resets the CPU, and autoloads
+    #   the battery save file (.sav).
+    #
+    #   @param rom_path [String] path to the ROM file (.gba, .gb, .gbc)
+    #   @param save_dir [String, nil] directory for .sav files.
+    #     When +nil+, saves are stored alongside the ROM.
+    #   @raise [ArgumentError] if the ROM format is unrecognized or the file cannot be opened
+    #   @raise [RuntimeError] if core initialization or ROM loading fails
+
+    # @!method run_frame
+    #   Advance the emulation by one video frame (~16.7 ms of GBA time).
+    #   Releases the GVL so other Ruby threads can run during emulation.
+    #   After this call, {#video_buffer} and {#audio_buffer} contain
+    #   the new frame's output.
+    #   @return [nil]
+
+    # @!method video_buffer
+    #   Raw pixel data for the current frame.
+    #   Returns a binary String of +width * height * 4+ bytes in mGBA's
+    #   native color format (ABGR8888 — R in low bits of each uint32).
+    #   @return [String] binary pixel data
+    #   @see #video_buffer_argb
+
+    # @!method video_buffer_argb
+    #   Pixel data converted to ARGB8888 for SDL2 textures.
+    #   Same dimensions as {#video_buffer} but with R and B channels
+    #   swapped so the data can be passed directly to
+    #   {Teek::SDL2::Texture#update}.
+    #   @return [String] binary pixel data in ARGB8888 format
+
+    # @!method audio_buffer
+    #   Drain the audio output for the most recent frame(s).
+    #   Returns interleaved stereo signed 16-bit PCM samples (L R L R ...).
+    #   The number of samples varies per frame (~548 at 32768 Hz).
+    #   @return [String] binary PCM data (packed int16, little-endian)
+
+    # @!method set_keys(bitmask)
+    #   Set the currently pressed buttons as a bitmask.
+    #   Combine key constants with bitwise OR:
+    #     +core.set_keys(Gemba::KEY_A | Gemba::KEY_START)+
+    #   Pass +0+ to release all buttons.
+    #   @param bitmask [Integer] bitwise OR of +KEY_*+ constants
+    #   @return [nil]
+
+    # @!method width
+    #   Video output width in pixels (240 for GBA).
+    #   @return [Integer]
+
+    # @!method height
+    #   Video output height in pixels (160 for GBA).
+    #   @return [Integer]
+
+    # @!method title
+    #   Internal ROM title (up to 12 characters for GBA).
+    #   @return [String]
+
+    # @!method game_code
+    #   Game code from the ROM header, prefixed with platform
+    #   (e.g. "AGB-BTKE" for GBA, "CGB-XXXX" for GBC).
+    #   @return [String]
+
+    # @!method maker_code
+    #   2-character maker/publisher code from the GBA ROM header
+    #   at offset 0xB0 (e.g. "01" for Nintendo).
+    #   Returns empty string for non-GBA ROMs.
+    #   @return [String]
+
+    # @!method checksum
+    #   CRC32 checksum of the loaded ROM.
+    #   @return [Integer]
+
+    # @!method platform
+    #   Platform string: "GBA", "GB", or "Unknown".
+    #   @return [String]
+
+    # @!method rom_size
+    #   Size of the loaded ROM in bytes.
+    #   @return [Integer]
+
+    # @!method save_state_to_file(path)
+    #   Save the complete emulator state (CPU, memory, audio, video) to a file.
+    #   Includes battery save data and RTC state.
+    #   @param path [String] destination file path
+    #   @return [Boolean] true on success
+    #   @raise [RuntimeError] if the file cannot be opened for writing
+
+    # @!method load_state_from_file(path)
+    #   Restore emulator state from a previously saved state file.
+    #   @param path [String] state file path
+    #   @return [Boolean] true on success, false if file doesn't exist or is invalid
+
+    # @!method destroy
+    #   Shut down the emulator core and free all resources.
+    #   Further method calls will raise.
+    #   @return [nil]
+
+    # @!method destroyed?
+    #   Whether the core has been destroyed.
+    #   @return [Boolean]
+  end
+end

data/lib/gemba/headless.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Lightweight entry point for headless (no GUI) usage of gemba.
+# Loads only the C extension and pure-Ruby modules — no Tk, no SDL2.
+#
+#   require "gemba/headless"
+#   Gemba::HeadlessPlayer.open("game.gba") { |p| p.step(60) }
+
+require_relative "runtime"
+require_relative "recorder"
+require_relative "recorder_decoder"
+require_relative "headless_player"

data/lib/gemba/headless_player.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'zlib'
+
+module Gemba
+  # Headless mGBA player for scripting and automated testing.
+  # Wraps Core with a simple API — no Tk, no SDL2, no event loop.
+  #
+  # @example Run 60 frames and inspect the video buffer
+  #   HeadlessPlayer.open("game.gba") do |player|
+  #     player.step(60)
+  #     pixels = player.video_buffer_argb  # 240*160*4 bytes
+  #   end
+  class HeadlessPlayer
+    # @param rom_path [String] path to ROM file (.gba, .gb, .gbc, .zip)
+    # @param config [Config, nil] config object (uses default if nil)
+    def initialize(rom_path, config: nil)
+      @config = config || Gemba.user_config
+      rom_path = RomLoader.resolve(rom_path)
+
+      saves = @config.saves_dir
+      FileUtils.mkdir_p(saves) unless File.directory?(saves)
+      @core = Core.new(rom_path, saves)
+      @keys = 0
+    end
+
+    # Open a HeadlessPlayer, yield it, and close when done.
+    # @param rom_path [String]
+    # @param opts [Hash] passed to {#initialize}
+    # @yield [HeadlessPlayer]
+    # @return result of block
+    def self.open(rom_path, **opts)
+      player = new(rom_path, **opts)
+      begin
+        yield player
+      ensure
+        player.close
+      end
+    end
+
+    # Run one or more frames. Captures to recorder if recording.
+    # @param n [Integer] number of frames to advance (default 1)
+    # @yield [Integer] frame number (1-based) after each frame, if block given
+    def step(n = 1)
+      check_open!
+      if block_given?
+        n.times do |i|
+          @core.run_frame
+          @recorder&.capture(@core.video_buffer_argb, @core.audio_buffer) if @recorder&.recording?
+          yield i + 1
+        end
+      else
+        n.times do
+          @core.run_frame
+          @recorder&.capture(@core.video_buffer_argb, @core.audio_buffer) if @recorder&.recording?
+        end
+      end
+    end
+
+    # Set currently pressed buttons as a bitmask.
+    # Use KEY_* constants: `player.press(KEY_A | KEY_START)`
+    # @param keys [Integer] bitwise OR of KEY_* constants
+    def press(keys)
+      check_open!
+      @keys = keys
+      @core.set_keys(@keys)
+    end
+
+    # Release all buttons.
+    def release_all
+      check_open!
+      @keys = 0
+      @core.set_keys(0)
+    end
+
+    # @return [String] raw ARGB8888 pixel data (240*160*4 bytes for GBA)
+    def video_buffer_argb
+      check_open!
+      @core.video_buffer_argb
+    end
+
+    # @return [String] raw interleaved stereo PCM audio data
+    def audio_buffer
+      check_open!
+      @core.audio_buffer
+    end
+
+    # @return [Integer] video width in pixels
+    def width
+      check_open!
+      @core.width
+    end
+
+    # @return [Integer] video height in pixels
+    def height
+      check_open!
+      @core.height
+    end
+
+    # @!group ROM metadata
+
+    def title;      check_open!; @core.title;      end
+    def game_code;  check_open!; @core.game_code;  end
+    def maker_code; check_open!; @core.maker_code; end
+    def checksum;   check_open!; @core.checksum;   end
+    def platform;   check_open!; @core.platform;   end
+    def rom_size;   check_open!; @core.rom_size;   end
+
+    # @!endgroup
+
+    # @!group Save states
+
+    # @param path [String] destination file path
+    # @return [Boolean] true on success
+    def save_state(path)
+      check_open!
+      @core.save_state_to_file(path)
+    end
+
+    # @param path [String] state file path
+    # @return [Boolean] true on success
+    def load_state(path)
+      check_open!
+      @core.load_state_from_file(path)
+    end
+
+    # @!endgroup
+
+    # @!group Rewind
+
+    def rewind_init(seconds)
+      check_open!
+      @core.rewind_init(seconds)
+    end
+
+    def rewind_push
+      check_open!
+      @core.rewind_push
+    end
+
+    # @return [Boolean] true if a snapshot was loaded
+    def rewind_pop
+      check_open!
+      @core.rewind_pop
+    end
+
+    # @return [Integer] number of saved snapshots
+    def rewind_count
+      check_open!
+      @core.rewind_count
+    end
+
+    def rewind_deinit
+      check_open!
+      @core.rewind_deinit
+    end
+
+    # @!endgroup
+
+    # @!group Recording
+
+    # Start recording video + audio to a .grec file.
+    # @param path [String] output file path
+    # @param compression [Integer] zlib level 1-9 (default 1 = fastest)
+    def start_recording(path, compression: Zlib::BEST_SPEED)
+      check_open!
+      raise "Already recording" if recording?
+      @recorder = Recorder.new(path, width: @core.width, height: @core.height,
+                               compression: compression)
+      @recorder.start
+    end
+
+    # Stop recording and finalize the file.
+    def stop_recording
+      @recorder&.stop
+      @recorder = nil
+    end
+
+    # @return [Boolean] true if currently recording
+    def recording?
+      @recorder&.recording? || false
+    end
+
+    # @!endgroup
+
+    # Shut down the core and free resources.
+    def close
+      return if closed?
+      stop_recording if recording?
+      @core.destroy
+      @core = nil
+    end
+
+    # @return [Boolean] true if the player has been closed
+    def closed?
+      @core.nil? || @core.destroyed?
+    end
+
+    private
+
+    def check_open!
+      raise "HeadlessPlayer is closed" if closed?
+    end
+  end
+end

data/lib/gemba/hotkey_map.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Gemba
+  # Maps player actions (quit, pause, etc.) to keyboard hotkeys.
+  #
+  # A hotkey is either a plain keysym String ("F5") or an Array of
+  # modifier(s) + key (["Control", "s"]). Provides reverse lookup for
+  # efficient dispatch in the input loop.
+  class HotkeyMap
+    ACTIONS = %i[quit pause fast_forward fullscreen show_fps
+                 quick_save quick_load save_states screenshot rewind
+                 record].freeze
+
+    DEFAULTS = {
+      quit: 'q', pause: 'p', fast_forward: 'Tab',
+      fullscreen: 'F11', show_fps: 'F3',
+      quick_save: 'F5', quick_load: 'F8',
+      save_states: 'F6', screenshot: 'F9',
+      rewind: ['Shift', 'Tab'],
+      record: 'F10',
+    }.freeze
+
+    # Tk keysyms that are modifier keys → normalized name
+    MODIFIER_KEYSYMS = {
+      'Control_L' => 'Control', 'Control_R' => 'Control',
+      'Shift_L' => 'Shift', 'Shift_R' => 'Shift',
+      'Alt_L' => 'Alt', 'Alt_R' => 'Alt',
+      'Meta_L' => 'Alt', 'Meta_R' => 'Alt',
+      'Super_L' => 'Super', 'Super_R' => 'Super',
+    }.freeze
+
+    # Tk event state bitmask → modifier name
+    STATE_BITS = { 1 => 'Shift', 4 => 'Control', 8 => 'Alt' }.freeze
+
+    # Display-friendly modifier names
+    MODIFIER_DISPLAY = { 'Control' => 'Ctrl', 'Shift' => 'Shift', 'Alt' => 'Alt', 'Super' => 'Super' }.freeze
+
+    # Canonical sort order for modifiers
+    MODIFIER_ORDER = %w[Control Shift Alt Super].freeze
+
+    # Tk keysym aliases — modifier combos can produce variant keysyms
+    # that must be normalized for both lookup and capture.
+    #
+    # Known cases:
+    #   Shift+Tab   → ISO_Left_Tab
+    #   Shift+1     → exclam (US layout)
+    #   Shift+a     → A (universal — handled dynamically in normalize_keysym)
+    KEYSYM_ALIASES = {
+      'ISO_Left_Tab' => 'Tab',
+      # Shift+number (US keyboard layout)
+      'exclam'       => '1', 'at'           => '2', 'numbersign'   => '3',
+      'dollar'       => '4', 'percent'      => '5', 'asciicircum'  => '6',
+      'ampersand'    => '7', 'asterisk'     => '8', 'parenleft'    => '9',
+      'parenright'   => '0',
+      # Shift+punctuation (US keyboard layout)
+      'underscore'   => 'minus',        'plus'         => 'equal',
+      'braceleft'    => 'bracketleft',  'braceright'   => 'bracketright',
+      'bar'          => 'backslash',    'colon'        => 'semicolon',
+      'quotedbl'     => 'apostrophe',   'less'         => 'comma',
+      'greater'      => 'period',       'question'     => 'slash',
+      'asciitilde'   => 'grave',
+    }.freeze
+
+    def initialize(config)
+      @config = config
+      @map = DEFAULTS.dup
+      load_config
+    end
+
+    # @param action [Symbol] e.g. :quit, :pause
+    # @return [String, Array] hotkey for this action
+    def key_for(action)
+      @map[action]
+    end
+
+    # Look up which action matches a keysym + active modifiers.
+    # @param keysym [String] e.g. 'q', 'F5'
+    # @param modifiers [Set<String>, nil] active modifier names (e.g. Set["Control"])
+    # @return [Symbol, nil] action bound to this hotkey, or nil
+    def action_for(keysym, modifiers: nil)
+      keysym = self.class.normalize_keysym(keysym)
+      mods = modifiers && !modifiers.empty? ? modifiers : nil
+
+      @map.each do |action, hk|
+        if hk.is_a?(Array)
+          hk_mods = hk[0...-1]
+          hk_key = hk.last
+          next unless mods && hk_key == keysym
+          next unless hk_mods.size == mods.size && hk_mods.all? { |m| mods.include?(m) }
+          return action
+        else
+          return action if hk == keysym && mods.nil?
+        end
+      end
+      nil
+    end
+
+    # Rebind an action to a new hotkey. Clears any existing action
+    # using the same hotkey to prevent conflicts.
+    # @param action [Symbol]
+    # @param hotkey [String, Array]
+    def set(action, hotkey)
+      normalized = self.class.normalize(hotkey)
+      @map.delete_if { |_, v| self.class.normalize(v) == normalized }
+      @map[action] = normalized
+    end
+
+    # Restore all bindings to defaults.
+    def reset!
+      @map = DEFAULTS.dup
+    end
+
+    # Load hotkeys from config. Falls back to defaults for missing keys.
+    def load_config
+      cfg = @config.hotkeys
+      return if cfg.empty?
+
+      @map = DEFAULTS.dup
+      cfg.each do |action_str, hk|
+        action = action_str.to_sym
+        @map[action] = self.class.normalize(hk) if ACTIONS.include?(action)
+      end
+    end
+
+    # Re-read config from disk, then reload bindings.
+    def reload!
+      @config.reload!
+      load_config
+    end
+
+    # Write current hotkeys to config (does not call save!).
+    def save_to_config
+      @map.each do |action, hk|
+        @config.set_hotkey(action, hk)
+      end
+    end
+
+    # @return [Hash{Symbol => String, Array}] action → raw hotkey
+    def labels
+      @map.dup
+    end
+
+    # Normalize a hotkey: sort modifiers canonically.
+    # @param hotkey [String, Array] e.g. "F5" or ["Shift", "Control", "s"]
+    # @return [String, Array]
+    def self.normalize(hotkey)
+      return hotkey unless hotkey.is_a?(Array)
+      return hotkey.last if hotkey.size == 1
+
+      key = hotkey.last
+      mods = hotkey[0...-1].sort_by { |m| MODIFIER_ORDER.index(m) || 99 }
+      [*mods, key]
+    end
+
+    # Human-readable display name for a hotkey.
+    # @param hotkey [String, Array]
+    # @return [String] e.g. "F5", "Ctrl+S"
+    def self.display_name(hotkey)
+      return hotkey unless hotkey.is_a?(Array)
+
+      parts = hotkey[0...-1].map { |m| MODIFIER_DISPLAY[m] || m }
+      parts << hotkey.last.capitalize
+      parts.join('+')
+    end
+
+    # Normalize variant Tk keysyms to their canonical form.
+    # Handles: ISO_Left_Tab → Tab, Shift+letter uppercase → lowercase,
+    # Shift+number → number (US layout), Shift+punctuation → base key.
+    # @param keysym [String] e.g. 'ISO_Left_Tab', 'Q'
+    # @return [String] canonical keysym e.g. 'Tab', 'q'
+    def self.normalize_keysym(keysym)
+      return KEYSYM_ALIASES[keysym] if KEYSYM_ALIASES.key?(keysym)
+      # Shift+letter: single uppercase ASCII letter → lowercase
+      return keysym.downcase if keysym.length == 1 && keysym.match?(/\A[A-Z]\z/)
+      keysym
+    end
+
+    # @param keysym [String] Tk keysym
+    # @return [Boolean] true if the keysym is a modifier key
+    def self.modifier_key?(keysym)
+      MODIFIER_KEYSYMS.key?(keysym)
+    end
+
+    # Normalize a Tk modifier keysym (e.g. "Control_L" → "Control").
+    # @param keysym [String]
+    # @return [String, nil] normalized modifier name, or nil if not a modifier
+    def self.normalize_modifier(keysym)
+      MODIFIER_KEYSYMS[keysym]
+    end
+
+    # Extract active modifier names from a Tk event state bitmask.
+    # @param state [Integer] Tk %s value
+    # @return [Set<String>]
+    def self.modifiers_from_state(state)
+      result = Set.new
+      STATE_BITS.each { |bit, name| result << name if (state & bit) != 0 }
+      result
+    end
+  end
+end