/RetroAppleJS.github.io

A complete AppleII+ assembler debugger and emulator environment, browser-native JavaScript (serverless).

Primary LanguageJavaScriptMIT LicenseMIT

Apple II+ emulator, assebler & debugger in JavaScript

Unlike other emulation engines, RetroAppleJS wraps a complete AppleII+ IDE toolchain featuring an emulator, assembler, debugger, and reference manual bundled in one client-side JavaScript web application. Yes indeed, this project runs as-is, locally on any browser, no server required.

Back in 1980, a few young chaps like me were passionate about coding on the Apple II+. Machine coding was the way to get something done gracefully on the 6502, a low-cost & spec CPU originally designed for calculators. Before starting, several authors made this project possible, mainly as a tribute to the pioneers of home computing. Even for those unfamiliar with the Apple II, it is still a great platform to understand the foundations of computer hardware, operating systems, firmware, expansion architecture, and low-level software development. So, enjoy the beauty of 8-bit computing on a 6502 CPU, its math tricks, and deceivingly simple instruction set.

Install & Run

Getting started

  1. Inside the assembler, tap the 'generate' button
  2. Tap the 'to emulator' button
  3. Inside the emulator, tap the 'paste' button
  4. Type G6000 to run the code at address 6000h, that's it !


Other assembler listings can be found here: (https://github.com/RetroAppleJS/RetroAppleJS.github.io/tree/main/asm_code_examples), feel free to copy any of those in the left pane of the assembler and proceed the same way as described here above.

Vintage Lab

Explore our vintage computing laboratory, an exciting hub where all the components of our cutting-edge emulator are thoroughly tested and refined before being transformed into the retro-inspired recipes. Each of these components is a distinct project, meticulously crafted to allow you to delve into the complexities of our vast codebase in a fun and engaging way. Here, you can watch as we use a variety of techniques, including boiling, baking, smoking, and aging, to ensure that every component is primed and ready for use. Whether you're a developer looking to explore new codebases or a tech enthusiast interested in the history of computing,

Module overview

Emulator

The Apple II+ emulator is probably the most intuitive module, at least for those who were familiar using an Apple II. One can:

  1. use the pasteboard to paste any text through the text prompt (APPLESOFT BASIC LISTINGS, DOS COMMANDS, ASSEMBLY... anything) Just mind that a 1 MHz computer does not ingest many characters per second, so be patient.
  2. insert any disk found on the internet (.do, .dsk)

Assembler

The assembler contains handy tools to edit source-code originating from all over the internet, but purposefully avoids the implementation of any exotic macro language as this would perpetuate numerous assembler code compatibility problems. Once the code is generated, one can send the object code with one click to the debugger or the pasteboard of the emulator.

Debugger

The debugger is composed of 5 sections

  1. Disassembler
  2. Memory tracer
  3. CPU operations monitor
  4. CPU register
  5. Memory map
  6. Help screen

User manuals

EMULATOR.md
ASSEMBLER.md DEBUGGER.md
6502.md
ZEROPAGE_APPLE2PLUS.md
PERIPHERALS.md
TOOLS.md

Note that the markdown files here above must be compiled by a tool called Docs_updater.html, into a JavaScript file included in the main application, called COM_CONFIG.js located here. In short, do not manually update this JavaScript file.

Feature wish-list

  • EMULATOR: Step debugger (decommission or extend the current debugger ?)
  • EMULATOR: pasteboard macro scripting supporting keyboard/paddle/mouse recording, playback events and conditional stops
  • EMULATOR: popup tool with DEC-HEX-BIN-BASE64 converter, binary file converter and byte stream generator for Apple II pasteboard
  • EMULATOR: slot configurator & activity monitor + tool to operate soft-switches e.g. SPKR and hard-switches e.g. USER1 jumper manually
  • EMULATOR .NIB to .DSK converter DiskJS
  • EMULATOR: paddle/mouse capture
  • ASSEMBLER: Step Assembler completion (currently in alpha release)
  • ASSEMBLER: Disassembler to standard assembly listings
  • ASSEMBLER: Transpiler from 6502 assembler to JavaScript (followed by a JavaScript->6502 assembler transpiler)
  • ASSEMBLER: Extend pragma's (pick a few useful ideas from Merlin assembler)
  • ASSEMBLER: complete memory-map (incl. zero-page) documentation -> share memorymap data with assembler/disassembler to generate extra context
  • ASSEMBLER: better compatibility with listings from different Apple II assemblers (except virtual mnemonics)
  • RETRO LAB: realtime dithering in CameraJS
  • RETRO LAB: GPT completion
  • RETRO LAB: real-time camera capture tool - lo-res through software color-approximation (QuickCam emulation ? http://schmenk.is-a-geek.com/wordpress/?p=17)
  • RETRO LAB: lo-res and hi-res graphics conversion tool (including dithering and color optimization algorithms)
  • OTHER: better document assembler code located in asm_code_examples

Contribute

This project is build with HTML/JavaScript, CSS, Markdown documentation and 6502 assembler source code. Contributions in any of these fields are welcome, but the latest feature developments (here below) are currently the most valuable on my priority list.

Latest developments

interactive Apple II+ virtual keyboard

Currently developing the interactive Apple II+ pop-up keyboard from feature whish-list. feature details & status:

  • AppleII+ keyboard pop-up image (onmouseover)
  • alphanumeric keys + ESC key + arrow keys + space bar + RETURN key
  • POWER key
  • RESET key
  • REPT key
  • SHIFT keys
  • CTRL key

Also to be considered: detect if host device is mouse-driven or touch-driven. When touch-driven, hovering the keyboard is not possible without actioning a key.

Note: Only two files are impacted:

  • index.html
  • res/EMU_AP2keys.js

apple II peripherals emulation

Apple II wizards out there, anyone familiar with emulating any of these popular cards ? Recollecting ROM images from Apple II peripherals looks like a major challenge. Can anyone help ?