badline 0.8.0 → 0.10.0

data/doc/sid-player.md

@@ -46,7 +46,7 @@ channels.
 Playback asks the device for 44.1 kHz and takes whatever rate it
 offers, unless `--rate` says otherwise. Ctrl-C stops it. The emulator
 window's own options, `--no-autostart`, `--writable`, `--sound`,
-`--true-drive`, `--reu`, `--ntsc` and `--verbose`, don't apply.
+`--true-drive`, `--reu`, `--model`, `--ntsc` and `--verbose`, don't apply.
 
 ## The window
 
@@ -86,9 +86,13 @@ first and last. `n` and `p` step to the next and previous tune. `s`
 turns shuffle on and off, which plays the queue's tunes in a random
 order, and `l` turns looping on and off, so that the end of the queue
 goes on to its start. `,` and `.` seek 10 seconds back and forward
-within the subtune: a seek forward runs on silently from where the
-subtune is, and a seek back plays it again from its start up to the
-point asked for. Space pauses and `q` quits. The status line shows which
+within the subtune. As a subtune plays, the player saves its state every
+10 seconds. A seek back runs silently from the latest of those saved
+states at or before the point asked for, or from the subtune's start
+before the first. A seek forward runs on silently from where the
+subtune is, or from a saved state further on, when an earlier seek back
+left one there. The saved states last until the tune or subtune
+changes. Space pauses and `q` quits. The status line shows which
 modes are on, and they last until the player quits.
 
 `--no-tui`, or output that isn't a terminal, gives plain progress output

data/doc/snapshots.md

@@ -1,11 +1,35 @@
 # Snapshots
 
-In the window, `F11` saves the whole machine to a new
-`badline-<date>-<time>.vsf` in the working directory, and `F12` goes
-back to the snapshot last saved or opened, in a new machine built as the
-saved one was. Both executables do this, and both open a `.vsf` given as
-the media. A snapshot that fails to open leaves the machine running as
-it was.
+In the window, `F11` quicksaves the whole machine to one of five slots,
+`quicksave-1.vsf` to `quicksave-5.vsf` in the `quicksaves` folder of
+badline's data folder. It fills the empty slots first, then replaces the
+one saved longest ago. `F12` restores the newest quicksave, or a named
+save in the data folder's `saves` folder if one is newer, in a new
+machine built as the saved one was. Quicksaves stay after badline quits,
+so `F12` finds them the next time it starts. What's printed on a save or
+a restore names the slot and the file.
+
+A run without `--frames` also autosaves every 6,000 frames the machine
+has run, two minutes on PAL, to `autosave-1.vsf` to `autosave-3.vsf` in
+the `autosaves` folder, replacing the oldest. Time in the pause menu
+doesn't count, nothing is printed, and `F12` never picks an autosave. An
+autosave that fails warns once and stops autosaving.
+
+The pause menu's Snapshots page quicksaves, saves under a name in the
+`saves` folder and loads a named save. The name starts as the game's,
+from its cartridge, disk or tape, or BASIC, with the next free number,
+and saving over a name already taken asks first. Below those, the
+newest quicksaves and autosaves, with the time each was saved, load
+with a press.
+
+The data folder is `~/Library/Application Support/badline` on macOS,
+and `$XDG_DATA_HOME/badline` or `~/.local/share/badline` elsewhere.
+`BADLINE_DATA_PATH` puts it somewhere else.
+
+Both executables do this, and both open a `.vsf` given as the media,
+in a machine built as the saved one was, whatever `--model` says.
+`--save-snapshot FILE` saves one to `FILE` after the last frame. A
+snapshot that fails to open leaves the machine running as it was.
 
 ## From Ruby
 
@@ -25,45 +49,67 @@ a disk or directory mounted through the traps with its open channels,
 and the tape with its place on it. A restored machine runs on exactly
 as the saved one would have.
 
-A directory, a tape and a true drive's disk image open again from their
-paths when the snapshot is restored, the disk with its tracks as the
-drive last saw them. A disk image mounted through the traps comes back
-with its contents from the snapshot. What the host holds stays the
+A tape, a `.t64` archive and a disk image mounted through the traps come
+back with their contents from the snapshot, so they need no file to
+restore. A true drive's disk opens again from its image's path, with its
+tracks as the drive last saw them. When that file is gone, the disk
+comes back from the tracks alone, write-protected. A directory mounted
+as device 8 opens again from its path. What the host holds stays the
 host's: the keyboard, the joysticks, the mouse and paddles, sound, and
 blocks given to `on_init` that hadn't run yet, which a restore reports.
 
-A snapshot only restores in the badline version that wrote it, into a
-machine with the same chip models, RAM expansion and REU.
-`computer.snapshot` holds an REU's RAM, registers and transfer too, but
-a machine with an REU doesn't save to a file yet, as badline doesn't
-write VICE's REU module. Nor does an NTSC machine, as badline doesn't
-write an NTSC VIC-II in VICE's terms yet.
+Every model saves this way, PAL, NTSC, old NTSC and Drean alike, and so
+does a machine with an REU, with its RAM, its registers and a transfer
+part way through. A snapshot only restores in the badline version that
+wrote it, into a machine with the same chip models, region, RAM
+expansion, REU, KERNAL and datasette. One saved before badline recorded
+the KERNAL and the datasette restores as a machine with the C64's KERNAL
+and a datasette.
+
+## The VIC-20
+
+`badline vic20` saves and restores the same way, with the same keys,
+slots and pause menu page. A VIC-20 snapshot holds its RAM and colour
+RAM, a cartridge's ROM, the VIC with its picture and sound, both VIAs,
+the CPU, the tape with its place on it, the disk or directory device 8
+serves through the traps and a true 1541, and restores into a VIC-20
+with the same RAM expansion. Its file names its machine `VIC20`, as
+xvic's do, and holds only the `BADLINE` module, so xvic doesn't open
+it, and badline doesn't open xvic's. Restoring a
+VIC-20 snapshot while a C64 runs, or a C64 one while a VIC-20 runs,
+swaps the machine in the window.
 
 ## VICE
 
 Snapshots use VICE's `.vsf` format. badline writes VICE's modules for
-the CPU, RAM and CPU port, both CIAs, the SID and the VIC-II, plus the
-ones x64sc needs to open the file, with nothing attached to the
-cartridge, tape or user ports and no true drive. A `BADLINE` module,
-which VICE skips, holds the whole machine, and badline restores its own
-snapshots from it.
+the CPU, RAM and CPU port, both CIAs, the SID and the VIC-II, and an
+REU's `REU1764`, plus the ones x64sc needs to open the file, with
+nothing else attached to the cartridge port, nothing on the tape or user
+ports and no true drive. The VIC-II module names the chip as VICE does:
+the 6569 or 8565 on PAL, the 6567R8 or 8562 on NTSC, the 6567R56A on old
+NTSC and the 6572 on PAL-N. A `BADLINE` module, which VICE skips, holds
+the whole machine, and badline restores its own snapshots from it.
 
 x64sc 3.10 opens badline's snapshots, taken at the end of the
-instruction the CPU was in, as long as its VIC-II model matches
-(`-model c64` for the default machine). It keeps its own drives and
-leaves out the cartridge, the expansions and the tape.
+instruction the CPU was in, and of an REU transfer under way, as long
+as its VIC-II model matches: `-model c64`, `c64c`, `ntsc`, `newntsc`,
+`oldntsc` or `drean`, as `--model` names the machine. It takes the REU
+from the snapshot, keeps its own drives and leaves out the cartridge,
+the other expansions and the tape. A program x64sc runs on from badline's
+snapshot reads the raster as badline does, cycle for cycle.
 
 Snapshots x64sc saves open in badline through the same modules: the CPU
 at its instruction boundary, RAM, the CPU port, the CIAs' registers,
-timers and clocks, the SID's registers and reSID voice state, and the
-VIC-II's registers, beam position, counters and colour RAM. The VIC-II's
-pixel pipeline starts empty. badline reads the modules x64sc 3.7 to 3.10
-write, and VICE's development versions' `MAINC64CPU` and `VIC-IISC`. A
-module version it doesn't know is left out, or fails the restore for the
-CPU and RAM. It reports the modules it leaves out, such as the 1541
-drives, the cartridge, the datasette and the keyboard, and carries on
-without them. A snapshot of an NTSC machine fails, as badline reads only
-VICE's PAL VIC-II. Restored into a running machine, a VICE snapshot
+timers and clocks, the SID's registers and reSID voice state, the
+VIC-II's registers, beam position, counters and colour RAM, and an
+REU's size, registers and RAM. The VIC-II's model builds the machine's
+region, and the 6569R1 runs as the 6569. The VIC-II's pixel pipeline
+starts empty. badline reads the modules x64sc 3.7 to 3.10 write, and
+VICE's development versions' `MAINC64CPU` and `VIC-IISC`. A module
+version it doesn't know is left out, or fails the restore for the CPU
+and RAM. It reports the modules it leaves out, such as the 1541 drives,
+the cartridge port, the datasette and the keyboard, and carries on
+without them. Restored into a running machine, a VICE snapshot
 fails for a machine built another way, such as a C64C's snapshot in a
 C64, and otherwise takes the cartridge out and switches the machine off
 and on.

data/lib/badline/address_bus/pla.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Badline
+  class AddressBus
+    # The C64's PLA: what each page of the CPU's view maps to, from the
+    # CPU port's LORAM, HIRAM and CHAREN lines and the cartridge's EXROM
+    # and GAME. The bus that includes it supplies the page tables, the
+    # ROMs, the chips, and #map_ram_pages, which lays out the RAM that the
+    # ROMs, the cartridge and I/O map over.
+    module PLA
+      private
+
+      def map_pla_pages
+        map_ram_pages
+        @ultimax ? map_ultimax_pages : map_banked_pages
+      end
+
+      def map_banked_pages
+        map_rom_overlays
+        map_cartridge_ram
+        @write_pages.fill(@cartridge.romh_writes, 0xe0, 0x20) if @cartridge&.romh_writes
+
+        if io?
+          map_io_pages
+        elsif character?
+          @read_pages.fill(character_rom, 0xd0, 0x10)
+        end
+      end
+
+      # Ultimax cartridges ignore the $01 lines: 4K of RAM, ROML/ROMH windows,
+      # I/O always visible and open address space everywhere else. The ROML
+      # and ROMH selects fire on writes as well, so cartridge RAM or flash in
+      # either window takes the writes there.
+      def map_ultimax_pages
+        @read_pages.fill(@open_bus, 0x10, 0xf0)
+        @write_pages.fill(@open_bus, 0x10, 0xf0)
+        @read_pages.fill(@cartridge.roml, 0x80, 0x20) if @cartridge.roml
+        map_ultimax_writes(@cartridge.roml, 0x80)
+        @read_pages.fill(@cartridge.romh, 0xe0, 0x20) if @cartridge.romh
+        map_ultimax_writes(@cartridge.romh, 0xe0)
+        map_ultimax_a000
+        map_io_pages
+      end
+
+      def map_ultimax_writes(bank, first_page)
+        @write_pages.fill(bank, first_page, 0x20) if bank.respond_to?(:poke)
+      end
+
+      def map_ultimax_a000
+        return unless (window = @cartridge.ultimax_a000)
+
+        @read_pages.fill(window, 0xa0, 0x20)
+        @write_pages.fill(window, 0xa0, 0x20)
+      end
+
+      # EXROM and GAME select the cartridge whether or not it has a chip
+      # there, and an empty socket leaves the bus floating.
+      def map_rom_overlays
+        @read_pages.fill(@cartridge.roml || @open_bus, 0x80, 0x20) if roml?
+        if romh?
+          @read_pages.fill(@cartridge.romh || @open_bus, 0xa0, 0x20)
+        elsif basic?
+          @read_pages.fill(basic_rom, 0xa0, 0x20)
+        end
+        @read_pages.fill(kernal_rom, 0xe0, 0x20) if kernal?
+      end
+
+      # Cartridge RAM in the ROML or ROMH window decodes writes itself,
+      # whatever the $01 lines say.
+      def map_cartridge_ram
+        return unless @cartridge&.exrom&.zero?
+
+        map_cartridge_ram_bank(@cartridge.roml, 0x80)
+        map_cartridge_ram_bank(@cartridge.romh, 0xa0) if @cartridge.game.zero?
+      end
+
+      def map_cartridge_ram_bank(bank, first_page)
+        @write_pages.fill(bank, first_page, 0x20) if bank.is_a?(Cartridge::RAMBank)
+      end
+
+      def map_io_pages
+        {
+          vic => 0xd0..0xd3, sid => 0xd4..0xd7, color_ram => 0xd8..0xdb,
+          cia1 => 0xdc..0xdc, cia2 => 0xdd..0xdd, @open_bus => 0xde..0xdf
+        }.each do |chip, pages|
+          pages.each { |p| @read_pages[p] = @write_pages[p] = chip }
+        end
+        @ram_expansion.map_io(@read_pages, @write_pages)
+        @read_pages[0xd7] = @write_pages[0xd7] = @debug_register if @debug_register
+        @read_pages[0xdf] = @write_pages[0xdf] = @reu if @reu
+        map_cartridge_io if @cartridge
+        map_extra_sids unless @sid_slots.empty?
+      end
+
+      def map_cartridge_io
+        @write_pages.fill(@cartridge, 0xde, 2)
+        @cartridge.readable_io_pages.each { |p| @read_pages[p] = @cartridge }
+      end
+
+      def basic?
+        io_port.kernal? && io_port.basic? && game_high?
+      end
+
+      def game_high?
+        @cartridge.nil? || @cartridge.game == 1
+      end
+
+      def roml?
+        @cartridge&.exrom&.zero? && io_port.kernal? && io_port.basic?
+      end
+
+      def romh?
+        @cartridge&.exrom&.zero? && @cartridge.game.zero? && io_port.kernal?
+      end
+
+      # In 16K mode LORAM alone leaves $d000 as RAM, where it still maps I/O.
+      def character?
+        (io_port.kernal? || (io_port.basic? && game_high?)) && !io_port.io?
+      end
+
+      def io?
+        (io_port.basic? || io_port.kernal?) && io_port.io?
+      end
+
+      def kernal?
+        io_port.kernal?
+      end
+    end
+  end
+end

data/lib/badline/address_bus/roms.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Badline
+  class AddressBus
+    # The BASIC, character and KERNAL ROMs, and which KERNAL is fitted.
+    module ROMs
+      # The KERNAL ROMs a machine can be fitted with, by name: the C64's
+      # and the SX-64's.
+      KERNALS = { c64: "kernal.rom", sx64: "kernal-sx64.rom" }.freeze
+
+      attr_reader :basic_rom, :character_rom, :kernal_rom, :kernal
+
+      # Fits the KERNAL ROM KERNALS names `name`, in place of the one before.
+      def kernal=(name)
+        raise ArgumentError, "no KERNAL named #{name}" unless KERNALS.key?(name)
+
+        @kernal = name
+        @kernal_rom = ROM.load(KERNALS[name], 0xe000)
+        update_overlays!
+      end
+
+      private
+
+      def load_roms
+        @basic_rom = ROM.load("basic.rom", 0xa000)
+        @character_rom = ROM.load("character.rom", 0xd000)
+        @kernal = :c64
+        @kernal_rom = ROM.load(KERNALS[:c64], 0xe000)
+      end
+    end
+  end
+end

data/lib/badline/address_bus.rb

@@ -3,7 +3,8 @@
 require "badline/address_bus/saved_state"
 require "badline/address_bus/sid_slots"
 require "badline/address_bus/extra_sids"
-require "badline/address_bus/ultimax_pages"
+require "badline/address_bus/pla"
+require "badline/address_bus/roms"
 
 module Badline
   # Memory layout:
@@ -33,8 +34,9 @@ module Badline
   # 0xE000-0xFFFF - KERNAL ROM / Cartridge ROM (high) - 8kb
   class AddressBus
     include Addressable
-    include UltimaxPages
+    include PLA
     include ExtraSIDs
+    include ROMs
 
     # I/O 1 and 2, and the Ultimax holes, with nothing on the bus. A read
     # picks up the byte the VIC fetched in the preceding phi1 half-cycle,
@@ -58,7 +60,7 @@ module Badline
     # See doc/pinned-behaviour.md.
     RAM_POWER_ON = Array.new(2**16) { |addr| (((addr + 2) / 4) ^ (addr / 0x4000)).odd? ? 0xff : 0x00 }.freeze
 
-    attr_reader :io_port, :ram, :basic_rom, :character_rom, :kernal_rom,
+    attr_reader :io_port, :ram,
                 :vic, :sid, :color_ram, :cia1, :cia2, :keyboard, :joystick1, :joystick2,
                 :control_ports, :cartridge, :ultimax, :phi1_ultimax, :datasette, :region, :video_ram, :reu
 
@@ -71,15 +73,13 @@ module Badline
       @cartridge = @reu = nil
       @debug_register = nil
 
-      @basic_rom     = ROM.load("basic.rom",     0xa000)
-      @character_rom = ROM.load("character.rom", 0xd000)
-      @kernal_rom    = ROM.load("kernal.rom",    0xe000)
+      load_roms
 
       @keyboard = Keyboard.new
       @joystick1 = Joystick.new
       @joystick2 = Joystick.new
       @control_ports = ControlPorts.new(keyboard: @keyboard, joystick1: @joystick1, joystick2: @joystick2)
-      @vic  = VIC.new(self, model: vic_model, region:)
+      @vic  = VIC.new(model: vic_model, region:)
       @cia1 = CIA.new(start: 0xdc00, peripheral: @control_ports, model: cia_model, region:)
       @cia2 = CIA.new(start: 0xdd00, model: cia_model, region:)
       @control_ports.port_a_source = @cia1
@@ -92,6 +92,8 @@ module Badline
       @datasette.on_sense_change { @io_port.value = port_value }
 
       @color_ram = ColorMemory.new(@vic)
+      @vic.vic_bank.connect(cia2: @cia2, color_ram: @color_ram)
+      @vic.vic_bank.map_character_rom(character_rom)
       @open_bus = OpenBus.new(@vic)
       @cpu_off_bus = false
 
@@ -201,96 +203,15 @@ module Badline
     def update_overlays!
       @ultimax = @cartridge ? @cartridge.ultimax? : false
       @phi1_ultimax = @cartridge ? @cartridge.phi1_ultimax? : false
-      @ram_expansion.map(@read_pages, @write_pages)
       @video_ram = @ram_expansion.video_ram
+      @vic.vic_bank.map(@video_ram, phi1_ultimax: @phi1_ultimax, ultimax: @ultimax, romh: @cartridge&.romh)
 
-      @ultimax ? map_ultimax_pages : map_banked_pages
+      map_pla_pages
       @write_pages[0xff] = @reu.trigger.wrap(@write_pages[0xff]) if @reu
     end
 
-    def map_banked_pages
-      map_rom_overlays
-      map_cartridge_ram
-      @write_pages.fill(@cartridge.romh_writes, 0xe0, 0x20) if @cartridge&.romh_writes
-
-      if io?
-        map_io_pages
-      elsif character?
-        @read_pages.fill(character_rom, 0xd0, 0x10)
-      end
-    end
-
-    # EXROM and GAME select the cartridge whether or not it has a chip
-    # there, and an empty socket leaves the bus floating.
-    def map_rom_overlays
-      @read_pages.fill(@cartridge.roml || @open_bus, 0x80, 0x20) if roml?
-      if romh?
-        @read_pages.fill(@cartridge.romh || @open_bus, 0xa0, 0x20)
-      elsif basic?
-        @read_pages.fill(basic_rom, 0xa0, 0x20)
-      end
-      @read_pages.fill(kernal_rom, 0xe0, 0x20) if kernal?
-    end
-
-    # Cartridge RAM in the ROML or ROMH window decodes writes itself,
-    # whatever the $01 lines say.
-    def map_cartridge_ram
-      return unless @cartridge&.exrom&.zero?
-
-      map_cartridge_ram_bank(@cartridge.roml, 0x80)
-      map_cartridge_ram_bank(@cartridge.romh, 0xa0) if @cartridge.game.zero?
-    end
-
-    def map_cartridge_ram_bank(bank, first_page)
-      @write_pages.fill(bank, first_page, 0x20) if bank.is_a?(Cartridge::RAMBank)
-    end
-
-    def map_io_pages
-      {
-        vic => 0xd0..0xd3, sid => 0xd4..0xd7, color_ram => 0xd8..0xdb,
-        cia1 => 0xdc..0xdc, cia2 => 0xdd..0xdd, @open_bus => 0xde..0xdf
-      }.each do |chip, pages|
-        pages.each { |p| @read_pages[p] = @write_pages[p] = chip }
-      end
-      @ram_expansion.map_io(@read_pages, @write_pages)
-      @read_pages[0xd7] = @write_pages[0xd7] = @debug_register if @debug_register
-      @read_pages[0xdf] = @write_pages[0xdf] = @reu if @reu
-      map_cartridge_io if @cartridge
-      map_extra_sids unless @sid_slots.empty?
-    end
-
-    def map_cartridge_io
-      @write_pages.fill(@cartridge, 0xde, 2)
-      @cartridge.readable_io_pages.each { |p| @read_pages[p] = @cartridge }
-    end
-
-    def basic?
-      io_port.kernal? && io_port.basic? && game_high?
-    end
-
-    def game_high?
-      @cartridge.nil? || @cartridge.game == 1
-    end
-
-    def roml?
-      @cartridge&.exrom&.zero? && io_port.kernal? && io_port.basic?
-    end
-
-    def romh?
-      @cartridge&.exrom&.zero? && @cartridge.game.zero? && io_port.kernal?
-    end
-
-    # In 16K mode LORAM alone leaves $d000 as RAM, where it still maps I/O.
-    def character?
-      (io_port.kernal? || (io_port.basic? && game_high?)) && !io_port.io?
-    end
-
-    def io?
-      (io_port.basic? || io_port.kernal?) && io_port.io?
-    end
-
-    def kernal?
-      io_port.kernal?
+    def map_ram_pages
+      @ram_expansion.map(@read_pages, @write_pages)
     end
   end
 end

data/lib/badline/audio/bare_player.rb

@@ -74,6 +74,30 @@ module Badline
         settle
       end
 
+      # The rig between frames: the bus and its chips, the extra SIDs, the
+      # CPU, and the call waiting for the idle loop.
+      def save_state(out)
+        out.marker("BARE PLAYER")
+        @bus.save_state(out)
+        @extras.each { |sid| sid.save_state(out) }
+        @cpu.save_state(out)
+        out.optional_int(@pending).int(@argument).boolean(@idle)
+      end
+
+      # Takes a rig that hasn't started to where #save_state found one, in
+      # place of #start.
+      def load_state(input)
+        input.marker("BARE PLAYER")
+        @bus.load_state(input)
+        @extras.each { |sid| sid.load_state(input) }
+        @cpu.load_state(input)
+        @pending = input.optional_int
+        @argument = input.int
+        @idle = input.boolean?
+        @stereo.synthesize!
+        install_dispatch
+      end
+
       # Advances one call of play, or `budget` cycles if that is shorter,
       # then yields whatever the SIDs recorded over it, in stereo. Returns
       # the cycles advanced.

data/lib/badline/audio/checkpoints.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Badline
+  module Audio
+    # The states a subtune's renderer saved as it played, at the first
+    # frame end past every `every` seconds, so that a seek starts from the
+    # latest one at or before where it goes rather than from the subtune's
+    # start. Whoever plays the subtune keeps them across its renderers, and
+    # drops them for another subtune.
+    class Checkpoints
+      EVERY = 10.0
+
+      def initialize(every: EVERY)
+        @every = every
+        @cycles = []
+        @states = []
+      end
+
+      # Whether the frame ending `cycles` into the subtune is the first past
+      # the next mark.
+      def due?(cycles, clock_hz) = cycles >= ((@cycles.length + 1) * @every * clock_hz).round
+
+      def keep(cycles, state)
+        @cycles << cycles
+        @states << state
+      end
+
+      # The state saved latest at or before `cycles`, or nil.
+      def latest(cycles)
+        index = @cycles.rindex { |at| at <= cycles }
+        index.nil? ? nil : @states[index]
+      end
+
+      # The cycles into the subtune of the state saved latest at or before
+      # `cycles`, or 0 for the start.
+      def reach(cycles)
+        index = @cycles.rindex { |at| at <= cycles }
+        index.nil? ? 0 : @cycles[index]
+      end
+    end
+  end
+end

data/lib/badline/audio/jukebox.rb

@@ -7,9 +7,11 @@ module Badline
     # turn the queue's shuffle, loop and all-subtunes modes on and off, and
     # quit, and the status line follows along. Seeking runs the subtune
     # silently up to where it was asked to go: on from where it is to go
-    # forward, and from the start again to go back. A subtune that plays to
-    # its end moves on as Media::Queue#advance says. It stops at the end of
-    # the queue, on q, or on Ctrl-C.
+    # forward, and from the latest of its Checkpoints at or before there to
+    # go back, or to go forward when that checkpoint is further on than
+    # where the subtune is. A subtune that plays to its end moves on as
+    # Media::Queue#advance says. It stops at the end of the queue, on q, or
+    # on Ctrl-C.
     #
     # `renderer` builds the renderer for an entry's subtune at the sink's
     # rate, or returns nil for an entry that can't play, which is skipped
@@ -34,6 +36,9 @@ module Badline
         @backward = false
         @below_at = -BELOW_NOTE
         @from = 0.0
+        @entry = nil
+        @subtune = 0
+        @checkpoints = Checkpoints.new
       end
 
       # Returns the result of the last subtune's Playback#play, or :unplayable
@@ -77,6 +82,7 @@ module Badline
       end
 
       def play(entry, subtune)
+        @checkpoints = Checkpoints.new unless entry.equal?(@entry) && subtune == @subtune
         @entry = entry
         @subtune = subtune
         @elapsed = 0.0
@@ -84,6 +90,7 @@ module Badline
         return :unplayable if renderer.nil?
 
         renderer.from = @from
+        renderer.checkpoints = @checkpoints
         @streaming = renderer
         @from = 0.0
         @backward = false
@@ -127,7 +134,7 @@ module Badline
 
       def seek(seconds)
         target = seconds.clamp(0.0, [@length.call(@entry, @subtune) - 1.0, 0.0].max)
-        return @streaming.from = target if target > @elapsed
+        return @streaming.from = target if target > @elapsed && !@streaming.checkpoint_ahead?(target)
 
         @from = target
         skip

data/lib/badline/audio/machine_player.rb

@@ -39,6 +39,22 @@ module Badline
 
       def clock_hz = @computer.region.clock_hz
 
+      # The whole machine, as Computer#snapshot takes it, and the extra SIDs,
+      # once it plays.
+      def save_state(out)
+        @computer.save_state(out)
+        @extras.each { |sid| sid.save_state(out) }
+      end
+
+      # Takes a machine that hasn't started to where #save_state found one,
+      # in place of #start.
+      def load_state(input)
+        @computer.load_state(input)
+        @extras.each { |sid| sid.load_state(input) }
+        @stereo.synthesize!
+        @started = true
+      end
+
       # Advances one frame of the machine, or `budget` cycles if that is
       # shorter, then yields whatever the SIDs recorded over it, in stereo.
       # Returns the cycles advanced.