gemba 0.1.1 → 0.2.1

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/list_picker_frame.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module Gemba
+  # Startup frame showing all library ROMs as a sortable treeview list.
+  #
+  # Alternative to GamePickerFrame (no boxart). Columns: Title, Last Played.
+  # Clicking a column header sorts; the active column shows a ▲/▼ indicator.
+  # Double-clicking a row emits :rom_selected. Right-clicking shows a context
+  # menu identical to the GamePickerFrame card menu.
+  # Pure Tk — no SDL2.
+  class ListPickerFrame
+    include BusEmitter
+    include Locale::Translatable
+
+    LIST_DEFAULT_W = 480
+    LIST_DEFAULT_H = 600
+    LIST_MIN_W     = 320
+    LIST_MIN_H     = 400
+
+    SORT_ASC  = ' ▲'
+    SORT_DESC = ' ▼'
+
+    def default_geometry = [LIST_DEFAULT_W, LIST_DEFAULT_H]
+    def min_geometry     = [LIST_MIN_W,     LIST_MIN_H]
+
+    def initialize(app:, rom_library:, rom_overrides: nil)
+      @app         = app
+      @rom_library = rom_library
+      @overrides   = rom_overrides
+      @built       = false
+      @sort_col    = 'last_played'
+      @sort_asc    = false   # most-recent first by default
+      @row_data    = {}      # treeview item id => RomInfo
+    end
+
+    def show
+      build_ui unless @built
+      refresh
+      @app.command(:pack, @outer, fill: :both, expand: 1)
+    end
+
+    def hide
+      @app.command(:pack, :forget, @outer) rescue nil
+    end
+
+    def cleanup; end
+
+    def receive(event, **_args)
+      case event
+      when :refresh then refresh
+      end
+    end
+
+    def aspect_ratio = nil
+    def rom_loaded?  = false
+    def sdl2_ready?  = false
+    def paused?      = false
+
+    private
+
+    def build_ui
+      @outer = '.list_picker'
+      @app.command('ttk::frame', @outer, padding: 8)
+
+      # Treeview + scrollbar
+      @tree = "#{@outer}.tree"
+      @scrollbar = "#{@outer}.scroll"
+
+      @app.command('ttk::treeview', @tree,
+        columns: Teek.make_list('title', 'last_played'),
+        show: :headings,
+        selectmode: :browse)
+
+      @app.command('ttk::scrollbar', @scrollbar, orient: :vertical,
+        command: "#{@tree} yview")
+      @app.command(@tree, :configure, yscrollcommand: "#{@scrollbar} set")
+
+      build_columns
+      bind_events
+
+      @app.command(:grid, @tree,      row: 0, column: 0, sticky: :nsew)
+      @app.command(:grid, @scrollbar, row: 0, column: 1, sticky: :ns)
+      @app.command(:grid, :columnconfigure, @outer, 0, weight: 1)
+      @app.command(:grid, :rowconfigure,    @outer, 0, weight: 1)
+
+      build_toolbar
+
+      @built = true
+    end
+
+    def build_columns
+      @app.command(@tree, :heading, 'title',
+        text: translate('list_picker.columns.title') + (@sort_col == 'title' ? sort_indicator : ''),
+        anchor: :w,
+        command: proc { sort_by('title') })
+      @app.command(@tree, :heading, 'last_played',
+        text: translate('list_picker.columns.last_played') + (@sort_col == 'last_played' ? sort_indicator : ''),
+        anchor: :w,
+        command: proc { sort_by('last_played') })
+      @app.command(@tree, :column, 'title',       width: 280, stretch: 1)
+      @app.command(@tree, :column, 'last_played', width: 120, stretch: 0)
+    end
+
+    def bind_events
+      # Physical double-click fires virtual event so tests can trigger it
+      # directly without needing event generate <Double-Button-1> (forbidden in Tk 9).
+      @app.command(:bind, @tree, '<Double-Button-1>', proc {
+        @app.tcl_eval("event generate #{@tree} <<DoubleClick>>")
+      })
+      @app.command(:bind, @tree, '<<DoubleClick>>', proc {
+        iid = @app.tcl_eval("#{@tree} focus")
+        next if iid.to_s.empty?
+        rom_info = @row_data[iid]
+        emit(:rom_selected, rom_info.path) if rom_info
+      })
+
+      # Physical right-click: use %x/%y (widget-relative event coords) to
+      # identify the row, select and focus it, then fire the virtual event so
+      # tests can trigger the same code path without real pointer coordinates.
+      @app.tcl_eval(<<~TCL)
+        bind #{@tree} <Button-3> {+
+          set _iid [#{@tree} identify row %x %y]
+          if {$_iid ne {}} {
+            #{@tree} selection set $_iid
+            #{@tree} focus $_iid
+            event generate #{@tree} <<RightClick>>
+          }
+        }
+      TCL
+
+      # Virtual event reads the currently focused item. Decoupled from pointer
+      # position so tests can trigger it directly after setting focus.
+      @app.command(:bind, @tree, '<<RightClick>>', proc {
+        iid = @app.tcl_eval("#{@tree} focus")
+        rom_info = @row_data[iid.to_s]
+        post_row_menu(rom_info) if rom_info
+      })
+    end
+
+    def build_toolbar
+      sep = "#{@outer}.sep"
+      @app.command('ttk::separator', sep, orient: :horizontal)
+      @app.command(:grid, sep, row: 1, column: 0, columnspan: 2, sticky: :ew, pady: [4, 0])
+
+      toolbar = "#{@outer}.toolbar"
+      @app.command('ttk::frame', toolbar, padding: [4, 2])
+      @app.command(:grid, toolbar, row: 2, column: 0, columnspan: 2, sticky: :ew)
+
+      gear_btn  = "#{toolbar}.gear"
+      gear_menu = "#{toolbar}.gearmenu"
+      @app.command('ttk::button', gear_btn, text: "\u2699", width: 1,
+        command: proc { post_view_menu(gear_menu, gear_btn) })
+      @app.command(:pack, gear_btn, side: :right)
+    end
+
+    def refresh
+      @app.tcl_eval("#{@tree} delete [#{@tree} children {}]")
+      @row_data.clear
+
+      roms = sorted(@rom_library.all)
+      roms.each do |rom|
+        rom_info = RomInfo.from_rom(rom, overrides: @overrides)
+        lp       = format_last_played(rom['last_played'])
+        iid = @app.tcl_eval(
+          "#{@tree} insert {} end -values [list #{Teek.make_list(rom_info.title, lp)}]"
+        )
+        @row_data[iid] = rom_info
+      end
+    end
+
+    def sorted(roms)
+      sorted = roms.sort_by do |r|
+        case @sort_col
+        when 'title'       then r['title'].to_s.downcase
+        when 'last_played' then r['last_played'] || r['added_at'] || ''
+        end
+      end
+      @sort_asc ? sorted : sorted.reverse
+    end
+
+    def sort_by(col)
+      if @sort_col == col
+        @sort_asc = !@sort_asc
+      else
+        @sort_col = col
+        @sort_asc = (col == 'title')  # title: asc first; date: newest first
+      end
+      update_headings
+      refresh
+    end
+
+    def update_headings
+      ['title', 'last_played'].each do |col|
+        label_key = col == 'title' ? 'list_picker.columns.title' : 'list_picker.columns.last_played'
+        indicator = @sort_col == col ? sort_indicator : ''
+        @app.command(@tree, :heading, col, text: translate(label_key) + indicator)
+      end
+    end
+
+    def sort_indicator
+      @sort_asc ? SORT_ASC : SORT_DESC
+    end
+
+    def format_last_played(iso)
+      return translate('list_picker.never_played') if iso.to_s.empty?
+      require 'time'
+      Time.parse(iso).localtime.strftime('%b %-d, %Y')
+    rescue
+      iso.to_s
+    end
+
+    def post_view_menu(menu, btn)
+      @app.command(:menu, menu, tearoff: 0) unless @app.tcl_eval("winfo exists #{menu}") == '1'
+      @app.command(menu, :delete, 0, :end)
+      current = Gemba.user_config.picker_view
+      @app.command(menu, :add, :command,
+        label: "#{current == 'grid' ? "\u2713 " : '  '}#{translate('picker.toolbar.boxart_view')}",
+        command: proc { emit(:picker_view_changed, view: 'grid') })
+      @app.command(menu, :add, :command,
+        label: "#{current == 'list' ? "\u2713 " : '  '}#{translate('picker.toolbar.list_view')}",
+        command: proc { emit(:picker_view_changed, view: 'list') })
+      x = @app.tcl_eval("winfo rootx #{btn}").to_i
+      y = @app.tcl_eval("winfo rooty #{btn}").to_i
+      h = @app.tcl_eval("winfo height #{btn}").to_i
+      @app.tcl_eval("tk_popup #{menu} #{x} #{y + h}")
+    end
+
+    def post_row_menu(rom_info)
+      menu = "#{@tree}.ctx"
+      @app.command(:menu, menu, tearoff: 0) unless @app.tcl_eval("winfo exists #{menu}") == '1'
+      @app.command(menu, :delete, 0, :end)
+      @app.command(menu, :add, :command,
+        label: translate('game_picker.menu.play'),
+        command: proc { emit(:rom_selected, rom_info.path) })
+      qs_slot  = Gemba.user_config.quick_save_slot
+      qs_state = quick_save_exists?(rom_info, qs_slot)
+      @app.command(menu, :add, :command,
+        label: translate('game_picker.menu.quick_load'),
+        state: qs_state ? :normal : :disabled,
+        command: proc { emit(:rom_quick_load, path: rom_info.path, slot: qs_slot) })
+      @app.command(menu, :add, :command,
+        label: translate('game_picker.menu.set_boxart'),
+        command: proc { pick_custom_boxart(rom_info) })
+      @app.command(menu, :add, :separator)
+      @app.command(menu, :add, :command,
+        label: translate('game_picker.menu.remove'),
+        command: proc { remove_rom(rom_info) })
+      @app.tcl_eval("tk_popup #{menu} [winfo pointerx .] [winfo pointery .]")
+    end
+
+    def quick_save_exists?(rom_info, slot)
+      return false unless rom_info.rom_id
+      state_file = File.join(Gemba.user_config.states_dir, rom_info.rom_id, "state#{slot}.ss")
+      File.exist?(state_file)
+    end
+
+    def remove_rom(rom_info)
+      @rom_library.remove(rom_info.rom_id)
+      @rom_library.save!
+      refresh
+    end
+
+    def pick_custom_boxart(rom_info)
+      return unless @overrides
+      filetypes = '{{PNG Images} {.png}}'
+      path = @app.tcl_eval("tk_getOpenFile -filetypes {#{filetypes}}")
+      return if path.to_s.strip.empty?
+      @overrides.set_custom_boxart(rom_info.rom_id, path)
+    end
+  end
+end