2019-11-11 22:28:07 +00:00
# Apple ][+, //e emulator
2019-06-02 21:00:31 +00:00
2019-11-11 22:28:07 +00:00
Portable emulator of an Apple II+ or //e. Written in Go.
2019-06-02 21:00:31 +00:00
2019-06-10 22:13:56 +00:00
[![CircleCI ](https://circleci.com/gh/ivanizag/apple2/tree/master.svg?style=svg )](https://circleci.com/gh/ivanizag/apple2/tree/master)
2019-06-02 21:00:31 +00:00
## Features
2019-11-08 22:56:54 +00:00
- Models:
2020-08-08 11:40:48 +00:00
- Apple ][+ with 48Kb of base RAM
- Apple //e with 128Kb of RAM
- Apple //e enhanced with 128Kb of RAM
- Base64A clone with 48Kb of base RAM and paginated ROM
2019-11-09 16:44:04 +00:00
- Storage
2020-08-11 21:53:05 +00:00
- 16 Sector 5 1/4 diskettes in NIB, DSK or PO format
- 16 Sector 5 1/4 diskettes in WOZ 1.0 or 2.0 format (read only)
- 3.5 disks in PO or 2MG format
- Hard disk in HDV or 2MG format with ProDOS and SmartPort support
2019-06-02 21:00:31 +00:00
- Emulated extension cards:
2020-08-08 11:40:48 +00:00
- DiskII controller
- 16Kb Language Card
- 256Kb Saturn RAM
2020-08-10 18:52:17 +00:00
- 1Mb Memory Expansion Card (slinky)
- RAMWorks style expansion Card (up to 16MB additional) (Apple //e only)
2020-08-08 11:40:48 +00:00
- ThunderClock Plus real time clock
2020-08-11 21:53:05 +00:00
- Bootable Smartport / ProDOS card
2020-08-08 11:40:48 +00:00
- Apple //e 80 columns with 64Kb extra RAM and optional RGB modes
- VidHd, limited to the ROM signature and SHR as used by Total Replay, only for //e models with 128Kb
- FASTChip, limited to what Total Replay needs to set and clear fast mode
2020-08-16 13:30:44 +00:00
- No Slot Clock based on the DS1216
2019-06-02 21:00:31 +00:00
- Graphic modes:
2020-08-08 11:40:48 +00:00
- Text 40 columns
- Text 80 columns (Apple //e only)
- Low-Resolution graphics
- Double-Width Low-Resolution graphics (Apple //e only)
- High-Resolution graphics
- Double-Width High-Resolution graphics (Apple //e only)
- Super High Resolution (VidHD only)
- Mixed mode
2020-08-10 18:52:17 +00:00
- RGB card text 40 columns with 16 colors for foreground and background (mixable)
2020-08-08 11:40:48 +00:00
- RGB card mode 11, mono 560x192
2020-08-10 18:52:17 +00:00
- RGB card mode 12, ntsc 160*192
2020-08-08 11:40:48 +00:00
- RGB card mode 13, ntsc 140*192 (regular DHGR)
- RGB card mode 14, mix of modes 11 and 13 on the fly
2019-06-02 21:00:31 +00:00
- Displays:
2020-08-08 11:40:48 +00:00
- Green monochrome monitor with half width pixel support
- NTSC Color TV (extracting the phase from the mono signal)
- RGB for Super High Resolution and RGB card
- ANSI Console, avoiding the SDL2 dependency
2020-08-08 11:44:45 +00:00
- Debug mode: shows four panels with actual screen, page1, page2 and extra info dependant of the video mode
2019-11-11 22:28:07 +00:00
- Other features:
2020-08-08 11:40:48 +00:00
- Sound
- Joystick support. Up to two joysticks or four paddles
- Adjustable speed
- Fast disk mode to set max speed while using the disks
- Single file executable with embedded ROMs and DOS 3.3
- Pause (thanks a2geek)
- ProDOS MLI calls tracing
2019-06-02 21:00:31 +00:00
2020-08-12 20:50:40 +00:00
By default the following configuration is launched:
- Enhanced Apple //e with 65c02 processor
- RAMworks card with 80 column, RGB (with Video7 modes) and 8Gb RAM is aux slot
- Memory Expansion card with 1Gb in slot 1
- VidHD card (SHR support) in slot 2
- FASTChip Accelerator card in slot 3
- ThunderClock Plus card in slot 4
- SmartPort card with 1 device in slot 5 (if an image is provided with -disk35)
- DiskII controller card in slot 6
- SmartPort card with 1 device in slot 7 (if an image is provided with -hd)
2019-06-02 21:00:31 +00:00
## Running the emulator
2019-11-11 22:28:07 +00:00
No installation required. [Download ](https://github.com/ivanizag/apple2/releases ) the single file executable `apple2xxx_xxx` for linux or Mac, SDL2 graphics or console. Build from source to get the latest features.
2019-06-02 21:00:31 +00:00
### Default mode
2020-03-08 22:42:39 +00:00
Execute without parameters to have an emulated Apple //e Enhanced with 128kb booting DOS 3.3 ready to run Applesoft:
2020-08-08 11:40:48 +00:00
2020-08-10 18:52:17 +00:00
``` terminal
2019-06-02 21:00:31 +00:00
casa@servidor:~$ ./apple2sdl
```
![DOS 3.3 started ](doc/dos33.png )
### Play games
2020-08-08 11:40:48 +00:00
2019-12-22 13:32:54 +00:00
Download a DSK or WOZ file or use an URL ([Asimov](https://www.apple.asimov.net/images/) is an excellent source) with the `-disk` parameter:
2020-08-08 11:40:48 +00:00
2020-08-10 18:52:17 +00:00
``` terminal
2019-07-07 15:40:29 +00:00
casa@servidor:~$ ./apple2sdl -disk "https://www.apple.asimov.net/images/games/action/karateka/karateka (includes intro).dsk"
2019-06-02 21:00:31 +00:00
```
2020-08-08 11:40:48 +00:00
2019-06-02 21:00:31 +00:00
![Karateka ](doc/karateka.png )
2019-10-02 21:39:39 +00:00
### Play the Total Replay collection
2020-08-08 11:40:48 +00:00
2019-10-02 21:39:39 +00:00
Download the excellent [Total Replay ](https://archive.org/details/TotalReplay ) compilation by
[a2-4am ](https://github.com/a2-4am/4cade ). Run it with the `-hd` parameter:
2020-08-08 11:40:48 +00:00
2020-08-10 18:52:17 +00:00
``` terminal
2020-01-21 22:42:44 +00:00
casa@servidor:~$ ./apple2sdl -hd "Total Replay v3.0.2mg"
2019-10-02 21:39:39 +00:00
```
2020-08-08 11:40:48 +00:00
2019-11-11 22:28:07 +00:00
Displays super hi-res box art as seen with the VidHD card.
2019-10-02 21:39:39 +00:00
![Total Replay ](doc/totalreplay.png )
2019-06-02 21:00:31 +00:00
### Terminal mode
2020-08-08 11:40:48 +00:00
To run text mode right on the terminal without the SDL2 dependency, use `apple2console` . It runs on the console using ANSI escape codes. Input is sent to the emulated Apple II one line at a time:
2020-08-10 18:52:17 +00:00
``` terminal
2019-12-26 22:11:32 +00:00
casa@servidor:~$ ./apple2console -model 2plus
2019-06-02 21:00:31 +00:00
############################################
# #
# APPLE II #
# #
# DOS VERSION 3.3 SYSTEM MASTER #
# #
# #
# JANUARY 1, 1983 #
# #
# #
# COPYRIGHT APPLE COMPUTER,INC. 1980,1982 #
# #
# #
# ]10 PRINT "HELLO WORLD" #
# #
# ]LIST #
# #
# 10 PRINT "HELLO WORLD" #
# #
# ]RUN #
# HELLO WORLD #
# #
# ]_ #
# #
# #
############################################
2020-08-08 11:40:48 +00:00
Line:
2019-06-02 21:00:31 +00:00
```
### Keys
2019-11-20 23:13:53 +00:00
- Ctrl-F1: Reset button
2019-06-02 21:00:31 +00:00
- F5: Toggle speed between real and fastest
2019-11-20 23:13:53 +00:00
- Ctrl-F5: Show current speed in Mhz
2019-06-02 21:00:31 +00:00
- F6: Toggle between NTSC color TV and green phosphor monochrome monitor
2020-08-13 14:50:48 +00:00
- F7: Show the video mode and a split screen with the views for NTSC color TV, page 1, page 2 and extra info.
2020-08-08 11:44:45 +00:00
- F10: Cycle character generator code pages. Only if the character generator ROM has more than one 2Kb page.
2019-10-02 21:00:02 +00:00
- F11: Toggle on and off the trace to console of the CPU execution
2019-06-02 21:00:31 +00:00
- F12: Save a screen snapshot to a file `snapshot.png`
2020-04-02 21:05:21 +00:00
- Pause: Pause the emulation
2019-06-02 21:00:31 +00:00
Only valid on SDL mode
### Command line options
2020-08-10 18:52:17 +00:00
```terminal
2019-06-02 21:00:31 +00:00
-charRom string
2020-03-08 22:46:16 +00:00
rom file for the character generator (default "< default > ")
2019-06-02 21:00:31 +00:00
-disk string
2019-09-24 21:32:03 +00:00
file to load on the first disk drive (default "< internal > /dos33.dsk")
2019-06-02 21:00:31 +00:00
-disk2Slot int
2019-09-24 21:32:03 +00:00
slot for the disk driver. -1 for none. (default 6)
2020-08-11 21:53:05 +00:00
-disk35 string
file to load on the SmartPort disk (slot 5)
2019-06-02 21:00:31 +00:00
-diskRom string
2019-09-24 21:32:03 +00:00
rom file for the disk drive controller (default "< internal > /DISK2.rom")
2020-04-12 23:31:04 +00:00
-diskb string
2020-08-06 16:35:34 +00:00
file to load on the second disk drive
2019-06-02 21:00:31 +00:00
-dumpChars
2019-09-24 21:32:03 +00:00
shows the character map
2020-03-08 22:39:25 +00:00
-fastChipSlot int
2020-08-06 16:35:34 +00:00
slot for the FASTChip accelerator card, -1 for none (default 3)
2019-06-02 21:00:31 +00:00
-fastDisk
2019-09-24 21:32:03 +00:00
set fast mode when the disks are spinning (default true)
2019-10-02 21:39:39 +00:00
-hd string
2020-08-11 21:53:05 +00:00
file to load on the boot hard disk
2019-10-02 21:39:39 +00:00
-hdSlot int
slot for the hard drive if present. -1 for none. (default -1)
2019-06-02 21:00:31 +00:00
-languageCardSlot int
2019-09-24 21:32:03 +00:00
slot for the 16kb language card. -1 for none
2020-03-08 22:39:25 +00:00
-memoryExpSlot int
2020-08-12 20:50:40 +00:00
slot for the Memory Expansion card with 1GB. -1 for none (default 1)
2019-06-02 21:00:31 +00:00
-mhz float
2019-09-24 21:32:03 +00:00
cpu speed in Mhz, use 0 for full speed. Use F5 to toggle. (default 1.0227142857142857)
2019-10-20 22:06:28 +00:00
-model string
2019-11-08 22:56:54 +00:00
set base model. Models available 2plus, 2e, 2enh, base64a (default "2enh")
2019-06-02 21:00:31 +00:00
-mono
2019-09-24 21:32:03 +00:00
emulate a green phosphor monitor instead of a NTSC color TV. Use F6 to toggle.
2019-11-01 17:48:39 +00:00
-panicSS
2019-09-24 21:32:03 +00:00
panic if a not implemented softswitch is used
2019-10-19 18:31:18 +00:00
-profile
generate profile trace to analyse with pprof
2020-08-10 18:52:17 +00:00
-ramworks int
memory to use with RAMWorks card, 0 for no card, max is 16384 (default 8192)
2020-08-06 16:35:34 +00:00
-rgb
emulate the RGB modes of the 80col RGB card for DHGR (default true)
2019-06-02 21:00:31 +00:00
-rom string
2020-03-08 22:46:16 +00:00
main rom file (default "< default > ")
2019-06-02 21:00:31 +00:00
-saturnCardSlot int
2019-09-24 21:32:03 +00:00
slot for the 256kb Saturn card. -1 for none (default -1)
2019-09-28 11:37:42 +00:00
-thunderClockCardSlot int
2020-08-12 20:50:40 +00:00
slot for the ThunderClock Plus card. -1 for none (default 4)
2019-09-24 21:32:03 +00:00
-traceCpu
2019-10-02 21:39:39 +00:00
dump to the console the CPU execution. Use F11 to toggle.
2019-11-01 17:48:39 +00:00
-traceHD
2020-08-11 21:53:05 +00:00
dump to the console the hd/smartport commands
2020-06-07 16:23:39 +00:00
-traceMLI
2020-08-06 16:35:34 +00:00
dump to the console the calls to ProDOS machine language interface calls to $BF00
2019-09-24 21:32:03 +00:00
-traceSS
dump to the console the sofswitches calls
2019-11-11 22:28:07 +00:00
-vidHDSlot int
2020-08-06 16:35:34 +00:00
slot for the VidHD card, only for //e models. -1 for none (default 2)
2019-12-22 13:32:54 +00:00
-woz string
2020-08-06 16:35:34 +00:00
show WOZ file information
2019-11-11 22:28:07 +00:00
2019-09-24 21:32:03 +00:00
2019-06-02 21:00:31 +00:00
```
## Building from source
### apple2console
2019-06-15 12:01:10 +00:00
The only dependency is having a working Go installation on any platform.
2019-06-02 21:00:31 +00:00
Run:
2020-08-08 11:40:48 +00:00
2020-08-10 18:52:17 +00:00
``` terminal
2020-08-08 11:40:48 +00:00
go get github.com/ivanizag/apple2/apple2console
go build github.com/ivanizag/apple2/apple2console
2019-06-02 21:00:31 +00:00
```
### apple2sdl
2019-06-15 12:01:10 +00:00
Besides having a working Go installation, install the SDL2 developer files. Valid for any platform
2019-06-02 21:00:31 +00:00
Run:
2020-08-08 11:40:48 +00:00
2020-08-10 18:52:17 +00:00
``` terminal
2020-08-08 11:40:48 +00:00
go get github.com/ivanizag/apple2/apple2sdl
go build github.com/ivanizag/apple2/apple2sdl
2019-06-15 12:01:10 +00:00
```
2019-12-26 22:11:32 +00:00
### Use docker to cross compile for Linux and Windows
2019-06-15 12:01:10 +00:00
2019-12-26 22:11:32 +00:00
To create executables for Linux and Windows without installing Go, SDL2 or the Windows cross compilation toosl, run:
2020-08-08 11:40:48 +00:00
2020-08-10 18:52:17 +00:00
``` terminal
2020-08-08 11:40:48 +00:00
cd docker
./build.sh
2019-06-15 12:01:10 +00:00
```
2019-12-26 22:11:32 +00:00
To run in Windows, copy the file `SDL2.dll` on the same folder as `apple2sdl.exe` . The latest `SDL2.dll` can be found in the [Runtime binary for Windows 64-bit ](https://www.libsdl.org/download-2.0.php ).