apple2(1)

NAME

apple2, xapple2 - Apple ][+ and //e emulator

SYNOPSIS

apple2

xapple2 [ -noshm ]

DESCRIPTION

apple2 (svgalib) and xapple2 (X11) both emulate a 64k Apple ][+ and 128k Apple //e computer (the latter only if //e support compiled in). To use the emulator you need to acquire the original ][+ and //e ROM files which are not distributed due to copyright reasons. The emulator reads standard 143360-byte and 232960-byte disk image files with .dsk and .nib suffixes respectively. You can also change any images with the extension .do to .dsk and they will work too.

There are only a few command line options:

-noshm This forces the X11 version to not use the MITSHM extension.: This may degrade the speed of the emulator but allow you to run it remote.

THE .apple2 FILE

The emulator reads user preferences from a .apple2 file located in your home directory. Copy the .apple2 file that comes distributed with the emulator to your home directory. You can edit the settings using your favorite editor, but most of the settings can be tweaked from within the emulator (see menus section below).

speed Speed of emulation, 1 - XXX. (Actually this is an inverse: delay-loop counter). 1 is slow, and XXX is as fast as can be. A delay loop is needed to bring the emulation rate down to near what would be considered a normal Apple ][ speed. The max speed value should be determined by YOU when you compile the emulator. For <= 100Mhz Pentium systems, I personally like a max value of 100 with a normal apple ][ speed somewhere in the 70s. For faster machines, try larger ranges.
mode Starting emulation mode. One of "][+", "][+ undocumented",: "//e". You can also dynamically change the emulation mode from within the emulator.
disk path: Toplevel path of disk images directory. Personally I like /usr/local/games/apple2/disks.
color Black/white, lazy color, color, lazy interpolated, interpolated.
sound Off, pc speaker.
joystick: Off, linear, pc joystick.
joystick range: 2 - 256. Range of the joystick values. Good settings are 256 and sometimes 128, with centers at 128 and 64 respectively. This often depends on the game.
origin_x: X coordinate origin. 128 is good for many games with a range of 256. Others like 64 with a range of 128.
origin_y
Y coordinate origin. 128 is good for many games with a range of 256. Others like 64 with a range of 128.
pc joystick parms You can configure this from within the emulator. Select the 'Calibrate' option from the F10 menu. If the emulator complains that it cannot open the joystick device, make sure the module is loaded. This option is only valid if you've compiled the emulator with -DPC_JOYSTICK.
sensitivity 1% - 100%. This value is used for the emulated joystick using the numeric keypad.
system path The directory holding the rom files. The emulator won't run if this is not set properly. You can only change this by editing the .apple2 file.
So here is an example .apple2 file: speed = 72 mode = ][+ disk path = /usr/local/games/apple2/disks color = interpolated sound = pc speaker joystick = pc joystick joystick range = 256 origin_x = 128 origin_y = 128 pc joystick parms = 767 693 1344 28 1454 28 13 sensitivity = 13% system path = /usr/local/games/apple2/rom

ROM FILES

The emulator requires several ROM files to run.

apple_II.rom: You need this file for basic ][+ emulation. It contains the 12K ROM of your Apple ][+. It is not distributed due to copyright issues, so you have to get this file on your own. If you have been running another apple2 emulator, you can most likely use its ROM files directly. This file is a memory dump of the consecutive addresses from D000 to FFFF of the Apple ][+. This file may also be named apple.rom or apple2.rom, but is referenced internally as apple_II.rom.
slot6.rom You need this file for basic disk drive emulation. It is 256 byte memory dump of the consecutive addresses from C600 to C6FF. This file is not distributed again due to copyright issues. This file may also be named controller.rom, but is referenced internally as slot6.rom.
apple_IIe.rom
If //e support was not compiled into the emulator, then you do not need this file. It is the 32K ROM of your 128k Apple //e, a dump of main memory (bank 0) addresses C000-FFFF concatenated with auxiliary memory (bank 1) addresses C000-FFFF. Because the apple_IIe.rom contains the C600 slot, you can construct the slot6.rom file from this one. The apple_IIe.rom file may also be named apple2e.rom but is referenced internally as apple_IIe.rom.
character.rom A 2048 byte ][+ character rom file. This file is distributed with the emulator.

DISK IMAGES

The emulator reads standard DOS3.3-order 143360 byte '.dsk' images and raw-nibble 232960 byte '.nib' images. The emulator can handle images which are gzip'ed as long as the suffixes are '.dsk.gz' and '.nib.gz' respectively. The emulator simply assumes that /bin/gzip is available to compress/decompress these images in place as needed and that you have permission to do so.

The images are raw binary dumps, containing the tracks from 0 to 34 from the original 5.25 disk. For the standard 143360 byte '.dsk' format each track is partitioned into sectors of 256 bytes, numbered from 0 to 15.

The raw nibblized 232960-byte images are usually made of programs that have non-standard formatting as a means of copy protection. The nibblized format attempts to preserve the non-standard format, and so defeats the copy protection without "cracking" the program.

To transfer Apple ][ diskettes into one of these formats requires that you own an original Apple ][. Since the drives provided by the IBM PC's are not compatible with the original Apple ][ drives there are no conversion programs directly available. If you have used other Apple ][ emulators it is most likely that the files will work with this emulator too. For more information on Apple ][ disk formats and such, see Beneath Apple DOS by Don Worth and Pieter Lechner, published long ago by Quality Software.

EMULATOR KEYS/MENUS

F1 Interface to switch disk in Drive A, Slot 6. Arrow keys navi: gate the selection. If the disk highlighted is already in the drive, it will have a <rw1> or <r1> tag after the name indicating read/write or read-only access. Select this disk to eject it. To select a disk, you can press 'w' or RETURN to insert it into the drive. Pressing 'w' will attempt to open the disk as read/write (if you have permission to do so). Pressing RETURN defaults to opening the disk read-only. Press ESC to accept current settings and exit the menu.
F2 Interface to switch disk in Drive B, Slot 6. Same controls as for F1.
F4 Pause the emulation. The Pause/Break key will also work. Hit a key to resume.
F5 Display the Apple ][+ or //e keyboard layout.
F7 Enter the Debugger console (if this support was compiled into the program). See the file DEBUGGER that came with the emulator for command information.
F9 Toggles between maximum speed and configured speed. This is useful to 'fastboot' programs, and then slip back to normal Apple ][ speed.
F10 General parameter settings menu, including the all-important QUIT option. You can edit most of the parameters in your .apple2 file from this menu. Two options worth mentioning are the 'Calibrate' and 'JS Sample' options. 'Calibrate' lets you calibrate the PC Joystick device. 'JS Sample' lets you set the sample rate of the PC Joystick device. 'Save' lets you save the settings to your .apple2 file.
Special Keys The key combination Ctrl-'PrintScrn/SysReq' will reboot the machine. The Ctrl-'Pause/Break' combination will reset the machine. Remember that 'Pause/Break' alone will pause emulation. AltLeft and AltRight keys correspond to the OpenApple and ClosedApple keys (joystick buttons 0 & 1). NOTE: In //e mode try Ctrl-AltRight-'Pause/Break' sequence for a system self-test. The numeric keypad is used for emulated joystick movement.

BUGS AND STUFF

See the PROBLEMS file that came with the code.

Using the joystick for some disk images is problematic. Apparently there is a bug in Apple ]['s where reading values from the joystick ports too quickly results in a smaller value than normal. Unfortunately the emulator doesn't emulate this bug in the machine, but you can mostly get the same effect by changing the range of the joystick. For instance, games like Space Rogue and Airheart like a range of 0x80 with the center around 0x40. Most other games will like a range of 0x100 with the center around 0x80.

Under X, you may notice that some keys are not working as advertised (Pause/Break as reboot for instance). Make sure that these keys are mapped. (Run xmodmap -pke for the current mapping).

MORE INFO

More information is available in the online newsgroups comp.emulators.apple2, and comp.sys.apple2.

AUTHORS

Apple //e support and revisions v006, v005, v004, v003 by Aaron Culliney (aculline@bbn.com). Revision v002 by Stephen Lee. Original version(s) by Alexander Jean-Claude Bottema.

docs.sk

comprehensive documentation repository

In section