badline 0.7.0 → 0.9.0

data/doc/media.md

@@ -0,0 +1,78 @@
+# Media
+
+The [README](../README.md#media) lists the formats badline takes. This
+page covers how device 8 and the true 1541 work, and how to attach media
+from Ruby.
+
+## Device 8 without a drive
+
+Apart from a `.g64`, which only a true drive can read, there is no 1541
+unless `--true-drive` asks for one. Device 8 works by trapping the
+KERNAL's `LOAD` and `SAVE` routines and its serial bus primitives, so
+files open by name through `OPEN` and `CHRIN` as well. `LOAD"$",8` lists
+the directory of any medium mounted there, as a 1541 does.
+
+The command channel answers `I`, `B-P` and `U1` block reads, which
+covers loaders that read blocks directly. On a writable disk image it
+also takes `SAVE` (with `@0:` to replace a file), files opened for
+writing or appending, `S` to scratch, `U2` and `B-W` block writes, and
+`B-A` and `B-F`. It doesn't rename, copy, format or validate disks.
+Loaders that upload their own code to the drive with `M-W` and `M-E`,
+and copy protection that reads raw GCR, won't work there, but do on a
+true drive.
+
+A directory mounted as device 8 serves the `.prg` and `.p00` files in it
+and the contents of any `.t64`, and `SAVE` writes a new `.prg`.
+
+## The true 1541
+
+`--true-drive` puts an emulated 1541 on device 8 instead, running its
+own DOS ROM on its own 6502 and talking to the machine over the serial
+bus. It reads `.d64` and `.g64` images, which it autostarts with the
+same `LOAD"*",8,1` and `RUN`, but not `.d71`, `.d81` or `.t64` images
+or directories. Loading runs at the speed of a real 1541, and the
+drive's red LED lights in the bottom right corner of the border.
+
+A `.g64` holds the disk's raw GCR, half tracks and all, so copy
+protection and fast loaders that read it work.
+
+## Write protection
+
+Disks given on the command line, inserted from the pause menu or by an
+`--at` insert go in write-protected, so the drive reports
+`26,WRITE PROTECT ON` for any write and the image file stays as it was.
+`--writable`, or WRITABLE on the pause menu's Drive page, lets writes go
+straight back to the image file. An image the host can't write, and a
+`.t64`, stay write-protected.
+
+## From Ruby
+
+`Badline::Media.attach(computer, path)` attaches any medium the
+command line takes, and autostarts it unless given `autostart: false`.
+`Badline::Media.insert_disk(computer, path)` swaps the disk image or
+directory in device 8 while the machine runs, for software that asks for
+another disk. Both write to disk images unless told otherwise:
+`insert_disk` takes `read_only: true`, and `attach` takes
+`disk: { read_only: true }`, as the test harnesses under `bin/` do. A
+`.g64` goes in the true 1541, and takes out a disk mounted through the
+traps, so `LOAD` and `SAVE` reach the 1541 too. With the 1541 in device
+8, a `.d64` goes in its drive as well.
+
+`Badline::Media::DiskSet.around(path)` lists the disks of the set a disk
+image belongs to, which the pause menu's PREVIOUS DISK and NEXT DISK step
+through. An `.m3u` or `.vfl` list in the disk's folder that names it
+gives the set. Without one, the set is found by name in the folder.
+Given a list, it returns the disks the list names.
+
+A list names one disk image a line, as a path relative to the list or an
+absolute one. Blank lines and lines starting with `#` are skipped, and
+entries that aren't there are left out. In a VICE `.vfl` flip list, only
+the entries after a `UNIT 8` line, or before any `UNIT` line, count.
+`Media.attach` and the command line take a list as media and attach its
+first disk.
+
+## The light pen
+
+Control port 1's fire line is also the VIC-II's light pen input, so
+joystick 1's fire button and the 1351's left button in port 1 latch the
+light pen registers.

data/doc/pinned-behaviour.md

@@ -26,6 +26,7 @@ only catches the rows that happen to move.
 - [VIC light pen](#vic-light-pen)
 - [VIC-II 8565](#vic-ii-8565)
 - [VIC-II NTSC](#vic-ii-ntsc)
+- [VIC-II 6572 (Drean)](#vic-ii-6572-drean)
 - [CIA 6526 timer pipeline](#cia-6526-timer-pipeline)
 - [CIA 6526A interrupt register](#cia-6526a-interrupt-register)
 - [CIA serial shift register](#cia-serial-shift-register)
@@ -293,7 +294,9 @@ only catches the rows that happen to move.
   early in the next one for 3–7.
   - A sprite still shifting at K loses the rest of its row. Its output
     holds its last pixel from K through **K+6**, then goes dark.
-  - A comparator hit in K..K+11 shows nothing.
+  - A comparator hit in K..K+11 shows nothing. Where K falls in the
+    last 11 pixels of the line, as sprite 3's does on a 65-cycle line,
+    the twelve run on into the next line's first pixels.
   - A hit from K+12 on shows the row the reload brought. For sprites 0–2
     that is the *next* line's row, a line early. For sprites 3–7 it is the
     current row, and a hit ahead of their K shows the previous line's row.
@@ -307,6 +310,11 @@ only catches the rows that happen to move.
     `spritex/demusinterruptus` and `spritegap2` pass on it too.
   - Spec guard: *the reload* in
     [`vic/sprite_spec.rb`](../spec/badline/vic/sprite_spec.rb).
+  - The run into the next line is pinned by `spritescan_drean`'s 6572
+    dump, where sprite 3 shows nothing for X = $193 to $19e, the twelve
+    pixels from K = 515 on a 520-pixel line. Without it a hit at $198 to
+    $19e collides. Spec guard: *the reload near the end of a 65-cycle
+    line*. The `testbench-ntsc` sprite rows pass either way.
   - The hold's length is pinned by `spritefetchbug/test-136-2a`, whose
     X-expanded sprite 0 sits at X = $136 and is still shifting at 459. Its
     reference holds the last pixel through 465. Holding it for one pixel
@@ -941,14 +949,22 @@ region moves the sprites. The positions live in `Region::Profile` and
   - Spec guard: *sprite DMA cycle stealing on NTSC* and *#phi1_data on
     NTSC* in [`vic_spec.rb`](../spec/badline/vic_spec.rb), and
     [`timing_spec.rb`](../spec/badline/vic/sprite/timing_spec.rb).
-- **Display compare and X counter.** The 6567R8 turns a sprite's display
-  on and off in cycle 59 (`sprite_display_cycle`), where the 6567R56A
-  keeps the 6569's cycle 58. Its X counter holds for 8 pixels
-  (`x_hold`), reading $184-$187 three times, so it reaches $1ff on a
-  520-pixel line. The 6567R56A's runs straight through 512 pixels.
-  Neither is pinned yet: moving the 6567R8's display compare to 58, the
-  6567R56A's to 59, or running the 6567R8's counter straight through and
-  wrapping it at 512 fails no row of those subsets.
+- **Display compare.** The 6567R8 turns a sprite's display on and off in
+  cycle 59 (`sprite_display_cycle`), where the 6567R56A keeps the 6569's
+  cycle 58. This isn't pinned yet: moving the 6567R8's to 58 or the
+  6567R56A's to 59 fails no row of those subsets.
+- **X counter.** The 6567R8's X counter spends 8 pixels more on a line
+  (`x_hold`): after $187 it runs over $180-$187 a second time, then on
+  from $188, so it reaches $1ff on a 520-pixel line. The 6567R56A's runs
+  straight through 512 pixels.
+  - Pinned for the 6572, which shares the line, by `spritescan_drean`'s
+    dump (see [VIC-II 6572 (Drean)](#vic-ii-6572-drean)).
+  - The 6567R8's own lightpen dump (`split-tests/lightpen`'s
+    `dump6567.prg`, run by hand on `--model ntsc`) agrees: the sample the
+    test takes 8 pixels into the hold reads $c2 ($180-$181). Reading
+    $184-$187 there instead, as badline did before, gives $c4. The 6572's
+    `dump6572.prg` has the same values. The `testbench-ntsc` rows pass
+    either way.
 - **Blanking and crop.** The blanked lines are the ones VICE's NTSC view
   leaves out, 12-27 on the 6567R8 and 13-27 on the 6567R56A, so the
   `testbench-ntsc` screenshots, VICE's 247 lines from line 28 running on
@@ -970,6 +986,34 @@ What the NTSC references don't settle, and so what stays as it is:
   readme says it was matched against screenshots, and the one 6567R8
   photograph in the testprogs is of revision R01.
 
+## VIC-II 6572 (Drean)
+
+The 6572 of the Drean C64 (`Region::DREAN`) runs the 6567R8's line, 65
+cycles with its sprite fetches in cycle 59, its display compare in cycle
+59 and its X counter running over $180-$187 twice, on PAL-N's 312 lines at
+1,023,440 Hz. The oracle is `split-tests/spritescan/spritescan_drean.prg`,
+which checks itself against its `dump6572.bin`, from a real 6572R1. The
+testlist comments that row out, and `testbench-drean`
+(`bin/testbench --drean`) runs it.
+
+- Pinned by that dump: every byte the test compares matches, and the
+  test passes.
+- The X counter's second run over $180-$187 is pinned by sprite 1,
+  pattern C (a one-pixel sprite against one shifted a pixel left), which
+  collides for X = $180 to $186 on the 6572. Those are inside sprite 1's
+  twelve dead pixels (K = 483), so the sprite only shows from the second
+  time the counter reads its X. Repeating $184-$187 in the hold instead
+  misses $180-$183 (4 bytes), repeating $180-$183 misses $184-$186 (3),
+  and repeating $17c-$183 or $184-$18b moves 18 bytes. Spec guard: the
+  6567R8 and 6572 examples in
+  [`timing_spec.rb`](../spec/badline/vic/sprite/timing_spec.rb).
+- The display compare isn't pinned: the dump matches with it in cycle
+  58 as well as 59.
+- Not matched: `spritegap3`'s 6572 dump has sprite 0 at X = 0 miss the
+  sprite at X = 1 for every pair it is in, where badline, like the
+  6567R8 dump, has them collide. The test still passes, because it
+  accepts the 6567R8's dump too.
+
 ## CIA 6526 timer pipeline
 
 - Start and stop go through two stages. A force load lands one tick after

data/doc/sid-player.md

@@ -0,0 +1,136 @@
+# The SID player
+
+The [README](../README.md#playing-and-rendering-sid-tunes) shows how to
+start it. This page covers the player in detail.
+
+```sh
+badline sid ~/C64Music/MUSICIANS/H/Hubbard_Rob               # play every tune below a directory
+badline sid tune.sid other.sid                               # play a queue of tunes
+badline --headless tune.sid                             # play, length from HVSC
+badline --headless -s 3 tune.sid                        # play the third subtune
+badline --headless --all-subtunes tune.sid              # play on through every subtune
+badline --seconds 180 tune.sid --audio-out out.aiff
+badline -s 3 --rate 48000 tune.sid --audio-out out.wav
+badline --headless --sid 8580 tune.sid
+badline --filter-chunk 1 tune.sid --audio-out out.wav   # exact filter, slower
+```
+
+## The queue
+
+`badline sid FILE|DIR...` plays a queue of tunes in the SID player's
+window, in the order given, and a directory adds every `.sid` tune below
+it in path order. `badline sid --headless` plays the queue in the
+terminal instead. `badline sid` on its own opens the window with an
+empty queue. Dropping `.sid` files or folders on the window adds them
+to the end of the queue, and an empty queue starts playing them. A file
+that isn't a tune is skipped.
+
+`badline tune.sid` plays the tune in the SID player too, unless an
+option of the emulator's window, such as `--ntsc` or `--reu`, asks for
+the machine: then a tune for one SID runs on the emulated C64, started
+through a small driver after boot.
+
+`--subtune` (or `-s`) picks the first tune's subtune, counting from 1 as
+HVSC does, and defaults to the tune's own start subtune. Each tune plays
+that one subtune, and when it ends the player goes on to the next tune,
+stopping after the last. `a`, or `--all-subtunes`, turns on playing all
+subtunes, so that a subtune that ends goes on to the tune's next
+subtune, and a tune stepped to starts on its first subtune.
+
+`--sid auto`, the default, fits each of a tune's SIDs the model its
+header names. A tune written for 2 or 3 SIDs plays on as many, at the
+addresses its header gives, in stereo: SID 1 on the left, SID 2 on the
+right and SID 3 in the centre. A tune on one SID plays the same on both
+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`, `--model`, `--ntsc` and `--verbose`, don't apply.
+
+## The window
+
+The window is worked with the mouse. Its header shows the tune's name,
+author and release, the tune the subtune covers at the moment when
+HVSC's STIL credits one, following the times STIL gives, and buttons
+that switch between three views and between the tune's own SID model,
+the 6581 and the 8580, which changes the chips playing on the spot. Its
+footer shows the time played on a bar you can click to seek, and buttons
+that pause, step between tunes and between a tune's subtunes, and turn
+shuffle, looping and all subtunes on and off.
+
+- The visualizer shows each voice's note, and how far off it is in
+  cents, over a scope of the voice's output, and the mixed output below
+  them. A tune on more than one SID gets a row of voices for each SID,
+  and the mix splits into its left and right.
+- The SID view shows one SID at a time, and for a tune on more than one,
+  a row of SID 1, 2 and 3 buttons at its top picks which. It shows each
+  voice's output, its control bits, pulse width, envelope settings, and
+  the envelope's level and stage, and the filter's modes, cutoff,
+  resonance, volume and its response on the chip playing.
+- The INFO view shows the tune's STIL entry and the subtune's, with a
+  scroll bar, the mouse wheel or the up and down keys for the long ones.
+
+The terminal's keys work in the window too, along with Tab to switch
+views and `c` to step through the SID models.
+
+## The terminal
+
+Played on a terminal, `--headless` and `sid` show each tune's name,
+author and release as it starts, then the tune's place in the queue, the
+subtune number and the time played against the subtune's length.
+`--headless` queues just the one tune.
+
+→ and ← step to the tune's next and previous subtune, stopping at its
+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. 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
+instead and plays through the queue without the keys.
+
+## Rendering
+
+`--audio-out` renders one subtune to a 16-bit stereo PCM file. The
+file's extension picks the format, `.wav` or `.aiff`.
+
+## Lengths and STIL
+
+A `.sid` file doesn't store its length, so the player looks the tune up
+by MD5 in HVSC's `Songlengths.md5`. It finds the database through
+`--songlengths`, in a `DOCUMENTS` directory in any of the tune's parent
+directories (the layout of an HVSC collection), or under
+`$HVSC_BASE/DOCUMENTS`. Without a database or `--seconds` it runs for 60
+seconds, but a subtune that falls silent for 5 seconds before then ends
+there, when played and when rendered alike. Silent means the output
+holds within 16 steps of one level, since a 6581 idles at a DC offset
+rather than at zero. A subtune with a known length plays to its length
+whatever it sounds like.
+
+A tune in an HVSC collection also gets its entry in HVSC's `STIL.txt`,
+found the same way: comments, covers, and subtune names and composers.
+The tune's own fields follow its header, and each subtune's print as it
+starts.
+
+## Speed
+
+`badline` plays PSID and RSID tunes in real time. In `badline-ruby`,
+PSID tunes run on a CPU and RAM with only the SID clocked, at about
+twice real time, so they play smoothly, but RSID tunes set up their own
+interrupts, so they boot a full C64 first and run at about half real
+time. They render fine but stutter when played, and `badline-ruby` says
+so when it falls behind. Both builds run the same code, so they render
+the same file sample for sample. See
+[native/README.md](../native/README.md#without-the-window).
+
+The filter steps four cycles at a time; `--filter-chunk 1` steps it
+every cycle, which is exact and takes about twice as long.

data/doc/snapshots.md

@@ -0,0 +1,102 @@
+# Snapshots
+
+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
+
+`computer.save_snapshot(path)` saves, `computer.restore_snapshot(path)`
+takes a machine back to a snapshot, and `Badline::Snapshot.load(path)`
+builds a new machine as the saved one was built and restores it.
+`computer.snapshot` and `computer.restore(state)` do the same in memory,
+without a file. A restore that fails leaves the machine as it was.
+
+## What a snapshot holds
+
+A snapshot holds the machine as it was on the cycle it was saved: the
+chips down to the instruction step and the pixel pipeline, the RAM and
+any +60K or +256K expansion, the cartridge with its RAM and flash, a
+GEO-RAM, a true 1541 with its RAM, its VIAs and the disk under the head,
+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 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.
+
+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.
+
+## 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, 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, 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, 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/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

@@ -4,6 +4,7 @@ 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/roms"
 
 module Badline
   # Memory layout:
@@ -35,6 +36,7 @@ module Badline
     include Addressable
     include UltimaxPages
     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,9 +73,7 @@ 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

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.