Apple-2-Tools/izapple2
1
0 Fork 0
mirror of https://github.com/ivanizag/izapple2.git synced 2026-10-22 00:02:27 +00:00
Code Issues Projects Releases Wiki Activity

A page per frontend

Browse Source 
The README listed only the SDL2 and the console frontends, and the build
instructions for all of them lived in the README. Now there is a Frontends
section with the eight of them, each linking to a page with how to build it,
how to use it and what it can not do.

The libretro pages take the frontend_ prefix as well. The feature list moves
to doc/features.md, leaving a summary in the README.

The default configuration was wrong in the two places it was written: it
listed a parallel card in slot 1 and a mouse in slot 4, which are empty and a
Mockingboard, and flags -disk35 and -hd that no longer exist. Both lists now
come from -showConfig.
This commit is contained in:
Iván Izaguirre authored and Iván Izaguirre committed 2026-08-10 00:14:11 +02:00
1 parent f268f2901f
commit 29c1762452
15 files changed
+754 -214
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

AGENTS.md
+4 -2
View File
@@ -31,7 +31,7 @@ cd frontend/a2wasm
go build .
# Build console frontend
cd frontend/a2console
cd frontend/console
go build .
# Build the libretro core, needs a C toolchain
@@ -220,7 +220,9 @@ The project uses GitHub Actions (`.github/workflows/go.yml`) and CircleCI (`.cir
## Additional Resources
- See `README.md` for user documentation and features
- See `README.md` for user documentation
- See `doc/features.md` for the complete feature list and the default configuration
- See `doc/command_line.md` for command-line options
- See `doc/frontend_*.md` for a page per frontend: how to build it, how to use it and what it does not do
- See `storage/WozSupportStatus.md` for WOZ format support details
- Reference implementation uses iz6502 CPU emulator: https://github.com/ivanizag/iz6502
README.md
+33 -196
View File
@@ -4,111 +4,12 @@ Portable emulator of an Apple II+ or //e. Written in Go.
## Features
- Models:
- 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 paged ROM
- Basis 108 clone (partial)
- Storage
- 16 Sector 5 1/4 diskettes. Uncompressed or compressed witth gzip or zip. Supported formats:
- NIB (read only)
- DSK
- PO
- [WOZ 1.0 or 2.0](storage/WozSupportStatus.md) (read only)
- 13 Sector 5 1/4 diskettes. Uncompressed or compressed witth gzip or zip. Supported formats:
- NIB (read only)
- [WOZ 2.0](storage/WozSupportStatus.md) (read only)
- 3.5 disks in PO or 2MG format
- Hard disk in HDV or 2MG format with ProDOS and SmartPort support
- Cassette tape input from WAV recordings
- Emulated extension cards:
- DiskII controller (state machine based for WOZ files)
- 16Kb Language Card
- 256Kb Saturn RAM
- Parallel Printer Interface card
- 1Mb Memory Expansion Card (slinky)
- RAMWorks style expansion Card (up to 16MB additional) (Apple //e only)
- ThunderClock Plus real time clock
- Apple //e 80 columns card with 64Kb extra RAM and optional RGB modes
- No Slot Clock based on the DS1216
- Videx Videoterm 80 column card with the Videx Soft Video Switch (Apple ][+ only)
- Videx Ultraterm 80 to 160 column card wuth integrated Video Switch
- SwyftCard (Apple //e only)
- Brain Board
- Brain Board II
- MultiROM card
- Dan ][ Controller card
- ProDOS ROM card
- Microsoft Z80 Softcard using the [Z80](https://github.com/koron-go/z80) emulation from Koron
- Mockinboard A sound card
- Useful cards not emulating a real card
- Bootable SmartPort / ProDOS card with the following smartport devices:
- Block device (hard disks)
- Fujinet network device (supports only http(s) with GET and JSON)
- Fujinet clock (not in Fujinet upstream)
- 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
- Mouse Card, emulates the entry points, not the softswitches.
- Host console card. Maps the host STDIN and STDOUT to PR# and IN#
- ROMXe, limited to font switching
izapple2 emulates the Apple ][+ and the Apple //e, enhanced or not, and the Base64A and Basis 108 clones.
See [doc/features.md](doc/features.md) for the complete list of features and supported cards and graphic modes.
- Graphic modes:
- Text 40 columns
- Text 80 columns Apple //e
- Text 80 columns Videx VideoTerm
- Text up to 160 columns and 48 lines Videx UltraTerm
- 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
- RGB card text 40 columns with 16 colors for foreground and background (mixable)
- RGB card mode 11, mono 560x192
- RGB card mode 12, ntsc 160*192
- RGB card mode 13, ntsc 140*192 (regular DHGR)
- RGB card mode 14, mix of modes 11 and 13 on the fly
- Displays:
- 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
- Debug mode: shows four panels with actual screen, page1, page2 and extra info dependant of the video mode
- Tracing capabilities:
- CPU execution disassembled
- Softswitch reads and writes
- ProDOS MLI calls
- Apple Pascal BIOS calls
- SmartPort commands
- BBC MOS calls when using [Applecorn](https://github.com/bobbimanners/)
- Other features:
- Sound
- Joystick support. Up to two joysticks or four paddles
- Mouse support. No mouse capture needed
- Adjustable speed
- Fast disk mode to set max speed while using the disks
- Save directory with `-saveDir`: what the software writes goes to an overlay file per disk, keeping the images untouched and making writable the disks loaded from a compressed file, an URL or the embedded resources
- Single file executable with embedded ROMs and DOS 3.3
- Pause (thanks a2geek)
- Passes the [A2AUDIT 1.06](https://github.com/zellyn/a2audit) tests as II+, //e, and //e Enhanced.
- Partial pass ot the [ProcessorTests](https://github.com/TomHarte/ProcessorTests) for 6502 and 65c02. Failing test 6502/v1/20_55_13; flags N anv V issues with ADC; and missing some undocumented 6502 opcodes.
## Installation
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 in aux slot
- Parallel print inteface in slot 1
- VidHD card (SHR support) in slot 2
- FASTChip Accelerator card in slot 3
- Mouse 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)
## Running the emulator
No installation required. [Download](https://github.com/ivanizag/izapple2/releases) the single file executable `izapple2xxx_xxx` for linux or Mac, SDL2 graphics or console. Build from source to get the latest features.
No installation required. [Download](https://github.com/ivanizag/izapple2/releases) the single file executable `izapple2` for Linux, Windows or Mac. It is the SDL2 frontend, see [Frontends](#frontends) for the others. Build from source to get the latest features.
Optionally, it can be installed with homebrew using:
@@ -116,17 +17,17 @@ Optionally, it can be installed with homebrew using:
brew install ivanizag/izapple2/izapple2
```
### Default mode
## Default mode
Execute without parameters to have an emulated Apple //e Enhanced with 128kb booting DOS 3.3 ready to run Applesoft:
Execute without parameters to have an emulated Apple //e Enhanced with 128kb booting DOS 3.3 ready to run Applesoft. The cards it comes with are in [the default configuration](doc/features.md#the-default-configuration):
``` terminal
casa@servidor:~$ ./izapple2sdl
casa@servidor:~$ ./izapple2
```
![DOS 3.3 started](doc/dos33.png)
### Play games
## Play games
Download a DSK or WOZ file or use an URL ([Asimov](https://www.apple.asimov.net/images/) is an excellent source):
@@ -136,7 +37,7 @@ casa@servidor:~$ ./izapple2 "https://www.apple.asimov.net/images/games/action/ka
![Karateka](doc/karateka.png)
### Play the Total Replay collection
## Play the Total Replay collection
Download the excellent [Total Replay](https://archive.org/details/TotalReplay) compilation by
[a2-4am](https://github.com/a2-4am/4cade):
@@ -149,60 +50,33 @@ Displays super hi-res box art as seen with the VidHD card.
![Total Replay](doc/totalreplay.png)
### Terminal mode
To run text mode right on the terminal without the SDL2 dependency, use `izapple2console`. It runs on the console using ANSI escape codes. Input is sent to the emulated Apple II one line at a time:
``` terminal
casa@servidor:~$ ./izapple2console -model 2plus
############################################
# #
# 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 #
# #
# ]_ #
# #
# #
############################################
Line:
```
### RetroArch and other libretro frontends
izapple2 can also be built as a libretro core, to run inside RetroArch, Lakka,
Batocera, RetroPie and the rest. On a Mac,
[doc/libretro_macos.md](doc/libretro_macos.md) walks through the whole thing
from installing RetroArch. See [doc/libretro.md](doc/libretro.md) for how
to build it, install it and what it supports.
### Command line options
## Command line options
See [doc/command_line.md](doc/command_line.md) for a complete guide on command line configuration.
## Frontends
The emulator itself is a Go library. What you run is one of the frontends in the `frontend` directory: they all build the same machine, take the same [command line options](doc/command_line.md) and load the same disks, but they differ in what they can show and in how you talk to them.
Each one has a page with how to build it, how to use it and what it can not do:
- [**a2sdl**](doc/frontend_sdl2.md): a window with SDL2. The complete one, and the one in the [releases](https://github.com/ivanizag/izapple2/releases) and in the Homebrew formula. Use this one unless you have a reason not to.
- [**a2sdl3**](doc/frontend_sdl3.md): the same, on SDL3. It needs neither cgo, nor a C compiler, nor SDL developer files, and it cross compiles to every platform from any of them. Experimental, not in the releases.
- [**console**](doc/frontend_console.md): text mode right on the terminal with ANSI escape codes, without the SDL2 dependency. Input goes in a line at a time.
- [**a2libretro**](doc/frontend_libretro.md): a libretro core, to run inside RetroArch, Lakka, Batocera, RetroPie and the rest. On a Mac, [doc/frontend_libretro_macos.md](doc/frontend_libretro_macos.md) walks through the whole thing from installing RetroArch.
- [**a2ebiten**](doc/frontend_ebiten.md): a window with [Ebitengine](https://ebitengine.org/). The same keys as a2sdl, no disks to drop and no joysticks. It is the desktop half of the WebAssembly frontend.
- [**a2wasm**](doc/frontend_wasm.md): the emulator in the browser, compiled to WebAssembly with a React interface around it.
- [**a2fyne**](doc/frontend_fyne.md): a window with [Fyne](https://fyne.io/), a toolbar and a panel listing the cards in the slots. No sound. Unfinished.
- [**headless**](doc/frontend_headless.md): no window and no screen, a command prompt to drive the machine and take snapshots. For scripting and for tests.
Additionally there is a derived project, [izapplebasic](https://github.com/ivanizag/izapplebasic), that adds a couple of frontends to a simplified Apple ][+ emulator with no cards and tape drive:
- CLI: with getline like support and command history.
- Telegram: Interactive use. Currently running at <https://t.me/a2basic_bot>
## Building from source
### Linux
Besides having a working Go installation, install the SDL2 developer files. Run:
Every frontend is a Go main package in its own directory. With a working Go installation, the build is always:
``` terminal
git clone github.com/ivanizag/izapple2
@@ -210,44 +84,7 @@ cd izapple2/frontend/a2sdl
go build .
```
### MacOS
That builds `a2sdl`, the SDL2 frontend, which needs a C compiler and the SDL2 developer files: `libsdl2-dev` on Linux, `brew install SDL2` on MacOS, [mingw-w64](http://mingw-w64.org/doku.php/download/mingw-builds) and the [SDL2 developer files](https://www.libsdl.org/release/) on Windows. See [doc/frontend_sdl2.md](doc/frontend_sdl2.md) for the details.
With a working Go installation, run:
``` terminal
brew install SDL2
git clone github.com/ivanizag/izapple2
cd izapple2/frontend/a2sdl
go build .
```
### Windows
On Windows, CGO needs a gcc compiler. Install [mingw-w64](http://mingw-w64.org/doku.php/download/mingw-builds) and the [SDL2 developer files](https://www.libsdl.org/release/) for mingw-64.
Run:
``` terminal
git clone github.com/ivanizag/izapple2
cd izapple2\frontend\a2sdl
go build .
```
To run in Windows, copy the file `SDL2.dll` on the same folder as `a2sdl.exe`. The latest `SDL2.dll` can be found in the [Runtime binary for Windows 64-bit](https://www.libsdl.org/download-2.0.php).
### The experimental SDL3 frontend
The `a2sdl3` frontend uses SDL3 through [go-sdl3](https://github.com/Zyko0/go-sdl3), which needs neither cgo nor a C compiler nor any SDL developer files. On Linux, MacOS and Windows alike, run:
``` terminal
git clone github.com/ivanizag/izapple2
cd izapple2/frontend/a2sdl3
go build .
```
As there is no cgo involved, it also cross compiles to any of the supported platforms, for example:
``` terminal
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build .
```
The other frontends replace `a2sdl` with their own directory and need other things, or nothing at all. Each page in [Frontends](#frontends) has its own instructions.
doc/command_line.md
+3 -3
View File
@@ -23,7 +23,7 @@ The emulator can be started with various command line options to customize the h
## Models
Models are pre-configured hardware setups that define the Apple II variant to emulate. Each model specifies the board type, CPU, ROM, default cards, and other hardware characteristics. It also load a default set of diskettes.
Models are pre-configured hardware setups that define the Apple II variant to emulate. Each model specifies the board type, CPU, ROM, default cards, and other hardware characteristics. It also loads a default set of diskettes.
### Available Models
@@ -111,7 +111,7 @@ The default model (`2enh`) configures slots as follows:
- **Slot 1:** Empty
- **Slot 2:** VidHD
- **Slot 3:** FastChip
- **Slot 4:** Empty
- **Slot 4:** Mockingboard
- **Slot 5:** Empty
- **Slot 6:** Disk II with DOS 3.3
- **Slot 7:** Empty
@@ -435,7 +435,7 @@ izapple2 boot.dsk -s7 smartport,image1="harddisk.po"
1. **Flags must come before positional arguments** in the command line
2. **Use quotes** around filenames with spaces: `-s6 "my disk.dsk"`
3. **Boolean flags** use `true`, `false` or nothing: `-showConfig=true` is the same as `-showConfig`
3. **Boolean flags** use `true`, `false` or nothing: `-showConfig=true` is the same as `-showConfig`
4. **View all options** with `izapple2 -h`
5. **Test configurations** with `-showConfig` to see the final setup without starting the emulator
doc/cpm65.md
+6 -5
View File
@@ -5,12 +5,13 @@ CPM-65 is a native port of Digital Research's seminal 1977 operating system CP/M
It runs on an Apple IIe with 80 columns.
To run use the preconfigured model `cpm65`.
Usefull commands:
Useful commands:
- `ìzapple -model cpm65` : To run the preconfigured setup
- `izapple apple2e.po`: To use the disk apple2e.po to run any release from [cpm65 releases](https://github.com/davidgiven/cpm65/releases/tag/dev)
- `ìzapple -model cpm65 -trace cpm65` : To trace the BDOS calls, skipping the console related calls
- `ìzapple -model cpm65 -trace cpm65full` : To trace all the BDOS calls.
- `izapple2 -model cpm65` : To run the preconfigured setup
- `izapple2 apple2e.po`: To use the disk apple2e.po to run any release from [cpm65 releases](https://github.com/davidgiven/cpm65/releases/tag/dev)
- `izapple2 -model cpm65 -trace cpm65` : To trace the BDOS calls, skipping the console related calls
- `izapple2 -model cpm65 -trace cpm65full` : To trace all the BDOS calls.
Todo:
- The address for the BIOS and BDOS entrypoints is hardwired. It should be extracted somehow from the running memory.
doc/features.md
+117
View File
@@ -0,0 +1,117 @@
# Features
- Models:
- 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 paged ROM
- Basis 108 clone (partial)
- Storage
- 16 Sector 5 1/4 diskettes. Uncompressed or compressed with gzip or zip. Supported formats:
- NIB (read only)
- DSK
- PO
- [WOZ 1.0 or 2.0](../storage/WozSupportStatus.md) (read only)
- 13 Sector 5 1/4 diskettes. Uncompressed or compressed with gzip or zip. Supported formats:
- NIB (read only)
- [WOZ 2.0](../storage/WozSupportStatus.md) (read only)
- 3.5 disks in PO or 2MG format
- Hard disk in HDV or 2MG format with ProDOS and SmartPort support
- Cassette tape input from WAV recordings
- Emulated extension cards:
- DiskII controller (state machine based for WOZ files)
- 16Kb Language Card
- 256Kb Saturn RAM
- Parallel Printer Interface card
- 1Mb Memory Expansion Card (slinky)
- RAMWorks style expansion Card (up to 16MB additional) (Apple //e only)
- ThunderClock Plus real time clock
- Apple //e 80 columns card with 64Kb extra RAM and optional RGB modes
- No Slot Clock based on the DS1216
- Videx Videoterm 80 column card with the Videx Soft Video Switch (Apple ][+ only)
- Videx Ultraterm 80 to 160 column card with integrated Video Switch
- SwyftCard (Apple //e only)
- Brain Board
- Brain Board II
- MultiROM card
- Dan ][ Controller card
- ProDOS ROM card
- Microsoft Z80 Softcard using the [Z80](https://github.com/koron-go/z80) emulation from Koron
- Mockingboard A sound card
- Useful cards not emulating a real card
- Bootable SmartPort / ProDOS card with the following smartport devices:
- Block device (hard disks)
- Fujinet network device (supports only http(s) with GET and JSON)
- Fujinet clock (not in Fujinet upstream)
- 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
- Mouse Card, emulates the entry points, not the softswitches.
- Host console card. Maps the host STDIN and STDOUT to PR# and IN#
- ROMXe, limited to font switching
- Graphic modes:
- Text 40 columns
- Text 80 columns Apple //e
- Text 80 columns Videx VideoTerm
- Text up to 160 columns and 48 lines Videx UltraTerm
- 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
- RGB card text 40 columns with 16 colors for foreground and background (mixable)
- RGB card mode 11, mono 560x192
- RGB card mode 12, ntsc 160*192
- RGB card mode 13, ntsc 140*192 (regular DHGR)
- RGB card mode 14, mix of modes 11 and 13 on the fly
- Displays:
- 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
- Debug mode: shows four panels with actual screen, page1, page2 and extra info dependent on the video mode
- Tracing capabilities:
- CPU execution disassembled
- Softswitch reads and writes
- ProDOS MLI calls
- Apple Pascal BIOS calls
- SmartPort commands
- BBC MOS calls when using [Applecorn](https://github.com/bobbimanners/)
- Other features:
- Sound
- Joystick support. Up to two joysticks or four paddles
- Mouse support. No mouse capture needed
- Adjustable speed
- Fast disk mode to set max speed while using the disks
- Save directory with `-saveDir`: what the software writes goes to an overlay file per disk, keeping the images untouched and making writable the disks loaded from a compressed file, an URL or the embedded resources
- Single file executable with embedded ROMs and DOS 3.3
- Pause (thanks a2geek)
- Passes the [A2AUDIT 1.06](https://github.com/zellyn/a2audit) tests as II+, //e, and //e Enhanced.
- Partial pass of the [ProcessorTests](https://github.com/TomHarte/ProcessorTests) for 6502 and 65c02. Failing test 6502/v1/20_55_13; flags N and V issues with ADC; and missing some undocumented 6502 opcodes.
## The default configuration
By default the following configuration is launched:
- Enhanced Apple //e with 65c02 processor
- RAMWorks card with 80 columns and 8Mb of RAM in the aux slot
- No Slot Clock on the main ROM
- Language card in slot 0
- VidHD card (SHR support) in slot 2
- FASTChip accelerator card in slot 3
- Mockingboard sound card in slot 4
- DiskII controller card with DOS 3.3 in slot 6
Slots 1, 5 and 7 are empty, and the RGB modes of the 80 columns card are added
with `-rgb`. Diskettes and hard disks named in the command line take the slots
they need: diskettes go to slot 6 and then slot 5, block devices to a SmartPort
card in slot 7 and then slot 5.
Run `izapple2 -showConfig` to see the configuration a command line ends up
with, without starting the machine.
Everything here is chosen with the [command line options](command_line.md), and
what each frontend can do with it is in its own page, listed in the
[README](../README.md#frontends).
doc/frontend_console.md
+71
View File
@@ -0,0 +1,71 @@
# The console frontend
`console` runs the emulator on the terminal. There is no window and no SDL2
dependency: the text screen of the Apple II is drawn in place with ANSI escape
codes, and what you type is sent to the machine a line at a time.
It is the frontend for a machine without a graphical session, or for a quick
run over ssh. Only the 40 column text screen exists here: there are no
graphics, no sound and no joysticks.
## Building
Nothing to install besides Go:
``` terminal
git clone github.com/ivanizag/izapple2
cd izapple2/frontend/console
go build .
```
## Running
The trick of redrawing the screen in place does not work with the Apple //e
ROM, so use one of the Apple ][ models:
``` terminal
casa@servidor:~$ ./console -model 2plus
############################################
# #
# 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 #
# #
# ]_ #
# #
# #
############################################
Line:
```
The rest of the [command line options](command_line.md) work as everywhere
else, so the diskettes, the cards and the tracing are the same.
Ctrl-C quits.
## Typing
The `Line:` at the bottom is the terminal reading a line. Nothing reaches the
Apple II until you press Enter, and then the whole line goes in at once. That
is fine for Applesoft and for the monitor, and it is no good for anything that
reads the keyboard while it runs, like a game or a full screen editor.
The screen is redrawn ten times a second, and only when something changed.
doc/frontend_ebiten.md
+53
View File
@@ -0,0 +1,53 @@
# The Ebitengine frontend
`a2ebiten` opens a window with [Ebitengine](https://ebitengine.org/). It has
the screen with all its modes, the sound and the same function keys as
[a2sdl](frontend_sdl2.md), and it is missing the things around them: no
diskettes dropped on the window, no joysticks and no mouse.
## Building
Ebitengine needs no SDL, and on Linux and MacOS it needs a C compiler and the
graphics developer files. See
[the Ebitengine install page](https://ebitengine.org/en/documents/install.html)
for the list of packages of your distribution. On Windows it needs nothing.
``` terminal
git clone github.com/ivanizag/izapple2
cd izapple2/frontend/a2ebiten
go build .
```
## Running
``` terminal
casa@servidor:~$ ./a2ebiten
```
The [command line options](command_line.md) are the same as everywhere else,
and the diskettes have to go in the command line: this frontend has no way to
insert one afterwards. Press F1 for the help.
## Keys
The same as [a2sdl](frontend_sdl2.md#keys), with two differences:
- Ctrl-F5 shows a readout with the speed of the emulated machine and the frame
rate on the corner of the screen, instead of printing the speed on the
terminal.
- There is no paste from the clipboard.
The help screen that F1 shows is the one of a2sdl and mentions dropping a file
on the window. That does not work here.
## What is missing
- **Diskettes dropped on the window.** They go in the command line.
- **Joysticks and paddles**, and the mouse as a joystick.
- **The mouse**, so the models that use it, like `desktop`, are not much use.
- **Pasting** from the clipboard.
The window is 564x384 and can be resized. The picture is generated at a fixed
1128x768 and scaled to the window, so the modes wider than 560 pixels, like the
Videx cards or the RGB card, are squeezed to fit instead of widening the
window.
doc/frontend_fyne.md
+89
View File
@@ -0,0 +1,89 @@
# The Fyne frontend
`a2fyne` opens a window with [Fyne](https://fyne.io/). Unlike the other
frontends with a window, it has a proper interface around the screen: a toolbar
with the controls, and a side panel listing the cards in the slots with what
each of them is doing.
It is missing the latest features. Not much more is done there.
## Building
Fyne needs a C compiler and the graphics developer files of the platform. See
[the Fyne prerequisites](https://docs.fyne.io/started/) for the list of
packages of your distribution.
``` terminal
git clone github.com/ivanizag/izapple2
cd izapple2/frontend/a2fyne
go build .
```
## Running
``` terminal
casa@servidor:~$ ./a2fyne
```
The [command line options](command_line.md) are the same as everywhere else,
and the diskettes have to go in the command line: there is no way to insert one
afterwards.
## The toolbar
From left to right:
- Reset.
- Pause and unpause.
- Full speed or normal speed.
- The screen mode: NTSC colour, plain or green, the current one shown greyed
out.
- Show or hide the four panels with the actual screen, page 1, page 2 and the
extra info of the video mode.
- Save the screen as `snapshot.png`. It says so with a notification of the
desktop.
- Force the keyboard to uppercase, for the software that expects a machine
without lowercase. The title goes uppercase while it is on.
- Full screen.
- Show or hide the panel with the devices.
## The devices panel
On the right, and hidden until the toolbar asks for it. It has the state of the
joysticks and then a card per slot, with the name of the card and whatever it
reports about itself: the diskette in each drive of a Disk II, the tracks it is
on, and so on for the rest.
## Keys
Fewer than in the other frontends, and not the same ones:
| Key | What it does |
| --- | --- |
| Ctrl-F1 | Reset |
| F5 | Print the current speed on the terminal |
| F6 | Next screen mode |
| F7 | Show or hide the four panels |
| F9 | Dump the state of the machine on the terminal |
| F10 | Next character set |
| F11 | Show or hide the CPU trace on the terminal |
| F12 | Save the screen as `snapshot.png` |
Ctrl and a letter reach the machine as the control character. The arrows,
Return, Escape, Backspace and Delete are mapped as usual. On the Base64A, F2 is
the Delete key of that keyboard.
There is no Pause key and no PrintScreen, use the toolbar. The Tab key never
arrives.
## What is missing
- **Sound.** Nothing is connected to the speaker here.
- **The mouse**, so the models that use it, like `desktop`, are not much use.
- **Diskettes dropped on the window**, and the toolbar button to insert one is
written but not enabled.
- **The character map** and the alternate text, which the other frontends show
with F10.
- **A help**, the F1 of the other frontends.
Joysticks do work, read through GLFW.
doc/frontend_headless.md
+72
View File
@@ -0,0 +1,72 @@
# The headless frontend
`headless` has no window and no screen. It builds the machine, leaves it
paused and gives you a prompt to drive it: run so many cycles, type something,
print the text screen, save a snapshot. It is the frontend for a script, for a
test, or for looking at what a machine does without watching it happen.
## Building
Nothing to install besides Go:
``` terminal
git clone github.com/ivanizag/izapple2
cd izapple2/frontend/headless
go build .
```
## Running
``` terminal
casa@servidor:~$ ./headless
* run 40000
* text
* type 10 PRINT "HELLO WORLD"
* enter
* run 100
* text
* quit
```
The machine is built with the [command line options](command_line.md) like
everywhere else, and starts paused. Nothing happens until you say `start` or
`run`.
## Commands
| Command | What it does |
| --- | --- |
| `help` | Prints the list of commands |
| `quit` | Quits |
| `start` | Runs the machine at its normal speed, and returns to the prompt while it runs |
| `pause` | Stops it |
| `run <cycles>` | Runs `<cycles>` thousand cycles at full speed and waits until they are done. Only while paused |
| `cycle` | Prints the cycle count |
| `reset` | Resets the machine |
| `key <number>` | Queues a key, as a decimal number from 0 to 127 |
| `type <text>` | Queues the characters of `<text>`. No quotes, it can have spaces |
| `enter` | Queues the Return key. The same as `key 13` |
| `clearkeys` | Empties the key queue |
| `text` | Prints the text screen on the terminal |
| `png` | Saves the screen as `snapshot.png` in NTSC colour |
| `pngm` | The same in monochrome |
| `gif` | Records one second of the screen to `snapshot.gif`, 20 frames of 5 hundredths |
The keys are queued, not typed: they are handed to the machine as it asks for
them, so a `type` before a `run` is a fine way to feed a program that is not
running yet.
`run` is the useful one for a script. It asks for full speed, sets a breakpoint
that many cycles ahead and waits, so a DOS 3.3 boot is over in a moment and the
prompt comes back exactly when it is done. A boot from a diskette spends some
37 million cycles, mostly waiting for the drive, so `run 40000` covers it.
The `help` the program prints is ahead of what it does in a few places: there
is no `stop` (it is `pause`) and no `gifm`, and `png`, `pngm` and `gif` take no
arguments, they always write `snapshot.png` and `snapshot.gif`.
## What is missing
There is nothing to insert a diskette while it runs, and nothing to move the
joysticks or press their buttons. Both have to come from the command line, or
not at all.
doc/libretro.md → doc/frontend_libretro.md
+5 -5
View File
@@ -9,10 +9,10 @@ The core is not part of the [releases](https://github.com/ivanizag/izapple2/rele
you have to build it from source. It is a small build, the instructions are below.
If you just want to run Apple II software on your computer, the regular
`izapple2sdl` executable is easier and does more. Use the core if you already
`izapple2` executable is easier and does more. Use the core if you already
live in RetroArch.
On a Mac, [libretro_macos.md](libretro_macos.md) is the whole thing end to end,
On a Mac, [frontend_libretro_macos.md](frontend_libretro_macos.md) is the whole thing end to end,
from installing RetroArch to checking that it works. Follow that instead, there
are two traps on macOS that it walks you around.
@@ -46,7 +46,7 @@ A frontend can only load a core of its own architecture, and the frontend has to
be running natively: a Go core cannot run inside a frontend translated by
Rosetta, whichever slice it loads. On macOS that rules out the `retroarch` cask
of Homebrew, which is an Intel build. See
[libretro_macos.md](libretro_macos.md).
[frontend_libretro_macos.md](frontend_libretro_macos.md).
### Windows
@@ -289,7 +289,7 @@ centered.
## What is not supported
The core is deliberately smaller than the other frontends. If you need any of
this, use `izapple2sdl`.
this, use `izapple2`.
- **Super hi-res graphics.** The VidHD card is removed from the machine, so the
box art of the [Total Replay](https://archive.org/details/TotalReplay)
@@ -340,7 +340,7 @@ or cross compile with the right `CC`, `GOOS` and `GOARCH`.
`runtime.(*mheap).allocNeedsZero`. The frontend is being translated, Rosetta on
a Mac, and the Go runtime of the core cannot allocate in a process like that. A
core for both architectures does not help, the frontend itself has to run
natively. See [libretro_macos.md](libretro_macos.md).
natively. See [frontend_libretro_macos.md](frontend_libretro_macos.md).
**Some keys do nothing, or `p` pauses the emulator.** Those are hotkeys of the
frontend, turn on Game Focus, see [Keyboard](#keyboard).
doc/libretro_macos.md → doc/frontend_libretro_macos.md
+1 -1
View File
@@ -1,7 +1,7 @@
# Running the libretro core on a Mac
From nothing to the core running in RetroArch, with the checks worth doing on
the way. See [libretro.md](libretro.md) for what the core is and what it
the way. See [frontend_libretro.md](frontend_libretro.md) for what the core is and what it
supports.
## 1. Install RetroArch
doc/frontend_sdl2.md
+136
View File
@@ -0,0 +1,136 @@
# The SDL2 frontend
`a2sdl` is the complete frontend, the one the
[releases](https://github.com/ivanizag/izapple2/releases) and the Homebrew
formula contain. It opens a window with SDL2 and gives you everything the
emulator has: the screen with all its modes, sound, joysticks, the mouse,
diskettes dropped on the window and the whole set of function keys.
Use this one unless you have a reason not to. The reason is usually SDL2
itself, which needs a C compiler and its developer files to build: if that is
in the way, [a2sdl3](frontend_sdl3.md) is the same frontend without any of it.
## Building
Besides a working Go installation you need a C compiler and the SDL2 developer
files.
### Linux
``` terminal
sudo apt-get install libsdl2-dev
git clone github.com/ivanizag/izapple2
cd izapple2/frontend/a2sdl
go build .
```
### MacOS
``` terminal
brew install SDL2
git clone github.com/ivanizag/izapple2
cd izapple2/frontend/a2sdl
go build .
```
### Windows
CGO needs a gcc compiler. Install
[mingw-w64](http://mingw-w64.org/doku.php/download/mingw-builds) and the
[SDL2 developer files](https://www.libsdl.org/release/) for mingw-64, and run:
``` terminal
git clone github.com/ivanizag/izapple2
cd izapple2\frontend\a2sdl
go build .
```
To run it, copy `SDL2.dll` to the same folder as `a2sdl.exe`. The latest one is
in the [Runtime binary for Windows 64-bit](https://www.libsdl.org/download-2.0.php).
### A single file executable
The released binaries are built with SDL2 linked statically, so that they run
on a machine without SDL2 installed:
``` terminal
go build -tags static -ldflags "-s -w" -o izapple2 .
```
That is what the release workflow does, see [release.md](release.md).
## Running
``` terminal
casa@servidor:~$ ./a2sdl
```
Without arguments you get the default machine, an enhanced Apple //e booting
DOS 3.3. A file on the command line is loaded in the right place by its
extension, and everything else is set with the
[command line options](command_line.md):
``` terminal
casa@servidor:~$ ./a2sdl "https://www.apple.asimov.net/images/games/action/karateka/karateka (includes intro).dsk"
casa@servidor:~$ ./a2sdl -model 2plus Total\ Replay\ v6.0.1.hdv
```
The window is resizable and the picture follows it. Press F1 for the list of
keys without leaving the emulator.
## Keys
The Apple II keyboard is where you expect it, with the arrows, Tab, Delete and
Escape mapped to what the Apple II understands. The rest:
| Key | What it does |
| --- | --- |
| F1 | Show or hide the help |
| Ctrl-F2 | Reset. F2 alone also resets while the help is shown, for the window managers that eat Ctrl-F2 |
| F4 | Show or hide the CPU trace on the terminal |
| F5 | Full speed or normal speed |
| Ctrl-F5 | Print the current speed on the terminal |
| F6 | Next screen mode: NTSC colour, plain, green, with or without scan lines |
| F7 | Show or hide the four panels with the actual screen, page 1, page 2 and the extra info of the video mode |
| F9 | Dump the state of the machine on the terminal |
| F10 | Next character set |
| Ctrl-F10 | Show or hide the character map |
| Shift-F10 | Show or hide the alternate text of the character map |
| F12 or PrintScreen | Save the screen as `snapshot.png` |
| Pause | Pause and unpause the emulation |
| Left alt or option | Open-Apple |
| Right alt or option | Closed-Apple |
| Shift-Insert, Cmd-V | Paste the clipboard, typed in slowly so that the machine keeps up |
On the Base64A, F3 is the Delete key of that keyboard.
The title bar says which machine is running and shows `PAUSED!` while it is
paused. With the four panels or the character map on screen it shows what is
being displayed instead.
## Diskettes
Drop a file on the window to insert it: on the left half it goes to drive 1, on
the right half to drive 2. It works with everything that goes on the command
line, including compressed images.
Whatever the emulated software writes goes back to the file it came from. To
keep the images untouched use `-saveDir`, which puts the writes in an overlay
file per disk and makes writable even the disks loaded from an URL, a
compressed file or the embedded resources.
## Joysticks and mouse
Joysticks connected to the host are used as the Apple II joysticks, up to two
of them or four paddles. If the machine has no mouse card, the host mouse acts
as a joystick too.
The mouse card needs no capture: the pointer of the host is the pointer of the
Apple II, wherever it is on the window.
## Sound
The speaker and the sound cards, like the Mockingboard, are mixed and sent to
the SDL2 audio device. At full speed the sound gets choppy, which is what
happens when the machine that generates it runs faster than the sound it
generates.
doc/frontend_sdl3.md
+65
View File
@@ -0,0 +1,65 @@
# The SDL3 frontend
`a2sdl3` is [a2sdl](frontend_sdl2.md) on SDL3. It does the same things, with the
same keys, the same diskettes dropped on the window and the same joysticks. The
difference is in what it takes to build it: it uses SDL3 through
[go-sdl3](https://github.com/Zyko0/go-sdl3), which needs neither cgo, nor a C
compiler, nor SDL developer files. SDL3 itself travels inside the binary, and
is extracted to a temporary directory while the emulator runs.
It is experimental and it is not in the
[releases](https://github.com/ivanizag/izapple2/releases), which stay on SDL2.
## Building
On Linux, MacOS and Windows alike, with nothing installed but Go:
``` terminal
git clone github.com/ivanizag/izapple2
cd izapple2/frontend/a2sdl3
go build .
```
As there is no cgo involved it also cross compiles, so a single machine can
build for all of them:
``` terminal
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build .
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build .
```
The resulting binary carries the SDL3 library for the target platform, so there
is no DLL to copy next to it.
## Running
``` terminal
casa@servidor:~$ ./a2sdl3
```
The same command line as every other frontend, see
[command_line.md](command_line.md). Press F1 for the help.
## Keys
The same as [a2sdl](frontend_sdl2.md#keys), including the paste with
Shift-Insert or Cmd-V and the Open-Apple and Closed-Apple on the alt or option
keys.
The Apple keys are found by scancode instead of by keycode. On the keyboard
layouts where the right alt is AltGr, SDL3 does not report it as an alt key,
and the Closed-Apple would never be pressed if it were looked up by keycode.
## What is different from SDL2
Nothing that you use, and a few things underneath:
- SDL3 reports where a file was dropped, so the drive it goes to is the one
under the pointer. In SDL2 it is worked out from the last known mouse
position.
- Losing the window focus releases the joystick keys, so an Open-Apple held
while switching windows does not stay pressed.
- Ctrl-C on the terminal quits the same way as closing the window, releasing
everything on the way out.
- The scaling of the picture is a property of the renderer instead of the
global hint SDL2 uses.
doc/frontend_wasm.md
+97
View File
@@ -0,0 +1,97 @@
# The WebAssembly frontend
`a2wasm` is the emulator compiled to WebAssembly, running in the browser. The
machine and the screen are the Go code of [a2ebiten](frontend_ebiten.md) built
for `js/wasm`, and around it there is a React interface with the controls and
the disk drives.
There is nothing to install for whoever opens the page, and there is a fair
amount to build: it is the only frontend that needs Node besides Go.
## Building
You need Go and Node 18 or newer.
``` terminal
git clone github.com/ivanizag/izapple2
cd izapple2/frontend/a2wasm
npm install
npm run build
```
`npm run build` compiles the Go code to WebAssembly, type checks the React
code and puts everything in `dist`, which is a static site that any web server
can serve. To build only the WebAssembly part, run `./build-wasm.sh`: it leaves
`izapple2.wasm`, its gzipped copy and the `wasm_exec.js` of your Go
installation in `public/wasm`.
The binary is around 26 MB, 7 MB gzipped, so serve it compressed.
## Running it while working on it
``` terminal
casa@servidor:~$ npm run dev
```
Then open <http://localhost:5173>. Vite reloads the page when the React code
changes; a change in the Go code needs `./build-wasm.sh` and a refresh.
## Serving it
`dist` is a static site, with two things to get right in the server:
- `.wasm` files have to be served as `application/wasm`.
- The page asks for `Cross-Origin-Embedder-Policy: require-corp` and
`Cross-Origin-Opener-Policy: same-origin`, which Vite sets by itself while
developing.
## Using it
The machine boots by itself when the page loads. The toolbar on top has pause
and resume, reset, a screenshot that downloads a PNG, and the screen mode: NTSC
colour, plain or green. The bar at the bottom shows the speed in MHz.
The keyboard goes to the emulator once you click on the screen. There are no
joysticks and no mouse.
To insert a diskette, use the file picker of a drive or drop the file on the
disk panel: the first one goes to drive 1 and the second to drive 2. There is
also a button to load DOS 3.3 from the resources embedded in the binary. The
formats are the same as in the other frontends, compressed ones included.
## Driving it from JavaScript
The Go code exports `window.wasmAPI`, which is what the React interface uses
and is there for whatever else you want to do with it:
``` javascript
wasmAPI.reset()
wasmAPI.pause()
wasmAPI.resume()
wasmAPI.isPaused()
wasmAPI.getFrequency()
wasmAPI.setScreenMode("ntsc") // "ntsc", "plain" or "green"
wasmAPI.screenshot()
wasmAPI.sendKey(13)
wasmAPI.sendText("10 PRINT \"HELLO\"\n")
wasmAPI.loadDisk(1, bytes, "game.dsk")
wasmAPI.loadDiskFromURL(1, "https://example.com/game.dsk")
wasmAPI.loadDiskFromURL(1, "<internal>/dos33.dsk")
```
An URL is fetched by the browser, so it has to allow it with CORS.
## What is missing
- **Command line options.** The machine is the default one and there is no way
to choose a model or to configure the slots yet.
- **Joysticks and mouse.**
- **Sound in some browsers** until you click on the page: they do not start
audio before the visitor asks for something.
- **State that survives a refresh.** Reloading the page starts a new machine.
- **`getDiskInfo`**, which is in the API and always answers null, so the drives
do not show what is in them.
The notes on how it is put together, the file layout and the deployment
recipes are in
[frontend/a2wasm/README.md](../frontend/a2wasm/README.md).
frontend/a2libretro/README.md
+2 -2
View File
@@ -3,8 +3,8 @@
A [libretro](https://www.libretro.com/) core, to run izapple2 inside RetroArch
and the other libretro frontends.
**If you want to use the core, read [doc/libretro.md](../../doc/libretro.md)**,
or [doc/libretro_macos.md](../../doc/libretro_macos.md) on a Mac,
**If you want to use the core, read [doc/frontend_libretro.md](../../doc/frontend_libretro.md)**,
or [doc/frontend_libretro_macos.md](../../doc/frontend_libretro_macos.md) on a Mac,
which covers building it for each platform, installing it in the frontends,
loading disks, the controls and what it supports. What follows are the notes on
how it is put together.