Loading Software

Bizmuth opens snapshots, tapes, disk images and Next programs, and each does something different to the machine.

Formats

File ▸ Open takes all of them, and so does a file dragged onto the window.

Machine switching

Opening a file that needs a different machine switches to it first.

A .sna or .z80 opened on the Next therefore switches away from it. To load one onto the Next, give it to --load with --machine next (see Command line).

Snapshots

A snapshot is a frozen machine. Loading one replaces the registers, memory, paging and border, and the program continues from where the snapshot was taken.

Tapes

Inserting a tape sets the loading mode from its format.

A .tap loads at once. Bizmuth intercepts the ROM’s LD-BYTES routine and hands each block over directly.

A .tzx loads at tape speed. TZX carries the custom and turbo loaders commercial games used, which do not call the ROM routine, so the tape signal is played to them as a recorder would.

Media ▸ Tape overrides the mode for the tape in the deck:

• Fast intercepts the ROM routine. It works for a .tap loaded by the ROM’s own loader.
• Real Time plays the tape signal to the machine as a recorder would.

Inserting another tape sets the mode from its format again. --tape-mode fast or --tape-mode real on the command line overrides the mode for the --tape file.

A .tap that does not load in Fast mode uses a custom loader; Real Time loads it.

Tapes on the Next

The Next has no Fast mode. A tape inserted with Media ▸ Tape ▸ Insert Tape while the Next is running plays into it at tape speed, whatever its format. File ▸ Open and a dropped tape switch to the 128K instead.

--tape inserts a tape into the Next in the same way, at tape speed.

LOAD

A tape loads only when the program asks for it, as on the hardware:

• 48K: type LOAD "" and press ENTER.
• 128K, +2A, +3: choose Tape Loader from the start-up menu.

Disks

.dsk and .edsk images go in drive A on the +3, through Media ▸ Disk ▸ Insert Disk A.

Flip Disk A turns a double-sided image over. Write Protect A stops the guest writing to it. Save Disk A As writes the image, with the guest’s changes, to a new file; the file you opened is not changed.

Next programs

A .nex is a Next program, and there are two ways to load one:

• File ▸ Open writes it into the running machine’s memory at once.
• --load on the command line boots NextZXOS first, then loads the program.

Some programs expect NextZXOS to have set the machine up: the font in the tilemap, the default palettes, the system variables. Written into a machine that has not booted, such a program finds none of it set, and can draw garbage. A .nex that misbehaves one way and works the other differs for that reason, not from a fault in the file.

A .nex also runs as on a Next: browse to it on the SD card in NextZXOS and press ENTER.

Command line

--load FILE loads a .nex, .fxi, .snx, .sna or .z80 after boot. --nex and --snapshot are older names for the same option.

An .fxi is the image fantasm link -f fxi writes, and selects the Next. Each of its regions is written at the address the image names, through the memory map the running Next has, and the program starts at the image’s entry. A region over a slot that holds ROM is refused, naming the region and the slot. A file holding several images places them all and starts at the first one’s entry.

Given more than once, --load loads each file in order over the one before, so a program can go in over the kernel it runs on:

bizmuth --machine next --sd next.img --load flint.nex --load prog.fxi

A file cannot follow a .nex that loads through .nexload, which has not loaded the .nex by the time the next file would go in. --nex-route inject writes the .nex into memory first.

On the Next, --load boots NextZXOS, waits for it to go idle, then loads the file. The first boot is saved, and a later run with the same boot ROM and the same card image, unmodified since, starts from that saved state; --no-boot-cache boots every time. --max-boot-frames N gives up on a boot that never goes idle after N frames, 1300 by default.

Without --machine, a .sna or .z80 runs on the 48K or 128K it was taken on, chosen as in Machine switching.

--nex-route chooses how a .nex reaches the Next:

• auto, the default: through NextZXOS’s .nexload from the SD card where the file’s header asks for an open file handle or extra files, and written into memory otherwise.
• nexload: always through .nexload.
• inject: always written into memory.

The .nexload route places the .nex in /tmp on the card in slot 0, with each file named by --load-with beside it, then runs .nexload on it. A card attached read-write is switched to copy-on-write for the run, so the placed files never reach the image.

bizmuth --machine next --sd next.img --load game.nex --load-with game.dat

Load failures

A file that cannot be loaded raises a dialog naming the reason:

• A damaged file: a truncated snapshot, or a tape with a bad block length.
• An unsupported format: an extension not in Formats.

See also

• SD Cards: the Next’s own way of loading software.
• Save States: freezing and restoring the whole machine, which a snapshot does not.

← User Guide