gemba 0.1.1 → 0.2.0

data/lib/gemba/help_window.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Gemba
+  # Floating hotkey reference panel toggled by pressing '?'.
+  #
+  # Non-modal — no grab, no focus steal. Positioned to the right of the
+  # main window via ChildWindow#position_near_parent. AppController pauses
+  # emulation while the panel is visible and restores play on close.
+  class HelpWindow
+    include ChildWindow
+    include Locale::Translatable
+
+    TOP = '.help_window'
+
+    def initialize(app:, hotkeys:)
+      @app     = app
+      @hotkeys = hotkeys
+      build_toplevel(translate('settings.hotkeys'), geometry: '220x400') { build_ui }
+    end
+
+    def show    = show_window(modal: false)
+    def hide    = hide_window(modal: false)
+    def visible? = @app.tcl_eval("wm state #{TOP}") == 'normal'
+
+    private
+
+    def build_ui
+      f = "#{TOP}.f"
+      @app.command('ttk::frame', f, padding: 8)
+      @app.command(:pack, f, fill: :both, expand: 1)
+
+      @app.command('ttk::label', "#{f}.title",
+        text: translate('settings.hotkeys'),
+        font: '{TkDefaultFont} 11 bold')
+      @app.command(:pack, "#{f}.title", pady: [0, 4])
+
+      @app.command('ttk::separator', "#{f}.sep", orient: :horizontal)
+      @app.command(:pack, "#{f}.sep", fill: :x, pady: [0, 6])
+
+      Settings::HotkeysTab::LOCALE_KEYS.each do |action, locale_key|
+        row = "#{f}.row_#{action}"
+        @app.command('ttk::frame', row)
+        @app.command(:pack, row, fill: :x, pady: 1)
+
+        act_lbl = "#{row}.act"
+        key_lbl = "#{row}.key"
+
+        key_text = HotkeyMap.display_name(@hotkeys.key_for(action))
+
+        @app.command('ttk::label', act_lbl, text: translate(locale_key), anchor: :w)
+        @app.command('ttk::label', key_lbl, text: key_text, anchor: :e,
+          font: '{TkFixedFont} 9')
+
+        @app.command(:grid, act_lbl, row: 0, column: 0, sticky: :w)
+        @app.command(:grid, key_lbl, row: 0, column: 1, sticky: :e)
+        @app.command(:grid, :columnconfigure, row, 0, weight: 1)
+        @app.command(:grid, :columnconfigure, row, 1, weight: 0)
+      end
+    end
+  end
+end

data/lib/gemba/hotkey_map.rb

@@ -11,7 +11,7 @@ module Gemba
   class HotkeyMap
     ACTIONS = %i[quit pause fast_forward fullscreen show_fps
                  quick_save quick_load save_states screenshot rewind
-                 record].freeze
+                 record input_record open_rom].freeze
 
     DEFAULTS = {
       quit: 'q', pause: 'p', fast_forward: 'Tab',
@@ -20,6 +20,8 @@ module Gemba
       save_states: 'F6', screenshot: 'F9',
       rewind: ['Shift', 'Tab'],
       record: 'F10',
+      input_record: 'F4',
+      open_rom: ['Control', 'o'],
     }.freeze
 
     # Tk keysyms that are modifier keys → normalized name

data/lib/gemba/input_recorder.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Gemba
+  # Records per-frame input bitmasks to a .gir (Gemba Input Recording) file.
+  #
+  # Each GBA frame's pressed-button bitmask is stored as a 3-char hex line.
+  # An anchor save state is written alongside so replays start from the
+  # exact same emulator state.
+  #
+  # The header's frame_count is a best-effort hint (correct on clean stop,
+  # zero on crash). The replayer counts lines for the authoritative count.
+  #
+  # @example
+  #   recorder = InputRecorder.new("session.gir", core: core)
+  #   recorder.start
+  #   loop do
+  #     mask = poll_input
+  #     recorder.capture(mask)
+  #     core.set_keys(mask)
+  #     core.run_frame
+  #   end
+  #   recorder.stop
+  class InputRecorder
+    VERSION = 1
+    FLUSH_INTERVAL = 60 # frames between flushes (~1s at 59.7 fps)
+
+    # @param path [String] output .gir file path
+    # @param core [Gemba::Core] mGBA core (for ROM metadata and save state)
+    # @param rom_path [String, nil] path to the ROM file (stored in header for easy replay)
+    def initialize(path, core:, rom_path: nil)
+      @path = path
+      @core = core
+      @rom_path = rom_path
+      @recording = false
+      @frame_count = 0
+    end
+
+    # Start recording. Saves an anchor save state and opens the .gir file.
+    def start
+      raise "Already recording" if @recording
+
+      @core.save_state_to_file(anchor_state_path)
+      @frame_count = 0
+      @file = File.open(@path, 'w')
+      write_header
+      @file.flush
+      @recording = true
+    end
+
+    # Capture one frame's input bitmask.
+    # @param bitmask [Integer] bitwise OR of KEY_* constants (0x000–0x3FF)
+    def capture(bitmask)
+      return unless @recording
+
+      @file.puts(format('%03x', bitmask & 0x3FF))
+      @frame_count += 1
+      @file.flush if (@frame_count % FLUSH_INTERVAL).zero?
+    end
+
+    # Stop recording and close the file.
+    def stop
+      return unless @recording
+
+      @recording = false
+      rewrite_frame_count
+      @file.close
+      @file = nil
+    end
+
+    # @return [Boolean] true if currently recording
+    def recording?
+      @recording
+    end
+
+    # @return [Integer] number of frames captured so far
+    attr_reader :frame_count
+
+    # @return [String] path to the anchor save state file
+    def anchor_state_path
+      @path.sub(/\.gir\z/, '.state')
+    end
+
+    private
+
+    FRAME_COUNT_WIDTH = 10 # zero-padded digits (covers ~5.3 years at 60fps)
+
+    def write_header
+      @file.puts "# GEMBA INPUT RECORDING v#{VERSION}"
+      @file.puts "# rom_checksum: #{@core.checksum}"
+      @file.puts "# game_code: #{@core.game_code}"
+      @file.puts "# rom_path: #{@rom_path}" if @rom_path
+      @file.write "# frame_count: "
+      @frame_count_offset = @file.pos
+      @file.puts format("%0#{FRAME_COUNT_WIDTH}d", 0)
+      @file.puts "# anchor_state: #{File.basename(anchor_state_path)}"
+      @file.puts "---"
+    end
+
+    # Best-effort: seek to the frame_count field and overwrite in place.
+    def rewrite_frame_count
+      @file.flush
+      @file.seek(@frame_count_offset)
+      @file.write(format("%0#{FRAME_COUNT_WIDTH}d", @frame_count))
+      @file.seek(0, IO::SEEK_END)
+    end
+  end
+end

data/lib/gemba/input_replayer.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Gemba
+  # Replays a .gir (Gemba Input Recording) file by feeding recorded
+  # per-frame bitmasks back to the emulator core.
+  #
+  # The authoritative frame count comes from counting bitmask lines,
+  # not the header (which is best-effort and may be zero on crash).
+  #
+  # @example
+  #   replayer = InputReplayer.new("session.gir")
+  #   replayer.validate!(core)
+  #   core.load_state_from_file(replayer.anchor_state_path)
+  #   replayer.each_bitmask do |mask, frame|
+  #     core.set_keys(mask)
+  #     core.run_frame
+  #   end
+  class InputReplayer
+    class ChecksumMismatch < StandardError; end
+
+    # @param gir_path [String] path to .gir file
+    def initialize(gir_path)
+      @path = gir_path
+      @header = {}
+      @bitmasks = []
+      parse!
+    end
+
+    # @return [Integer] ROM checksum from the recording header
+    def rom_checksum
+      @header[:rom_checksum]
+    end
+
+    # @return [String] game code from the recording header
+    def game_code
+      @header[:game_code]
+    end
+
+    # @return [String, nil] ROM path from the recording header
+    def rom_path
+      @header[:rom_path]
+    end
+
+    # @return [Integer] number of recorded frames (counted from bitmask lines)
+    def frame_count
+      @bitmasks.length
+    end
+
+    # @return [String] path to the anchor save state file
+    def anchor_state_path
+      dir = File.dirname(@path)
+      File.join(dir, @header[:anchor_state])
+    end
+
+    # Validate that the recording matches the loaded ROM.
+    # @param core [Gemba::Core] mGBA core to validate against
+    # @raise [ChecksumMismatch] if ROM checksum doesn't match
+    def validate!(core)
+      if rom_checksum && core.checksum != rom_checksum
+        raise ChecksumMismatch,
+          "ROM checksum mismatch: recording has #{rom_checksum}, " \
+          "loaded ROM has #{core.checksum}"
+      end
+    end
+
+    # @param frame [Integer] zero-based frame index
+    # @return [Integer] bitmask for the given frame
+    def bitmask_at(frame)
+      @bitmasks[frame]
+    end
+
+    # Iterate over all recorded bitmasks.
+    # @yield [Integer, Integer] bitmask and zero-based frame index
+    def each_bitmask(&block)
+      @bitmasks.each_with_index(&block)
+    end
+
+    private
+
+    def parse!
+      in_header = true
+
+      File.foreach(@path) do |line|
+        line = line.strip
+
+        if in_header
+          if line == '---'
+            in_header = false
+          elsif line.start_with?('# ')
+            parse_header_line(line)
+          end
+        else
+          next if line.empty?
+          @bitmasks << line.to_i(16)
+        end
+      end
+    end
+
+    def parse_header_line(line)
+      # Format: "# key: value"
+      content = line.sub(/^# /, '')
+      key, _, value = content.partition(': ')
+      return if value.empty?
+
+      case key
+      when 'rom_checksum'
+        @header[:rom_checksum] = value.to_i
+      when 'game_code'
+        @header[:game_code] = value
+      when 'anchor_state'
+        @header[:anchor_state] = value
+      when 'rom_path'
+        @header[:rom_path] = value
+      when 'frame_count'
+        @header[:header_frame_count] = value.to_i
+      end
+    end
+  end
+end

data/lib/gemba/keyboard_map.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Gemba
+  # Manages keyboard keysym → GBA bitmask mappings.
+  #
+  # Shares the same interface as {GamepadMap} so that Player can
+  # delegate to either without knowing which device type is active.
+  class KeyboardMap
+    DEFAULT_MAP = {
+      'z'         => KEY_A,
+      'x'         => KEY_B,
+      'BackSpace' => KEY_SELECT,
+      'Return'    => KEY_START,
+      'Right'     => KEY_RIGHT,
+      'Left'      => KEY_LEFT,
+      'Up'        => KEY_UP,
+      'Down'      => KEY_DOWN,
+      'a'         => KEY_L,
+      's'         => KEY_R,
+    }.freeze
+
+    def initialize(config)
+      @config = config
+      @map = DEFAULT_MAP.dup
+      @device = nil
+      load_config
+    end
+
+    attr_writer :device
+
+    def mask
+      return 0 unless @device
+      m = 0
+      @map.each { |key, bit| m |= bit if @device.button?(key) }
+      m
+    end
+
+    def set(gba_btn, input_key)
+      bit = GBA_BTN_BITS[gba_btn] or return
+      @map.delete_if { |_, v| v == bit }
+      @map[input_key.to_s] = bit
+    end
+
+    def reset!
+      @map = DEFAULT_MAP.dup
+    end
+
+    def load_config
+      cfg = @config.mappings(Config::KEYBOARD_GUID)
+      if cfg.empty?
+        @map = DEFAULT_MAP.dup
+      else
+        @map = {}
+        cfg.each do |gba_str, keysym|
+          bit = GBA_BTN_BITS[gba_str.to_sym]
+          next unless bit
+          @map[keysym] = bit
+        end
+      end
+    end
+
+    def reload!
+      @config.reload!
+      load_config
+    end
+
+    def labels
+      result = {}
+      @map.each do |input, bit|
+        gba_btn = GBA_BTN_BITS.key(bit)
+        result[gba_btn] = input if gba_btn
+      end
+      result
+    end
+
+    def save_to_config
+      @map.each do |input, bit|
+        gba_btn = GBA_BTN_BITS.key(bit)
+        @config.set_mapping(Config::KEYBOARD_GUID, gba_btn, input) if gba_btn
+      end
+    end
+
+    def supports_deadzone? = false
+    def dead_zone_pct = 0
+
+    def set_dead_zone(_)
+      raise NotImplementedError, "keyboard does not support dead zones"
+    end
+  end
+end

data/lib/gemba/locales/en.yml

@@ -5,8 +5,12 @@ menu:
   quit: "Quit"
   settings: "Settings"
   view: "View"
+  game_library: "Game Library"
   fullscreen: "Fullscreen"
   rom_info: "ROM Info…"
+  achievements: "Achievements…"
+  open_logs_dir: "Open Logs Directory"
+  patch_rom: "Patch ROM…"
   emulation: "Emulation"
   pause: "Pause"
   resume: "Resume"
@@ -14,8 +18,10 @@ menu:
   quick_save: "Quick Save"
   quick_load: "Quick Load"
   save_states: "Save States…"
-  start_recording: "Start Recording"
-  stop_recording: "Stop Recording"
+  start_recording: "Start Capture"
+  stop_recording: "Stop Capture"
+  start_input_recording: "Start Recording Inputs"
+  stop_input_recording: "Stop Recording Inputs"
 
 toast:
   save_blocked: "Save blocked (too fast)"
@@ -32,12 +38,18 @@ toast:
   no_rewind: "No rewind data"
   paused: "Paused"
   waiting_for: "Waiting for {label}…"
-  recording_started: "Recording started"
-  recording_stopped: "Recorded {frames} frames"
+  recording_started: "Capture started"
+  recording_stopped: "Captured {frames} frames"
+  input_recording_started: "Recording inputs"
+  input_recording_stopped: "Inputs recorded ({frames} frames)"
 
 dialog:
   game_running_title: "Game Running"
   game_running_msg: "Another game is running. Switch to {name}?"
+  return_to_library_title: "Return to Game Library"
+  return_to_library_msg: "Return to the Game Library? Unsaved progress will be lost."
+  quit_title: "Quit Gemba"
+  quit_msg: "A game is running. Quit anyway? Unsaved progress will be lost."
   drop_error_title: "Drop Error"
   drop_single_file_only: "Please drop a single ROM file."
   drop_unsupported_type: "Unsupported file type: {ext}"
@@ -51,6 +63,8 @@ dialog:
   reset_hotkeys_title: "Reset Hotkeys"
   reset_hotkeys_msg: "Reset all hotkey bindings to defaults?"
   key_conflict_title: "Key Conflict"
+  cancel_bulk_sync_title: "Cancel Sync?"
+  cancel_bulk_sync_msg: "A bulk sync is in progress. Closing will cancel it — games will need to be re-synced manually."
 
 settings:
   video: "Video"
@@ -91,7 +105,9 @@ settings:
   hk_save_states: "Save States"
   hk_screenshot: "Screenshot"
   hk_rewind: "Rewind"
-  hk_record: "Record"
+  hk_record: "Capture"
+  hk_input_record: "Record Inputs"
+  hk_open_rom: "Open ROM"
   hk_reset_defaults: "Reset to Defaults"
   pixel_filter: "Pixel Filter:"
   filter_nearest: "Nearest Neighbor"
@@ -111,11 +127,39 @@ settings:
   tip_per_game: "Save separate video, audio, and save state settings for each ROM."
   tip_turbo_speed: "Fast-forward speed when holding the turbo hotkey."
   tip_toast_duration: "How long on-screen notifications stay visible."
+  system: "System"
+  bios_header: "GBA BIOS"
+  bios_path: "BIOS file:"
+  bios_browse: "Browse…"
+  bios_clear: "Clear"
+  bios_not_set: "Not set — using built-in HLE (recommended for most games)"
+  bios_not_found: "File not found"
+  skip_bios: "Skip boot animation"
+  tip_skip_bios: "Jump straight to the game, skipping the Game Boy Advance logo screen.\nOnly applies when a real BIOS file is loaded."
+  retroachievements: "Achievements"
+  ra_enabled: "Enable RetroAchievements"
+  ra_credentials: "Account"
+  ra_username_placeholder: "Username:"
+  ra_token_placeholder: "Password:"
+  ra_rich_presence: "Rich Presence (per-game)"
+  ra_hardcore: "Hardcore mode (disables save states and rewind)"
+  tip_ra_password: "Your password is only used to fetch an API token and is never saved."
+  ra_login: "Login"
+  ra_verify: "Verify Token"
+  ra_logout: "Logout"
+  ra_reset: "Reset"
+  ra_reset_title: "Reset RetroAchievements"
+  ra_reset_confirm: "Clear saved credentials and log out?"
+  ra_test_ok: "Connection OK ✓"
+  ra_disabled: "RetroAchievements is disabled"
+  ra_not_logged_in: "Not logged in"
+  ra_logged_in_as: "Logged in as {username}"
   recording: "Recording"
   recording_compression: "Compression:"
   tip_recording_compression: "Zlib level for .grec files.\n1 = fastest (default), 6+ has diminishing returns."
   recordings_folder: "Recordings folder:"
   open_recordings_folder: "Open Recordings Folder…"
+  open_replay_player: "Open Input Replay…"
   gp_a: "A"
   gp_b: "B"
   gp_l: "L"
@@ -134,6 +178,13 @@ picker:
   slot: "Slot {n}"
   close: "Close"
 
+game_picker:
+  menu:
+    play: "Play"
+    quick_load: "Quick Load"
+    set_boxart: "Set Boxart"
+    remove: "Remove from Library"
+
 rom_info:
   title: "ROM Info"
   field_title: "Title:"
@@ -148,6 +199,29 @@ rom_info:
   close: "Close"
   na: "N/A"
 
+replay:
+  open_recording: "Open Input Recording…"
+  replay_player: "Input Replay"
+  ended: "Replay complete ({frames} frames)"
+  empty_hint: "Open Input Recording (Cmd+O)"
+
+patcher:
+  title: "Patch ROM"
+  rom_label: "ROM file:"
+  patch_label: "Patch file:"
+  outdir_label: "Output dir:"
+  browse: "Browse…"
+  apply: "Apply Patch"
+  working: "Applying patch…"
+  done: "Done →"
+  err_missing_fields: "Please fill in all fields."
+  err_rom_not_found: "ROM file not found."
+  err_patch_not_found: "Patch file not found."
+  err_failed: "Patch failed:"
+  overwrite_title: "File Exists"
+  overwrite_msg: "{path} already exists. Overwrite it?"
+  thread_mode_warn: "Note: Progress may appear stuck on Ruby < 4"
+
 player:
   open_rom_hint: "File > Open ROM…"
   fps: "{fps} fps"
@@ -155,3 +229,21 @@ player:
   ff_max: ">> MAX"
   none: "(none)"
   clear: "Clear"
+
+achievements:
+  title: "Achievements"
+  game_label: "Game:"
+  sync: "Sync"
+  name_col: "Achievement"
+  points_col: "Points"
+  earned_col: "Earned"
+  none: "No achievements loaded"
+  earned_label: "{earned} / {total} earned"
+  sync_pending: "Syncing…"
+  sync_failed: "Sync failed"
+  sync_no_game: "No game loaded"
+  sync_timeout: "Sync timed out"
+  not_logged_in: "Not logged in"
+  include_unofficial: "Include Unofficial"
+  bulk_syncing: "Syncing {title} ({n}/{total})…"
+  bulk_sync_done: "Synced {count} games"