badline 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9175400f11b212812092f887bea13e0880417fb151011fdbc568c4789050dcf1
-  data.tar.gz: dbd07633e45bfcc06fd6b4ab1b680389276ff81340cc6c72d26bd4e7fdf6baad
+  metadata.gz: b238dd5194dd5fc7783779eced6e4b718b73890e81d78566d12c26c08a379597
+  data.tar.gz: 4a47225b0d7e2a055674ce9f4f61cd2bc1064413a2c4c8b6bf228ed99f4dde07
 SHA512:
-  metadata.gz: d00a54fba0e530ff578a35b3b5953c0f011b6ea32a2b5ac3f8ccaf19dc8c8f3e26bb81dedfac4c53b026b0e2d0a8e3a35c9f212369624995765c0c8a99678542
-  data.tar.gz: '0918a31ea33114c1f46d76ec3c0e9978a5e922bd7b39f6abe9494ee03423fad48f4aecbf8c4a2e0af4414ee19b2ce2d33c6cb21774a473138db15a588c149f2b'
+  metadata.gz: c636911838f2d65ae88c6b4e940085790c54573c2cc6a9d97450b68f2319eb374f3330e75243487bd7538b56d5cb695f2fe085739ead20db06eb3f24b9169c45
+  data.tar.gz: c48b8ecfe80b51a178a757246adba3ea267901db096ccb74c28dbc6482a9ff1f71193c26b4829e98744bcd6847f5fe3f073ff01275604d8383dd36dd91f50f69

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.6.0](https://github.com/elektronaut/badline/compare/v0.5.1...v0.6.0) (2026-09-29)
+
+
+### Features
+
+* save and restore the machine in VICE .vsf snapshots ([07c0a26](https://github.com/elektronaut/badline/commit/07c0a26d7e73595d5cd4a5bfa90b633ee01195be))
+
+
+### Bug Fixes
+
+* forget the drive's orbits after restoring it ([0238d81](https://github.com/elektronaut/badline/commit/0238d81ab12a0b0ff1e841661e10004ab3683cc1))
+
 ## [0.5.1](https://github.com/elektronaut/badline/compare/v0.5.0...v0.5.1) (2026-09-29)
 
 

data/README.md

@@ -57,6 +57,7 @@ badline game.d64       # Mount a disk image as device 8 and load it
 badline game.tap       # Insert a tape and load it
 badline game.crt       # Attach a cartridge
 badline tune.sid       # Play a SID tune
+badline game.vsf       # Restore a snapshot, from badline or VICE
 badline ~/c64          # Mount a directory as device 8
 ```
 
@@ -107,6 +108,7 @@ slows the emulation down.
 | `.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 |
 | `.sid` | PSID and RSID tunes, started through a small driver after boot |
+| `.vsf` | A snapshot of a running machine, badline's own or one VICE's x64sc saved. See [Snapshots](#snapshots) |
 | A directory | Mounted read-write as device 8. It serves the `.prg` and `.p00` files in it and the contents of any `.t64`, and `SAVE` writes a new `.prg` |
 
 Apart from a `.g64`, which only a true drive can read, there is no 1541
@@ -139,6 +141,62 @@ 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.
 
+## 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. 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.
+
+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 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 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.
+
+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.
+
+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. 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.
+An NTSC snapshot fails, as badline runs PAL only. 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.
+
 ## Playing and rendering SID tunes
 
 `badline-ruby --headless` plays a `.sid` tune on the host's audio

data/exe/badline-ruby

@@ -55,7 +55,8 @@ begin
                                               disk: { read_only: options.read_only? })
 rescue Badline::Media::TrueDrive::Error, Badline::Storage::SIDFile::FormatError, Badline::Storage::T64::FormatError,
        Badline::Storage::TAP::FormatError, Badline::Storage::CRTFile::FormatError,
-       Badline::Storage::G64Image::FormatError, Badline::Cartridge::UnsupportedTypeError => e
+       Badline::Storage::G64Image::FormatError, Badline::Cartridge::UnsupportedTypeError,
+       Badline::Snapshot::FormatError => e
   warn "badline-ruby: #{options.media_path}: #{e.message}"
   exit 1
 end

data/lib/badline/address_bus/saved_state.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Badline
+  class AddressBus
+    # The bus's state for a snapshot: the CPU port, the RAM, colour RAM and
+    # a RAM expansion, the cartridge, the datasette and the chips.
+    module SavedState
+      # The RAM expansion fitted, or an Unexpanded stand-in.
+      attr_reader :ram_expansion
+
+      # Takes the cartridge out of the expansion port, as a restore does for
+      # a state without one.
+      def detach_cartridge
+        @cartridge = nil
+        update_overlays!
+      end
+
+      # The 6510 port's direction and output registers, and the charge left
+      # on its floating bits.
+      def port_state = [@port_ddr, @port_out, @port_floating]
+
+      # Sets the port as port_state reads it, as a snapshot restores it,
+      # leaving the RAM under $00 and $01 alone.
+      def restore_port(ddr, out, floating)
+        @port_ddr = ddr
+        @port_out = out
+        @port_floating = floating
+        update_port!
+      end
+
+      # The machine's memory and everything on the bus but the keyboard, the
+      # joysticks and the pot devices, which the host holds. A cartridge is
+      # already in the port, built from its setup (Computer#load_state).
+      def save_state(out)
+        out.marker("BUS")
+        out.int(@port_ddr).int(@port_out).int(@port_floating)
+        @ram.save_state(out)
+        @color_ram.save_state(out)
+        @ram_expansion.save_state(out)
+        @cartridge&.save_state(out)
+        @datasette.save_state(out)
+        @vic.save_state(out)
+        @cia1.save_state(out)
+        @cia2.save_state(out)
+        @sid.save_state(out)
+      end
+
+      def load_state(input)
+        input.marker("BUS")
+        ddr = input.int
+        port_out = input.int
+        floating = input.int
+        @ram.load_state(input)
+        @color_ram.load_state(input)
+        @ram_expansion.load_state(input)
+        @cartridge&.load_state(input)
+        @datasette.load_state(input)
+        @port_ddr = ddr
+        @port_out = port_out
+        @port_floating = floating
+        @io_port.value = port_value
+        update_overlays!
+        @vic.load_state(input)
+        @cia1.load_state(input)
+        @cia2.load_state(input)
+        @sid.load_state(input)
+      end
+    end
+
+    include SavedState
+  end
+end

data/lib/badline/address_bus.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "badline/address_bus/saved_state"
 require "badline/address_bus/ultimax_pages"
 
 module Badline

data/lib/badline/audio/stream.rb

@@ -38,6 +38,12 @@ module Badline
 
       def rate = @sink.rate
 
+      # Plays another machine's SID from here on.
+      def sid=(sid)
+        @sid = sid
+        sid.record(rate: rate)
+      end
+
       def muted? = @muted
 
       def playing? = @started

data/lib/badline/cartridge/action_replay.rb

@@ -64,6 +64,21 @@ module Badline
 
       private
 
+      def save_mapper(out)
+        save_windows(out, windows)
+        out.int(window_index(@rom, windows)).boolean(@active).boolean(@io2_ram).blob(@ram_data)
+      end
+
+      def load_mapper(input)
+        load_windows(input, windows)
+        @rom = window_at(input.int, windows)
+        @active = input.boolean?
+        @io2_ram = input.boolean?
+        input.blob_into(@ram_data)
+      end
+
+      def windows = [@through, @isolated, @contended, *@rom_banks, EMPTY_BANK]
+
       def io2_peek(addr)
         @io2_ram ? @ram_data[IO2_PAGE | (addr & 0xff)] : @rom.peek(addr)
       end

data/lib/badline/cartridge/comal80.rb

@@ -33,6 +33,14 @@ module Badline
 
       private
 
+      def save_mapper(out)
+        save_windows(out, [*@roml_banks, *@romh_banks, EMPTY_BANK])
+      end
+
+      def load_mapper(input)
+        load_windows(input, [*@roml_banks, *@romh_banks, EMPTY_BANK])
+      end
+
       def select(number, mode)
         @roml = bank(@roml_banks, number)
         @romh = bank(@romh_banks, number)

data/lib/badline/cartridge/dinamic.rb

@@ -24,6 +24,14 @@ module Badline
 
       private
 
+      def save_mapper(out)
+        save_windows(out, [*@banks, EMPTY_BANK])
+      end
+
+      def load_mapper(input)
+        load_windows(input, [*@banks, EMPTY_BANK])
+      end
+
       def install_chips(chips)
         @banks = banks_from(chips).first
         self.mode = :rom8k

data/lib/badline/cartridge/easy_flash.rb

@@ -78,9 +78,28 @@ module Badline
       private
 
       def select_bank
+        map_bank
+        changed!
+      end
+
+      def map_bank
         @roml = @low_flash.window(@bank * BANK_SIZE)
         @romh = @high_flash.window(@bank * BANK_SIZE)
-        changed!
+      end
+
+      def save_mapper(out)
+        out.int(@bank).int(@control).blob(@io_ram)
+        @low_flash.save_state(out)
+        @high_flash.save_state(out)
+      end
+
+      def load_mapper(input)
+        @bank = input.int
+        @control = input.int
+        input.blob_into(@io_ram)
+        @low_flash.load_state(input)
+        @high_flash.load_state(input)
+        map_bank
       end
 
       def apply_control

data/lib/badline/cartridge/epyx_fastload.rb

@@ -56,6 +56,14 @@ module Badline
 
       private
 
+      def save_mapper(out)
+        out.int(@discharged_at)
+      end
+
+      def load_mapper(input)
+        @discharged_at = input.int
+      end
+
       def discharge!
         @discharged_at = @clock ? @clock.call : 0
       end

data/lib/badline/cartridge/final_cartridge3.rb

@@ -62,6 +62,18 @@ module Badline
 
       private
 
+      def save_mapper(out)
+        save_windows(out, [*@roml_banks, *@romh_banks, EMPTY_BANK])
+        out.boolean(@register_visible).boolean(@phi1_ultimax)
+      end
+
+      def load_mapper(input)
+        load_windows(input, [*@roml_banks, *@romh_banks, EMPTY_BANK])
+        @io_bank = @roml
+        @register_visible = input.boolean?
+        @phi1_ultimax = input.boolean?
+      end
+
       def select(number)
         @io_bank = @roml = bank(@roml_banks, number)
         @romh = bank(@romh_banks, number)

data/lib/badline/cartridge/flash.rb

@@ -2,6 +2,37 @@
 
 module Badline
   class Cartridge
+    # A Flash chip's state, for a snapshot.
+    module FlashState
+      STATES = %i[read program_setup autoselect programming erase_window erasing suspended chip_erase
+                  program_error].freeze
+
+      # The array, the command state, a timed operation's end on the
+      # machine's clock, and the windows handed out so far, which load_state
+      # builds anew.
+      def save_state(out)
+        out.blob(@data).int(STATES.index(@state)).int(STATES.index(@base_state)).int(@cycle).int(@toggle)
+        out.optional_int(@done_at).optional_int(@programmed).optional_int(@remaining)
+        out.boolean(!@erasing_sectors.nil?)
+        out.ints(@erasing_sectors) if @erasing_sectors
+        out.ints(@windows.keys).ints(@status_windows.keys)
+      end
+
+      def load_state(input)
+        input.blob_into(@data)
+        @state = STATES.fetch(input.int).to_sym
+        @base_state = STATES.fetch(input.int).to_sym
+        @cycle = input.int
+        @toggle = input.int
+        @done_at = input.optional_int
+        @programmed = input.optional_int
+        @remaining = input.optional_int
+        @erasing_sectors = nil
+        @erasing_sectors = input.ints if input.boolean?
+        rebuild_windows(input.ints, input.ints)
+      end
+    end
+
     # An AMD 29F0x0 flash chip, driven through the JEDEC command set in the
     # AMD datasheets. Each command opens with two unlock cycles, $AA to the
     # first unlock address and $55 to the second, and a third write picks
@@ -66,6 +97,8 @@ module Badline
         alias [] peek
       end
 
+      include FlashState
+
       attr_reader :data, :state
       attr_writer :clock
 
@@ -95,6 +128,14 @@ module Badline
         end
       end
 
+      # Hands out new windows at the bases given, as #window would have.
+      def rebuild_windows(bases, status_bases)
+        @windows = {}
+        @status_windows = {}
+        bases.each { |base| @windows[base] = Window.new(self, base) }
+        status_bases.each { |base| @status_windows[base] = StatusWindow.new(self, base) }
+      end
+
       def array_mode?
         @state == :read || @state == :program_setup
       end

data/lib/badline/cartridge/fun_play.rb

@@ -28,6 +28,14 @@ module Badline
 
       private
 
+      def save_mapper(out)
+        save_windows(out, [*@banks, EMPTY_BANK])
+      end
+
+      def load_mapper(input)
+        load_windows(input, [*@banks, EMPTY_BANK])
+      end
+
       def install_chips(chips)
         @banks = []
         chips.each { |chip| @banks[self.class.bank_number(chip.bank)] = rom_bank(chip.data) }

data/lib/badline/cartridge/g_mod2.rb

@@ -47,6 +47,18 @@ module Badline
         changed!
       end
 
+      def save_mapper(out)
+        out.int(@bank).boolean(@flash_writes)
+        @flash.save_state(out)
+      end
+
+      def load_mapper(input)
+        @bank = input.int
+        @flash_writes = input.boolean?
+        @flash.load_state(input)
+        @roml = @flash.window(@bank * BANK_SIZE)
+      end
+
       def install_chips(chips)
         data = Array.new(BANKS * BANK_SIZE, 0xff)
         chips.each do |chip|

data/lib/badline/cartridge/game_system.rb

@@ -25,6 +25,14 @@ module Badline
 
       private
 
+      def save_mapper(out)
+        save_windows(out, [*@banks, EMPTY_BANK])
+      end
+
+      def load_mapper(input)
+        load_windows(input, [*@banks, EMPTY_BANK])
+      end
+
       def select(addr)
         @roml = bank(@banks, addr & 0x3f)
         changed!

data/lib/badline/cartridge/geo_ram.rb

@@ -52,8 +52,24 @@ module Badline
         @block = @page = @window = 0
       end
 
+      # A GEO-RAM is built from its size alone.
+      def save_setup(out)
+        out.int(GEO_RAM_SETUP).int(@size)
+      end
+
       private
 
+      def save_mapper(out)
+        out.blob(@ram_data).int(@block).int(@page).int(@window)
+      end
+
+      def load_mapper(input)
+        input.blob_into(@ram_data)
+        @block = input.int
+        @page = input.int
+        @window = input.int
+      end
+
       def install_chips(_chips)
         @ram_data = Array.new(@size * 1024, 0)
         reset

data/lib/badline/cartridge/magic_desk.rb

@@ -20,6 +20,14 @@ module Badline
 
       private
 
+      def save_mapper(out)
+        save_windows(out, [*@banks, EMPTY_BANK])
+      end
+
+      def load_mapper(input)
+        load_windows(input, [*@banks, EMPTY_BANK])
+      end
+
       def install_chips(chips)
         @banks = banks_from(chips).first
         @bank_mask = (bank_mask(@banks) | 0x03) & 0x7f

data/lib/badline/cartridge/ocean.rb

@@ -19,6 +19,14 @@ module Badline
 
       private
 
+      def save_mapper(out)
+        save_windows(out, [*@banks, EMPTY_BANK])
+      end
+
+      def load_mapper(input)
+        load_windows(input, [*@banks, EMPTY_BANK])
+      end
+
       # In 16K mode the selected bank shows through ROMH as well.
       def select_bank(number)
         @roml = bank(@banks, number)

data/lib/badline/cartridge/pagefox.rb

@@ -29,6 +29,18 @@ module Badline
 
       private
 
+      def save_mapper(out)
+        save_windows(out, windows)
+        @ram_banks.each { |ram| out.blob(ram.data) }
+      end
+
+      def load_mapper(input)
+        load_windows(input, windows)
+        @ram_banks.each { |ram| input.blob_into(ram.data) }
+      end
+
+      def windows = [*@roml_banks, *@romh_banks, *@ram_banks, @open_bus || EMPTY_BANK, EMPTY_BANK]
+
       def select(value)
         half = (value >> 1) & 0x01
         chip = (value >> 2) & 0x03

data/lib/badline/cartridge/retro_replay.rb

@@ -2,6 +2,44 @@
 
 module Badline
   class Cartridge
+    # A Retro Replay's registers, RAM and flash, for a snapshot.
+    module RetroReplayState
+      private
+
+      def save_jumpers(out)
+        out.boolean(true).boolean(@flash_jumper).boolean(@bank_jumper)
+      end
+
+      def save_mapper(out)
+        [@active, @frozen, @phi1_ultimax, @ram_enabled, @ram_at_a000, @allow_bank, @no_freeze, @reu_mapping,
+         @write_once].each { |flag| out.boolean(flag) }
+        out.int(@bank).int(RetroReplay::CONTROL_MODES.index(@config))
+        @ram_data.each { |data| out.blob(data) }
+        @flash.save_state(out)
+      end
+
+      def load_mapper(input)
+        load_flags(input)
+        @bank = input.int
+        @config = RetroReplay::CONTROL_MODES.fetch(input.int)
+        @ram_data.each { |data| input.blob_into(data) }
+        @flash.load_state(input)
+        map_windows
+      end
+
+      def load_flags(input)
+        @active = input.boolean?
+        @frozen = input.boolean?
+        @phi1_ultimax = input.boolean?
+        @ram_enabled = input.boolean?
+        @ram_at_a000 = input.boolean?
+        @allow_bank = input.boolean?
+        @no_freeze = input.boolean?
+        @reu_mapping = input.boolean?
+        @write_once = input.boolean?
+      end
+    end
+
     # Retro Replay: an Am29F010 flash chip of two 64K halves, each eight 8K
     # ROM banks, and four 8K RAM banks, with the Action Replay's register at
     # $DE00 and an extended one at $DE01. The Nordic Replay (subtype 1) adds
@@ -44,6 +82,7 @@ module Badline
     # the half in bit 5.
     class RetroReplay < Cartridge
       include Freezer
+      include RetroReplayState
 
       CONTROL_MODES = %i[rom8k rom16k off ultimax].freeze
       IO1_PAGE = 0x1e00
@@ -212,11 +251,15 @@ module Badline
       end
 
       def configure
+        map_windows
+        changed!
+      end
+
+      def map_windows
         self.mode = @config
         @rom = flash_window(@bank)
         @roml = roml_window
         @romh = romh_window
-        changed!
       end
 
       def roml_window

data/lib/badline/cartridge/rgcd.rb

@@ -28,6 +28,16 @@ module Badline
 
       private
 
+      def save_mapper(out)
+        save_windows(out, [*@banks, EMPTY_BANK])
+        out.boolean(@disabled)
+      end
+
+      def load_mapper(input)
+        load_windows(input, [*@banks, EMPTY_BANK])
+        @disabled = input.boolean?
+      end
+
       def select(value)
         value ^= 0x07 if @hucky
         if value.anybits?(0x08)

data/lib/badline/cartridge/super_games.rb

@@ -20,6 +20,16 @@ module Badline
 
       private
 
+      def save_mapper(out)
+        save_windows(out, [*@roml_banks, *@romh_banks, EMPTY_BANK])
+        out.boolean(@locked)
+      end
+
+      def load_mapper(input)
+        load_windows(input, [*@roml_banks, *@romh_banks, EMPTY_BANK])
+        @locked = input.boolean?
+      end
+
       def select(value)
         @roml = bank(@roml_banks, value & 0x03)
         @romh = bank(@romh_banks, value & 0x03)

data/lib/badline/cartridge/zaxxon.rb

@@ -31,6 +31,14 @@ module Badline
         def peek(addr)
           @bank.peek(addr)
         end
+
+        def save_state(out)
+          out.int([*@banks, EMPTY_BANK].index { |bank| bank.equal?(@bank) })
+        end
+
+        def load_state(input)
+          @bank = [*@banks, EMPTY_BANK].fetch(input.int)
+        end
       end
 
       def reset
@@ -39,6 +47,14 @@ module Badline
 
       private
 
+      def save_mapper(out)
+        @romh.save_state(out)
+      end
+
+      def load_mapper(input)
+        @romh.load_state(input)
+      end
+
       def install_chips(chips)
         roml, romh = banks_from(chips)
         @romh = High.new(romh)