Virtual ][

Copyright © Gerard Putter


About the ROM image file
Run a demo to test the installation
Where to find Apple II documentation
About the evaluation version and licensed versions
Starting and stopping the application
Saving and restoring machine snapshots
General operation


The Apple ][ keyboard
Working with disk images
5.25" floppy disk drive
Hard disk and 3.5" floppy disk drive
Serial interface
Cassette recorder
80-column card for the Apple ][ and Apple ][+
80-column display on the Apple //e
Real time clock
Z80 card and CP/M

Gameplay and other fun stuff

Joystick and game paddles
Working with sound
Recording a movie

Transferring Apple II diskettes to the Mac

The A2V2 utility application

Advanced options

Working with character sets and international keyboards
Controlling Virtual ][ with AppleScript
The Virtual ][ Inspector


Getting support
Release notes

Other issues

Specifications of the virtual machine
Unsupported features
Why did I create this application?


Virtual ][ is an application that emulates the Apple ][ computer. Its main purpose is to enjoy, on your Mac, the nostalgic fun of the Apple ][.

Key features More features Advanced features

Virtual ][ accurately implements the hardware of the original machine in software, so all programs should behave like they did on the real machine.

The application requires macOS 10.13 "High Sierra" or better. There are no specific hardware requirements.

Note that, for reasons of copyright, the application is not bundled with the original Apple ROM images. For more on this, read "About the ROM image file".

You can download and try an evaluation version of Virtual ][ for free. If you like the application, you can buy a license and enjoy the full-featured Apple II emulation. Read more about this in "About the evaluation version and licensed version".

About the ROM image file

Installing a ROM image file

The Apple II machines came with built-in software in ROM. This software is not bundled with Virtual ][, but downloadeding and installing it is easy.

Step 1: Download the appropriate ROM image file(s)

The easiest way is to download ROMs for all five supported machines in one zip file.

If the above link doesn't work, or if you prefer getting individual ROM files you can find them on archive sites, or can search for ROM files with DuckDuckGo or Google.

Before installing, unzip any zip file by simply double-clicking it in the Finder.

Step 2: Copy the ROM image files to the right location on your system

In Virtual ][, select "Show ROM Folder" from the File menu. This opens a Finder window showing the folder where the ROM files must go. Copy or move the ROM files there.

Virtual ][ automatically figures out which file to use for which virtual machine, based on the file contents. The only requirement is that the file names must end in ".rom" or ".ROM".

Step 3: Verify the installation

From the File menu, use "New Machine" to create an instance of the machine you want to emulate, as shown in the next picture. The application will automatically search the ROM folder for a file that matches the selected machine type. If no such ROM can be found, it shows a warning.

If you updated from an older version

Before version 8.0, Virtual ][ allowed the ROM files to reside in the same folder as the application. This setup is likely to fail with later versions of the application, depending on the version of macOS and the configured file access permissions.
It is recommended to move the files to the ROM folder, which you can easily access by selecting "Show ROM Folder" from the File menu.

Some technical background

In each Apple ][, the memory address range from $D000 to $FFFF is occupied by ROM, containing the Basic interpreter (either Integer Basic or Applesoft Basic) and the system monitor. In the Apple //e and //c the memory range $C100 - $CFFF is also used for ROM.
Virtual ][ needs a valid ROM image file to behave like a real Apple II. Because the ROMs are copyrighted by Apple, they are not bundled with Virtual ][. The ROMs must be present as external files containing the exact memory image. To be more precise: Virtual ][ uses the last 12 KB of the designated file (or 16 KB in the case of Apple //e and //c) as the ROM of a newly created virtual machine. The Apple //c needs a ROM file of exactly 32KB.
If the application does not find a suitable ROM file, it uses a built-in ROM image, which shows the message about the missing ROM (and also hides an easter egg 😉).

If you want to use a non-standard ROM, and know what you are doing, you can override the standard ROM image file search, and specify a ROM image file in the "ROM memory" section of the configuration window.

Running a demo to further test the installation

After installing the ROM image files, you can see some examples of what Virtual ][ can do. To that purpose, click on the Applescript menu, and select any of the "example scripts".

You'll see a short explanation of what the demo will do; click the "Run" button to start the demo.

If you want to learn more about using Applescript with Virtual ][, read Controlling Virtual ][ with AppleScript

Where to find Apple II documentation

This Help file is about the Virtual ][ application. For example, it tells you how to configure a virtual machine, how to use the emulated printer and how to work with disk images.
It does however not explain how to use the Apple II computer. If you want to refresh your memory on Applesoft Basic, Integer Basic, DOS or ProDOS commands, you might find this web page useful: Apple ][ Programmer's reference. Or, if you want more detailed information, have a look at this site; it contains a large collection of Apple II manuals.

About the evaluation version and licensed versions

The application runs in one of three license modes:

This table shows the difference between the licenses:


"Evaluation Version" watermark in screen


Pauses every few minutes


Full use of matrix printer emulation (no "Evaluation Version" watermark)


Make and restore machine snapshots at any time


Record a movie of the emulated screen


Mount a Mac folder as a ProDOS disk


Use Unix named pipes for serial I/O


Intelligent power management (as described in Setting the speed)


Available amount of emulated memory

128 KB
128 KB
16 MB

You're entitled to all future improvements of the application


You can purchase a license in the online Virtual ][ store, or with "Buy a License" in the application menu. If you purchase a limited license, you can upgrade to the full license later on.

A license gives you the right to run Virtual ][ on one computer at a time. You can install it on multiple computers though.

Right after ordering the license, the online store sends you an e-mail with the license code. Choose "Enter License Code" in the Virtual ][ application menu, and enter (with copy / paste) the information received in the e-mail.
When everything checks out, the application is upgraded to the licensed version immediately. There is no need to stop and restart the application.

Starting and stopping the application


There are two ways to start the Virtual ][ application:

In either case, the application requires a ROM image file to boot a virtual machine. This is described in more detail in "About the ROM image file".


A virtual machine stops (is "switched off") when you close its window (or when you stop the Virtual ][ application). The application presents a sheet asking if it should make a snapshot of the running machine. If you do, you can continue running the same machine later on by simply opening the snapshot file. Also see Saving and restoring machine snapshots.

Note that you can customize the starting and stopping behavior in the application preferences.

Saving and restoring machine snapshots

Virtual ][ lets you save and restore machine snapshots at any time (full-license only). This can be useful, for example, if you encounter a critical point in a game, and want to make sure you can return to this point in case your game character doesn't survive.
The "Machine" menu has the items you need to save and load snapshots. The virtual machine automatically pauses while a snapshot is being made.
You can also open a previously saved snaphot with File -> Open, or by double-clicking the snapshot file in the Finder. However, if you run a machine and want to go back to a previously saved snapshot of the same machine, you should use one of the the "Load" items in the Machine menu. Using File -> Open in that situation would fail because it would try to open a second machine using the same disk images.

Be aware that working with snapshots has a few limitations:

General operation

The application's main window shows the Apple II screen on the left, and a number of connected devices at the right. These devices depend on the type of machine and any configuration options you may have chosen.

The Apple ][, ][+ and //e allow you to set up different devices by inserting and removing peripheral cards, just like their original counterparts.
The Apple //c machines did not have slots for peripheral cards, and can be sonfigured in a more limited way.


The examples show a monochrome monitor, but the leftmost two buttons in the toolbar make it easy to show a color monitor, or to change "green" to a different color (such as amber).
When a virtual machine is started it waits for a boot diskette. If you want you can skip the diskette boot by pressing Reset (control-F12 or the Reset button in the toolbar).

Each device at the right is a button. The way these buttons and the devices work is described in the next chapters.
The smaller buttons at the top of the peripherals section can be used to select or create diskettes and other media.

Copying the screen to the Macintosh clipboard

The contents of the Apple ][ screen can be copied to the Macintosh clipboard. This can be done in two ways:

Temporarily pausing a virtual machine

A virtual machine can temporarily be paused by selecting "Freeze Virtual Machine" from the "Machine" menu, or by clicking the "Freeze" button in the toolbar. You can later on resume with "Resume Virtual Machine" or the same toolbar button. As a shortcut you can also use the F1 key to pause / resume.

Setting the speed

Virtual ][ faithfully emulates the speed of the original Apple machines, which ran at a CPU clock speed of 1 MHz. Maintaining this exact speed is essential for programs that display animated graphics or produce sound. There are however situations where it would be nice to have a faster machine: while doing a lengthy calculation for example, or when accessing a floppy disk. To this purpose Virtual ][ has three modes of operation, which you can choose from the Machine menu or using the "Speed" slider in the toolbar.

  1. Regular Speed: in this mode, the virtual machine runs exactly at the speed of the original machine. Use this for the genuine Apple II experience.
  2. High Speed: if this is selected, the machine runs as fast as it can, but falls back to regular speed when it writes output to the screen or produces sound. This mode is suitable for game play: some things go fast, like loading and initializing the game, but the game play itself runs at regular speed.
  3. Maximum Speed: the machine runs as fast as it can, and only switches back to regular speed when it must produce sound. This option is intended for things like printing, disk copying, compilations and so on.

A different way to set the machine speed is in the CPU section of the machine configuration, where you can set the machine speed with steps of 1 MHz.

If you have the full license version of Virtual ][, the high speed and maximum speed settings come with a power management feature: while the Apple II is "idle", in other words if it isn't doing anything useful, the speed is automatically reduced to "regular", to conserve energy.
If you want, you can switch the power management feature off with the menu item "Regular Speed if Apple II is Idle", in the Machine menu.

Note that the highest effective speed that can be obtained depends on your Macintosh, on the number of simultaneously open virtual machines, and on other applications running at the same time.

You can preserve battery power even further by selecting the option "Pause virtual machines if minimized or hidden" in the "Power" section of the application preferences. The option is switched on by default.

The Apple ][ keyboard

Key mapping

The built-in keyboard of the original Apple ][ and ][+ computer has far fewer keys than your Macintosh keyboard. It even has hardly enough keys to produce the entire supported character set. For example, on the original machine the user had to press shift-M to produce the character "]", and shift-N for "^". The characters "[" and "\" could not be entered at all, although they could be displayed on screen.

These restrictions do not apply to the Virtual ][ emulator. All characters in the Apple ][ character set can be entered by typing the corresponding character on the Macintosh keyboard. This implies that shift-M just produces a capital M, not a "]".

The "soft caps lock" feature

The keyboard of the original Apple ][ and ][+ could not be used to enter lowercase characters. Typing any of the letters "a" to "z" produced uppercase "A" to "Z".
The Apple //e and //c keyboard was able to enter uppercase and lowercase characters, but many programs still expected uppercase input only.
To emulate flexible keyboard behavior, Virtual ][ has the "soft caps lock" option. When it is on, the keys "a" to "z" produce uppercase letters, as on the original Apple ][ keyboard. When the option is off, these keys produce lowercase letters (or uppercase when shift is also held down), as on the Apple //e. This option can be toggled with the "Caps" toolbar button.

Special keys

The Apple ][ had four special keys that did not produce a character. Here is how they are emulated.

Additional keys on the Apple //e and //c

The Apple //e and //c have a few additional keys.

Pasting the Macintosh clipboard

If the Macintosh clipboard contains text, it can be pasted into the virtual machine. The effect is as if each individual character were typed on the keyboard. This "typing" occurs as fast as the virtual machine can accept the characters, so no characters are lost in the process. If the Apple II is not reading the keyboard when the text is pasted, the text remains queued. Manual input is disabled as long as a pasted text is being entered into the virtual machine. A "newline" character in the text is converted to the Apple II "Return" key.

Working with disk images


A disk image is a representation, in a single Macintosh file, of an entire floppy disk or hard disk. Apple II disk image files come in several different formats; the next table shows the formats that Virtual ][ supports.

Disk image type

File extension


5.25" diskette, 16 sectors per track

.dsk, .do, .po

A regular diskette with 35 to 40 tracks, used with DOS, ProDOS, UCSD Pascal or CP/M. The size of the disk image file is 140 KB for a 35 track disk, up to 160 KB for a 40 track disk.

5.25" diskette, 13 sectors per track


A diskette with 35 tracks of 13 sectors each, as used in Apple DOS before version 3.3. This format is not widely used, and Virtuall ][ supports it in a limited way. Any changes made to the mounted disk, such as new or modified files, are lost when the disk is ejected from the drive.
It is recommended to use the .woz format if you want full read and write access to 13-sector disk images.

5.25" diskette, exact replica of real diskette


Stores the data in exactly the same way as a real Disk ][. The format is suitable for both regular and copy-protected disk images. The size of a .woz diskette image is typically between 200 KB and 250 KB. Virtuall ][ supports both version 1 and version 2 of the Woz file format.

Copy protected 5.25" diskette


A disk in so-called "nibbilized" form. Although this format supports some copy-protection schemes it has some serious limitations, unlike the .woz format. The size of a nib image is 232960 bytes for a 35 track disk, up to 266240 bytes for a 40 track disk.

Copy protected 5.25" diskette (proprietary and deprecated)


A proprietary format, capable of supporting many features of the Disk ][, including "half-tracks" and tracks of non-standard length. The format is compatible with the "D5NI" format used by one of the first Apple II emulators, "Stop The Madness". You won't find disks with this format on internet.
It has been made obsolete by the .woz disk image format.

Compressed 5.25" diskette

.gz, .gzip

Any of the above diskette types, compressed with the gzip utility. Many internet archives offer diskettes in this form, to save space and bandwidth. Such files can directly be used in Virtuall ][, without the need to expand them first.

3.5" diskette


Typically 800KB in size; contains the disk sectors in ascending order. Usually intended for use in ProDOS.

Hard disk or 3.5" diskette

.2mg, .2img

A widely used, universal disk image format.

Hard disk or 3.5" diskette (legacy format)


A disk format based on one of the Mac Classic DiskCopy formats, "NDIF R/W". If you have DiskCopy disk images, there is a good chance you can convert them to the .hdv format by selecting "Convert Legacy Disk Images" from the Media menu. This starts a utility application that allows you to select one or more disk image files and then tries to convert them. If successful, the converted disk images are saved with the ".hdv" extension in the same folder as the original. The original disk images remain untouched. Note the conversion works one-way only.
For the technically interested: the hdv format is extremely straightforward: it just contains all 512 byte disk blocks in ascending order.

Apart from disk images, Virtual ][ also lets you mount a Macintosh folder as an Apple ][ floppy disk or a ProDOS hard disk; this provides a way to copy files from one environment to the other.

Converting original Apple ][ diskettes to disk image files

Many disk images with original programs are available on internet, but Virtual ][ can also help you converting your own Apple II diskettes to disk images, using the A2V2 utility application. If you still have an original Apple ][ with a working disk drive, Virtual ][ can help you converting original diskettes to disk image files. To this purpose, select "Convert Apple II Diskettes" from the "Media" menu. This will start a separate application, named A2V2 (short for Apple ][ - Virtual ][). Read the application's Help section to learn how to do the conversion. A2V2 can convert in both directions: from diskettes to disk image files and vice versa.

Because the capacity of an Apple ][ diskette is very small by todays standards (typically 140 KB), you might end up with many diskette image files. Virtual ][ offers several ways to keep track of the diskettes and their contents. These options are discussed below.

Organizing your disk image files: create a "favorite disk folder"

If you don't have too many disk images, you could put all your disk images in one folder (with subfolders as necessary), and make this the "favorite disk folder" in the Virtual ][ preferences. That way you can use the "Disks" button in the toolbar to open your disks folder in the Finder and drag a disk to an empty Virtual ][ disk drive.

Organizing your disk image files: the "search" window

A powerful feature of Virtual ][ is a built-in search window. It lets you find the disk images that contain an Apple II file with a specific name, no matter where these disk images are on your Mac. This works for diskette images as well as hard disk and 3.5" disk image files. This feature relies on Apple's Spotlight technology, so the disk image files must be in folders that are included in the Spotlight search (by default your entire home folder, and everything in it, is included).
Note that some copy-protected diskettes may have a non-standard structure, and therefore cannot be searched by Spotlight.

To use the feature, select "Search Apple II Disk Images" from the "Media" menu.

If no disk image files appear at all, or when you feel there should be more disk images than are actualy shown, choose "Import Disk Images in Spotlight" from the Application menu. The search window will be updated while new disk images are found.

Initially, the window shows you all disk images belonging to the selected file systems (DOS, ProDOS, etc.). You can narrow down the displayed collection by typing (part of) an Apple II file name in the search field and pressing return.
For example, suppose you want to find all Apple II files that have the term "adventure" in their name. Open the search menu, type the word you are looking for, and press return. This is what might appear.

Apparently, these disk images all contain one or more files with the requested name. To insert one of the disks in an emulated floppy disk drive, double-click it, or drag it to a disk drive.

Because the search mechanism uses the Spotlight feature, you can also search disk images without starting Virtual ][, by just typing a file name in the system-wide Spotlight search field. Selecting one of the disk images from the Spotlight menu launches Virtual ][ with the selected disk inserted.

Note that when you select a disk image file in the Finder, and open the "Info" window, it shows you the Apple II file system.

Searching for disk images on the command line

Advanced users can make command-line Spotlight queries. For example, to list all woz2 disk images on your Mac, open a Terminal window and do:

mdfind 'kMDItemFSName == *.woz && * == woz2'

You can use the mdls tool to find what other meta data is stored for a specific disk image.

Quickly inspecting your disk image files using "QuickLook"

Virtual ][ contains a module for the macOS QuickLook feature. It is installed automatically with Virtual ][, and allows you to quickly inspect the contents of most Apple II diskette and hard disk images. In the Finder, select the Cover Flow view, as shown in the screen snapshot. Alternatively, select a disk image and press the space bar to go to the QuickLook view.
The quick look shows the diskette with an 1980's style label, and the names of the file on the diskette. It also shows the file system, such as DOS or CP/M.

Write-protecting a disk

An Apple II diskette could be write-protected by closing its "write-protect notch" with a piece of tape. In Virtual ][ this can be done by selecting "Set Disk Properties..." from the Media menu. This not only works for diskettes, but also for hard disk images. As with the original Apple II, you can change the write-protect state only while the disk is not inserted in the drive.
Alternatively, you can select the disk image file in the Finder and set its "Locked" property in the Info window.

Setting volume numbers of DOS and ProDOS diskette images

In Apple II DOS and ProDOS, diskettes have a volume number, which is assigned when formatting the diskette. Disk images with the .woz extension also store this volume number. However, diskettes images with file extension .dsk, .do and .po. do not; they only contain the diskette data. For that reason they are assigned the default volume number 254 when you insert them in a disk drive.
This default volume number works fine most of the time, but sometimes Apple II software requires a specific volume number in order to run. To make this posible, Virtual ][ allows you to set a specific volume number, by selecting "Set Disk Properties..." from the Media menu. You can only change the volume number for diskettes while they are not inserted in the disk drive.
Thechnically, the volume number is stored as a so called "extended attribute" in the Mac file system.

Using the floppy disk drives

Supported disk image formats

The original Apple Disk ][ accepts 5.25" diskettes with 35 tracks. However, it was possible to move the disk drive arm to track 36, and some copy protection schemes actually relied on this. Furthermore, disk drives existed (not made by Apple) that supported 40 tracks. In order to support a wide range of disk formats, the disk drive emulation of Virtual ][ supports up to 40 tracks.
The 5.25" diskette image formats supported in Virtual ][ are listed here.

Apart from disk images, the disk drive accepts a Macintosh folder to be mounted as a DOS 3.3 diskette. This feature is described in more detail below.

Inserting and removing a disk

In order for a disk image to be inserted in a disk drive it must have the appropriate file extension. Inserting a disk can be done in several ways: one is to click the appropriate media button at the top of the peripherals section and then select the disk image and the target drive in the file open panel that appears. The same can be done by selecting "Insert Diskette Image" from the "Media" menu, or by simply clicking an empty disk drive.
In the file open panel you will also see a checkbox to make the disk image a part of the configuration. This means that when you save the configuration and later re-open it, the selected disk image is already inserted in the disk drive. This allows you to make a "turnkey" system, which automatically boots from an already inserted disk.

A different way to insert a disk is to simply drag the disk image file or shared folder from its Finder window (or from the disk search window) to an empty disk drive. An empty disk drive can be recognized by the opened drive door. Using this technique, you can still make the disk part of the configuration by holding down the "alt" key while dropping the file or folder.

The third way to insert a diskette is to double-click its icon in the Finder or the disk search window.
When double-clicking a disk image, Virtual ][ will be started when it isn't running already, and the diskette is inserted in the disk drive with the highest slot number and the lowest drive number. This is the disk drive used for booting the machine, so effectively you can boot a DOS session by simply double-clicking the DOS boot diskette.
If Virtual ][ already runs when you double-click the diskette image, it will be inserted in any free disk drive. When no such drive is available, a new virtual machine will be created.

A disk can be removed by clicking on the disk drive or by using "Eject Disk" in the Media menu. Note that a disk can be removed while it is being used for I/O; this is however not recommended, just as with a real Apple II.
If the disk image or mounted folder is part of the configuration, the application presents a confirmation dialog. Ejecting the disk removes it from the configuration.

Creating a new disk image

A new, uninitialized disk can be inserted by clicking the "new disk" media button, or by clicking an empty disk drive and selecting the proper option from the menu that pops up.

A blank disk must be initialized by the Apple II operating system before it can be used.

Mounting a Macintosh folder

A Macintosh folder can be mounted as a DOS 3.3 diskette. This is an easy way to share files between a virtual machine and the Macintosh environment. What actually happens is that the files in the folder are converted to Apple DOS format (if necessary) and stored on a temporary (in-memory) disk image, which is inserted in a disk drive. When files are modified in the virtual machine, they are copied back (with conversion as necessary) to the Macintosh folder.
This approach implies that the mounted Macintosh folder is limited to the maximum diskette size DOS 3.3 can handle, which is approximately 200 KB. Furthermore, it should contain only files, not subfolders (because DOS 3.3 doesn't support a file hierarchy). The file names must adhere to the DOS 3.3 file name rules: the first character must be alphabetic, the file name must contain at most 30 characters and must not contain a comma. Virtual ][ checks on these conditions and ignores any files that do not meet these requirements.

In Apple DOS every file has a file type, such as A(pplesoft Basic), I(nteger Basic) or B(inary). In order to handle the files correctly, Virtual ][ must be aware of the DOS file type of every shared file. Furthermore, some files need conversion. A text file for example has different representations in Apple DOS and in macOS, so if you want to edit a DOS text file in the macOS environment it must be converted. Virtual ][ has a feature that allows you to specify the file type of each shared file, and the conversion rules if appropriate. A dialog window is automatically presented when a Macintosh folder is mounted that contains files with unknown DOS file type. You can also open this window when you choose "Assign Apple DOS Types" from the "Media" menu. This is what the dialog looks like:

The list presents all files and folders in the selected folder. Invalid files are marked with a little red cross, as are folders. Valid files that have already been assigned a DOS type have a green dot. Files that have never been assigned a DOS type appear with the exclamation mark icon, and are assigned type Binary by default.
You can use the popup menus in "Type" and "Macintosh Format" to change the settings. The next table lists your options:

DOS Type

Macintosh Format


B (Binary)

No Conversion: the file is stored in the Macintosh folder exactly as it is stored on the DOS diskette.

Not Applicable

B (Binary)

Strip Prefix: in Apple DOS, all binary files have a 4 byte prefix, containing the load address and the length of the file. With this option, the prefix is omitted from the stored Macintosh file.

This specifies the load address to be used when converting the file to DOS format. You can enter a decimal number or a hexadecimal number preceded by '$'. So for example $2000 is the same as 8192.

T (Text)

No Conversion: the file is stored in the Macintosh folder exactly as it is stored on the DOS diskette.

Not Applicable

T (Text)

Macintosh Text: in Apple DOS, text files are encoded differently than on Macintosh. Select this option if you want to be able to edit the text file in the macOS environment.

Not Applicable

A (Applesoft Basic)
I (Integer Basic)
R (Relocatable)
S (Undefined)
X (Undefined)
Y (Undefined)

Always copied without conversion.

Not Applicable

Virtual ][ remembers the file types and conversion rules you assign, and it automatically uses these settings the next time the folder is mounted.

Note there are some special considerations when using shared folders:

Hard disk and 3.5" floppy disk drive

NOTE: this feature is not available on the original Apple //c, it is available on the Apple //c with 32KB ROM though.


General description

Hard disks and 3.5" floppy disks share the same technical characteristics, and Virtual ][ supports both with an imaginary type of emulated disk drive, called "OmniDisk". This device can handle disk images of any size up to 32 MB (the maximum supported by ProDOS), including 400 KB and 800 KB floppy disk images.

The hard disk / 3.5" disk image formats supported by Virtual ][ are listed here.

Apart from disk images, the OmniDisk accepts a Macintosh folder to be mounted as a ProDOS hard disk. This allows for an easy way to exchange files between the Apple ][ and the Macintosh environments. Note this feature requires a full license to be fully functional.

Setting up hard disk drives

You can connect one or more OmniDisk drives to the virtual machine with the Configuration panel. If the machine has slots, first "insert" a SCSI card, preferably in slot 7 or slot 5. Then connect one or two OmniDisk drives to the SCSI card.

Using the hard disk and 3.5" floppy images

Disk images can be inserted and ejected just like floppy disk images. The only difference is you use the OmniDisk buttons in the devices view.

Using a Macintosh folder as a ProDOS hard disk

A Macintosh folder can be used as a ProDOS disk by "inserting" it in an OmniDisk drive. You can do this in two ways: either choose "Mount Folder as ProDOS Disk" from the "Media" menu, or simply drag a folder from the Finder to an empty OmniDisk in Virtual ][.

A few restrictions apply to the mounted folder:

These restrictions are imposed by the ProDOS system. If Virtual ][ detects that these conditions are not met, it will refuse to mount the folder.

While the folder is mounted, it is not accessible from the Finder. You'll notice the icon gets a lock and a "no entry" sign to indicate this.

The restricted access to a mounted folder is lifted when you eject the disk by clicking the OmniDisk icon. From that point you'll have full access to the folder again in the Mac environment.
So what if Virtual ][ crashes while a folder is mounted? In that case the disk wasn't ejected, so the folder is inaccessible, and you won't be able to mount it again. To solve this, Virtual ][ has an option to reset the state of a mounted folder; you'll find it in the "Media" menu as "Reset Mounted ProDOS Folder". Use it in case of emergency only!

To use the mounted folder, you must boot the virtual machine from a ProDOS system disk.

Every file and every folder in the mounted folder will be present on the ProDOS disk; any changes made on the ProDOS disk (like making new files and directories or changing existing files) result in the same change in the Macintosh folder. Note that a Macintosh file might have a name that is not allowed in ProDOS; in that case Virtual ][ composes an alternative name for use in ProDOS, but this name will be as close to the original as possible.

The contents of text files are treated in a special way: the Apple ][ software expects each line to end with a carriage return character (ASCII 13), whereas macOS uses a linefeed character (ASCII 10) for this purpose. Virtual ][ sees to it that these codes are automatically converted between the Mac and ProDOS environments. All non-text files are stored in the Macintosh folder without any conversion.

If the virtual machine deletes files or directories on the shared folder, the same items are deleted from the Macintosh folder. However, as you would expect on the Mac, they are not deleted right away, but moved to the trash.

The mounted ProDOS folder disk is almost 100% compatible with a "real" ProDOS disk. You can even install the ProDOS system on it, which will give you a bootable disk. The only thing not supported is making a full disk copy (block-by-block) to a mounted ProDOS folder disk. An attempt to do so will result in an error message.

You can store the state of a virtual machine while a folder is mounted as a ProDOS disk; if you do, the folder will keep its access restrictions, because making any changes to the folder would render the saved state invalid and useless. When you open the saved state later on, the folder is mounted automatically and you can continue where you left off.

Finally, the mounted ProDOS folder feature is only fully functional with a full Virtual ][ license. Without the license you can still mount a Mac folder, and examine the directories in ProDOS, but you cannot read or write any files.

ProDOS file types and subtypes

The ProDOS "catalog" command shows file types and subtypes.

Although the file type is shown as a 3-character code, it is internally stored as a number between 0 and 255. For example, file type 4 is a text file (ProDOS shows it as "TXT"); file type 252 is a Basic program (.BAS). When mounting a Mac folder as ProDOS disk, this is how Virtual ][ determines each file's type:

Note that using the "prodos.FileType" extended attribute makes the shared folder compatible with files extracted from a Shrinkit archive by Shrink-Fit X, a utility app to expand shk archives.
If the virtual machine creates a new file on the shared disk, it assigns a file extension based on the ProDOS file type; it does not create the "prodos.FileType" extended attribute.

The ProDOS subtype is a 16-bit integer number. Its meaning depends on the file type. For example, for binary files it indicates the load address; for random-access files it represents the record length. Virtual ][ stores the auxiliary type as extended file attribute "prodos.AuxType" (this is compatible with Shrink-Fit X). If a Mac file does not have this extended attribute, a default value is assumed.
Note that versions of Virtual ][ up to 7.3 used a different way to store the subtype, namely in the file's resource fork. When mounting a shared folder with files created by a previous version, this information is automatically converted to the "prodos.AuxType" extended attribute.

Using the printer

General description

Virtual ][ supports four different emulated printers:

The printer is represented by a "Printer" button in the peripherals section. While the Apple ][ is printing, the green light on the printer blinks. When you press the button, the printer goes offline and the application shows a print preview. You can also click the button with the "alt" key held down: this just sets the printer offline without showing the preview. Pressing the button a second time sets the printer online again.

The Epson FX-80 printer

NOTE: the Epson printer is not available on the Apple //c machines.

The Epson FX-80 was a very popular printer in the 1980's, and is therefore supported by many Apple ][ programs.
A printer on the Apple ][ must always be connected via a printer interface card. When you want to use the Epson printer, use the Configuration panel to insert an emulated Grappler+ card, preferably in slot 1. Then connect the Epson printer to it.

The emulation supports most of the functions of the original printer, such as different character pitches, bold, italic and underlined text, margins, tabs, and graphic modes. Actually the only feature not supported is printing proportional characters.
The technology used by the emulator for text rendering is very different from the technology used in the original Epson. As a result, the characters are somewhat different, but the size and general looks of the characters are just like the real thing, as this example shows:

Apart from all Epson built-in character types, the emulation is also able to print graphics. This allows you to run a program like Broderbund's PrintShop. The print shown here was created with the built-in Printshop demo in the Applescript menu of Virtual ][.

Using the Epson printer is straightforward. While the Apple ][ is printing, the green light on the "Printer" button blinks. When printing has finished, click the Printer button to see a preview.

While the preview is open, the emulated printer is offline, so the Apple ][ will hold new output. The printer comes back online when the preview sheet is closed.
The preview shows the printed output on one or more pages of fanfold paper. The length of one page can be chosen in the Printer section of the Configuration panel, and is 11 inches by default.
Two blue triangles, on the left and right hand side of the paper, indicate the "current position": this is where the next line of output will appear.
At the bottom of the sheet are a few buttons:

After saving the output to a pdf file you can use Apple's Preview application to view the output or print it on a real printer.

The "Action" menu in the preview sheet contains a number of special options.

The Printer section of the Configuration panel lets you set additional printer options, corresponding with the "DIP switches" in the original printer.
Be aware that some Apple II applications need some tweaking of these settings. For example, the number of bits in the connection (7 or 8) can make a big difference. Most applications only work with 7 bits, but some need 8. The best way to go is experimenting a bit with the settings until the output looks as expected.

The ImageWriter II printer

From a user perspective, the ImageWriter II is very much like the Epson FX-80. Both are capable of printing text in different styles, and both can print graphics. From a technical perspective however, the printers are quite different. As a result, some Apple II programs are compatible with just one of these printers. For example the "MousePaint" program, which came with the Apple Mouse, can only print on the ImageWriter, not on the Epson.

The ImageWriter II printer must be connected via a serial interface card. When you want to use the ImageWriter II, use the Configuration panel to insert an emulated Serial Printer card, preferably in slot 1. Then connect the printer to it.

The ImageWriter II did have a unique feature, not found in the Epson, namely the ability to print colors when a color ribbon was installed. This feature is fully supported by Virtual ][.
The ImageWriter II allowed the user to select three different print qualities: draft, correspondence, and near letter quality (NLQ). The emulation only supports the "correspondence" setting, which is the most versatile and has less restrictions than the other two. Note that text is printed with the Macintosh font rendering engine, which in practice gives even better results than NLQ on the original printer.

Operating the ImageWriter in Virtual ][ is identical to operating the Epson priner, so refer to the previous section for details.

The simple "text only" printer

NOTE: the text only printer is not available on the Apple //c machines.

This printer can be connected to either the Grappler+ or the serial printer card. It writes all printed output to an ASCII text file. When printing is finished, or even during printing, you can open the file and process it in whatever way is useful. The name of the printer file is of the form "Printer x - slot y.txt". In this name, x is simply a number starting at 1; y is the slot number the printer is connected to. All printer files are created on the desktop; the location cannot be configured. If a printer file with the same name already exists, new printed output is appended to the end of the file, so in effect the printer file is like an infinite supply of fanfold paper. When a virtual machine is closed the corresponding printer files that are still empty are removed, so the desktop will not be cluttered with empty files.

The easiest and safest way to inspect the printed output is by clicking the "Printer" button in the peripherals section. First, this button places the emulated printer in the "offline" state, so the Apple ][ will hold new output until the printer goes online again. Next, the corresponding output text file is opened in TextEdit. To continue printing, close the text file and press the "Printer" button to put the printer online again.

Printing to the Macintosh clipboard

You can temporarily override the current printer by selecting "Print to Clipboard" from the Edit menu. While this mode is in effect, all printed characters go to the Macintosh clipboard, so they can be pasted in a text editor or word processor after printing has finished. Be aware that clipboard printing is only intended for ASCII text output. This makes it ideal for making a text copy of an Applesoft Basic program; first list it to the clipboard printer, then paste it into a Macintosh text editor. The "print to clipboard" mode is terminated by selecting the same menu option again.

The serial interface

NOTE: the serial port is not available in the emulated Apple //c machines.


In the early 80's, a serial connection was an inexpensive, simple, and therefore popular way to connect the Apple II to another computer. This could either be a local computer, directly connected with a serial cable, or a remote computer, accessible via a modem. There was no such thing as internet back then, but a network of bulletin board systems (BBS's) existed that allowed their members to log on using a modem (typically 1200 baud, sometimes even slower).

Serial port emulation

Virtual ][ emulates the Super Serial card (SSC), which was produced by Apple and was the de facto standard for serial communication on the Apple II. This card implemented the universally accepted RS-232 standard.
The SSC emulation can be connected to the "outside world" in two different ways.

The Virtual ][ configuration panel presents you with a pop-up menu that contains all serial devices available on your Mac. Exactly what it shows depends on your hardware configuration, but here is an example of what it could look like.

In this example, the "KeySerial" and the two "USA28X" items belong to a USB-to-serial adpater. The last item in the menu allows using Unix named pipes (in a full-licensed version only), and the other entries are Bluetooth connections.

Configuring the serial connection

Configuring the serial communication setup requires some patience, just as with the original Apple II. There are three areas to take into account: the DIP switches on the Super Serial card, the device connected to it, and the Apple II software.

The DIP switches on the SSC control a number of customizable options like the baud rate at power-on. These options can be configured in a separate window, by pressing the "Configure..." button below the picture of the SSC in the main configuration panel.

The DIP switches cannot be manipulated directly with the mouse, but they will move when you select the corresponding options.
Note that many of these settings can also be set by the Apple II software, which is actually more convenient than setting the DIP swiches and restarting the virtual machine.
The options that can not be changed by the Apple II software are communications / printer mode and interrupt mode. When the latter is selected the SSC triggers an interrupt when data is sent or received, in order for the Apple II to deal with that event immediately. Only activate this option if you know the Apple II software supports it!
Note that some of the DIP switches cannot be changed at all; they must have a fixed setting in order for the emulation to work properly. In particular, Virtual ][ does not support the old Apple serial interface modes of the SSC.
Note further that switch 8 is a dummy on both banks; it has no function.

The second area to worry about is the Macintosh device connected to the SSC emulation. Note you can select this device and the associated options without the need to restart the virtual machine.

These checkboxes correspond to three RS-232 signals the SSC can receive: Data Set Ready, Data Carrier Detect, and Clear To Send. These signals all tell something about the status of the connected device. For example, the DCD signal is generated by a modem when it has a connection over a phone line with another modem. This signal is useful for an Apple II program waiting for an incoming call: when DCD is activated, the program knows someone made a dial-up connection.
Unfortunately, due to a lack of strict standards, some Apple II programs interpret these signals in a different way. For example, the firmware of the SSC only sends a character when it detects that the DCD signal is ON. This effectively prevents the program to send a dial-up command to a modem! With the original Apple II this was solved in hardware, by connecting the DCD pin to another pin, to ensure it was always ON. This same technique is supported by Virtual ][: checking a box in the configuration panel sets the corresponding signal to ON.
Also, not all serial devices generate these signals. Usually the Apple II software will verify the DSR signal, which indicates that the connected device is powered on. However, when the other device does not generate this signal, or when the line is absent from the serial cable, the only option is to force the signal to be ON.
The CTS signal is used for hardware handshake and should usually not be forced ON.
More information on these signals can be found in Wikipedia.

The "asynchronous send" option controls a timing aspect. When the option is turned on (the default), Virtual ][ forwards each outgoing byte to macOS, and immediately allows the Apple II to send the next byte. Meanwhile, macOS sends these bytes whenever it has the opportunity to do so, in other words: asynchronously. As a result, there can be some delay between the Apple II sending the byte and macOS actually delivering it to the device at the other end of the line. Usually this works fine, and this approach results in a throughput that is almost identical to the original Super Serial card.
However, there are circumstances where the asynchronous approach fails. For example, consider a situation in which the Apple II sends characters to a printer, and pauses after each "newline" character, in order to give the printer the opportunity to move the paper. In that case, the asynchronous mode would not work, because the Apple II must pause after the newline character has been received by the printer (and not after the character has just been sent by the Apple II program). The only way to accomplish this, is to use the synchronous mode: the Apple II will not send the next byte until the current byte has been delivered to the other side.
Note that synchronous mode causes overhead and considerably slows down the output stream.

As a last step of your configuration efforts, the Apple II software must be set up to match the selected emulated hardware options. Most applications offer the Super Serial card as one of the standard configuration options.
When you want to use a modem, and the modem you use is not listed in the program's configuration options, the best guess is to configure it as a "Hayes compatible" modem. Also, choose a moderate baud rate; 1200 or 2400 baud are speeds typically used in the Apple II days. When it all works, you can try to increase the speed.

Configuring the serial connection for Unix named pipes

If you are familiar with Unix pipes you can connect the super serial card to other applications running on the same Mac, using named pipes.
With this option activated, the super serial card emulation uses two Unix named pipes, one for input and one for output. The pipes have fixed names, "IN" and "OUT" (as seen from the standpoint of the virtual machine), and are located in the directory /tmp/VII-machine-name-slotn. So for example, for a machine in an Untitled window, with the super serial card in slot 2, the two named pipes are /tmp/VII-Untitled-slot2/IN and /tmp/VII-Untitled-slot2/OUT.
Virtual ][ creates these pipes when it starts a virtual machine, replacing any old versions of the same files. In order to use the pipes, both must be connected at the other end as well.

Some points of attention for configuring the super serial card with named pipes:

Example of using Unix named pipes

This example demonstrates the serial pipes in operation by connecting to the Terminal application. It is just an example; the feature is intended for connecting to an application that implements an actual communication channel, such as internet.
First configure a Virtual ][ machine with the super serial card in slot 2. Configure the card to use 7 data bits and send a line feed (LF) after each carriage return (CR). Select the Unix named pipes option, and configure as shown below. Note that "force DCD" must be selected because we won't connect to a modem device.

Start the Terminal application, and open two windows. In one window execute the command
cat /tmp/VII-Untitled-slot2/OUT

In the other window execute the command
cat $stdin > /tmp/VII-Untitled-slot2/IN

In the RS-232 monitor of the peripherals section you will now see the DSR and CTS lines become available, which is an indication that the emulation detected that both pipes are now open.

Finally, at the Applesoft prompt in the virtual machine give the command

In the peripherals section the RS-232 output lines light up, indicating that the super serial card has been activated. All output of Virtual ][ is now also shown in the output terminal window; lines typed in the input terminal window appear in Virtual ][.
Unfortunately the "return" key in the input terminal window is ignored by the Apple ][ because the terminal sends a linefeed character, whereas the Apple ][ expects a carriage return character.

Monitoring the serial connection

When you have a Super Serial card installed, Virtual ][ shows a status panel in the peripherals section. The panel shows the status of the RS-232 signals, and can be a great help in troubleshooting. The signals are described in this Wikipedia article. When a signal is OFF, it is shown in dark red; when a signal is ON (or "asserted"), it lights up. The signals are presented as seen from the standpoint of the Apple II, so "RD" indicates the Apple II receives data, and "TD" means the Apple II is transmitting data.

The signals on the left are input for the Super Serial card; the signals on the right are output. You can click on the button to get a pop-up menu that gives the same options as the configuration panel: you can force any of the input signals to be ON, and you can select (a)synchronous send mode.

If you are familiar with the RS-232 standard, you might notice that the signal "RI" (Ring Indicator) is missing in the status panel; the Super Serial card does not support it.

Using the cassette recorder

NOTE: the cassette interface is not available on the Apple //c machines.

General description

The cassette recorder emulation is able to record a file with the sounds produced by the Apple ][ cassette output, and also to read such a file and feed it to the Apple ][ cassette input. Effectively, this provides a fully functional cassette tape emulation. The cassette tape files are actually standard AIFF files. If you are curious how they sound, you can rename a cassette tape file to have the ".aiff" extension, and play it. It is recommended to turn down the volume a bit, because the sound is loud and ugly.

It is even possible to sample an original Apple ][ cassette tape and read it in the emulator. Refer to "Format of the cassette tape file" for details.

Remember that the main purpose of the cassette tape support is nostalgia. It is much more practical to store data on an emulated disk, because the cassette files can become pretty big and the I/O is time consuming.

Playing a cassette tape

To "play" a cassette tape, it is sufficient to "insert" the cassette tape file in the cassette recorder. This can be done in a similar way as inserting a disk in a disk drive: either click the appropriate media button and select a file, or drag the file from the Finder to the cassette recorder icon in the peripherals section. The cassete recorder icon will show a "Play" symbol, but actually the tape starts playing when the first sample is read by the Apple ][ software. So there is no hurry to start the Apple ][ software that reads the tape, even if the tape is inserted first.

You can try this using the "Welcome tape" distributed with the application. It contains a simple Applesoft program. First make sure you see the Applesoft prompt ("]"), then type "LOAD" and press return. Now insert the tape as described. Reading the tape takes about 30 seconds. When the prompt shows up again you can type "RUN" to run the program just loaded.

To eject the cassette tape click the cassette recorder icon.

Recording to a cassette tape

It is not possible to overwrite an existing tape file. To make a recording, create a new tape by clicking the "New cassette tape" icon in the peripherals section and specify the name of the tape in the file save panel that appears. The cassette tape icon shows a "Recording" symbol, and recording starts right away, so the first few seconds of the recording are probably silence. Note however that after the Apple ][ software has produced the last sound sample, no more silence is recorded, so there is no rush to remove the tape after recording has finished; the file won't grow more than necessary.

Format of the cassette tape file

If you want to try sampling an actual Apple II cassette tape, you'll need to know the exact file format:

When reading such a sample in the virtual machine, you might end up with "ERR" displayed on the screen. If this happens, the emulated software did detect a signal (which is good), but was not able to read all data. In this case, try a few different settings for the playback volume slider. You'll find it in the "Cassette interface" section of the configuration panel.

Note that the entire file is kept in memory as long as the cassette tape is in use.

Using the 80-column card with the Apple ][ and Apple ][+

NOTE: this chapter is only applicable to the Apple ][(+). For the Apple //e and //c, see "Using 80-column display on the Apple //e and //c ".

Selecting 80-column video or built-in video

The Virtual ][ emulator has the option to present 80-column text video by inserting an emulated 80-column card in slot 3. Note that the card does not work in any other slot! The 80-column card contains its own video generator circuitry, and is connected to the video monitor through a "video soft switch". This switch has two inputs, designated as the "primary" and "secondary" video signals. Virtual ][ has a configuration option to select which video generator is connected to the primary input and which one is connected to the secondary input. You'll find this configuration in the "Quick settings" menu as well as in the machine settings panel. The Quick settings menu is the easiest way to swicth between the two video generators.
The Apple II software selects the primary or secondary video by refering to annunciator #0. POKE -16296,0 selects the primary video (address $C058); POKE -16295,0 selects the secondary video ($C059).

Selecting the 80-column card for keyboard input

As the 80-column card is in slot 3, "PR#3" will shift input and output to the card. Or when you start the UCSD Pascal system, it determines the card automatically and switches I/O to it. In all cases it is still necessary to direct the 80-coumn video output to the monitor as described above.

The 80-column card supports the full ASCII character set (upercase and lowercase). In order to work correctly, the "shift key modification" must be applied. You'll find this setting under the keyboard configuration. The "shift key modification" in the original Apple ][ involved connecting pin 2 of the keyboard encoder board to push button 2 (pin 4) of the game I/O connector. This modification allowed the software on the 80-column card to detect whether the shift key was pressed in combination with any of the other keys.
Note that in order to enter lower case letters, "Soft Caps Lock" must be turned off in the "Quick settings" menu.

80-columns card special characters

When the keyboard is correctly configured for use with the 80-column card, all characters can be entered in the normal way, except two: when you enter "^", the 80-column card translates it to "N". Likewise, it translates "@" to "P". This is a result of the original Apple ][ keyboard layout. These two characters must be entered with the "ctrl" key pressed.

Also, the 80-column card has a few interesting special key combinations. The below table summarizes all special key combinations.


Enter the character "^"


Enter the character "@"


Inverse mode


Normal (non-inverse) mode


Make hardcopy of the screen on the emulated printer.


Toggles the soft caps lock of the 80-column card. This is basically the same as the soft caps lock of the emulated keyboard (command-shift-A). You can use either option to enter lower case characters.

Using 80-columns display on the Apple //e and //c

The Apple //c machines have built-in built-in 80-column text support. The Apple //e supports it if a memory card has been inserted in the auxiliary slot. By default, such a card is present in a newly configured virtual Apple //e.

Using the Apple Mouse

The Apple //c machines have built-in mouse support; the other emulated machines need the emulated mouse card to be inserted in one of the slots, preferably slot 4. This allows you to run programs such as MousePaint or GEOS.
Apple II software that uses the mouse first switches it "on". When this happens, the Macintosh mouse pointer is hidden, and replaced by whatever mouse pointer the Apple II software provides.

The mouse emulation smoothly integrates with the Macintosh mouse: when the mouse pointer enters the window, it instantly turns into the Apple II mouse, and the Macintosh mouse pointer is hidden. The reverse happens when the mouse moves out of the window: in that case it becomes a Macintosh mouse pointer again.

Relative mouse mode

Unfortunately, smooth integration with the Macintosh mouse is not possible for all Apple II programs. It works fine with MousePaint for example, but it cannot work with GEOS. To solve this problem, the mouse emulation supports a special mode of operation: "relative mouse mode". You'll find it in the "Quick settings" menu. When this mode is switched on, programs like GEOS work well, at the expense of Macintosh mouse integration. Once the mouse has entered the window, it will be captured there, and you must hold down the command key to let it escape.

Using the real time clock

The Apple ][ was not equipped with a built-in real time clock. Several extensions existed to provide a clock, and Virtual ][ emulates three of these.

The emulated clocks take the current time and date from the Macintosh clock. Only the Thunderclock emulation allows adjusting the date and time; the others do not. However, when you reboot the virtual machine, or create a new one, the Thunderclock will always be reset to the Macintosh system clock. Changing the Thunderclock time does not affect the Macintosh clock.

Using the Z80 card and CP/M

NOTE: Z80 support is not available on the Apple //c machines.

A popular enhancement for the Apple ][ (and //e) computers was the Z80 card. This card contains a Zilog Z80 or Z80A processor, plus hardware to transfer the flow of control from the main 6502 processor to the Z80 and vice versa (only one of the processors can be active at any time). The Z80 card made it possible to run the CP/M operating system, and gave access to popular applications like WordStar, DBase and SuperCalc. It also allowed the use of programming languages like Turbo Pascal, Fortran, and even COBOL.
The Z80 card in Virtual ][ emulates the Z80A processor. You can configure the processor to run at a speed of either 2 MHz or 4 MHz.
To use the card you need a bootable Apple ][ CP/M disk image. The boot software on this disk searches for the presence of a Z80 card. When it detects one, it switches to the Z80A processor. After booting is complete, the CP/M prompt is presented.

Using the joystick / game paddles


The Apple II came with two game paddles. Each paddle provided an "analog" input by turning a knob, and a "one-bit" input by pushing a button. Replacing the two paddles with a single joystick was a popular enhancement.
The Game I/O connector of the Apple II allows for connecting up to 4 analog inputs and 3 one-bit inputs. Virtual ][ emulates all of these connections. The best way to play the old games is using a USB or Bluetooth game controller. Alternatively, you can control the game input with the keyboard and mouse.
Virtual ][ will automatically use the game controller if it detects one.

Mapping the gamepad elements to the Virtual ][ game inputs

If Virtual ][ detects a USB or Bluetooth game pad, it automatically maps the available controls to the emulated Apple II game inputs. You can inspect these mappings by selecting "Configure Game Controller" from the "Virtual ][" menu (or by clicking the game pad button in the toolbar).

If you are running macOS 11 (Big Sur) or higher you can use the Gamecontrollers section of the System Settings to assign different buttons and joysticks. You could, for example, switch the left and right joysticks.
If you run macOS older than Big Sur, or use a game controller that cannot be configured at the system level, Virtual ][ presents you with a built-in configuration panel.

Example of game controller profile (macOS 11 and up)

Example of built-in game controller configuration

Testing the game controller

Here is a little Applesoft Basic application to check if your game pad or joystick works correctly. It continuously displays lines with the four game paddle analog values. Move the joysticks on your gamepad to see the values change. They should run from 0 to 255, and have 127 as their neutral value.
To run it, start a standard Apple //e or //c. You don't have to boot from a diskette; just click "Reset" to go to the Applesoft Basic prompt. Now copy the next few lines and paste them in Virtual ][

10 PRINT PDL (0); TAB( 10); PDL (1); TAB( 20); PDL (2); TAB( 30); PDL (3)
20 GOTO 10

Another little Basic program lets you test paddles #0 and #1, which are used for most games. It shows the analog values as well as each paddle's push button.

10 PRINT PDL (0); TAB( 10); PEEK ( - 16287); TAB( 20); PDL (1); TAB( 30); PEEK ( - 16286)
20 GOTO 10

Emulating the game paddles with keyboard and mouse

Virtual ][ lets you control the game paddle inputs with the Mac keyboard and mouse, albeit in a limited way. To this purpose, select "Use Arrows as Joystick" from the "Quick settings" menu.
This may work fine for some games, but be aware that it does not give you the same amount of control a real joystick does. A joystick produces values from 0 to 255. With the keyboard arrows, the possible values are limited to only three: 0, 127, and 255.
Also be aware that many Apple II games have a built-in option for keyboard play. This usually gives a better user experience than emulating the joystick with the Mac keyboard!

You can operate the paddles' push buttons with the command and option keys. If you want to use the command key for this purpose, it is recommended to disable the Virtual ][ command key shortcuts using the "Quick settings" menu.

You'll find additional configuration options in the "Game connector" configuration panel of the machine configuration (not available on the Apple //c machines).

Working with sound


Sounds played an important role in the Apple ][ computer. First of all, it had an internal speaker, controlled by the software. It could do more than just produce simple "beep" sounds; many games used it to produce music and sound effects. Secondly, there were the sounds produced by the hardware. Everyone who used an Apple II knows the "clackety-clack" sound of the disk drive when you booted the operating system.
Finally, if the machine supported peripheral cards, you could increase the sound capabilities of the machine with third party hardware; the most popular was the Mockingboard card.
Virtual ][ supports all these options, and allows you to control their behavior.


NOTE: the Mockingboard is not available on the Apple //c machines – these machines have no slots.

The Mockingboard card was able to produce much higher quality sounds than the internal speaker. It came in different flavors; the one supported by Virtual ][ emulates two sound chips that together can produce 6 simultaneous sounds. The Mockingboard card is used in some popular games, such as Ultima V. When the Apple ][ asks you to identify the card, specify type "A", or "Sound II".

Recording a movie

Virtual ][ lets you easily record a QuickTime movie of everything that happens on the emulated Apple II screen. Just select "Make Movie of Apple II Screen" from the File menu. The application will present a standard File Save panel to let you select where the movie must be saved. After that, recording starts, and will continue until you select "Stop Movie Recording" from the File menu. After recording has stopped, the movie will automatically be opened in the QuickTime movie player.

If you pause the virtual machine, movie recording also pauses. It continues when you resume the virtual machine.

During recording, the movie is written to a temporary file on your disk. When you stop recording, the temporary file is moved to the location you selected. This might take a few seconds.

Virtual ][ records at 20 frames per second. The movies typically take 3 to 6 MB of disk space per minute. The feature does not record sound.

Note that the movie recording option is only available in the full license version of the application.

Working with character sets and international keyboards

About character sets

The computer's "character set" is the collection of all characters that can be displayed on the text screen. In the USA the Apple II computer came with the standard ASCII characters, but international models usually had an alternative character set, with characters for specific languages. For example, the French Apple II supported characters such as à, é, and ç. These characters replaced @, {, and \ respectively, because the character coding space was limited.
Some international Apple II machines came with a switch that allowed the user to instantly switch between character sets. A similar feature is available in Virtual ][. The "Quick settings" pull-down menu contains a list of available character sets.

By selecting a character set, the screen is immediately updated. This example shows how the Apple //e welcome line is shown in the Latin and the Greek character sets.

About international keyboards

On the Apple II, international characters were supported on the screen as well as on the keyboard. To that purpose the machines were equipped with a special character generator rom that defined both the international and the standard ASCII characters. For example, the French keyboard has a key labeled é. This key results in an é on the screen, provided the French character set is selected.
Selecting a character set in Virtual ][ not only updates the screen, but also maps the special characters on your Mac keyboard to the equivalent Apple II character code. So for example, if you have a French Mac, and you set Virtual ][ to the French character set, pressing the key labeled é will produce an é on the screen, like on the real machine. However, if you select the "Latin" character set (the standard ASCII characters), pressing the same key will not produce any character on the screen at all.
Because the keyboard behavior obviously depends on the currently selected character set, you'll see a little flag symbol at the top left of the window to remind you what the current setting is.

Character sets in Virtual ][

The application comes with a number of predefined character sets, as shown above. The character sets "Latin" and "Latin Uppercase Only" are the ones representing the standard ASCII characters. The "uppercase only" variant was used in the Apple ][ and the Apple ][+, because these machines lacked lowercase character support. The "Latin" set was standard in the Apple //e, and contains the standard ASCII characters plus a number of special characters (the so called "mouse characters", used to draw user interface elements such as window borders).

Note that the Bulgarian character set is based on the Pravetz-82 (Правец-82), a popular Apple ][ clone. The character set works best when you install the Pravetz-82 system ROM.

Defining your own character sets

In the Apple II computer the characters were defined in a character generator ROM, which could be replaced by a customized ROM. Virtual ][ offers the same feature. In order to do this, you must provide the application with the following:

The character definition bitmap should be placed in the directory ~/Library/Application Support/Virtual ][/CharacterSets. The file contains pictures of all symbols in the character set, and must be structured as follows:

As an example, here is the definition file of the character set "Latin", used in a standard Apple //e.

The second element of your own character set, the "flag" symbol representing the character set, can be any picture format supported by macOS. It is recommended to use the png format. For best results, make the picture at most 11 pixels high and at most 16 pixels wide. The picture must be stored in the same directory as the character set definition file.

These files are tied together with the keyboard translation table in an XML file with this path: ~/Library/Application Support/Virtual ][/CharacterSets/International.plist.
Such a file can best be created with a property list editor. The file can best be explained with an example.

This example contains two custom character defintions, named "My character set" and "Yet another character set". These names will appear in the Character Set menu. If you choose a name already in use by a built-in set, your definition replaces the built-in one. So if you want to add a new character set, be sure to choose a unique name.
Each character set entry is itself a dictionary with three elements: the file name of the character set definition, the file name of the associated icon (the optional "flag" symbol), and the keyboard translation table.
The keyboard translation table contains two columns: the first is the character typed on the Mac keyboard; the second is the resulting ASCII code (in the range 0 - 127) that will be input in the virtual machine. You can specify the second column value as either a number (the ASCII value) or as a string (the corresponding character). The first column must be one single character, and it must not be in the standard ASCII range. So for example, you cannot translate the character "a" to something else, nor can you translate a control code or a function key. You can, however, translate non-ASCII characters, as shown in the example.


Virtual ][ comes with a number of pre-configured machines. You can change these, or set up a completely new machine from scratch, with the Configuration panel. After configuring a specific machine, you can save the setup with "Save Configuration As..." in the File menu. Alternatively, you can make it the default configuration with the Machine menu.

The Apple //c allows devices, such as disk drives, to be connected directly to the machine. A mouse and a printer are automatically included.
The other machines have slots for peripheral interface cards, and allow more customization. Therefore Virtual ][ has two different configuration panels, as shown here.

To change the configuration of a virtual machine, choose "Configure..." from the Machine menu, or click the "Setup" button in the toolbar. Note that some configuration changes require a restart of the virtual machine.

Additional options can be found under "Quick settings" in the main menu bar. It provides an easy way to change properties that do not require a restart of the virtual machine.

For expert users the Apple //c configuration has a hidden "advanced" section, which can be shown by opening the panel while holding down the "option" key.

Controlling Virtual ][ with AppleScript


Virtual ][ supports Apple's powerful AppleScript technology, which allows you to control the virtual machine using a script. The script can do such things as create and configure virtual machines, type commands on the virtual keyboard, wait until the screen indicates an operation has finished, save printed output, and even insert disk images directly from internet. It allows you to let Virtual ][ perform an automated task, such as starting up your favorite Apple II game. You can also use it to create some nice Apple II demo's.
The application comes with a number of example scripts, which you can find in the AppleScript menu.

When you select one of the example scripts from the menu, you will get the choice to either run the script or open it in the Script Editor. The scripts are hidden inside the Virtual ][ application bundle, so if you want to make changes, it is recommended to save them in a different location.

When you make your own scripts, you can add them to the AppleScript menu by copying them to the Virtual ][ scripts folder. The easiest way to locate that folder is to select "Open Scripts Folder" from the AppleScript menu.

A practical example

This example shows some of Applescript's possibilities.

Suppose you often play the game "Little brick out", which was distributed on the original DOS 3.3 master diskette. You always play it on an Apple ][+ with a color screen. When you make a script that starts your favorite game in Virtual ][, you only have to double-click that script to begin your game play.
In its most elementary form this is what such a script looks like.

The script assumes that the disk is called "3.3 master.dsk", and is in the folder you configured as your "favorite disk folder" in the Virtual ][ preferences.
The script first moves Virtual ][ to the foreground (activate) and gets rid of any currently running virtual machines. It then creates an Apple ][+ and makes sure it has a color screen. After that, it inserts the disk image into slot 6, drive 1. While the machine boots, the script types the DOS command to run the game: "RUN LITTLE BRICK OUT". Virtual ][ sees to it that the typed characters are buffered until the Apple ][+ is ready to process them (which is after booting is complete).

Although this script works OK, it can be improved by temporarily switching the virtual machine to a higher speed during booting and loading the game. This dramatically reduces the start-up time; from 25 seconds it takes on a real Apple ][, to just one or two seconds, depending on the speed of your Mac.

The trick is that the script sets the speed of the virtual machine to "maximum", and resets it to "regular" after the game finished loading. The latter is important: you don't want to play the game at top speed! The script must know when to reset the speed; it does this by looking at the screen with intervals of 0.5 seconds. When the last line on the screen displays "PRESS THE SPACE BAR TO BEGIN....", we know the game has been loaded and the speed can be reset.

Writing your own scripts

When you want to write a script, a good start is to study the example scripts. Virtual ][ does not support recording a script in the Script Editor, so you'll have to use the editor to type the statements yourself.
However, if you are familiar with the AppleScript language you'll find it easy to write scripts for Virtual ][. The script dictionary is based on a simple object model. At the top of the object hierarchy is the application object, as in any AppleScript dictionary. The application contains one or more machines. When you make a new machine object, you'll get a machine that is configured like the default configuration, just as when you select "New Default Machine" from the File menu. Another way to create a machine object is by making an instance of one of the classes AppleII, AppleIIPlus or AppleIIe. The third way to make a machine is by opening a saved configuration file. You'll find examples of these techniques in the demo scripts.

Referring to a specific machine occurs just like referring to a document in other AppleScript-aware applications: by number or by name. When you have just one virtual machine running, the easiest way is to just say front machine.

A machine object contains a number of devices. You cannot create these device objects with AppleScript; they are automatically created when you create a machine. You refer to the devices by name. For slot devices, the name is derived from the slot it is connected to. For example, a device connected to a card in slot #1 is called "S1". A disk drive, typically connected to a disk card in slot #6, is called either "S6D1" or "S6D2", depending on whether it uses connection 1 or 2 of the disk card. If you are familiar with Applesoft Basic, these device names should look familiar. Devices that are not connected to a slot have fixed names. For example, the cassette recorder device is simply called "cassette recorder".

To find out the device names currently in a machine, execute a script as shown in the example below.

Each device has a property, devicetype, which indicates what it is: an Epson printer, a hard disk, and so on. This example shows the device types of the same virtual machine as the previous example.

You can find out what is on the machine's screen by using the property screen text or screen picture. The screen text gives a collection of all the lines on the screen. You can examine these text objects to see if the running process has produced screen output. Often it is more convenient to use the alternative compact screen text; this one omits empty lines and strips trailing space characters from the remaining lines. Study the example scripts to see how this can be used.

The screen picture property can be used in the same picture command. This powerful command compares (part of) the screen picture with a previously saved file. This allows you to wait until a running process has rendered a specific picture on the graphics screen. Virtual ][ offers a convenient way to save the pictures to compare to: use "Export Screen Picture" in the File menu.

Waiting for some screen output to appear is typically a combination of two things: testing the condition and using the command delay. The latter is part of the standard AppleScript additions. It suspends script execution for a specified time period, while the virtual machine keeps running. This allows you to test the screen at regular intervals (every second or so). The example scripts demonstrate this technique.

Finally, the dictionary supports a way to enter any key on the Apple keyboard with the type command. It has a number of variants, so apart from typing plain characters, you can also enter control-key combinations, open and solid Apple keys, and other special keys like up and down arrows. If the AppleScript type commands are executed faster than the Apple II can process them (which is very likely) the keystrokes are buffered until the Apple II processes them. So eventually all keystrokes will arrive in the virtual machine and none will get lost.

To find out the details of using AppleScript with Virtual ][, use the Script Editor to open the application's dictionary and study the classes, commands and properties.

Getting support

Did you encounter technical problems in Virtual ][? Or perhaps you found an Apple II program that doesn't run, or have suggestions for improvements? Tell me about it by e-mail. When reporting a problem, don't forget to mention what versions of macOS and Virtual ][ you use.

You might also want to check if a later version of Virtual ][ is available on the web site.

Release notes

Version 11.4, June 2023

Version 11.3.1, April 2023

Version 11.3, March 2023

Version 11.2, January 2023

Version 11.1, September 2022

Version 11.0, July 2022

Version 10.6.5, February 2022

Version 10.6, January 2022

Version 10.5.1, November 2021

Version 10.5, November 2021

Version 10.4.1, October 2021

Version 10.4, August 2021

Version 10.3.1, July 2021

Version 10.3, April 2021

Version 10.2.2, February 2021

Version 10.2.1, January 2021

Version 10.2, January 2021

Version 10.1, November 2020

Version 10.0.1, July 2020

Version 10.0, July 2020

Version 9.3.1, May 2020

Version 9.3, April 2020

Version 9.2, September 2019

Version 9.1.4, July 2019

Version 9.1.3, April 2019

Version 9.1.2, February 2019

Version 9.1.1, February 2019

Version 9.1, January 2019

Version 9.0, January 2019

Version 8.6, August 2018

Version 8.5, July 2018

Version 8.4, June 2018

Version 8.3, May 2018

Version 8.2, April 2018

This version fixes a number of issues reported by users, and simplifies ROM file installation.

Version 8.1, January 2018

This version adds two preference settings, but mainly fixes issues reported for version 8.0.1. Thanks everyone for your feedback!

Version 8.0.1, December 2017

This version contains extensive behind-the-scenes updates and rewrites to remain compatible with new versions of macOS, forming a basis for further future development.
For example, the application was still 32-bit; as of this release it is a 64-bit app, making it compatible with modern Mac APIs, improved memory management, etc.


Version 7.6.1, March 2017

Version 7.6, March 2017

Version 7.5.5, January 2017

Version 7.5.4, January 2017

Version 7.5.3, August 2016

Version 7.5.2, January 2015

Version 7.5.1, January 2015

Version 7.5, January 2015

Version 7.4.1, December 2013

Version 7.4, December 2013

Version 7.3, September 2013

Version 7.2.1, March 2013

Version 7.2, March 2013

Version 7.1, December 2012

Version 7.0, July 2012

Version 6.5, February 2012

Version 6.4.1, January 2012

Corrected some minor issues that were introduced in version 6.4:

Version 6.4, January 2012

Version 6.3.7, April 2010

Version 6.3.6, February 2010

Version 6.3.5, October 2009

Version 6.3.1, September 2009

Version 6.3, August 2009

Version 6.2, July 2009

Version 6.1, November 2008

Version 6.0, April 2008

Version 5.8.5, November 2007

Version 5.8, July 2007

Version 5.7.1, March 2007

Version 5.7, February 2007

Version 5.6, November 2006

Version 5.5, October 2006

Version 5.4, August 2006

Version 5.3, June 2006

Version 5.2, May 2006

Version 5.1, March 2006

Version 5.0, January 2006

Version 4.3, November 2005

This is a bug-fix release.

Version 4.2, October 2005

Version 4.1, August 2005

Version 4.0, June 2005

Version 3.5.1, June 2005

Version 3.5, May 2005

Version 3.4.1, March 2005

Version 3.4, January 2005

Version 3.3, November 2004

Version 3.2, October 2004

Version 3.1, September 2004

Version 3.0, August 2004

Version 2.6, March 2004

Many of the enhancements are the direct result of feedback I received from users. Thanks every-one!

Version 2.5.1, December 2003

Version 2.5, December 2003

Version 2.1, September 2003

Version 2.0, August 2003

This release adds much-requested features and a number of other improvements.

Version 1.1, June 2003

This release contains numerous new features and improvements.

Version 1.0, April 2003

Initial release

Specifications of the virtual machine

MCS6502 / SY6502, running at 1.023 MHz to 10.230 MHz (configurable). Only the "official" instruction set is supported; all other opcodes are treated as NOP.
WDC 65C02, running at 1.023 MHz to 10.230 MHz (configurable).
Main board
Apple II revision 1.
Apple //e revision B.
Video generator
Supports text, low resolution graphics and high resolution graphics. Screen refresh rate is configurable at 10, 15, 20, 30, or 60 Hz.
On Apple //e also supports 80-column display and double hires.
Character generator ROM
Can be configured to display only upper case characters or upper and lower case characters.
On the Apple //e, contains the regular and alternate character sets.
Allows installation of a custom character set.
Configurable color or monochrome. Size can be set to 560 x 384 pixels (i.e. 1 Apple ][ pixel is presented as 2 x 2 Macintosh pixels), 840 x 576 (1 pixel is 3 x 3), 1120 x 768 ( 1 pixel is 4 x 4), or full-screen.
Monochrome "phosphor" color can be configured.
ROM memory
12 KB configurable from an external file. Memory range $D000 to $FFFF. If the external file contains less than 12K of data, the top part of memory is set up using the file, and the remaining bytes are initialized to 0.
The Apple //e has 16K of ROM, and uses the last 16K of the ROM file.
RAM memory
Apple ][(+): configurable in sizes 4K, 8K, 12K, 16K, 20K, 24K, 32K, 36K and 48K.
Apple //e: 64 KB built-in; can be upgraded up to 16 MB with the RamWorks card.
The "speaker toggle" mechanism of the Apple ][ is fully implemented using macOS Core Audio.
Cassette interface
Using the built-in cassette recorder module, sound produced by the Apple ][ on the cassette output connector can be recorded to an AIFF file, and (uncompressed) AIFF files can be read and fed to the cassette input connector.
Game connector
All inputs of the game connector can be triggered with mouse and keyboard, or with a USB game device. The output functions (annunciators and C040 strobe) are not available.
All Apple ][ keys are supported, except "REPT". Can be configured to enter upper case characters only, or upper and lower case characters; on an Apple ][(+) the shift key can be connected to operate button 2 of the game connector (the "shift key modification").
16 K RAM Card
Implements the Ramex 16 card. Fully compatible with the UCSD Pascal system.
Saturn memory card
Implements the Saturn Systems 128K memory card.
Apple ][ 80-column card
Emulates the Term 80 Video Display Interface.
RamWorks III card (for Apple //e only)
Configurable 64 KB to 8128 KB of RAM, with increments of 64 KB. Allows 80-column and double-hires display.
Parallel printer interface card
Emulates the Orange Micro Grappler+ card. The DIP switches are pre-configured to support the Epson FX-80 printer.
Serial printer interface card
Emulates the Apple Super Serial Card, with the DIP switches pre-configured to support the ImageWriter II printer.
Super Serial card
Emulates the Apple Super Serial Card (SSC). The emulation can work with real serial devices connected to the Mac, or can communicate with other applications via Unix named pipes.
Note that the SCC was also able to emulate the older "Serial Interface card", but Virtual ][ does not support this option.
Mouse card
Emulates the AppleMouse // card.
Epson FX-80 printer
Emulates all Epson FX-80 features except printing proportional characters. The output can be saved to a pdf file for further processing.
ImageWriter II printer
Emulates all ImageWriter II features except printing proportional characters and selecting print quality. The output can be saved to a pdf file for further processing.
"Text only" printer
Writes to an ASCII text file in append mode.
AppleClock card
Emulates the Mountain Computer AppleClock. Is not compatible with the Apple //e.
Thunderclock card
Emulates the Thunderware Thunderclock Plus.
No-slot clock
Emulates the Dallas Phantom DS1216 SmartWatch/ROM Real-Time Clock.
SCSI card
Can only be used with the ProDOS software interface for block devices. Does not actually support the SCSI standard and has no documented I/O addresses. Is designed to work with the OmniDisk emulated drive.
ProDOS disk drive ("OmniDisk")
Emulates an imaginary disk drive able to work with ProDOS disk images of any size up to 32MB. The disk image formats supported are "hdv" and "2img".
Disk ][ card
Emulates the Apple Disk ][ card for DOS 3.3 (16 sectors per track).
Disk ][ drive
Supports up to 80 tracks (including half-tracks). Diskettes are implemented as disk image files or mounted Macintosh folders. Supports sector formats as well as nibble formats. Supports reading, writing and write protection.
Mockingboard card
Emulates the type "A" (a.k.a. "Sound II") Mockingboard card, which means it contains two sound chips able to produce 6 simultaneous sound channels. It does not support the speech chip.
Z80 card
Emulates the Zilog Z80A processor at a clock speed of either 2 MHz or 4 MHz (configurable).
Timing of all instructions is as specified in the Synertec 6502 Programming Manual. The internal clock runs with an average speed of 1.023 MHz. This means that not every individual instruction is accurately timed; however the average timing is accurate when measured over longer time intervals.

Unsupported features

Not all Apple ][ hardware features are supported, and some things work slightly different.

Why did I create this application?

I bought my first computer, an Apple ][ "europlus", in early 1982. It had 48 KB of RAM, a monochrome green monitor, and one Disk ][ drive. It was really expensive, but I never regretted the purchase. On the contrary: during the years I used the machine, from 1982 to 1986, it gave me enormous amounts of fun, and in the end it was worth every penny I paid for it. During that period, I purchased numerous add-on peripheral cards, such as the 16K RAM card, a Z80 card, an 80-column card, clock card, and a PAL TV card. The latter allowed me to finally see, on my TV screen, the colors the Apple ][ produced. I thoroughly enjoyed writing programs for the Apple ][, while discovering how everything worked inside the computer.

In 1986 I bought my first Mac, and soon after the Apple ][ was moved to the basement. Ten years later, around 1996, I discovered that a number of very good Apple ][ emulators were available for the Mac, such as Stop The Madness (STM) and Catakig. One weekend, I got the Apple ][ from the basement, set it up on my desk, and to my surprise everything still worked without a problem. I connected the Apple ][ to the Mac with a serial cable, and wrote software on both machines to convert my collection of floppy disks to disk images on the Mac. Again to my surprise, all disks could be read without a problem despite their ten years in the basement. In the end, I managed to convert all my disks, even the "copy protected" ones, like Bag of Tricks and Visicalc.
The purpose of this was just to enjoy the nostalgia and relive the magical early days of the home computer era.

When I switched to Mac OS X in early 2002, I was a bit disappointed that none of my favorite Apple ][ emulators were available in the new OS, and took the first steps to write one myself. It seemed like a challenging and fun project, and it has been ever since.

While developing Virtual ][, the more than 20 years old Apple ][ again played an important role. I used it for almost all of the pictures in the application, and it was instrumental for comparing the behavior of the emulator with "the real thing".