.TH Aq 1 "" "Aq @PROJECT_VERSION@" .SH NAME Aq \- The Mattel/Radofin Aquarius Emulator .SH SYNOPSIS \fBAq\fP [\fB-BEikln\fP] [\fB-b\fP \fIfile\fP] [\fB-t\fP \fIfile\fP] [\fB-g\fP \fIfile\fP] .br .SH DESCRIPTION Aq is an open source Mattel Aquarius emulator. It provides a graphical interface via \fISDL2\fP (see v0.1 for a curses-based interface, instead). It features a fairly complete cycle-exact Z80 emulator, which can also be run in unlimited (turbo) mode. It supports both built-in and expansion module sound (including higher-level tape drive support) and expansion module game controllers. Turbo mode is both manually select-able and automatic for initial BASIC file loads and tape operations. It also comes with a few extras; BASIC files are installed in \fB@DATA_DIR@/bas\fP, tapes in \fB@DATA_DIR@/tapes\fP, and ROMS in \fN@DATA_DIR@/roms\fP: .IP \(bu 2 All examples from the users' maual as BASIC text files and combined into a single tape file (\fBbasic.tape\fP). .PP .IP \(bu 2 A number of expansion cartridge sound samples, in the form of BASIC files and combined into a single tape file (\fBsndtest.tape\fP). .PP .IP \(bu 2 An Extended BASIC ROM (\fBebasic.bin\fP) which loads into the low Extended BASIC ROM slot. Other cartridges can be loaded at the same time. It has been verified to work with the \fIQuickDisk\fP ROM's Extended BASIC support. It was generated by automatically disassembling the standard (high-loading) version combined with some hand-editing and re-assembly. .PP .IP \(bu 2 A sample ROM: \fBCamelForth/80-1.2\fP ported from CP/M to the Aquarius. It is available both as a ROM (\fBcam80-12.bin\fP) and a tape file (\fBcam80-12.tape\fP). .PP .IP \(bu 2 A sample ROM: \fBZexAll\fP ported from CP/M to the Aquarius. Unfortunately, this requires write access to the BASIC ROM area, which Aq secretly supports just for this ROM. This is available both as a ROM (\fBzexall.bin\fP) and a tape file (\fBzexall.tape\fP). .PP .IP \(bu 2 Support for assembly language development for the Aquarius based around the (Small Device C compiler toolkit](\fIhttp://sdcc.sourceforge.net\fP), which may already be provided by your distribution. This includes the tools \fBihx2bin\fP and \fBasm2bas\fP as well as macros and symbols in \fBaquarius.mac\fP (in particular, a macro to easily create the magic ROM header). This was used to build the provided ROMs and sound samples. .PP .IP \(bu 2 The HALT instruction stops the emulator. .PP There is also an optional GUI, based on either \fBQt\fP or \fBDear ImGui\fP. The GUI adds a menu, and allows run-time changes of tape and ROM files, and immediate pasting of BASIC files. While it might be possible for it to run on Windows or MacOS, it was developed and tested only on Linux. See the CHANGES file for a list of major changes. .SH OPTIONS .TP \fB-b\fP \fIfile\fP Type in \fIfile\fP (presumably BASIC) at startup, in turbo mode. You should prefix the file with a blank line in order to get past the startup screen ("Press RETURN key to start"). To run the program after typing it in, add a RUN command at the end. Turbo mode will be exited after typing the file, so it will run at normal speed. .PP .TP \fB-t\fP \fIfile\fP Enable tape drive, saving by appending to \fIfile\fP and loading by reading from it at the current position (rewinding when at end). The format of the file is the raw serial data produced by the Aquarius. This is compatible with other emulators' files, regardless of what they call their format. .PP .TP \fB-g\fP \fIfile\fP Insert a (presumably game) cartridge from \fIfile\fP. If blank (an empty string), disable any configured cartridge file. .PP .TP \fB-E\fP Use the supplied Extended BASIC ROM. Unlike the separate Extended BASIC ROM, this is loaded into a special memory area designed just for it, and can be loaded at the same time as other cartridges. .PP .TP \fB-n\fP Don't read the config file. .PP .TP \fB-B\fP Enter batch mode. This is generally used along with \fB-b\fP, and simply enters turbo mode without any display or sound. The emulator does not know when to stop; this must be done by the loaded \fB-b\fP code or cartridge by executing the HALT instruction. For example: .br \fBPOKE14339,118:v=USR(0)\fP .PP .TP \fB-k\fP Use SCAN mode for keyboard event insertion (\fB-b\fP). By default, TIMER mode is used. In SCAN mode, the number of times Aquarius scans the keyboard is counted (71). In TIMER mode, a key is pressed for 20,000 CPU cycles (5.5 virtual ms), and then released for 22,000 (6.1 virtual ms). .PP .TP \fB-f\fP Start up in fullscreen mode. .PP .TP \fB-l\fP Create debugging log file (\fIlog\fP) .PP .TP \fB-i\fP Create I/O debugging log file (\fIilog\fP) .PP .SH KEY BINDINGS The default key bindings are: .TP F1 Toggle manual turbo mode (tape operations and BASIC loading will always enter turbo mode; this is for other times) .TP F11 RESET .TP F12 Exit emulator .TP Alt-F Toggle Fullscreen mode .TP Cursor keys Joystick A/1/left direction .TP Insert/Home/PgUp/Delete/End/PgDn Joystick A/1/left buttons 1 .. 6 .TP Numeric keypad 3/6/6/4/1/0/2/. Jostick A/1/left direction .TP Numeric keypad //*/-/8/9/+ Joystick A/1/left buttons 1 .. 6 .TP Numeric keypad Enter Swap joysticks A/1/left and B/2/right. .PP If a GUI is enabled, the default additional key bindings are: .TP F10 Toggle main menu .TP Alt-B Load text file (presumably BASIC) immediately .TP Alt-G Set cartridge for next RESET. Requires RESET (F11) to take effect. .TP Alt-P Set taPe file .TP Alt-H Display "About" box .TP Alt-A, Alt-R, Alt-T Bring up menus. .PP .SH CONFIGURATION Most configuration options are available in the GUI. The file \fBXDG_CONFIG_HOME\fP\fI/Aq/config.json\fP (usually \fI~/.config/Aq/config.jason\fP) contains a single JSON object. The keys are configuration keys: .SS ROMS .TP "\fBcartridge\fP": \fIstring\fP Set cartridge to load. Can be overridden using \fB-g\fP on the command line. Changing the cartridge via the GUI does no save this value: it can only be set by hand-editing the file. Can also be null or an empty string to disable the ROM (the default). .PP .TP "\fBuse_ebasic\fP": \fIboolean\fP Enable the special Extended BASIC ROM. Can be enabled via the command line (\fB-E\fP), but not disabled. Changing this via the GUI also updates the config file. .PP .TP "\fBebrom\fP": \fIstring\fP Set the name of the special Extended BASIC ROM file (default: \fBebasic.bin\fP). Changing this via the GUI also updates the config file. .PP .TP "\fBbasicrom\fP": \fIstring\fP Set the name of the main (presumably BASIC) ROM file (default: \fBradofin.bin\fP). Changing this via the GUI also updates the config file. .PP .TP "\fBcharrom\fP": \fIstring\fP Set the name of the character ROM file (default: \fBAquarius-chars.rom\fP). Changing this via the GUI also updates the config file. .PP .SS Tape .TP "\fBtape\fP": \fIstring\fP Set tape file to read/save to by default. Can be overridden, but not disabled on the command line using \fB-t\fP. Changing this via the GUI also updates the config file. Can also be null or an empty string to disable the tape. .PP .TP "\fBtape_ask_save\fP": \fIboolean\fP Enable asking for a new tape file every time a new save is detected. Changing this via the GUI also updates the config file. .PP .TP "\fBtape_ask_end\fP": \fIboolean\fP Enable asking for a new tape file every time a load reaches the end of tape, or on a save followed by a load. Changing this via the GUI also updates the config file. .PP .TP "\fBtape_ask_load\fP": \fIboolean\fP Enable asking for a new tape file every time a new file load is detected. Changing this via the GUI also updates the config file. .SS Misc .TP "\fBmenubar\fP": \fIboolean\fP Show menubar in GUI. Changing this via the GUI (\fBF10\fP) also updates the config file. You can still always access hotkeys and the right mouse button menu (which is identical). .PP .TP "\fBkeyscan\fP": \fIboolean\fP Set scan mode; see \fB-k\fP. \fB-k\fP overrides. Changing this via GUI, if a hotkey is assigned, also updates the config file. .PP .TP "\fBsnd_quiet\fP": \fInumber\fP Set the attenuation (quiet level) of the sound generator. This is an integer in the range 0..15, which attenuates by a power of 2. Changing this via the GUI, if a hotkey is assigned, also updates the config file. .PP .TP "\fBjoy_swap\fP": \fIboolean\fP Swap joystick ports. Changing this via the GUI, if a hotkey is assigned, also updates the config file. .PP .TP "\fBkeys\fP": \fIobject\fP Input bindings; see \fBAq_binding\fP(5). .PP .TP "\fBcontrollers\fP": \fIarray\fP Controller mapping; see \fBAq_binding\fP(5). .PP .TP "\fBinclude\fP": \fIarray\fP An array of configuation file names to load before this one, in the array's order. Later files overwrite previous configuration values, except for the following: "\fBkeys\fP" merges values by overwriting only identical sub-keys. "\fBinclude\fP" is processed immediately in the context of the loaded file. "\fBread_only\fP" is dropped (only the last one is kept). Relative file names are searched for in the same directory as the loading file first, and then in the XDG search path. .PP .TP "\fBread_only\fP": \fIboolean\fP If true, this file (and only this file) will not be updated by the GUI on configuration changes. .PP@IMGUI_FONT_DOC@ .SH FILES .TS l l . \fB~/.config/Aq\fP Default configuration location \fIconfig\fP\fB/config.json\fP Default configuration file@GUI_STATE_FILE@ \fB~/.local/share/Aq\fP Default user data directory \fB@DATA_DIR@\fP Default system data install directory \fIdata\fP\fB/bas\fP BASIC files (either data directory) \fIdata\fP\fB/tapes\fP TAPE files (either data directory) \fIdata\fP\fB/roms\fP ROM files (either data directory) \fBlog\fP Debugging log file when using -l \fBilog\fP I/O debugging log file when using -i .TE .SH AUTHORS Steve Baker (steve.baker.llc@gmail.com) .br Thomas J. Moore (darktjm@gmail.com) .SH "SEE ALSO" \fBAq_binding\fP(5) .PP