badline 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: feaedb95b99aa7efed205645c112426a2649ad7a08c975708d085bf69a7e9555
-  data.tar.gz: b284281a2e1256f0fe94abf5174990ac8dc8a98cd7035f1cd53aebd3ccbefbd6
+  metadata.gz: 2916044b89e174698de9dd60a2a72121dc6aa91058a9de914dfbaa5e70170f29
+  data.tar.gz: 56adae369f806a6adb31dea00b5164d6e02e4b88d6a6cc08209808abdae0392b
 SHA512:
-  metadata.gz: 870ff9cb5c9a9d65c8e9dd8dee6cc87a45871c1a07c79c4b9dc69a692600c3167f92b1debca0f860ab96b783a81bb608276542322b17e305acb82e95c9fc560b
-  data.tar.gz: 7c12bf1fd073b2b0e58e41195d67316f0c518a0f5b8c013ded19f025b48456fea738e5ad3df26a796c84151638e8c0449b5bf14b7d013fcb876c61db5d2d9469
+  metadata.gz: cac3c6ba20fff4bbabd7e77dd8eae4e53cb12a3785f946908407627eb29783764684c0e2cf208b6a8030ad31bcfb35811526873119d51cb5badd0f2598257b41
+  data.tar.gz: 93cecca78dbb7f4ca6393a629d113fa80a68a573359193ae4bcc54b87aadea883fdba0f84ad3ccb8acbad54539867b676e82e9f940420b50365f0fc7b93c33ff

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [0.9.0](https://github.com/elektronaut/badline/compare/v0.8.0...v0.9.0) (2026-10-05)
+
+
+### Features
+
+* add a per-user data folder for badline's own files ([27bdf0e](https://github.com/elektronaut/badline/commit/27bdf0edc16d95fc57dea940741cc0b7de74bbb1))
+* add the Drean C64, PAL-N with the 6572, as --model drean ([0562d8e](https://github.com/elektronaut/badline/commit/0562d8eb5b11239039eac934fd21eb7824868f98))
+* add the SX-64 as --model sx64 ([e947cba](https://github.com/elektronaut/badline/commit/e947cba8ff46f0f01eeb6e1a49c0bd4bf91324ea))
+* autosave, and a Snapshots page in the pause menu ([78aede9](https://github.com/elektronaut/badline/commit/78aede9a6052ce6c32184952a7b1d380e7c129e2))
+* keep five quicksave slots in the data folder ([6043543](https://github.com/elektronaut/badline/commit/6043543632aa61a42ff69bdff8ea15ae354ce810))
+* pick the C64 to run with --model ([d5539c8](https://github.com/elektronaut/badline/commit/d5539c8ade245b1e96e78765f15906ce4a80da5b))
+* restore snapshots without their tape, .t64 or true drive disk files ([0c0733a](https://github.com/elektronaut/badline/commit/0c0733a5c7eaf9c217466f7569769eb005c5248f))
+* run the testlist's Drean rows as testbench-drean ([dc8a075](https://github.com/elektronaut/badline/commit/dc8a07524168d399fb7c0305c661ab694c53bc2c))
+* save NTSC, Drean and REU machines as .vsf snapshots ([c4126cf](https://github.com/elektronaut/badline/commit/c4126cfa878d8efe7aaaa9e5113c4ee2a4886e6b))
+* seek within a subtune from checkpoints kept as it plays ([3ac57be](https://github.com/elektronaut/badline/commit/3ac57beac448a43a76387a0ff1f370cd07d06d81))
+* take disk sets from .m3u and .vfl lists ([b4e6845](https://github.com/elektronaut/badline/commit/b4e6845eb04cde80f87c1fcb372987311bf1dd97))
+
+
+### Bug Fixes
+
+* describe F11's quicksave slots, F12 and the autosave in --help ([6cbf148](https://github.com/elektronaut/badline/commit/6cbf148d327699070ef4fba4f2b3e3dd39d41348))
+* keep the board's low-pass stable for long filter steps ([c5af022](https://github.com/elektronaut/badline/commit/c5af0224aad60dbb665e6804bb536746e354da96))
+* leave CIA 1's timer B and the serial lines as the KERNAL's LOAD does ([b4f1a41](https://github.com/elektronaut/badline/commit/b4f1a4173b9413fd59b05bab12d173e0679c4c17))
+* play an NTSC machine's sound at its own clock ([510aab1](https://github.com/elektronaut/badline/commit/510aab1052a58a54b1790802e2a5705fcb208c5c))
+* put CIA 2's port A on the serial bus without a drive ([31f8a4f](https://github.com/elektronaut/badline/commit/31f8a4fad0ea210d4272b4672a84414527b68e31))
+* run the 6567R8 and 6572 X counter over $180-$187 twice ([08a4da3](https://github.com/elektronaut/badline/commit/08a4da33d4bd68a85d61895dcf8c1ea5fa5b539c))
+* set CIA 1's timer B for each byte the serial traps stand in for ([f98e6d7](https://github.com/elektronaut/badline/commit/f98e6d7666d2326ce4d8d3ab7f938dc4fd60cbd1))
+* take .m3u and .vfl lists of disks in --at's insert ([d1e771e](https://github.com/elektronaut/badline/commit/d1e771e6781fc5560dda2e10e6d76abb53be0807))
+
 ## [0.8.0](https://github.com/elektronaut/badline/compare/v0.7.0...v0.8.0) (2026-10-03)
 
 

data/README.md

@@ -78,7 +78,8 @@ differences noted in the table. `--help` lists the options for either.
 | `-s`, `--subtune N` | Pick a subtune of a `.sid` file, counting from 1 |
 | `--sid 6581`, `--sid 8580` | Fit the older or newer SID. `--sid auto`, the default, takes a `.sid` tune's own |
 | `--reu SIZE` | Plug in a RAM Expansion Unit of `SIZE` K: 128, 256, 512 (a 1750) or up to 16384 |
-| `--ntsc` | Run an NTSC C64, with the 6567R8 VIC-II, instead of a PAL one |
+| `--model NAME` | Run another C64, named as in VICE: `c64` (the default, a PAL C64 with the 6569 VIC-II, 6526 CIAs and the 6581 SID), `c64c` (the PAL C64C, with the 8565, 6526As and the 8580), `ntsc` (the 6567R8), `newntsc` (the NTSC C64C, with the 8562, 6526As and the 8580), `oldntsc` (the first NTSC C64s' 6567R56A), `drean` (the Drean C64 of Argentina, PAL-N with the 6572) or `sx64` (the portable SX-64, with its own KERNAL and no datasette). `--sid` or a `.sid` tune's own SID takes the model's place |
+| `--ntsc` | Run an NTSC C64, as `--model ntsc` does |
 | `--no-sound` | Don't play the SID (`badline` only, where sound is on by default) |
 | `--sound` | Play the SID (`badline-ruby`, where sound is off by default) |
 | `--no-vsync` | Pace the window by a timer, or by the sound while it plays, instead of the display's vsync |
@@ -117,6 +118,7 @@ library, are covered in [doc/library.md](doc/library.md).
 | `.prg`, `.p00` | Loaded into memory after boot. A program at the BASIC start (`$0801`) is `RUN`, anything else is left for you to `SYS` |
 | `.d64`, `.d71`, `.d81` | Mounted as device 8, then `LOAD"*",8,1` and `RUN`. Write-protected unless `--writable` |
 | `.g64` | Put in a true 1541, then `LOAD"*",8,1` and `RUN`. It holds the disk's raw GCR, so copy protection that reads it works. Write-protected unless `--writable` |
+| `.m3u`, `.vfl` | A list of disk images, one path a line, relative to the list: an `.m3u` playlist, or a VICE flip list, which only unit 8's entries are taken from. Its first disk goes in as above, and the list is its set for the pause menu |
 | `.t64` | Mounted read-only as device 8 and loaded like a disk image. The files load by name, and no tape is involved |
 | `.tap` | Inserted in the datasette with PLAY pressed, then `LOAD` and `RUN`. It loads at the speed of a real tape |
 | `.crt` | The hardware types listed under [Cartridges](#whats-emulated). Other types are rejected |
@@ -134,12 +136,14 @@ from Ruby.
 
 ## Snapshots
 
-`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. Snapshots use VICE's `.vsf` format: badline opens those
-x64sc saves, and x64sc opens badline's. See
-[doc/snapshots.md](doc/snapshots.md) for what they hold and how far the
-two agree.
+`F11` quicksaves the whole machine to the next of five slots in
+badline's data folder, replacing the oldest, and `F12` restores the
+newest, even after badline has quit and started again. badline also
+autosaves every two minutes of play, and the pause menu's Snapshots page
+saves under a name and loads any of them. Snapshots use
+VICE's `.vsf` format: badline opens those x64sc saves, and x64sc opens
+badline's. See [doc/snapshots.md](doc/snapshots.md) for where they're
+kept, what they hold and how far the two agree.
 
 ## Playing and rendering SID tunes
 
@@ -217,6 +221,7 @@ too.
 
 | Page | What it holds |
 |------|---------------|
+| Snapshots | Quicksave, save under a name, load a named save, and the latest quicksaves and autosaves |
 | Drive 8 | The disk: insert, eject, the previous or next disk of its set, and whether it's writable |
 | Datasette | The tape: insert, eject, PLAY and REWIND |
 | Expansion port | The cartridge: insert, remove, and its freeze button if it has one |
@@ -224,15 +229,17 @@ too.
 | Sound | Mute, and the SID's model |
 | Power | Reset, power cycle and quit |
 
-INSERT opens a file browser. A disk's set comes from the names in its
-folder: `Disk 1`, `Side B`, `d2`, TOSEC's `(Disk 1 of 2)`, or a trailing
-`_1`, `_2` when the first of the set is there. WRITABLE starts as
+INSERT opens a file browser. A disk's set is the `.m3u` or `.vfl` list it
+was opened from, or one in its folder that lists it. Without one, it comes
+from the names in its folder: `Disk 1`, `Side B`, `d2`, TOSEC's
+`(Disk 1 of 2)`, or a trailing `_1`, `_2` when the first of the set is
+there. WRITABLE starts as
 `--writable` sets it and stays as set for the next disk. Quick open starts
 a file in a new machine, as the command line does. It asks first, as
 inserting or removing a cartridge does, since each power cycles the
 machine.
 
-A disk or tape dropped on the window goes into its drive. A cartridge,
+A disk, list of disks or tape dropped on the window goes into its drive. A cartridge,
 program or `.sid` dropped on it opens the menu to ask first.
 
 ## What's emulated
@@ -242,8 +249,8 @@ program or `.sid` dropped on it opens the menu to ask first.
   [65x02 single step tests](https://github.com/SingleStepTests/65x02).
 - **Memory**: banking through the 6510 port, the cartridge lines and
   Ultimax mode, and the +60K and +256K RAM expansions.
-- **VIC-II**: the PAL 6569, the C64C's 8565, and NTSC's 6567R8 (`--ntsc`)
-  and 6567R56A: every graphics mode, sprites, collisions, bad lines,
+- **VIC-II**: the PAL 6569, the C64C's 8565, NTSC's 6567R8, 8562 and
+  6567R56A, and the Drean's PAL-N 6572 (`--model`): every graphics mode, sprites, collisions, bad lines,
   sprite DMA, the border and the light pen.
 - **CIA 1 and 2**: the 6526 and the C64C's 6526A, with timers,
   time-of-day clocks, the serial shift register, the keyboard matrix
@@ -261,8 +268,8 @@ program or `.sid` dropped on it opens the menu to ask first.
   Power / Nordic Power, Retro Replay / Nordic Replay, Final Cartridge III
   / III+ and the KCS Power Cartridge. Flash writes stay in memory.
 
-Machines other than the default, and the cartridges' jumpers, are
-built from Ruby: see [doc/library.md](doc/library.md).
+Chip combinations `--model` doesn't name, and the cartridges' jumpers,
+are built from Ruby: see [doc/library.md](doc/library.md).
 
 Known gaps:
 
@@ -270,7 +277,6 @@ Known gaps:
   turns on, stutters: it plays in bursts with silent gaps between them.
 - Without `--true-drive`, fast loaders and anything else that runs code
   on the drive won't work.
-- No PAL-N (Drean) machine.
 
 ## Contributing
 

data/doc/library.md

@@ -19,7 +19,9 @@ computer.address_bus.peek(0x0400)                   # screen RAM starts at $0400
 ## Building a machine
 
 `Badline::Computer.new` builds the default machine: a PAL C64 with the
-6569 VIC-II, 6526 CIAs and a 6581 SID. Its keywords build others:
+6569 VIC-II, 6526 CIAs and a 6581 SID. Its keywords build others, and
+`Badline::Model.named("c64c")` gives the ones `--model` names for each
+model (`Badline::Model::ALL`):
 
 - `vic_model: :mos8565` fits the C64C's 8565, with its grey dots on
   colour register writes and its own timing for mode splits, sprite
@@ -28,7 +30,8 @@ computer.address_bus.peek(0x0400)                   # screen RAM starts at $0400
   65 cycles by 263 lines at 1,022,727 Hz, with its later sprite fetches
   and its X counter, and TOD clocks on 60 Hz mains.
   `Badline::Region::NTSC_OLD` is the first NTSC C64s' 6567R56A, 64 cycles
-  by 262 lines. The stock KERNAL tells them from PAL by the raster, so
+  by 262 lines, and `Badline::Region::DREAN` the Drean C64's PAL-N
+  6572, 65 cycles by 312 lines at 1,023,440 Hz. The stock KERNAL tells them from PAL by the raster, so
   every region boots the same ROMs.
 - `cia_model: :mos6526a` fits the C64C's 6526As, whose interrupt
   register timing differs.
@@ -36,6 +39,9 @@ computer.address_bus.peek(0x0400)                   # screen RAM starts at $0400
 - `ram_expansion: :plus60k` or `:plus256k` fits the +60K or +256K RAM
   expansion, banked through its register at `$D100`.
 - `reu: 512` plugs in a RAM Expansion Unit of that many K.
+- `kernal: :sx64` fits the SX-64's KERNAL, and `datasette: false`
+  leaves the cassette port empty, so inserting a tape raises
+  `Badline::Datasette::Missing`. The SX-64 has both.
 
 ## Cartridges
 
@@ -57,6 +63,7 @@ Its contents are lost when the emulator quits.
 The KERNAL, BASIC and character ROMs come with the gem. To run other
 images, such as a patched KERNAL, point `BADLINE_ROM_PATH` at a
 directory that holds `kernal.rom`, `basic.rom` and `character.rom`, plus
-`eapi/eapi-am29f040-14` if you attach EasyFlash cartridges.
+`kernal-sx64.rom` for the SX-64 and `eapi/eapi-am29f040-14` if you
+attach EasyFlash cartridges.
 `Badline.rom_path = dir` does the same before a `Badline::Computer` is
 built, and `nil` restores the bundled set.

data/doc/media.md

@@ -59,8 +59,17 @@ 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, found by name in its folder, which the pause menu's
-PREVIOUS DISK and NEXT DISK step through.
+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
 

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

@@ -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,54 @@ 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.
 
 ## 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/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