ZEsarUX Emulator

For developers and advanced users, ZEsarUX provides a robust suite of debugging tools:

Core Debugging

• Reverse Debugging
• CPU History and CPU Transaction log
• Assembler and Disassembler
• Registers view
• Conditional Breakpoints (using text expressions)
• Watches
• Step-to-step, Step-over, and Runto
• Hexadecimal Editor

Specialized Debugging

• Text Adventure Debugger: For Quill/Paws/Daad/Gac adventures. Includes stepping through content, watching flags/objects, listing messages, connections, and viewing the Text Adventure Map.
• Memory Cheat: Tools to find counters (energy, bombs, ammo) for game modification.
• ZRCP (ZEsarUX Remote Command Protocol): A telnet-based protocol for enhanced debugging (e.g., from Visual Studio Code via DeZog).

Once you have saved your object code to a TAP file, you can load it into memory using standard BASIC commands.

NextZXOS / ESXDOS Pattern:

CLEAR 49151
.tapein PROJECT1.TAP
LOAD "name" CODE 49152
.tapein -c

Saving from Memory: To save the code back out from memory to a TAP:

• NextZXOS: SAVE "name" CODE 49152,length
• ESXDOS: SAVE *"name" CODE 49152,length

After editing your text in the editor, exit the editor with Q to return to the command prompt.

1. Assemble: Press A. SPED52 converts the text into machine code (numbers). If errors occur, press ENTER to proceed; note the line number to fix it later using EXTEND+L in the editor.
2. Save Source: Press S followed by a filename (e.g., S FIRST.SPE) to save the text version.
3. Save Object Code: Press O followed by a filename (e.g., O FIRST.BIN) to save the compiled machine code.

Note on TAP Files: To ensure you can save your work, you must have a TAP file attached. Use the NextZXOS NMI menu (Multiface button) or ESXDOS NMI to attach/select different TAP files to maintain a history of changes (e.g., PROJECT1.TAP, PROJECT2.TAP).

ZEsarUX is available in several formats across multiple platforms:

Official Releases

• Source code
• Binary compiled versions:
  • GNU/Linux (32/64 Bits)
  • FreeBSD 64 Bits
  • Haiku OS
  • macOS (Silicon/Intel)
  • Windows
  • Raspberry Pi (Raspbian)
• Docker image (available on Docker Hub)

Third-party/Community Distributions

• Arch Linux, Slackware, Retropie/EmulationStation, Open Pandora, PocketCHIP, MorphOS

Other

• ZEsarUX watchface for Pebble (via Rebble/Repebble stores)

1. Assemble

Press A at the command prompt. SPED53 converts your text instructions into machine code (numbers). If errors occur, press ENTER to proceed to the next error. You can use EXTEND+L in the editor to jump to a specific error line.

2. Save Source and Object Code

To prevent data loss, always attach a .TAP file using the NMI menu (Multiface button) before working.

To save the text (Source): S FILENAME.SPE (e.g., S FIRST.SPE)

To save the machine code (Object): O FILENAME.BIN (e.g., O FIRST.BIN)

3. Running the code

To run your assembled code, return to BASIC and load the object code from the tape:

NextZXOS:

CLEAR 49151
.tapein PROJECT1.TAP
LOAD "t:"
LOAD "name" CODE 49152
.tapein -c

ESXDOS:

CLEAR 49151
.tapein PROJECT1.TAP
LOAD "name" CODE 49152
.tapein -c

The Contabilidad General Spectrum software is available in three formats. Depending on the file you use, the loading procedure differs:

1. If using Contabilidad General Spectrum.tzx (Original converted tape): You must manually clear the memory before loading. Execute the following sequence:

   • CLEAR 59999
   • LOAD ""

2. If using Contabilidad General Spectrum_con_clear.tzx or Contabilidad General Spectrum_con_clear.tap: These versions include the CLEAR 59999 command and will load automatically.

Available Files:

• Contabilidad General Spectrum.tzx: Original converted tape (requires manual clear/load).
• Contabilidad General Spectrum_con_clear.tzx: Includes automatic clear and load.
• Contabilidad General Spectrum_con_clear.tap: Same as above, but in .tap format.

// For the original .tzx file:
CLEAR 59999
LOAD ""

To edit source code, press E at the command prompt.

Standard Editor Keys (after pressing EXTEND mode CAPS and SYMBOL on a 48K KB):

• A: Page down
• B: Delete Block
• C: Copy Block
• D: Search for Label
• E: " from start
• F: Search Text
• G: " from start
• N: Find Next text
• I: Insert ON/OFF
• J: Next Label
• K: Calculate Expression
• L: Goto line
• P: Mark start of Block
• Q: Page up
• U: Mark end of Block
• V: Paste Block
• X: Cut Block
• Z: Restore Line

While holding Symbol Shift:

• D: Delete line
• I: Insert line
• Q: Exit editor

Example Source Code:

;Sample program make A=200
 LD A,200
 RET

SPED53 is an integrated Assembler, Monitor, and Disassembler for the 128K Spectrum. To ensure optimal performance for the editor and assembly process, set the emulator speed to 14Mhz (use the browser or press F8).

Loading the software

• On NextZXOS: Load SPED53EN.TAP directly using Mode 0.
• On DivMMC/ESXDOS: Use SPED53.BAS from the tools directory; it will prompt you to select your preferred language version.

Returning to your code from BASIC

If you exit to BASIC (using B), the system will print a specific address (e.g., Return to 49453). To return to the SPED53 environment with your source code intact, use the following command in BASIC:

RANDOMIZE USR xxxxx

(Replace xxxxx with the printed address).

RANDOMIZE USR 49453

SPED52 is a 128K assembler, monitor, and disassembler for the ZX Spectrum. To run it effectively in ZEsarUX:

1. Set Speed: Use the Browser to set the emulation speed to 14Mhz. This significantly improves the editor and assembly performance. (Shortcut: F8).
2. Load the Tool: Use Mode 0 to load SPED52EN.TAP (or .RUN SPED52EN.TAP) from the tools directory.
3. Return to System: If you exit to BASIC (by pressing Capital B), the system will print an address (e.g., Return to 49453). To return to your source code with the system intact, type:

   RANDOMIZE USR xxxxx

   (Replace xxxxx with the printed address).

Important Rules:

• Use CAPITALS for almost all commands.
• ALWAYS SAVE your work before running the Assembler. There is no warning; a crash will result in loss of data.

RANDOMIZE USR 49453

To edit code, press E at the command prompt. The editor uses a Block system where text is held on multiple banked memory pages. The current block is displayed in the top right.

Editor Commands

After entering editor mode, use CAPS and SYMBOL (Shift) keys:

Standard Keys:

• A: Page down
• B: Delete Block
• C: Copy Block
• D: Search for Label
• E: Search " from start
• F: Search Text
• G: Search " from start
• N: Find Next text
• P: Mark start of Block
• Q: Page up
• U: Mark end of Block
• V: Paste Block
• X: Cut Block
• Z: Restore Line
• L: Goto line
• K: Calculate Expression

Using Symbol Shift:

• D: Delete line
• I: Insert line
• Q: Exit editor

Managing Blocks

Use G n (e.g., G 0,1,2) to navigate to specific blocks if they have been started.

;Sample program make A=200
 LD A,200
 RET