# Appler - The Apple II Emulator for MS-DOS ## What's an Appler? ![Apple II with dual disk drive and display](https://cdn-learn.adafruit.com/assets/assets/000/120/011/medium800/hacks_Apple_II-IMG_7064.jpg?1680290048 Apple II image from Musée Bolo) Hop in your DeLorean and head back to 1990, just a short 33 years ago... Thanks to the availability of cheaper clones and business software like Lotus 1-2-3, the IBM PC had taken over the computing market, claiming 84% market share. The Apple II had enjoyed a loyal following since its release in 1977, but for most of its life it had been outsold by other systems from Atari, Commodore, and later on the Macintosh. The IIe and IIgs were still being sold in 1990 and would continue until 1993, but the PC was here to stay. ![IBM PC with display and Model F keyboard](https://cdn-learn.adafruit.com/assets/assets/000/120/012/medium800/hacks_1024px-IBM_PC-IMG_7271.png?1680290132 IBM PC image from Musée Bolo) You've got a great new PC, but what do you do with your favorite Apple II software? Two hackers in Bulgaria, Alexander Patalenski and Emil Dotchevski, wrote an emulator to solve that problem. These days a multi-core, multi-GHz CPU barely notices that it's emulating a 1 MHz 6502, but an 8088 needed to work pretty hard (and your code needed to be clever) to make things feel smooth. Appler is written in 8088 assembly so it's as fast as possible, and it's probably still the fastest Apple II emulator. Appler also supports HGR - the high resolution graphics mode of the Apple II. By high resolution, I mean a staggering 280x192 pixels. It doesn't seem like much, but 40 years ago that was pretty impressive! The authors didn't have access to an actual Apple II color monitor, their Bulgarian clone systems only had a monochrome green display. But they knew what the colors should be, and using resistor values from the schematic calculated the values to use in their code. ![](https://cdn-learn.adafruit.com/assets/assets/000/120/048/medium800/hacks_appler09.png?1680531195 High res!) What can we do with an emulator from decades ago? More than you'd think! Of course we can run old software and play games, but Appler also has nice tools for dealing with memory and debugging, making it great if you want to get into 6502 assembly programming. Let's set it up and see what it can do! # Appler - The Apple II Emulator for MS-DOS ## Installation and Setup Appler runs on DOS, so first we need DOSBox. Yes, we're going to emulate while we emulate. If you already have DOSBox set up you can skip this part. Get it from [www.dosbox.com](https://www.dosbox.com). It runs on pretty much everything - Solaris? Sure! OS/2? Of course. BeOS?! Why not? I'll be installing it on a Mac but the procedure is similar on other systems. Download the DMG and extract it anywhere you like, I put mine in **~/DOSBox**. You'll also need a folder for the C drive and all of your programs, I made a folder called **~/DOSBox/CDrive**. Run DOSBox for the first time and you'll arrive at a Z:\\> prompt. We want to automate a few things, so type EXIT and press enter to quit. Now open **~/Library/Preferences/DOSBox 0.74-3-3 Preferences** with your favorite editor. This file will live in different places on different systems - on Windows you can find it under Config in the DOSBox folder on the Start menu. On Linux it's the conf file in **~/.dosbox**. At the bottom of the file is an [autoexec] section. Commands placed here will be run when DOSBox starts, so we can mount drives, add devices, etc. For now we just need our C drive, so add this: `MOUNT C ~/DOSBox/CDrive` `C:` In other operating systems use the appropriate **CDrive** path instead. You can also take a look at the other settings, but defaults will work fine for us. Now get Appler from the GitHub page: [https://github.com/zajo/appler](https://github.com/zajo/appler) Click Code and then Download Zip. Extract that and copy the **bin** folder to your DOSBox **CDrive** folder. Rename it to Appler. Things should look like this when you run DOSBox: ![](https://cdn-learn.adafruit.com/assets/assets/000/119/945/medium800/hacks_appler02.png?1680180608) Type in Appler and press enter. Press enter at the Appler screen and enjoy the demo! ![](https://cdn-learn.adafruit.com/assets/assets/000/119/915/medium800/hacks_appler03.png?1680099381) The demo then launches Lode Runner, which you can have fun playing if you like. Read on to learn how to use the various tools available and how to load more software. # Appler - The Apple II Emulator for MS-DOS ## Running Appler has many built-in features accessed via function keys. **F1** brings up the debugger, which is extremely handy if you're into 6502 assembly or want to get into it. It shows your currently running program code, the CPU registers, the stack, and memory. To navigate to different sections press Alt plus the highlighted letter, e.g. Alt+R will switch focus to the Registers. The options along the bottom of the screen are accessed via the corresponding function keys. The Apple option will return you to the emulator, and is always the same as the key that brought you here, so for the debugger it's **F1** , in the file manager it's **F2** , etc. ![](https://cdn-learn.adafruit.com/assets/assets/000/119/946/medium800/hacks_appler04.png?1680181067) Pressing  **F2** brings you to the file manager, which lets you load and save pieces of memory. Want to save exactly where you are in a game? This will save the whole state of the machine! We'll get back to it in a bit. **F3** brings you to the disk manager, which lets you load a virtual floppy disk in either of the two available drives. You can find software all over, check out [this ftp mirror](https://mirrors.apple2.org.za/ftp.apple.asimov.net/images/) or [apple2online](https://apple2online.com/) for a huge selection. Keep in mind that there are many different disk file formats and software was written in some cases for a specific model of Apple II, so some won't work in Appler. Let's play something! I'll start out with Zork - a classic text adventure that you should definitely play if you haven't already. Find the game on the apple2online site above - it comes with three disk files. DOSBox likes DOS filenames and Appler wants a .DSK extension, so put them in your Appler folder and rename them appropriately - ZORK1.DSK, ZORK2.DSK, ZORK3.DSK. Launch DOSBox, then run Appler and push F3 to use the Disk Manager. On the right you can see the available disks. Drive 1 is highlighted, so push F2 to remove the current disk from the drive. Press the up and down arrow keys to navigate to the disk image, then press F2 to insert a virtual floppy disk. It should end up looking like this: ![](https://cdn-learn.adafruit.com/assets/assets/000/120/000/medium800/hacks_appler08.png?1680273181) Press F1 to reboot the Apple II and load the game! ![](https://cdn-learn.adafruit.com/assets/assets/000/120/001/medium800/hacks_appler06.png?1680273279) Don't get eaten by a grue! Here are all of the commands for the emulator: - F1 - Debugger - F2 - File Manager - F3 - Disk Manager - F4 - Keyboard setup - F9 - About - F10 - Help - Alt+Esc - Run a DOS shell, type EXIT to get back to Appler - Alt+X - Quit Continue reading to see how we can save the memory state and effectively save the game. # Appler - The Apple II Emulator for MS-DOS ## Saving State So you'd rather not leave the emulator running all the time and you're sick of getting that leaflet from the mailbox every time. Let's see how you can use the file manager to save the state of the machine. At a suitable point in your game, press F2 to enter the File Manager. Keep in mind that we're dealing directly with memory now, we're not loading any disk images. These files are direct copies of the RAM contents. In order to save the state of the machine, navigate to the memory section by pressing Alt+M. Press the down arrow to select New File, then press enter. Type a short filename (remember, we're in DOS - 8 characters or less!) with no extension. Appler will save a status file (.SVD). I saved mine after opening the mailbox and taking the leaflet in Zork. ![](https://cdn-learn.adafruit.com/assets/assets/000/120/002/medium800/hacks_file01.png?1680274232) Press F2 to return to the game. Let's assume you continue on and want to reload this saved state in the same session. Press F2 to access the File Manager - things will look nearly the same but you should see your saved state on the right in the directory listing. Navigate there with Alt+D, select your save file, then press F3 to load it into memory. You should see a **Status restored** message at the bottom left. ![](https://cdn-learn.adafruit.com/assets/assets/000/120/003/medium800/hacks_file02.png?1680274558) Press F2 to return to the game - presto! You just loaded the previous state and returned to your saved game. ![](https://cdn-learn.adafruit.com/assets/assets/000/120/004/medium800/hacks_file03.png?1680275184) Now I don't need to get that leaflet again! Warning: You can also use the File Manager to load and save binary files. If you download a .APL file, load and run it by highlighting it in the File Manager and pressing F1. The [Appler GitHub page](https://github.com/zajo/appler#file-manager) also shows how you can save a binary after loading it. # Appler - The Apple II Emulator for MS-DOS ## Further Reading You can look at the source code for Appler and read all about the history of it on GitHub: [https://github.com/zajo/appler](https://github.com/zajo/appler)   Now try writing some code for the Apple II! - Write in [BASIC](https://www.howtogeek.com/659450/how-to-write-an-apple-ii-basic-program-in-your-web-browser/) - Or try assembly! - [Easy 6502](https://skilldrick.github.io/easy6502/) - tutorial for learning 6502 assembly - [6502.org](http://www.6502.org/tutorials/) - huge resource for 6502 programming And of course, [archive.org](https://archive.org) has a huge library of Apple II books, software, and other goodies. Just search for "Apple II" and see what you can find.   Apple II Software: - [https://mirrors.apple2.org.za/ftp.apple.asimov.net/images/](https://mirrors.apple2.org.za/ftp.apple.asimov.net/images/) - [https://apple2online.com](https://apple2online.com)   [DOSBox](https://www.dosbox.com) - Don't forget, now that you have DOSBox you can run all kinds of old DOS software.   ## Related Guides - [Ikea Vindriktning Hack with QT Py ESP32-S3 and Adafruit IO](https://learn.adafruit.com/ikea-vindriktning-hack-with-qt-py-esp32-s3-and-adafruit-io.md) - [Adafruit Feather RP2040 with USB Type A Host](https://learn.adafruit.com/adafruit-feather-rp2040-with-usb-type-a-host.md) - [USB C CC Resistor Fixer Case](https://learn.adafruit.com/resistor-fixer-case.md) - [Circuit Playground Minecraft Gesture Controller](https://learn.adafruit.com/circuitplayground-minecraft-gesture-controller.md) - [Custom HID Devices in CircuitPython](https://learn.adafruit.com/custom-hid-devices-in-circuitpython.md) - [DIY Camera Monitor](https://learn.adafruit.com/diy-camera-monitor.md) - [Neo Trinkey Auto Screen Locker](https://learn.adafruit.com/neo-trinkey-auto-screen-locker.md) - [Colorful Creations with the New JLCPCB PCB Service](https://learn.adafruit.com/colorful-creations-with-the-new-jlcpcb-pcb-service.md) - [LED Matrix Wall Arcade for Pico-8](https://learn.adafruit.com/led-matrix-wall-arcade.md) - [Running OpenGL-based Games & Emulators on Adafruit PiTFT Displays](https://learn.adafruit.com/running-opengl-based-games-and-emulators-on-adafruit-pitft-displays.md) - [Feather RP2040 DVI Video Synth](https://learn.adafruit.com/feather-rp2040-dvi-video-synth.md) - [Firework Ignitor](https://learn.adafruit.com/electric-ignitor.md) - [Retro Gaming with Raspberry Pi](https://learn.adafruit.com/retro-gaming-with-raspberry-pi.md) - [PiGRRL 2](https://learn.adafruit.com/pigrrl-2.md) - [How to Hack NES ROMs to Add Your Own Sprites](https://learn.adafruit.com/how-to-hack-roms-to-add-your-own-sprites.md)