9.1 Command-line options

Every option JNEXT accepts is listed below, grouped the way the manual groups them. This page, the jnext(1) man page and USAGE.md are three renderings of one source, so they cannot disagree with each other.

A bare filename is shorthand for --load, so jnext game.tap works. Anything starting with - is treated as an option, never as a filename, and naming the program both ways at once is rejected.

For a quick reminder without leaving the shell:

$ jnext --help
$ jnext --version
$ man jnext

If you ever find the documentation and the program disagreeing, the program is right — please report it.

A numeric value is taken whole. Trailing characters (5x), a value outside the option’s range, or a negative count are a usage error: jnext prints a message naming the option and the value, and exits with status 1.

Machine and program

--machine TYPE

Machine type: 48k, 128k, plus3, pentagon, next (default). A snapshot given to --load (.jns, .sna, .szx, .z80) runs on the machine it was saved on instead, and jnext warns when that is not the one given here.

--load FILE

Load a program. The format is detected from the extension: .nex, .jns, .sna, .szx, .z80, .tap, .tzx, .wav, .rzx. (.rzx is accepted here and plays back, as --rzx-play.) A .zip archive holding one of them loads that program (see the .zip entry).

.jns is jnext’s own whole-machine snapshot (see 5.9 Snapshots). Loading one restores the machine it was taken on, including the machine type: a .jns taken on a Next loads as a Next even if --machine says otherwise. A .sna, .szx or .z80 does the same: it runs on the machine it was saved on (the file says which: a .sna by its size, an .szx by its machine ID, a .z80 by its hardware mode), even over --machine, which is then warned about. The machine stays selected, in the GUI’s Machine > Machine Type too. A snapshot from a machine jnext does not emulate (a Timex, a Scorpion, a Pentagon 512 or 1024), or taken with the TR-DOS, Interface 1, MGT or Multiface ROM paged in, is refused, with the reason in the log, before anything is changed; at startup jnext then exits non-zero. A 16K, +2, +2A or +3e snapshot runs as the 48K, 128K, +3 or +3, and an NTSC 48K .szx as a 48K at 60 Hz.

A NEX file with bytes after the banks its header declares is an extended NEX. If its header asks for the file to be kept open (any non-zero file_handle: 1 to 0x3FFF hands the program the handle in BC, 0x4000 and above writes it at that address), the program can read the extra bytes from its own file. If the header says file_handle 0, jnext does what the Next’s own loader does: it loads only the declared banks, ignores the trailing bytes and starts the program. More than 16 KB of ignored bytes also logs a warning.

The debugger’s source map and symbols attach from beside the program: NAME.sld (or NAME.sld.txt), an sjasmplus source map whose labels join the symbols (a label assembled for a page names its address only while that page is mapped), beside any program, NAME.Memory.txt (or Memory.txt), NextBuild / Boriel ZX Basic symbols, beside a .nex, and NAME.map, a z88dk map (-m), beside a .nex, .tap or .sna: its symbols join the others (not when a Memory.txt exists; a symbol of a BANK_n or PAGE_n section names its address only while its page is mapped, the others take the page mapped at their address when the program is loaded, from tape too), and with -debug also its source lines, which attach when there is no SLD. z88dk’s -create-app also writes the section binaries (NAME_CODE.bin, …) that the map is checked against; without them it attaches unverified. Beside a tape (.tap, .tzx, .wav), whose program is not in memory yet, a map that carries a binary identity attaches at once and each memory space it covers is checked the first time the program runs its code there; a space that does not match drops the map and the symbols that came with it, with the reason in the log. A map given with --map or loaded by hand is kept over them. z88dk’s --list listings beside the map (NAME.lis, FILE.lis) are read too when they match the map, and add assembly lines and sdcc’s lines on z88dk 2.4; a listing that does not match is skipped with a note in the log. A map built for another binary, or a file over 64 MiB, is refused, with the reason in the log.

--nex-args LINE

Argument line for a NEX V1.3 program. LINE is placed, verbatim and zero-terminated, in the CLI buffer the file’s header declares (its address and size). When the program starts, DE holds that address plus the size - one past the buffer - which is where the reference V1.3 loader leaves it (the V1.3 header comment says the address itself). A line as long as or longer than that buffer is truncated to the buffer’s size with no terminator - which is what the reference V1.3 loader does. Quote LINE to pass more than one word: jnext --load game.nex --nex-args "level 3". Only V1.3 declares a CLI buffer, so the option is inert - with a warning - for a V1.0-V1.2 file, or a V1.3 file whose header declares no buffer.

--experimental-nex-v1.3

Allow loading NEX V1.3 files. NEX V1.3 is an experimental format and is not supported in any way; without this flag, loading a NEX file whose header version exceeds V1.2 is refused with an error naming the version found (exit status 1). In the GUI, selecting such a file shows a warning dialog instead, with Cancel as the default. V1.0-V1.2 files are unaffected either way.

--sdcard FILE

Mount SD-card image FILE (.img). Optional; see Why JNEXT needs an SD-card image.

--sdcard-download-confirm

Skip the download prompt for the default-location image and proceed.

--sdcard-download-force

Force re-download and re-patch of the default-location image, to recover a corrupted one. Also discards a half-finished download. Ignored when --sdcard is given: an explicit path always wins.

--sdcard-readonly

Open the SD image read-only, so the host file is never modified. The emulated machine sees a write-protected card: writes are rejected with the SD write-error token rather than silently discarded. Use it when a run must not disturb an image other runs share.

--sdcard-file-add FILE

Copy host FILE — a file, or a directory with everything in it — into the SD-card image and exit without starting emulation. Without --sdcard-file-dest it lands in the root of the card under its own name. Give it once per run. The image written is the one --sdcard names, or the default-location image when --sdcard is omitted — in which case a loud warning says so, because that image is shared with every other run. See PUTTING A FILE ON THE CARD.

--sdcard-file-dest PATH

Optional. The path on the card that --sdcard-file-add’s FILE becomes, from the root of the card (/NEXTZXOS/DRV-A.DSK). The leading / is optional, directories are separated with /, and any missing directory in the path is created. For a directory, / copies its contents straight into the root of the card.

--sdcard-file-force

Let --sdcard-file-add replace files that are already there. Without it an existing destination file is refused and nothing is written.

--warm-start-regenerate

Discard the cached warm-start recording and take a fresh one on the next --load of a .nex file.

A --load of a .nex on the ZX Spectrum Next runs the program on a RECORDING of a real firmware boot, not on the machine jnext assembles. This is the behaviour, not an option: on the first load with a given SD image jnext cold-boots it (nextboot.rom -> TBBLUE.FW -> NextZXOS, a few seconds), stores the resulting machine state under ~/.jnext/warm-start/, and applies the program on top of it — which is what .nexload does on real hardware. Later loads restore that state instead of booting. If no recording can be made or used — no SD image, a card with no firmware on it, a recording that will not load back — jnext says so on standard error and falls back to the machine it has always assembled.

The recording is keyed by the SD image’s size and modification time, the machine type and the state format, and it is also dropped when jnext itself writes to the image, so it invalidates itself whenever any of those change. The image’s contents are not read: an image replaced or edited from outside with the same size and the same modification time (cp -p, touch -r) is served the old recording. Use this option to force the issue in that case, and after replacing TBBLUE.FW or NextZXOS on the card. It applies to .nex files on the Next only: the other machine types run no firmware, and snapshots and tapes are loaded by mechanisms a firmware-resident machine does not have.

The recording is made on your machine from the image you mounted, and is never shipped with jnext: it contains NextZXOS and DivMMC ROM content.

--set SECTION.KEY=VALUE

Set one setting of ~/.jnext/jnext.conf for this run. Every Preferences setting can be given this way: the key is the file’s [section] and key name joined with a dot, the value is what the file holds, and the keys are listed under Settings for --set below. Repeat it for more (--set audio.gain_db=-6 --set startup.silent=false). The split is at the first =, so a value may contain one.

A value that is not accepted, or a key that does not exist, is a usage error naming both, and jnext exits with status 1. A key the running frontend has no use for (a window setting under --headless, say) is reported with a warning and ignored, so one command line can serve all three frontends.

Precedence. The command line wins over the saved jnext.conf, which wins over the built-in default; a flag and --set are the same thing, and the later of two settings of one key wins whichever way it is spelled (--cpu-speed 28 --set startup.cpu_speed=0 starts at 3.5 MHz). Nothing given on the command line is ever written to jnext.conf. A change made in the window during the run takes over from then on (a Preferences OK or Apply, a menu, a file dialog that moves the last directory), and Preferences shows the saved values, not the command line’s.

A boolean is true or false. It also reaches what a flag cannot: --set startup.silent=false plays sound for one run although the file says muted, --set startup.tape_fast_load=true forces fast loading over a saved real-time setting, and --set esp.allowed_hosts= (empty) allows any host over a saved list.

--cpu-speed MHZ

The CPU speed the machine starts at: 3.5, 7, 14 or 28, exactly. The same as --set startup.cpu_speed=0..3, and like it a starting value: the speed is programmed through NextREG 0x07 when the machine has started, as Preferences does. NextZXOS then sets its own speed while it boots, as the hardware’s firmware does, so on the Next machine a program that waits for the firmware sees the firmware’s speed, not this one. On the other machines it holds. Works in the Qt window, the SDL-only build and --headless.

--scale N

Window scale 1 to 3 for this run, over the saved Preferences value. The same as --set startup.window_scale. Qt window only: elsewhere jnext warns and ignores it.

--crt EFFECT

CRT effect for this run: off, scanlines, soft, tv or pc, the choices of the Preferences CRT effect pop-up. The same as setting startup.crt_filter, startup.crt_shader and startup.crt_shader_style together. soft, tv and pc need the GPU shader; a build without it refuses them (exit status 1) and offers off and scanlines. Qt window only: elsewhere jnext warns and ignores it.

--speed PERCENT

Emulator throttle: 50 = half, 100 = normal, 200 = 2x, 400 = 4x. Clamped to 10..1000. Works in the GUI and the SDL-only build; --headless runs uncapped, so there it has no effect, and jnext warns.

--when-slow-prefer WHAT

What to sacrifice on a host that cannot emulate in real time: audio (default) or video. It changes nothing on a host with headroom.

audio keeps the sound card fed by emulating two frames in one frame slot when it runs low. The first frame of such a pair is overwritten before it can be painted, so the picture advances in an uneven, lurching way while the sound stays clean.

video never drops a frame for the sound card. The extra frame runs in the next slot instead, so it gets its own present, and the machine simply runs slower than real time. The sound queue then runs down to its floor and the last sample level is held to bridge the gap, which is heard as stutter and a dropped pitch. This is how FUSE-style emulators degrade.

Interactive frontends only; inert under --headless, which is uncapped and has no audio device. The GUI equivalent is When the host is too slow under Settings > Preferences > Startup, which applies live.

--joy1-source SRC

Host source for Joy 1 (port 0x1F): sdl (autodetected gamepad, default), keys (host arrow keys, Space = fire) or none (nothing drives it).

--joy2-source SRC

Host source for Joy 2 (port 0x37): sdl (default), keys or none. Only one connector may use keys. Interactive (SDL/Qt) frontends only; inert under --headless.

--joy1-device ID

Physical controller for Joy 1 (port 0x1F), by the id jnext logs when it connects it (Joystick 1 connected: 'name' [id]): 32 hex digits, optionally followed by #N to tell identical pads apart. Used while the connector’s source is sdl; if that controller is not connected, jnext logs it and uses the first free one. An empty ID chooses Automatic (the first free controller) over a saved controller, the same as --set input.joy1_device=. Wins over the saved choice for this run.

--joy2-device ID

Physical controller for Joy 2 (port 0x37); same form as --joy1-device, an empty ID included. The two connectors cannot name the same controller. Interactive (SDL/Qt) frontends only; inert under --headless.

--mouse-release METHOD

How a captured mouse is released: ctrl-alt (default; Alt+Cmd in the Qt GUI on macOS), middle-click or esc. The methods are exclusive: only the one chosen releases. ctrl-alt is not consumed (Alt still types its compounds); the middle click and Esc are not passed to the program. Esc is the ZX BREAK key whenever the mouse is not captured, and middle-click needs a 3-button mouse. Wins over the saved GUI preference for this run. Interactive (SDL/Qt) frontends only; inert under --headless. The GUI equivalent is Release captured mouse with under Settings > Preferences > Input, which applies live.

--joy-uart-rx FILE

Attach FILE as a serial byte source on the joystick-port UART RX pin — the “PC” end of a joy-port serial cable, as used by a dezogif / DeZog serial rig.

The bytes do not reach the guest through either UART header. They arrive through the NR 0x0B I/O-mode multiplexer, which the guest controls, so the guest hears them ONLY while all three of these hold:

• bits 7 and 5 of NR 0x0B are both set (joy_iomode_uart_en), i.e. pin 7 is in one of the two UART modes. Modes 00 (static) and 01 (CTC-toggled) carry no UART and receive nothing;
• bit 4 selects the connector this cable is plugged into — see --joy-uart-connector;
• bit 0 picks the channel that receives it: 0 = UART 0, 1 = UART 1. While the cable owns a channel, the module on that channel’s header (the ESP-01 on UART 0, the Pi header on UART 1) can neither be heard nor be spoken to, which is what the hardware does.

Delivery is paced at the receiving channel’s current baud rate, so a stream longer than the 512-byte RX FIFO does not overrun a guest that is draining it. Bytes sent while the guest is not listening are LOST rather than queued, exactly as on the wire — use --joy-uart-rx-delay-frames to schedule them. If the whole stream is lost, jnext says so with a warning rather than finishing quietly.

An unreadable or empty FILE is refused at startup.

--joy-uart-rx-delay-frames N

Hold the --joy-uart-rx stream for N complete frames before its first byte arrives (default 0, i.e. from the first instruction). This is how a byte is made to land while the program is already running — the asynchronous-break case — rather than being spent before the program has set NR 0x0B up. Requires --joy-uart-rx.

--joy-uart-connector N

Which joystick socket the joy-port serial cable is in: 1 or 2 (default 2, the connector a real rig uses). NR 0x0B bit 4 selects the connector the machine reads, so a guest that selects the other one hears nothing at all. Applies to --joy-uart-rx, --joy-uart-fifo and --joy-uart-pty, and requires one of them.

--joy-uart-fifo PATH

Attach a LIVE, BIDIRECTIONAL serial cable on the joystick-port UART, as a pair of FIFOs named from PATH: PATH.rx carries host to Next and PATH.tx carries Next to host. Both names are from the guest’s point of view, the same way round as --joy-uart-rx. Either is created if it does not exist; a path that exists and is not a FIFO is refused.

This is the option to use for a debugger on the host — DeZog driving dezogif_ng — because it carries a conversation. --joy-uart-rx is a RECORDING: it reads its file whole at startup, so pointing it at a FIFO waits for the writer to close and then replays what it got. The two are mutually exclusive: one cable, one socket.

The guest side is gated by NR 0x0B exactly as --joy-uart-rx is, with one asymmetry that is the hardware’s: RECEIVE is connector-selected (bit 4 picks one socket’s pin to listen on), TRANSMIT is not — the Next presents joystick pin 7 to both sockets in turn, so a cable in the socket bit 4 does not select can still hear the machine while being unable to be heard by it.

NOTHING BLOCKS. With no peer attached, received bytes are simply absent and transmitted bytes wait; a peer that attaches later gets what was queued. A peer that goes away mid-session ends the conversation: what was queued is discarded rather than handed to whatever connects next, and the cable re-opens for a peer that reconnects. Receive is paced at the receiving channel’s current baud, so a large host message cannot overrun the 512-byte RX FIFO.

A rewind or an RZX playback holds the cable INERT — a re-executed frame neither re-transmits (the peer cannot un-receive a byte) nor consumes host bytes the resumed timeline still needs. Nothing about a live cable is saved in a snapshot. Rewinding does not rewind the program on the other end of the cable, so a debugger session will not survive one.

POSIX only.

--joy-uart-pty

As --joy-uart-fifo, but allocate a pseudo-terminal instead and log the slave device path at startup. This is the form a serial client opens — DeZog’s serial remote wants one serial device, not a pair of pipes — and it is put in raw mode so a binary protocol passes through untranslated. POSIX only.

--nextpi

Start NextPi — the software that runs on the Raspberry Pi of the Spectrum Next, on its GPIO header — under QEMU (qemu-system-arm, machine raspi0), connected to UART 1, the UART wired to that header. NextZXOS’s own Pi tools (.pisend, the NextPi UI) then talk to a real NextPi. jnext does not emulate the Pi: QEMU must be installed, and jnext starts it, wires it in and stops it when it exits.

jnext first checks that QEMU (and, until the first start has made the Pi’s overlay, qemu-img) is installed, and stops with the install hint if not, before anything is offered or downloaded.

The first run that needs it offers to download NextPi from its mirror (https://zx.xalior.com/NextPi2/) into ~/.jnext/nextpi — about 6 GB, with about 22 GB free needed while it is unpacked — with a progress bar, exactly as the SD-card image is provisioned; later runs start at once. An archive NextPi-<release>.tar.gz already in that directory is checked against its .md5 beside it (fetched only if absent) and unpacked without downloading; a directory that cannot be used is reported with the missing file, in the question and in the log. An interrupted download (Cancel, a dropped connection, or 30 seconds without data) is kept as NextPi-<release>.tar.gz.part and continues on the next run. NextPi then takes about a minute to reach its Supervisor prompt (SUP>). The release, the directory, the QEMU binary, where the Pi’s sound goes and any extra QEMU arguments are set under Settings > Preferences > NextPi (the [nextpi] section of ~/.jnext/jnext.conf) or, for one run, with --nextpi-dir, --nextpi-release, --nextpi-qemu, --nextpi-audio and --nextpi-qemu-args, which work in a headless session too; their defaults are release 1_93D, ~/.jnext/nextpi, qemu-system-arm on PATH, and the Next’s mixer.

On Linux and macOS the Pi’s sound reaches the Next’s mixer over I2S, as on the real machine: it is mixed with the beeper, the AY chips and the DAC, so --record and --wav-record include it, and NR 0xA2 enables and mutes it (NextPi’s tools enable it themselves). It is 10-bit, as the hardware’s input is, and arrives about 100 ms late. Rewinds and RZX playback hold it silent. With NR 0xA2 bit 0 set it goes to the EAR input instead (port 0xFE bit 6), as a tape signal: how a Next loads a tape the Pi plays to it.

The guest reaches the Pi only while NR 0xA0 bits 5:4 are 11 — UART 1 on GPIO 14/15, wired for a Pi — which NextPi’s tools set before they talk to it. Until then the Pi’s bytes are lost on the wire and the guest’s never reach it, as on the real machine; the first such loss is logged once. While NR 0x0B gives UART 1 to the joystick connector, the Pi cannot be heard either. Host bytes are paced at UART 1’s current baud; a rewind or an RZX playback holds the link inert, and nothing about it is saved in a snapshot. A soft or hard reset leaves the Pi running. A Pi asked for with this option that cannot start (no QEMU, a failed download) is an error; declining the download is not — jnext then starts without the Pi. On Linux and macOS the link is a pair of FIFOs; on Windows (QEMU for Windows, its folder on PATH or set in Preferences) it is a loopback TCP socket QEMU listens on. --nextpi starts the Pi with any machine (the header and UART 1 are there in every personality); the saved preference starts it only when jnext starts the ZX Next. Changing the machine while jnext runs neither starts nor stops it.

--no-nextpi

Do not start NextPi this run, overriding a saved preference that enables it.

--nextpi-dir DIR

The NextPi directory for this run (default ~/.jnext/nextpi), over the value saved under Settings > Preferences > NextPi. An empty value means the default. It is used when NextPi starts, so it goes with --nextpi (or the saved preference, when it starts NextPi); given when NextPi is not enabled for the run, this and the four options below are ignored, with a warning naming each.

--nextpi-release NAME

The NextPi release for this run: a release name on the mirror, or latest for the newest one listed there (default 1_93D). Over the saved value; an empty value means the default.

--nextpi-qemu PROGRAM

The QEMU program for this run (default qemu-system-arm on PATH; with a path, qemu-img is expected beside it). Over the saved value; an empty value means the default.

--nextpi-audio SPEC

Where the Pi’s sound goes for this run: empty for the Next’s mixer (the default), host, a QEMU -audiodev driver such as pa or none, or wav:FILE. Over the saved value.

--nextpi-qemu-args “ARGS”

Extra QEMU arguments for this run, added after jnext’s own. The text is split into arguments on spaces; '...' and "..." keep spaces in one argument; a backslash is an ordinary character; nothing is expanded and no shell is involved. Over the saved qemu_args. An unterminated quote stops NextPi from starting, with a message (an error when --nextpi asked for it). For example, a second serial port for the Pi, on ttyS0: --nextpi-qemu-args "-serial telnet:127.0.0.1:2357,server,nowait".

--tape-realtime

Real-time tape loading, at the speed of an actual tape, instead of fast load. It sets the one fast/real-time setting (the GUI’s Tape > Fast Load toggle) for this run only, overriding the saved preference without changing it; Tape > Open Tape File, File > Load NEX File, --load of a .tap or .tzx, and the tape restored by a .jns all follow that setting. The SDL-only build, which has no menu and no saved preference, is controlled by this option alone.

--tape-auto-play, --no-tape-auto-play

Turn automatic tape play/stop on (the default) or off for this run, overriding the saved GUI preference. While on, the tape deck stops in the silent gap between two blocks when no program is reading the tape, and resumes when one does, so tapes whose BASIC loader is slow between blocks load in real time. It does nothing in fast load mode. Off, the deck runs straight through, as a real one does (a TZX “stop the tape if in 48K mode” block now stops only on a 48K machine, as the TZX specification says, whatever this setting is).

--tape-save FILE

Save to tape, appending to FILE; its extension picks the format. A .tzx or .wav records the machine’s tape output (the MIC jack), so a program’s own saver is captured as well as BASIC SAVE: a .tzx holds it as standard (0x10), turbo (0x11) or raw pulse (0x13) blocks, a .wav as 8-bit mono 44100 Hz audio. Any other name (.tap) captures only blocks SAVEd through the 48K ROM routine. ROM saves are instant in all three: a trap at 0x04C2 (with the 48K ROM paged at slot 0) takes the block without running the routine. An existing file must be of the same format. Also Tape > Start Saving… in the window. Cannot be combined with RZX recording or playback: the trap skips the ROM routine, which a recording cannot replay.

--esxdos-stub

Answer a few RST $08 esxDOS calls for any program, for the whole session: the version query, one in-memory file and run sibling.nex chaining. Every other call goes to the code at $0008. For programs run without NextZXOS; a directly loaded NEX gets a fuller set automatically (see Programs that need NextZXOS). With NextZXOS booted it answers in front of NextZXOS’s own esxDOS for those calls, and NextZXOS’s file commands stop working.

--esxdos-stub-root DIR

Serve the host directory DIR to the guest through the esxDOS file and directory calls, instead of the single in-memory file. Implies --esxdos-stub. Read-only unless --esxdos-stub-writable is also given.

Which programs see DIR, and which do not. A NEX loaded with --load sees it, and so do dot commands: those reach the filesystem through RST $08, which is what jnext intercepts. NextZXOS does not see it — not its Browser, not its file selector, not BASIC’s LOAD, not its loader. NextZXOS carries its own SD-card driver and its own FAT code in ROM and reaches the card directly, without ever executing an RST $08, so there is no point at which jnext could answer for it. That boundary is permanent and deliberate; it is not a limitation that a later version lifts. To put a file where NextZXOS can see it, copy it into the SD-card image.

Inside DIR, paths behave as FAT paths: / and \ both separate components, a leading separator is the root of DIR rather than the host’s root, lookup ignores case, a component can also be given by its 8.3 short name, and the drive letters *:, $: and c: all mean DIR. A path that would leave DIR, and any symbolic link, is refused; symbolic links are not listed either. Because \ is a separator, a host file whose name contains one cannot be reached — FAT cannot name such a file either. Where two host files differ only in case and the guest’s spelling matches neither exactly, the first in byte order is taken.

Directory entries carry the host file’s modification time. M_GETDATE answers from the emulated clock instead, so it follows --rtc.

Do not combine it with a booted NextZXOS. It implies --esxdos-stub and inherits its limitation: the file calls are then answered in front of NextZXOS’s own esxDOS, and NextZXOS’s file commands stop working — .ls reports No such file or dir. This option is for programs jnext loads itself.

--esxdos-stub-writable

Allow the guest to create, truncate and write files under --esxdos-stub-root. Off by default, and deliberately a separate flag: a guest write changes a real file on the host immediately, and rewinding the emulator cannot undo it. Reads are fully rewindable; writes are not.

--rtc “YYYY-MM-DD HH:MM:SS”

Pin the RTC to a fixed date and time (a frozen clock) instead of following the host clock, which makes boot screenshots deterministic. The ISO YYYY-MM-DDTHH:MM:SS form is also accepted.

--silent

Disable all sound output (beeper, the three AY/YM chips, DAC/Covox/ Specdrum). No audio device is opened and the emulator skips PSG and mixer sample synthesis entirely, which can measurably speed up CPU-bound runs. Tape loading (EAR input) is unaffected.

--inject FILE

Load a raw binary into RAM.

--inject-org ADDR

Load address for --inject (hex, 0x prefix optional, default 8000). Requires --inject.

--inject-pc ADDR

Entry point for --inject (hex, 0x prefix optional, default: same as --inject-org). Requires --inject.

--inject-delay N

Wait N frames before injecting (default 0). Use around 100 if the binary calls ROM routines that need the system variables set up first. Requires --inject.

Networking (ESP-01 WiFi)

--esp

Enable the emulated ESP-01 WiFi module on UART 0. Off by default - see 5.6 Networking for what turning it on gives the running program.

--no-esp

Force the ESP off for this run, overriding a saved GUI preference that enables it. Given both, whichever comes last on the command line wins.

--esp-allow HOST

Only let the running program connect to HOST. Repeatable: give the option once per host. HOST is a single name - a comma is rejected rather than taken as a separator or as part of the name, because a name that silently matched nothing would look like a restriction that is in force when it is not. Matching is exact and case-insensitive, with no wildcards, and an IP address must be listed as itself. With no --esp-allow at all the program may name any host (subject to the always-refused addresses in 5.6 Networking). Requires --esp.

--esp-listen-address ADDR

Bind the running program’s AT+CIPSERVER to ADDR, default 127.0.0.1. ADDR is a numeric IP address, never a name - an address resolved through DNS could change under you. The default means a program that opens a server is reachable only from this machine; widening it (0.0.0.0) exposes that program to your network, which is why it has to be asked for. Nothing listens until the program itself sends AT+CIPSERVER. Requires --esp.

--esp-ip-address ADDR

Report ADDR as the module’s own station address instead of the default 192.168.1.50, so a program that recognises its own address can be run against the one it expects. It is what AT+CIFSR and AT+CIPSTA? answer, and nothing more: nothing binds it, nothing routes through it, and the emulated Next cannot be reached at it - that is --esp-listen-address, which is a real socket. ADDR is a numeric IP address, never a name, and 0.0.0.0 is refused because that is what the module reports while it has no network. Requires --esp.

--esp-ip-address-after ADDR

Report ADDR instead, once the outage ends. Defaults to the pre-outage address, which is what a short outage really does; give this when the address should come back different - a DHCP lease that expired during a long outage, or a router that reassigned. It is what makes a program’s stale-address handling testable at all: across an outage that returns the same address, a program that caches its address at start-up and one that re-reads it are indistinguishable. Requires --esp-delayed-associate-frames, and takes the same values as --esp-ip-address.

--esp-delayed-disassociate-frames N

Take the emulated module off its WiFi network after N emulated frames, as if the access point had gone away. From then on AT+CIFSR reports +CIFSR:STAIP,"0.0.0.0" instead of the module’s address, which is what a real ESP-01 with no association reports and what lets a program detect that its address has gone. Nothing else changes: connections already open keep running, new ones still open, and no unsolicited WIFI DISCONNECT is sent - what a real module does to traffic during an outage has not been measured, and jnext does not invent it. Requires --esp.

--esp-delayed-associate-frames N

Put it back on the network after N emulated frames, so AT+CIFSR reports the module’s address again - the same address as before, since a short outage does not normally change it. Requires --esp-delayed-disassociate-frames, and N must be greater than its value: an outage that ends before it starts is refused rather than run.

Recording and playback

--record FILE

Record video and audio to an MP4. Requires ffmpeg(1) on the PATH. If the recording cannot be produced (encoder failure, no usable output), jnext reports the error and exits non-zero. If the recording cannot even be started (no ffmpeg on the PATH), jnext exits non-zero immediately, without running the emulation.

--wav-record FILE

Record the mixed stereo output to a 44.1 kHz, 16-bit PCM WAV. Works headless and requires neither an audio device nor ffmpeg.

--dac-trace FILE

Record segment,tstate,channel,value rows for physical DAC writes. A cold boot starts a new segment.

--audio-gain-db DB

Set master host audio gain from -24 dB to +24 dB (default 0 dB). The gain is applied after the emulated hardware mix; overflow saturates at the 16-bit PCM limits.

--audio-gain-beeper-db DB

Set host gain for beeper EAR/MIC/tape-EAR audio from -24 dB to +24 dB.

--audio-gain-ay0-db DB

Set host gain for TurboSound AY chip 0 from -24 dB to +24 dB.

--audio-gain-ay1-db DB

Set host gain for TurboSound AY chip 1 from -24 dB to +24 dB.

--audio-gain-ay2-db DB

Set host gain for TurboSound AY chip 2 from -24 dB to +24 dB.

--audio-gain-dac-db DB

Set host gain for Specdrum, Soundrive and Covox DAC audio from -24 dB to +24 dB.

--rzx-play FILE

Play back an RZX recording from the start of the run. Works the same in the GUI, the SDL-only build and under --headless. A recording that fails to load is logged, and jnext then exits non-zero. The machine starts exactly as it does for --load FILE, so the two spellings replay identically, and so do File > Load NEX File… and File > Play RZX Recording in the GUI. The recording brings its own snapshot of the machine, so it cannot be combined with --rzx-record, with --load or --inject of another program, or with a second RZX file. It plays on the machine it was recorded on, whatever machine is configured: a recording jnext makes names its machine, and one from another emulator is judged by its embedded snapshot (an SNA’s size, an SZX’s machine ID, a .z80’s hardware mode). A recording that names none — one jnext 1.0.0 or earlier made with an SNA snapshot, or one whose snapshot is of a machine jnext does not emulate — plays on the configured machine. An explicit --machine given with the recording wins, and jnext warns when it disagrees with the recording, which then goes out of step; a recording played from the GUI’s menus always gets its own machine. The recording’s machine stays selected afterwards, in the GUI’s Machine > Machine Type too, as if chosen there.

--rzx-record FILE

Record input to an RZX file from the start of the run — or, with --load or --inject, from the moment that program is in the machine, so the snapshot the file carries is the program, and playback replays it. The file is written when jnext exits (or, in the GUI, at File > Stop RZX Recording). Works the same in the GUI, the SDL-only build and under --headless. While recording, a tape loads in real time: a fast load skips the ROM loader, which a recording cannot replay. The snapshot is an SZX on the 128K, Pentagon and +3 and a 48K SNA on the 48K. The file names the machine it was recorded on, which --rzx-play then uses.

Recording is not available on a ZX Spectrum Next, which is jnext’s default machine, so this needs an explicit --machine 48k, 128k, pentagon or plus3. An RZX carries a snapshot of the machine it starts from plus a log of the values the program read from ports — and the log records the values without the ports they came from. So no snapshot an RZX can carry both describes a Next (none of SNA, SZX or Z80 holds its extra RAM, NextREGs, Layer 2, tilemap, sprites or Copper) and keeps the value log aligned with what the restored machine goes on to read. jnext refuses rather than write a file that looks fine and replays wrong. --rzx-play still plays a Next recording made by an earlier jnext, with a warning that it may not replay faithfully. A FILE that cannot be written is refused before the machine starts, and a recording that cannot be saved when it is written is logged; either way jnext exits non-zero. A reset ends the recording: a hard reset (the Reset button, F1, or the program’s own), loading another program from the GUI, changing the machine type, or F4 writes the file there, and nothing after it is recorded — a recording cannot replay a reset.

--rewind-buffer-size N

Frame-snapshot ring buffer for backwards execution. Opt-in; default 0 = off.

--trace

Enable the per-instruction trace log (a 10K-entry ring). Also enabled implicitly by --rewind-buffer-size N with N > 0, and toggleable in the debugger.

--coverage

Record memory coverage from the start: for every byte of every memory (each RAM page, ROM image, DivMMC and Multiface window, Layer 2 mapping, …) whether the program executed it (first opcode byte of an instruction), read it or wrote it. Toggleable in the debugger (Debug > Coverage), where the Disassembly, Memory and Source views show it. With the SDL frontend or --headless it records but there is no viewer; it logs one summary line at exit. Costs a little speed while on (3-8% in release builds); no measurable cost while off.

Headless and automation

--headless

Run with no display and no audio device, at maximum speed.

--benchmark N

Headless only. Run exactly N frames uncapped, print one machine-parseable BENCH line (wall seconds, fps, T-states/s, T-states/frame, CPU speed, host core, build type) plus a human summary to stdout, then exit. Used by make bench (test/bench/bench.sh).

--benchmark-label NAME

Workload label printed verbatim in the BENCH line (default: the loaded file’s basename, or boot-<machine>). No whitespace, since the BENCH line is space-delimited. Requires --benchmark.

--delayed-screenshot FILE

Save a screenshot after a delay. The format is taken from FILE’s extension: .scr writes the raw ULA screen memory, anything else writes a PNG of the composited picture. See SCREENSHOT FORMATS below. The capture is taken from the next frame the machine renders, so if it comes due while the machine is paused - by the debugger, or by a --magic-breakpoint - it waits until the machine runs again; it is never written from the frame that was on screen before the pause. One still waiting when the exit comes is an error (see --delayed-automatic-exit).

--delayed-screenshot-time N

Delay in emulated seconds (default 10; see Emulated seconds under HEADLESS MODE). Requires --delayed-screenshot.

--delayed-screenshot-frames N

Delay in frames. Overrides --delayed-screenshot-time. Requires --delayed-screenshot.

--delayed-screenshot-layers LIST

Layers to compose into the screenshot: a comma-separated list of ula, layer2, sprites, tiles, all (default all). Requires --delayed-screenshot, and is rejected when that screenshot is a .scr, which has no layers to choose from.

--delayed-automatic-exit N

Exit the emulator after N emulated seconds (see Emulated seconds under HEADLESS MODE). The exit always fires, but work the command line deferred to a later frame and that has not happened by then is an error, and jnext exits non-zero: a --load still waiting out its boot delay (100 frames for .tzx and .wav), an --inject with --inject-delay, an --rzx-record waiting for that load, a --delayed-keypress, --delayed-nmi or --delayed-screenshot still to come, a --joy-uart-rx stream still held by --joy-uart-rx-delay-frames, and an edge of the --esp-delayed-disassociate-frames / --esp-delayed-associate-frames outage not yet reached. Give the exit headroom over the last of them.

--delayed-automatic-exit-frames N

Exit after N frames. Overrides --delayed-automatic-exit, and keeps its rule on work still to come.

--delayed-snapshot FILE

Headless only: requires --headless. Save a snapshot after a delay in frames. The format is chosen by the extension of FILE: .jns, .szx, .nex, anything else .sna. A snapshot is only ever taken at a frame boundary, so if the debugger has paused the machine part-way through a frame — a magic breakpoint, say — the frame in flight is completed first and the snapshot is written from the boundary that follows it. That pause never refuses the capture; the saved machine is then up to one frame past the point the debugger stopped at. A format that cannot represent the current machine is refused — it writes nothing, says why, and exits non-zero (see 5.9 Snapshots).

--delayed-snapshot-frames N

Delay in frames for --delayed-snapshot (default 0). Requires --delayed-snapshot.

--snapshot-compression STATE

Whether .jns snapshots are written deflated. on (the default) deflates every member; off stores them instead, so the file is readable with unzip -p and a hex editor at roughly five times the size. A debugging aid; it changes nothing about what the file contains, and jnext reads both forms. Any other STATE is an error.

--quick-snapshot-keep N|unlimited

How many quick snapshots File > Quick Save Snapshot keeps in ~/.jnext/snapshots/: after each save the oldest beyond N are deleted (default 20; N is 1 to 1000000). Only files named exactly like Quick Save’s own (jnext-YYYYMMDD-HHMMSS.jns, optional -NN) are ever deleted; anything else in the folder is left alone. unlimited keeps everything. Overrides the [snapshot] quick_keep setting for the run; the SDL-only build, which reads no configuration file, takes only this option.

--snapshot-mode MODE

How much a .jns load refuses. One setting with three positions, because they are one axis and asking for two of them at once is not a thing to want.

normal (the default) warns about a mismatched state model revision or mismatched ROM digests and refuses a different SD card.

strict turns those provenance warnings into refusals: a snapshot written by a jnext whose state model this build does not know, or one whose recorded ROM digests differ from the ROMs now loaded. A missing tape file is not covered — that always warns and never refuses, because a machine restores perfectly well without the tape it was loading from. The same goes for a tape that has changed or whose position cannot be restored.

force restores even though the mounted SD card is not the one the snapshot was taken on, printing a warning that names both cards. This is the setting that lets you create exactly the silently-wrong case the identity check exists to prevent, which is why it is spelled out in full.

Any other MODE is an error.

--delayed-keypress SECS KEY

Press KEY after SECS emulated seconds (see Emulated seconds under HEADLESS MODE). Headless only (requires --headless), repeatable.

--delayed-keypress-frames N KEY

Press KEY after N emulated frames. This is the frames-unit spelling of --delayed-keypress, not an override of it: both forms queue into the same list, so giving both schedules two keypresses. Requires --headless.

--delayed-nmi SECS BUTTON

Press an NMI BUTTON after SECS emulated seconds (see Emulated seconds under HEADLESS MODE). Headless only (requires --headless), repeatable. BUTTON is case-insensitive and names which button to press, spelled as the label on a real Next’s case. Of its three buttons, two raise an NMI: nmi (aliases mf, m1) is the NMI button, wired to the Multiface; drive (alias divmmc) is the DRIVE button, wired to the DivMMC. RESET is not an NMI button and is not accepted here. The press goes through the same path as the host F9 / F10 hotkeys, so it is subject to the same enable gates — NextREG 0x06 bit 3 for the Multiface, bit 4 plus NextREG 0x83 bit 0 for the DivMMC — and a press with its gate closed does nothing, exactly as on hardware. One press generates one NMI, not a repeating one.

--delayed-nmi-frames N BUTTON

Press BUTTON after N emulated frames. This is the frames-unit spelling of --delayed-nmi, not an override of it: both forms queue into the same list, so giving both schedules two presses. Requires --headless.

--delayed-sdcard-insert-frames N FILE

Insert SD-card image FILE after N emulated frames, exactly as File > Insert SD Card Image does (see Why JNEXT needs an SD-card image). The card keeps --sdcard-readonly. The run exits non-zero if the insert is refused - while an RZX recording is made or played, while a directly loaded NEX keeps its own file open, when FILE is not a readable file, or when another insert is due in the same frame - or if the automatic exit comes first. An empty FILE is rejected. Repeatable. Requires --headless.

--delayed-pok-frames N FILE

Apply trainers from the POK file FILE after N emulated frames, once the program has loaded. This is how a .pok file is used in the runs that have no Machine > POK Trainers… window: --headless and the SDL-only build’s window (see POK TRAINERS under LOADING PROGRAMS). The trainers are the ones --pok-trainers names, which this requires. N counts frames from the start of the run (50 a second on a 50 Hz machine), and a tape takes many; the trainers are written through the debugger’s memory path, exactly as the window’s Apply writes them. Given once. The file and the list are checked before the machine starts, and a run that fails the check exits 1 without starting: FILE unreadable, larger than 1 MiB or without a trainer, a listed trainer the file does not have or whose lines are malformed, a value missing or given where none is open. Later, the run exits non-zero if a trainer cannot be applied - an address that is ROM in the current memory map, a bank the machine does not have, an RZX recording or playback - and then the trainers before it stay applied; and if the automatic exit comes first. The Qt window refuses the option; with --headless every build accepts it.

--pok-trainers LIST

The trainers --delayed-pok-frames applies: their numbers in the POK file (1 is the first N line), comma-separated, no blanks, each T or T=VALUE. A trainer that leaves a value open (a 256 in the file, “Lives” without saying how many) needs T=VALUE, VALUE 0 to 255, which goes everywhere the trainer leaves one open; any other trainer takes none. 1,3=9,7 applies trainers 1, 3 (with 9) and 7, in that order. A trainer whose bytes memory already holds is left as it is. Requires --delayed-pok-frames.

--compositor-trace FILE

Dump a per-pixel compositor trace (CSV) for one frame.

--compositor-trace-frame N

Target frame for --compositor-trace (default 250). Requires --compositor-trace.

KEY is case-insensitive and is one of: a single character (a-z, 0-9, ., ,, ;, :), one of the symbolic names ENTER, RETURN, SPACE, UP, DOWN, LEFT, RIGHT, or a compound sym+char / caps+char (for example sym+m is .).

Debugging

--magic-breakpoint

Enable the magic-breakpoint opcodes (ED FF and DD 01).

--persistent-breakpoints

Keep breakpoints and watchpoints armed while the debugger window is closed. Without this option — the default — closing the window disarms them, and nothing stops. With it, a hit pauses the machine and reopens the debugger window at the breakpoint. With the window already open, behaviour is unchanged. The breakpoint check then runs on every instruction for the whole run, which is what “persistent” costs; it is accepted but has no effect in --headless, in the SDL-only build and in builds without the debugger, since only the debugger can set a breakpoint.

--dzrp-port PORT

Serve the DeZog Remote Protocol (DZRP) on TCP PORT, so DeZog - or any other DZRP client - can debug the running machine; see REMOTE DEBUGGING (DEZOG). Off unless given. PORT 0 binds a free port the system chooses, and the log says which (dzrp: listening on 127.0.0.1:40123). One client at a time: a second connection is closed at once. A port that cannot be bound (already in use, say) is a startup error. Works in every frontend, --headless included.

--gdb-port PORT

Serve the GDB remote serial protocol on TCP PORT, so z88dk-gdb can debug the running machine; see REMOTE DEBUGGING (Z88DK-GDB). Off unless given. PORT 0 binds a free port the system chooses, and the log says which (gdb: listening on 127.0.0.1:40125). One client at a time. A port that cannot be bound is a startup error. May be given together with --dzrp-port: each server has its own port and its own client. Works in every frontend, --headless included.

--zrcp-port PORT

Serve the ZEsarUX remote command protocol (ZRCP) on TCP PORT, so DeZog (its zrcp remote) - or telnet, or any other ZRCP client - can debug the running machine; see REMOTE DEBUGGING (ZRCP). Off unless given; 10000 is the port those clients assume. PORT 0 binds a free port the system chooses, and the log says which (zrcp: listening on 127.0.0.1:40123). One client at a time: a second connection is told so and closed. A port that cannot be bound is a startup error. Works in every frontend, --headless included, and alongside --dzrp-port and --gdb-port.

--debug-listen-address ADDR

Bind address for the debugger protocol servers (--dzrp-port, --gdb-port, --zrcp-port), default 127.0.0.1. ADDR is a numeric IP address, never a name - an address resolved through DNS could change under you - and anything else is refused at startup. The default means only this machine can reach the debugger; a non-loopback address (0.0.0.0) exposes it to your network, and none of the debugger protocols has any authentication. Refused unless a server port is given too: an address for servers that are all off would configure nothing.

--script FILE

Load a debugger script (.jds); see Debugger scripting. Repeatable: the scripts load, and their rules run, in the order given. A script that cannot be read, or that has any error, is reported as file:line:column: message and jnext exits 1 before the machine runs - nothing of it runs partially. With --load, a script that names a source line (on execute main.c:19), an @symbol that --map does not know, or a z88dk --map symbol of a section that names no page waits, with the scripts after it, until the program is in (it is still read and parsed at once); an error then also exits 1. Its rules start at the load: an on frame N or a --script-key due before it never fires (a .tzx or .wav loads about 100 frames in), so give such rules in an earlier script that names neither. In --headless and the SDL-only build a script decides the exit status: exit N exits N, a stop or a failed assert exits 3, a run-time error exits 1. In the Qt GUI a script never ends the program: stop and exit pause the machine instead.

--script-key FRAME N

Deliver script host key N (1 to 8) at emulated frame FRAME (--headless only; repeatable): the script’s on hostkey N rules run at the end of frame FRAME, where on frame FRAME runs. Needs a --script, or a --record-script (key 8 is the recorder’s capture).

--record-script FILE

Record the session as a replay script; see Recording a session under Debugger scripting. Every input change is written as the frame it landed on, each Alt + 8 (Command+8 on macOS) (or --script-key FRAME 8) captures the screen, and FILE is written when jnext exits. Works in every frontend.

--map FILE

Load a symbol table, a z88dk .map or an sjasmplus --sym or --exp file, told apart by its contents (z88dk’s assembler also writes a .sym, in the map format), so a script can name an address as @symbol (an sjasmplus label is @main.loop), and the debugger shows the names (the same table Map > Load MAP fills). A z88dk map’s symbols take their pages as its source lines do: a banked one only while its page is mapped, the rest in the page mapped at their address when the program is loaded (a map read before --load takes them then). A file that cannot be loaded, or holds no symbols, is a startup error. More than 64 MiB (of a file, or of what a pipe such as --map <(cmd) delivers) is refused, and the error names the limit.

--source-map FILE

Attach a source map, an sjasmplus SLD or a z88dk -debug .map (told apart by its contents), to the program --load loads, as if loaded by hand with Debug > Source > Load Source Map…. A z88dk map gives source lines only (and reads the --list listings beside it); its symbols stay with --map. Requires --load, unless FILE is the map of a z88dk dot command (-subtype=dot, dotx; built with -debug): that map is attached at once, before any script loads, and stays pending until the guest runs the command, when it is checked (the command is loaded into DivMMC RAM by NextZXOS, which jnext does not know until it runs; see the User Guide). Any other map without --load is refused (exit status 1). An RZX replay (--rzx-play R, or --load R.rzx) is the same case: a dot command’s map attaches pending, any other map is refused at start-up naming RZX (exit status 1). A map whose binary identity does not match the program, or that cannot be loaded, is a startup error (exit status 1). With a tape program (.tap, .tzx, .wav) the map attaches at once and is checked the first time the program runs its code; a mismatch then drops it, and the run exits with status 1.

--source-dir DIR

Also search DIR for the source files a source map names, in the Source tab of the debugger (the Qt window with the debugger; elsewhere a warning, and ignored). One directory per option, repeat it for more; the list separator (:, ; on Windows) is refused. The Source tab tries a file beside the source map and in its parent directories first, then these directories, the longest matching trailing part of the recorded name first and the directories in the order given. For this run only, like --set paths.source_dirs, whose list it appends to (a later --set of that key replaces what came before). A list given on the command line REPLACES the saved one for the run; directories added by Locate File… still apply. A relative DIR is taken from the working directory. The saved list is edited under Preferences > Paths, and Locate File… in the Source tab adds a directory.

--annotations FILE

Load a debugger annotations file (.jdp): the user’s labels and comments, each keyed by a memory (the page or ROM that supplies the address, written as the debugger shows it: P0E, ROM1, DIVRAM2) and a 16-bit address. A user label is shown by the debugger views, named by a script’s @name and by GDB monitor sym, over the toolchain’s own symbols, and only while its memory supplies the address. The file is plain UTF-8 text: the line jnext-annotations 1, then label SPACE $ADDR NAME and comment SPACE $ADDR TEXT records (in TEXT \\ is a backslash and \n a line break); lines starting with # and blank lines are ignored. It is loaded before the scripts, replaces nothing the program or --map loaded, and is kept across resets, state loads and rewinds. In the Qt debugger the labels and comments are added from the Disassembly and Source right-click menus, and Map > Open Annotations…, Save Annotations and Save Annotations As… read and write the file (Save writes back to FILE). A file that cannot be read, or does not parse (the message names the line), is a startup error (exit status 1).

--import-skoolkit FILE

At start, after --annotations, read FILE, a skoolkit control file (your own, or one made by skool2ctl.py -k -h from a disassembly), into the debugger’s labels and comments. Taken: the @ ADDR label=NAME lines (a leading * is dropped) and the text of the B, C, S, T and W sub-blocks, with their . and : continuation lines, as the instruction comment at that address. Counted in the log, not imported: block titles (sna2skool writes its own), D descriptions and the other directives. The memory of a file is its # jnext space TAG first line, else its name (TAG.ctl or WWWW-TAG.ctl, as --export-skoolkit writes them), else the memory that supplies the address when the file is read, which is before --load runs (the page mapped at start, the ROM at $0000). An imported label or comment replaces the one at the same address; all the files of the option are read first, so a failure changes nothing. Repeatable. A file that cannot be read, or that skoolkit would only warn about (an address that is not decimal, $hex or %binary, or above 65535; an unknown directive; a label name that is not a name; one name at two addresses), is a startup error (exit status 1) naming the line.

--import-ghidra FILE

As --import-skoolkit for a Ghidra symbol file: lines NAME ADDRESS l (l or f or anything else, ignored), the address 0xHHHH or TAG:0xHHHH with a jnext memory tag, as --export-ghidra writes them. A blank line is skipped. A # line, an address prefix that is not a jnext memory tag (ram:0x8000), an expression, or a name that is not a name is a startup error (exit status 1). Repeatable. There are no comments in the format.

--export-skoolkit DIR

When jnext exits, write the debugger’s labels and the code/data map that --coverage recorded into DIR as skoolkit control files (DIR is created). One WWWW-TAG.ctl and WWWW-TAG.bin pair per memory and window: TAG names the memory as the debugger does (P0A, ROM0, DIVRAM3), WWWW is the hex base of the 8 KB window (16 KB for ROM) the labels sit in, and the .bin holds that window’s bytes, so sna2skool.py -o 0xWWWW WWWW-TAG.bin picks its control file by itself and sna2skool.py -c DIR combines them. Unpaged labels are in 0000-0CPU.ctl. Executed bytes become c blocks, read or written ones b, the rest u; without --coverage each window is one c block. skoolkit has no Z80N support, so Z80N instructions are written as DEFB sub-blocks. sna2skool drops without a word a label that is not at the start of a line it writes, so every window file also splits (B/C sub-blocks) at each unpaged label that falls in it, and the labels survive sna2skool.py -c DIR. A previous export’s files in DIR are replaced; any other file there is never touched, and a .ctl or .bin of the same name that is not jnext’s makes the export fail. A failed export is logged and jnext exits with status 1.

--export-ghidra DIR

When jnext exits, write the debugger’s labels into DIR (created) as symbol files for Ghidra’s ImportSymbolsScript.py, one line NAME ADDRESS l per label: TAG.ghidra.txt for each memory (P0A:0x8000, the address in the overlay address space TAG that you create for that page), CPU.ghidra.txt for the unpaged labels (0x8000) and view.ghidra.txt for the memory as mapped when jnext exits (0x8000, no overlay needed). A previous export’s CPU.ghidra.txt, view.ghidra.txt and TAG.ghidra.txt files in DIR are replaced or removed; any other file there, any other *.ghidra.txt included, is never touched. A failed export is logged and jnext exits with status 1.

--magic-port PORT

Enable the magic debug port at PORT (hex, 0x prefix optional, for example 0x00FF).

--magic-port-mode MODE

Magic-port output mode: hex (default), dec, ascii, line. Requires --magic-port.

--profile

Enable the CPU T-state profiler. It allocates an mmap’d histogram and accumulates one entry per executed instruction; on exit the histogram is written to --profile-output.

--profile-output FILE

Output path for --profile (default profile.dat). Requires --profile.

--log-level SPEC

Set per-subsystem log levels; see the LOGGING section of the man page.

--log-file FILE

Write the log to FILE instead of the console. FILE is truncated at the start of every run, and jnext exits non-zero if it cannot be opened rather than quietly logging to the console instead. See the LOGGING section of the man page.

Misc

--help, -h

Print the built-in help and exit.

--version, -V

Print the version and exit.

Settings for --set

Each entry below is a key of ~/.jnext/jnext.conf, written section.key, with the values it takes. Where the setting has a flag of its own, the entry names it: the flag and --set are the same setting, and the later one given wins. The entries say which frontends use the key: the Qt window, the SDL-only build (both interactive) or --headless. Booleans are true or false.

startup.machine_type 48k|128k|plus3|pentagon|next

The machine type; --machine. All frontends.

startup.cpu_speed 0..3

The CPU speed at start: 0 is 3.5 MHz, 1 is 7, 2 is 14, 3 is 28; --cpu-speed takes the MHz. A starting value: NextZXOS sets its own speed while it boots. All frontends.

startup.emulator_speed_percent 10..1000

The emulation speed as a percentage of real time; --speed. Where --speed clamps a value outside the range, --set refuses it. The Qt window and the SDL-only build.

startup.window_scale 1..3

The window scale; --scale. The Qt window.

startup.crt_filter true|false

The software scanlines effect; --crt scanlines. The Qt window.

startup.crt_shader true|false

The GPU CRT shader; --crt. The Qt window.

startup.crt_shader_style 0..2

The shader’s look: 0 is tv, 1 is pc, 2 is soft; --crt. The Qt window.

startup.silent true|false

Start with the sound muted; --silent. All frontends.

startup.tape_fast_load true|false

Tape fast-load; false is real time, which is --tape-realtime. All frontends.

startup.tape_auto_play true|false

Automatic tape play and stop; --tape-auto-play and --no-tape-auto-play. All frontends.

startup.when_slow_prefer audio|video

What a host too slow for real time sacrifices; --when-slow-prefer. The Qt window and the SDL-only build.

audio.gain_db, audio.gain_beeper_db, audio.gain_ay0_db, audio.gain_ay1_db, audio.gain_ay2_db, audio.gain_dac_db -24..24

The master, beeper, AY #0, #1, #2 and DAC gains in dB; --audio-gain-db, --audio-gain-beeper-db, --audio-gain-ay0-db, --audio-gain-ay1-db, --audio-gain-ay2-db and --audio-gain-dac-db. All frontends.

paths.last_load_dir PATH

The directory the Load dialogs open in. The Qt window.

paths.sd_card_path FILE

The SD card image; --sdcard. Empty means none given. All frontends.

paths.screenshot_dir PATH

The directory the Save Screenshot dialog opens in. The Qt window.

paths.source_dirs DIRS

The directories the debugger’s Source tab also searches for source files, separated by : (; on Windows); --source-dir appends one. Empty means none. Given on the command line, the list REPLACES the saved one for that run. A relative directory is taken from the working directory. The Qt window with the debugger.

screenshot.quick_dir PATH

The Quick Screenshot directory; empty means ~/.jnext/screenshots. The Qt window.

screenshot.quick_format png|scr

The Quick Screenshot format. The Qt window.

snapshot.quick_keep 1..1000000|unlimited

How many quick snapshots Quick Save keeps; --quick-snapshot-keep. The Qt window and the SDL-only build.

input.joy1_source, input.joy2_source sdl|keys|none

The host source for Joy 1 and Joy 2; --joy1-source and --joy2-source. The Qt window and the SDL-only build.

input.joy1_device, input.joy2_device ID

The controller assigned to Joy 1 and Joy 2 (32 hex digits, optionally #N); empty is Automatic, which --joy1-device and --joy2-device also take as an empty ID. The Qt window and the SDL-only build.

input.mouse_release ctrl-alt|middle-click|esc

How a captured mouse is released; --mouse-release. The Qt window and the SDL-only build.

debugger_keys.ACTION COMBO

The key combination of a debugger action, like the Preferences Debugger Keys tab: ACTION is run, pause, step_into, step_over, step_out, step_back, frame_back, run_to_cursor, run_to_eof, run_to_eosl, trace_toggle, trace_export, source_step_into, source_step_over, source_step_out, source_step_back or source_reverse_continue, and none unbinds it. A combination that is not legal there, or that another action already holds (unless the same command line frees it), is refused with exit status 1 before the window opens. The Qt window with the debugger.

source.colour_scheme auto|light|dark|borland

The colour scheme of the debugger’s Source tab, like the Preferences Debugger tab: auto (the default) is light or dark after the application, borland is Borland C++ 3.1 (yellow on blue). The Qt window with the debugger.

esp.enabled true|false

The emulated ESP-01 WiFi module; --esp and --no-esp. All frontends.

esp.allowed_hosts HOST,HOST,…

The hosts the ESP may connect to, comma-separated; empty means any; --esp-allow gives one host per option and is appended to this list. All frontends.

nextpi.enabled true|false

NextPi under QEMU on UART 1; --nextpi and --no-nextpi. All frontends.

nextpi.dir, nextpi.release, nextpi.qemu_binary, nextpi.audio, nextpi.qemu_args TEXT

The NextPi directory, release, QEMU binary, Pi audio and extra QEMU arguments; --nextpi-dir, --nextpi-release, --nextpi-qemu, --nextpi-audio and --nextpi-qemu-args. Surrounding blanks are removed. All frontends.

debugger.attached true|false

Whether the debugger window follows the emulator window. The window opens as told for this run; the file keeps its value until the Attach to Emulator Window menu item is toggled. The Qt window with the debugger.

debugger.physical_addresses true|false

Whether the debugger names an address’s memory by where it sits in the Next’s memory ($060000, BRAM7+$0000) instead of by page and ROM name (P0E, ROM1, DIVROM). The window opens as told for this run; the file keeps its value until the Physical Addresses item of the Debug menu is toggled. The Qt window with the debugger.