Return to index

System Configuration

A number of aspects of the simulation can be changed to correspond with typical hardware and software changes that would have been made to real machines.

This configuration is controlled by a set of system properties that are processed when the simulator starts up. There are a number of different ways in which these properties may be provided. Combinations of these methods can also be used, with properties from later in the list taking precedence over those earlier in the list:

  1. Do nothing. A default set of properties corresponding to a standard machine configuration will be used.
  2. Load a machine image. The properties saved as part of the machine image will be applied.
  3. Default properties file. A Java properties file called can be placed in the same directory as the program JAR file. This can be useful if you always want to set some specific property values.
  4. Additional properties file. The command line parameter -configuration (or -c) can be used to point to an alternative properties file. This is useful if you want to keep a number of different configurations available.
  5. Command line overrides. The command line parameter -properties (or -p) can be used to apply one or more property overrides from the command line. If more than one property is required a comma or semicolon should be used to separate them. This can be useful to temporarily try the effect of an individual property or two.

As an example the following start-up command could be used to start up the simulation temporarily with a large size, green display and a 2MHz CPU:

java -jar uk101-n.n.n.jar -p cpu.speed=2,screen.size=2,screen.colour=green

An example of a Java properties file that contains the default configuration can be found in the file:


An example of a Java properties file that contains settings suitable for emulating an Ohio Scientific Superboard II can be found in the file:


The following sections list all the property names and property values that can be used. Note that property names and values are case-sensitive.


These settings control details of the CPU.

NameValues DefaultNotes
cpu.speed from 0 to 4 1 This defines the maximum simulated CPU speed in MHz. A standard 6502 ran at 1Mhz but most could be over-clocked to 2Mhz quite successfully, which doubles the speed of the machine (although some games may then run too fast). The simulation allows any speed from 1MHz to 4Mhz to be specified.

Setting a value of 0 will cause the simulation to run as fast as it can.
cpu.control auto, sleep, yield or spin auto This determines the method used by the CPU emulation to manage instruction timings. Generally this is best left set to auto to let the system decide the method based on measured system performance. The other options are mainly for experimentation and debug.
sleep  causes the processor thread to sleep when possible. This uses least host system CPU but may give a less smooth emulation on some slow machines.
yield  uses spin-loops to manage timings but causes the processor thread to yield when spinning. This uses more host CPU but the rest of the system should remain fairly responsive.
spin  uses spin-loops to manage timings. This uses a lot of host CPU but should give a smooth emulation although the rest of the system may be less responsive.

Note: The cpu.speed setting represents a maximum simulation speed. It is possible that an older or slower PC will not be able reach the maximum requested.


These settings control details of the installed RAM and ROMs.

NameValues DefaultNotes
ram.size from 4 to 40 8 This defines amount of RAM installed in KBytes. the standard machine came with 4KB and there were sockets on the board to allow up to 8KB to be installed. In theory, with an expansion board, up to another 32KB could be installed giving an absolute maximum contiguous RAM of 40KB.
rom.monitor MONUK01
or filename
This defines the monitor ROM that is installed. The value can be one of the built-in names MONUK01, MONUK02 or CEGMON, or it can be the name of a file containing a replacement ROM.
MONUK01  was the original monitor shipped with the early machines.
MONUK02  was the standard New Monitor shipped with later machines.
CEGMON  is the UK101 version of the popular replacement CEGMON monitor.
rom.basic BASUK101
or filename
This defines the BASIC ROM that is installed. The value can be the built-in name BASUK101 or it can be the name of a file containing a replacement ROM.
rom.charset CHGUK101
or filename
This defines the video character generator ROM that is installed. The value can be the built-in name CHGUK101 or it can be the name of a file containing a replacement ROM.
rom.XXXX filename This allows additional ROMs to be installed. The ROM is installed at address XXXX which must be a valid four digit hexadecimal address from 0000 to FFFF and the value should be the name of a file containing the ROM code.

Note: The additional ROMs are processed and installed after the system monitor and BASIC ROMs, so they can be used to replace some or all of the system ROM address spaces.

Patching ROM Images

When a ROM image is loaded it is possible to define a set of patches to be applied to the ROM data. This can be useful, for example, to force a ROM to default correctly for a 32 line screen, or to change timings such as typing auto-repeat rate for use with faster CPU clocks. Patching can also be done by creating a completly separate ROM image, but for quick testing and simple changes adding the patches to the configuration can often be easier.

Patches are defined using the following syntax appended to the name of the ROM to be loaded:

ADDR  Is a four-digit hexadecimal address at which to begin patching.
BB Are one or more two-digit hexadecimal bytes used to update the ROM starting at the specified address.

Some useful patches include:

ACIA Baud Rate

This setting controls the default baud rate for the ACIA.

NameValues DefaultNotes
baud.rate 110, 300, 600, 1200, 2400, 4800 or 9600 300 This defines default baud rate of the ACIA.

Some programs (in particular some games) relied on the ACIA control signals to generate accurate timings that were independent of the CPU speed.

Note: The ACIA baud rate setting is ignored when reading or writing to a simulated cassette tape, these operations simply run as fast as they can, however it is required if reading or writing a Kansas City Standard audio file.


These settings control the keyboard layout and available keys together with the default keyboard input mode.

NameValues DefaultNotes
keyboard.layout uk or us uk This defines keyboard layout and the available keys.
uk  gives a UK101 keyboard layout.
us  gives an Ohio Scientific Superboard II keyboard.
keyboard.mode normal or game normal This defines the initial keyboard input mode. See keyboard mode for details.

Video Hardware

These settings control the details of the video hardware.

NameValues DefaultNotes
video.rows from 16 to 32 16 This defines the number of rows in the video buffer.
video.cols from 32 to 64 64 This defines the number of columns in the video buffer.

Note: The settings of the video hardware define the amount of video RAM (rows x columns rounded up to the nearest 1K boundary) and the geometry of screen buffer. This is not quite the same as what gets displayed on the screen as real UK101's simple video hardware was not able to scan all of the memory locations to the TV output. Some characters we "lost" from the beginning and end of each scan line. The screen display section configures this.

Screen Display

These settings control the appearance of the video output.

NameValues DefaultNotes
screen.width from 16 to 64 50 This defines the number of characters visible on each screen line.
screen.offset from 0 to 63 12 This defines the offset of the first visible character on each row from the hardware video buffer.
screen.size 1 or 2 1 This defines the size of the video display: 1 is a smaller display, 2 is a larger display.
white, green or amber white This defines the colour of the screen display.
screen.update async or sync async This defines how screen updates are performed.
async  performs all updates via the Java Swing event dispatch thread. This is a more correct way to update the screen but can give slower results on older PCs.
sync  performs updates to each character cell as they are written by the simulation - this may give faster output but can lead to some screen corruption if there are windows overlapping the video window.

Note: On any modern PC, especially anything with a dual or multi-core processor, the default async screen update option is likely to produce the best results. On older hardware the sync option may result in faster and/or smoother operation.

Kansas City Audio Encoding

These settings control the audio encoding when creating Kansas City Standard data files.

NameValues DefaultNotes
audio.rate from 8000 to 96000 48000 This defines the audio sample rate. Higher sample values give higher quality sound but larger files.
audio.bits 8 or 16 16 This defines the number of bits for each sample. Higher bit values give higher quality sound but larger files.
audio.lead from 0 to 10 5 This is the number of seconds of carrier tone played before the start and after the end of the data.
audio.wave system or sine system This defines the shape of the audio waveform.
system  generates a waveform that closely matches that produced by the real UK101 hardware.
sine  encodes the audio as pure sine waves.

Note: The baud rate setting is also required when reading or writing audio data, however it is restricted to the values 300, 600 or 1200 only.

Tim Baldwin
November 2015
Return to index

© Tim Baldwin 2010,2015