Donate to plus4emu development plus4emu usage

Command line options

'File' menu

Configuration / Load from ASCII file

Select and load an ASCII format configuration file and apply the new settings. If the configuration file does not include all the supported options, those that are omitted are left unchanged.

Configuration / Load from binary file

Load a plus4emu format binary file, which may be a previously saved snapshot or demo, a binary format configuration file, or a program file with plus4emu header.

Configuration / Save as ASCII file

Save the current emulator configuration to an ASCII text file, which can be edited with any text editor, and can be loaded at a later time.

Configuration / Save

Save the current emulator configuration in binary format to the default file (~/.plus4emu/plus4cfg.dat). This is also automatically done when exiting the emulator.

Configuration / Revert

Reload emulator configuration from ~/.plus4emu/plus4cfg.dat, and apply the original settings.

Save snapshot

Save a snapshot of the current state of the emulated machine to the selected file. The snapshot will also include the current memory configuration and ROM images, but clock frequency and timing settings are not restored when loading a snapshot. The file format may be subject to changes between different releases of the emulator. Note that the state of any floppy drives is currently not saved, and the drives are reset on loading a snapshot.

Load snapshot (F7)

Load a plus4emu format binary file, which may be a previously saved snapshot or demo, a binary format configuration file, or a program file with plus4emu header.

Quick snapshot / Set file name

Select file name for quick snapshots. The default is ~/.plus4emu/qs_plus4.dat. This setting is not saved on exit.

Quick snapshot / Save (Ctrl + F9)

Save snapshot to the quick snapshot file (see notes above).

Quick snapshot / Load (Ctrl + F10)

Load the quick snapshot file if it exists.

Record demo

Save snapshot (including clock frequency and timing settings) and record keyboard events to the selected file until the recording is stopped. The events can be replayed with accurate timing when the file is loaded later. Note that the file format may change between different releases of the emulator, and the timing may also be incorrect when using a different version to play a demo file.

Stop demo (Ctrl + F12)

Stop any currently running demo playback or recording.

Load demo (F7)

Load a plus4emu format binary file, which may be a previously saved snapshot or demo, a binary format configuration file, or a program file with plus4emu header.

Record audio / Start...

Write 16 bit signed PCM sound output to a WAV format sound file.

Record audio / Stop

Close sound output file if it is currently being written.

Record video / Start...

Open new AVI file for video recording. This increases the CPU usage significantly, and since the data is written without compression, it will take up a lot of disk space. If the size of the output file reaches 2 GB, it is automatically closed, and the emulator asks for a new file to continue the recording.
NOTE: the video and audio streams in the AVI file are not affected by any of the display or sound configuration settings.

Record video / Stop

Stop video capture, and close any AVI file that is currently being written.

Save screenshot (F6)

Save a screenshot in 24 bit RLE compressed TGA format. The video output is captured immediately after activating this menu item, and is saved at a resolution of 768x576 without any processing (color correction, effects, etc.).

Quit (Shift + F12)

Exit the emulator.

'Machine' menu

Reset / Reset (F11)

This has the same effect as using the reset button on the real machine.

Reset / Force reset (Ctrl + F11)

In addition to a normal reset, make sure that the emulated machine is really restarted using the standard ROM reset routines, and do not allow programs to disable reset by setting custom (RAM) handlers; however, most of the RAM data is still preserved. This option will also turn off automatically enabled extensions that increase CPU usage, such as SID emulation and 1541/1551/1581 drives with no disk opened.

Reset / Reset clock frequencies

Reset clock frequency and timing settings to those specified in the machine configuration; this is normally only useful after demo playback, which may override the settings. The SID and ACIA configuration, which may be changed by snapshot or demo loading, are also reset.

Reset / Reset machine configuration (Shift + F11)

Reset memory configuration (RAM size, ROM images), clock frequency, and timing settings according to the machine configuration, and clear all RAM data. Implies 'Force reset' and 'Reset clock frequencies'. Reverting the configuration can be useful after snapshot loading or demo playback, as these may change the settings.

Quick configuration / Load config 1 (PageDown)

Load the configuration file ~/.plus4emu/p4vmcfg1.cfg, and apply the new settings.

Quick configuration / Load config 2 (PageUp)

Load the configuration file ~/.plus4emu/p4vmcfg2.cfg, and apply the new settings.

Quick configuration / Save config 1

Save the current clock frequency and timing settings to ~/.plus4emu/p4vmcfg1.cfg.

Quick configuration / Save config 2

Save the current clock frequency and timing settings to ~/.plus4emu/p4vmcfg2.cfg.

Printer / Disable printer
Printer / MPS-801 (IEC level)
Printer / MPS-802 (hardware level)
Printer / MPS-802 (1525 mode)

If enabled, an MPS-801 or 1526/MPS-802 printer is emulated as device 4 on the serial bus. The MPS-802 printer emulation is implemented at the hardware level for full compatibility with a real printer. On the other hand, the IEC level MPS-801 emulation uses less CPU time, prints faster, and supports printing graphics.

Printer / View printer output

Shows the printer output in real time in a window. It is also possible to save the page as a 520x736 (MPS-801) or 700x990 (MPS-802) 8-bit RLE compressed TGA file. When the printing reaches the bottom of the page, it stops, and the LED will flash; you can then save the page to a file, click the 'Clear' button, and turn on and then off 'Form feed' to continue printing.
In the case of MPS-801 emulation, the form feed button is ignored, so it is enough to click the 'Clear' button to continue with printing the next page; in this mode, there is also an input buffer of 128 kilobytes - until the buffer is full, the printing (and writing the output to a text file if enabled) is not blocked on the Plus/4.
NOTE: it is recommended to close this window while using the debugger, since it cannot display printer output then, and may slow down the GUI.

Enable light pen

Emulate a Trojan Light Pen connected to the first joystick port. Light pen input is only generated when a mouse button is held down while the mouse cursor is in the emulation display area.

SID emulation / Enable

Turn on SID emulation, making the SID registers appear at FD40-FD5F and FE80-FE9F; this increases the CPU usage of the emulator. SID emulation is also automatically enabled when a byte is written to the above mentioned address ranges, but some programs detect if a SID card is present by only reading the registers, and in those cases using this option is needed. SID emulation remains active until the next use of 'Force reset' or 'Reset machine configuration', and snapshot data includes SID state and whether it was enabled or not at the time of saving the snapshot.

SID emulation / Disable

Turn off SID emulation if it is currently enabled.

'Options' menu

Display / Set size to 384x288
Display / Set size to 768x576
Display / Set size to 1152x864

Resize the emulator window to predefined width/height values; this has no effect in fullscreen mode. While the window can also be resized using the window manager, sizes that are integer multiples of the actual screen resolution of the emulated machine may look better, particularly when texture filtering is not used, and are also slightly faster when using the software video driver.

Display / Cycle display mode (F9)

Cycle between these four display modes:

Sound / Increase volume

Increase sound output volume by about 2 dB.

Sound / Decrease volume

Decrease sound output volume by about 2 dB.

Floppy / Configure... (Alt + D)

Opens a dialog for setting up floppy drive emulation.
For each drive, an image file can be selected. If the file name is left empty, that means having no disk in that particular drive. It may also be possible to directly access a real 1581 800k disk by using the /dev/fd* devices (on Linux) or \\.\A: (on Windows) as the image file.
The file format must be either D64 or D81; the type is determined from the file size. Opening a D64 file will enable 1541 or 1551 emulation for that particular drive, while the 1581 will be emulated for D81 files.
Since these drives are emulated at the hardware level (with a 6502 CPU, etc.), enabling them increases the CPU usage. A drive will remain active until a different type of image file is opened, or a snapshot is loaded or 'Force reset' (or anything that implies it) is used while there is no disk opened.
Setting the drive type of unit 8 or unit 9 to 1551, and leaving the image file name empty enables IEC level 1551 drive emulation instead of true (hardware level) drive emulation. This can be used to access .PRG, .P00, .R00, .S00, and .U00 files in the currently selected working directory, and also has the advantage of not increasing the CPU usage.

Floppy / Remove disk / Unit 8
Floppy / Remove disk / Unit 9
Floppy / Remove disk / Unit 10
Floppy / Remove disk / Unit 11
Floppy / Remove disk / All drives

These are just shortcuts for setting the image file name for a specific floppy drive to an empty string.

Floppy / Replace disk / Unit 8
Floppy / Replace disk / Unit 9
Floppy / Replace disk / Unit 10
Floppy / Replace disk / Unit 11
Floppy / Replace disk / All drives

Set the image file name for a specific (or all) floppy drive to an empty string, and then set the original file name again. This is mostly useful when accessing real floppy disks, after the disk is changed.

Floppy / Reset / Unit 8
Floppy / Reset / Unit 9
Floppy / Reset / Unit 10
Floppy / Reset / Unit 11
Floppy / Reset / All drives

Reset a specific (or all) floppy drive.

Floppy / Disable unused drives

Turn off the emulation of all floppy drives that are currently active, but have no disk image attached. This can be useful to reduce CPU usage when a drive is no longer needed, without having to reset the emulated machine.
Using this option may also be needed to enable IEC level drive emulation, which cannot be used while hardware level emulation on the same unit is still active.

Set working directory (Alt + Q)

Set the directory to be accessed by the IEC level drive emulation. NOTE: the filesystem access is read-only by default, but writing can be enabled in the machine configuration.
This directory is also used by monitor commands that take a file name argument.

'Debug' menu

Start debugger (Alt + M)

Shows the debugger window. Many functions in the debugger can be used either in CPU addressing mode where the 16 bit address space of the currently selected CPU can be accessed, or physical address mode that allows access to all memory in the emulated system, regardless of any memory banking or the debug context selected. The following table shows the memory map in physical address mode; the 8-bit codes on the left are used in the 'Memory paging' window:

00 000000-003FFF Basic ROM
01 004000-007FFF Kernal ROM
02, 03 008000-00FFFF Function (3-plus-1) ROM
04, 05 010000-017FFF Cartridge 1
06, 07 018000-01FFFF Cartridge 2 (used by p4fileio.rom)
0A 028000-02BFFF MPS-801 printer ROM (4K, repeated 4x)
0C 030000-033FFF 1526/MPS-802 printer ROM (8K, repeated 2x)
10 040000-043FFF 1541 floppy drive ROM
20 080000-083FFF 1551 floppy drive ROM
30, 31 0C0000-0C7FFF 1581 floppy drive ROM
40-43 100000-10FFFF Main CPU address space
50-53 140000-14FFFF Printer CPU address space (MPS-802 only)
60-63 180000-18FFFF Floppy unit 8 CPU address space
64-67 190000-19FFFF Floppy unit 9 CPU address space
68-6B 1A0000-1AFFFF Floppy unit 10 CPU address space
6C-6F 1B0000-1BFFFF Floppy unit 11 CPU address space
FF 3FC000-3FFFFF RAM (16K)
FE-FF 3F8000-3FFFFF RAM (32K)
FC-FF 3F0000-3FFFFF RAM (64K; also the default bank for >64K)
F0-FF 3C0000-3FFFFF RAM (256K)
C0-FF 300000-3FFFFF RAM (1024K)

TED and I/O registers are not mapped into the RAM or ROM areas in physical address mode.

The monitor commands are mostly similar to those in TEDMON, although most commands - with the exception of G and TR - support CPU/physical address mode switching, and the following have some improvements:

A Supports undocumented opcodes (using opcode names from 64doc.txt), $ characters and leading zeros are optional, assemble offset can be used to write the code to a different area than where it will actually run
D Can disassemble to a file, supports undocumented opcodes and disassemble offset
F It is possible to fill memory with a pattern of any length, not just a single byte
H More advanced pattern matching (specific bits or bytes can be ignored); note that strings should be enclosed within double quote characters
T Allows the source and destination areas to overlap

There are also these new commands:

? Prints the list of available commands
? CMD Prints help for command 'CMD'
AM Set/toggle CPU/physical address mode
AO Set/clear assemble and disassemble offset
I Prints the current monitor settings (address mode, etc.)
SR Search for and replace pattern in memory; uses the same rules as the H command, and can also ignore (not change) bits or bytes when writing the replacement pattern
TR Logs CPU instructions to a file until the debugger is opened again, or the number of instructions exceeds a specified limit
W Set debug context
X Same as the 'Continue' button
Y Same as the 'Step over' button
Z Same as the 'Step' button

Lua scripting

Starting from version 1.2.5, it is possible to run scripts written in Lua from the debugger. This document only describes the use of scripts in the emulator, and the new API functions added; for general information about programming in Lua, see

Clicking the 'Run' button will run the script, and also enable the breakpoint callback function (see below) if it is defined. If there are any syntax or runtime errors, the script is terminated, and the breakpoint callback is disabled. After making any changes to the script, you need to click 'Run' and restart the script for the changes to take effect.

It is possible to define a breakpoint callback function in the script, which will be automatically called whenever a breakpoint is triggered, and the debugger window would be shown. This function has the following syntax:

    function breakPointCallback(debugContext, bpType, addr, value)
      return showWindow

where 'showWindow' is a boolean value, which, if true, will allow the debugger window to be shown like normal, or have the emulated program continue without any break if it is false. The four parameters passed to the function are as follows:

The breakpoint callback function will remain active until either a new script is run which does not define one, or the 'Stop' button is clicked.

NOTE: an infinite loop in the script will hang the emulator, and a very frequently called and/or complex breakpoint callback may slow down the emulation.

The following new functions are defined by the emulator for use in the scripts:

SHL(a, b)
SHR(a, b)

These simple helper functions implement bitwise operations that are not available in the Lua language by default. AND, OR, and XOR can take any number of integer arguments, and return the bitwise AND, OR, and XOR of the values, respectively. In the case of zero arguments, OR and XOR return zero, while AND returns -1.
SHL returns 'a' shifted to the left by 'b' bits, and SHR returns 'a' shifted to the right by 'b' bits. If 'b' is zero, the value is not changed, while a negative 'b' will reverse the direction of shifting. The result of shifting negative values to the right is unspecified.


Returns the current debugging context, which can be one of the following:


Set the debugging context to 'n' (0 to 5, see above). It is recommended to restore the original debugging context before the script returns.

setBreakPoint(bptype, addr, priority)

Set a breakpoint or watchpoint at address 'addr' (0-0xFFFF) for the current debugging context, with priority 'priority' (0 to 3). 'bptype' can be one of the following values:

NOTE: the changes made to the breakpoint list by the script are not reflected in the breakpoint editor. To restore the previously defined breakpoints, click the 'Apply' button.


Deletes all breakpoints that were previously defined for the current debugging context.


Returns the memory bank selected for $0000-$3FFF if 'n' is 0, $4000-$7FFF if 'n' is 1, $8000-$BFFF if 'n' is 2, or $C000-$FFFF if 'n' is 3. The returned value is a 8 bit integer, as described above at the beginning of the debugger documentation.


Read a byte from 'addr' (0 to 0xFFFF) in the address space of the current debugging context.

writeMemory(addr, value)

Write 'value' to 'addr' (0 to 0xFFFF) in the address space of the current debugging context.


Read a byte from 'addr' (0 to 0x3FFFFF) in the "physical" address space described above at the beginning of the debugger documentation.

writeMemoryRaw(addr, value)

Write 'value' to 'addr' (0 to 0x3FFFFF) in the "physical" address space described above at the beginning of the debugger documentation.


These functions return the registers of the currently selected CPU. PC is a 16 bit value, while the others are 8 bit.


Set registers of the currently selected CPU. 'n' should be a 16 bit value when setting PC, and 8 bit for the other registers. Note that changing the program counter only takes effect after the execution of the current instruction is completed.


Load PRG or P00 file 'fname', which must be a full path file name. The current debugging context is ignored, and zeropage variables at $2D-$32 and $9D-$9E are updated according to the file loaded.


Save the memory area defined by zeropage variables $2B-$2E to a PRG file 'fname', which must be a full path file name. The current debugging context is ignored, and the data is always read from RAM, regardless of memory paging by $FF3E/$FF3F.


Prints any number of strings or numbers to the monitor. No separator characters are inserted between the arguments being printed, and a newline character is automatically added at the end of the message.

    mprint("Running Lua script example...")
    setBreakPoint(2, 0x0C00, 2)
    setBreakPoint(2, 0x0C01, 2)
    function breakPointCallback(d, t, a, v)
      if (a == 0x0C00 and v == 0x00) or
         (a == 0x0C01 and v == 0x01) then
        return true
      return false

This will break only when $00 is written to $0C00, or $01 is written to $0C01.

Back to main page

© Istvan Varga <>, 2008 Logo