Platform Mattel Aquarius - z88dk/z88dk GitHub Wiki

Hardware summary

Aquarius hardware

  • Z80 @ 3.5Mhz
  • 4kb RAM (expandable to 52kb)
  • 8kb ROM (Microsoft BASIC)
  • 40x25 character mapped display
  • Optional AY-3-8190 (via Mini Expander/Micro Expander)
  • Optional Hand Controller/joystick pads (via Mini Expander/Micro Expander)

Aquarius Plus hardware

  • Z80 @ 3.5Mhz (or 7Mhz)
  • 512kb RAM
  • 8kb ROM (Microsoft BASIC)
  • 36kb Extended plusBasic ROM
  • Display capabilities
    • 40x25 character mapped display with redefinable PCG
    • 80x25 character mapped display with redefinable PCG
    • 320x200 hi-resolution bitmap with 40x25 colour resolution
    • 160x200 hi-color bitmap with 16 colours per pixel
    • 40x25 Tile map mode
    • Hardware sprites
  • 2x AY-3-8190
  • ESP32 providing file, network, and XBox bluetooth controller facilities

Classic library support (+aquarius)

  • Native console output
  • Native console input
  • ANSI vt100 engine
  • Generic console
    • Redefinable font
    • UDG support
    • Paper colour
    • Ink colour
    • Inverse attribute
    • Bold attribute
    • Underline attribute
  • Lores graphics (80x72 and 80x48)
  • Hires graphics
  • PSG sound
    • ETracker (SAA tracker)
    • PSG Lib (SN76489)
    • Arkos2 Player (AY)
    • WYZ Player (AY)
    • Vortex tracker (AY)
  • One bit sound (on the keyboard speaker)
  • Inkey driver
  • Hardware joystick
  • File I/O
  • Far heap
  • Interrupts
  • RS232

Classic library support - Aquarius+ (+aquarius -clib=aqplus)

  • Native console output
  • Native console input
  • ANSI vt100 engine
  • Generic console
    • Redefinable font
    • UDG support
    • Paper colour
    • Ink colour
    • Inverse attribute (Bitmap mode)
    • Bold attribute (Bitmap mode)
    • Underline attribute (Bitmap mode)
  • Lores graphics (80x72 and 80x48)
  • Hires graphics
  • PSG sound
    • ETracker (SAA tracker)
    • PSG Lib (SN76489)
    • Arkos2 Player (AY)
    • WYZ Player (AY)
    • Vortex tracker (AY)
  • One bit sound (on the keyboard speaker)
  • Inkey driver
  • Hardware joystick
  • File I/O
  • Far heap
  • Interrupts
    • IM1
    • IM2
  • RS232

Quick start

zcc +aquarius -lm -create-app -o adventure adv_a.c

-or-

zcc +aquarius -clib=ansi -lm -create-app -o adventure adv_a.c

The binary converter (appmake) will create two files: _adventure.caq and adventure.caq

The first one is the BASIC loader, and the second one is the binary block. They should be loaded in sequence; type CLOAD, play the first file, then type RUN and play the second one.

With the flag "-Cz--audio" and the related appmake options z88dk now creates a single WAV file with a short pause to permit typing "RUN" in the LOAD process.

Building ROM images

z88dk supports building 8k ROM images for the Aquarius:

zcc +aquarius world.c -subtype=rom -create-app

The ROM file can then be inserted using the emulator. Depending on the emulator, you may need to reset the machine following insertion.

The stack address chosen is at the top of unexpanded RAM. If your program requires more RAM, then move the stack using -pragma-define:REGISTER_SP=xxxx. If using Aquarius+ graphics, do not set it to higher than 0x8000.

The ROM printer doesn't appear to work correctly when used from cartridges. If you wish to print to console then you should use --generic-console to switch to the generic console.

Graphics support

Although the text display is 40x25, the top line also controls the border colour. As a result, z88dk deliberately doesn't use the top row of the screen reducing the resolution to 40x24.

Lores graphics by default is 80x72, a more evenly sized 80x48 graphical mode is available by linking -lgfxaq48.

Aquarius Plus library

Compiling with -clib=aqplus enables Aquarius Plus support which provides additional screen modes.

The screen mode value is passed directly through to the hardware and is bit orientated.

Bit number Value Purpose
0 1 Enable text mode (40x25)
1 2 Enable tile map mode
2 4 Enable bitmap mode (320x200)
3 8 Enable sprites
4 16 Text mode priority (i.e. on top of other modes)
5 32 Remap border character to offset 1023 (offset 2047 in 80-columns mode)
6 64 Enable 80 column text mode
7 128 Map in 2nd text page

Note that only one of tile map or bitmap mode can be enabled at one time. When text mode is enabled, the --generic-console preferentially prints to the text layer, however graphics will preferentially plot to the bitmap layer.

Note for the Aquarius+, high resolution graphics are supported and the default lores graphics resolution is 80x48.

Compiling with -clib=aqplus also provides access to files attached to the ESP32 and associated SD storage.

By default when -create-app is supplied, a .caq file is produced, providing -subtype=aqx -create-app will create a .aqx which can be loaded and run with, for example:

run a.aqx

512k memory support

The extra memory of the Aquarius+ can be accessed in a number of ways:

By default, the far heap will start from RAM page 36, this can be configured with -pragma-define:CLIB_FARHEAP_FIRST=nn. The size of the heap can be configured with -pragam-define:CLIB_FARHEAP_BANKS=nn where nn is the number of 16k banks to use.

Banked program support

Banking support is enabled by default and will automatically load banked code from the attached ESP32/sd card. With this option a .bin file will be generating along with a series of .._BANK_nn.bin files.

To specify the filename of the banks loaded, use -pragma-string:basename=xxxx where xxxx is the filename which is then appended with _BANK_00.bin ... _BANK_1f.bin. For ease of sharing code with other banked systems, z88dk refers to the banks as 0 .. 31 which map into AQ+ RAM pages 32 .. 63.

Emulators

For emulators that can read the .caq format, the following procedure should be used:

  • Run the emulator
  • From within the emulator, load the loader: cload
  • Press then play the "_filename.caq" cassette file (loader)
  • at the "OK" prompt, type RUN
  • Press then play the "filename.caq" cassette file (code)

The easiest way to test with the Aquarius Plus emulator is to use the -subtype=aqx option and copy the generated .aqx file into the emulated drive and then:

run a.aqx

Links

⚠️ **GitHub.com Fallback** ⚠️