Created by Chris Torrence (chris<at>ct6502<dot>org), with significant contributions from Michael Morrison (codebythepound<at>gmail<dot>com). Thanks also to the Apple II community for feedback, bug reports, and feature requests.
This project was originally create using Create React App and was then migrated to vite following these steps.
Be sure to install node.js
and npm
on your system using either nvm
(the Node version manager) or the Node installer. Either one should work fine.
In the project directory, to run the app in development mode:
npm install
npm start
This should automatically open your browser to http://localhost:6502.
The page will reload when you make changes. You may also see any lint errors in the console.
You can append parameters to the URL (to control say the emulator speed or the starting disk image) by using the following syntax:
npm start --urlparam=<parameters>
For example:
npm start --urlparam=speed=fast#Replay
This will start the emulator in fast mode and load the Total Replay disk image.
Runs all of the jest unit tests:
npm test
Run a single test:
npm test memory.test.ts
Run in watch mode:
npm test -- --watch
To builds the app for production:
npm install
npm run build
This will create the build in the dist
folder.
It correctly bundles React in production mode and optimizes the build for best performance. The build is minified and the filenames include hash values. These hashes force the browser to reload when the file content changes, ensure that the filenames are unique, and also verify the integrity of the file.
There should be no errors generated. If you see errors, be sure to check that your version of node and npm are up to date. If there are still errors, contact the author.
Note: This project uses Github Pages to host the emulator. You should not need to build the package, except to confirm that the build will work correctly when changes are committed.
When you check in code changes to Github, Github will automatically run one of two workflows. The main-build-deploy.yml
workflow will run for code checked into the main branch, while pull-request-build-only.yml
will run for pull requests. The main-build-deploy.yml
workflow should fire off two Github Actions. The first will build and test the code, while the second (using npm run deploy
) will deploy the build to Github Pages.
For the Github Actions, the secrets.GH_SECRET needs to be set to your current Personal Access Token. This needs to be regenerated each year. To do this, go under your main profile, choose Developer Settings -> Personal access tokens -> Fine-grained tokens, choose "gp-pages deploy". Choose an expiration date for one year in the future. Copy the new PAT and save it somewhere safe. Once you have the new Github PAT, you can set it on the repo. Under Settings, choose "Secrets and variables" -> "Actions", then click Edit on the GH_SECRET.
https://www.hostingadvice.com/how-to/update-npm-packages/
npm install -g npm-check-updates
npm outdated
ncu --upgrade
npm install
The launch.json
file contains the debug configurations and should not need to be modified.
To debug the emulator, open the Run/Debug panel and click the "Launch Chrome" play button. Or simply press the F5
key.
Any debug output or console.log messages should appear in the Debug Console. You should also be able to set breakpoints in the code, examine variable values, and execute simple JavaScript statements in the Debug Console.
Using Android Studio, create a new device (like a phone), start the device.
Start the emulator with npm run host
to make the application available to the network. You must do this - you cannot run on localhost:6502
or 10.0.2.2:6502
on Android (it's some conflict with vite and chrome).
Navigate to the provided URL - it will be something like 10.0.0.xxx:6502
.
On your Desktop Chrome, go to chrome://inspect/#devices
and then choose the appropriate "Remote Target".
https://developer.apple.com/documentation/safari-developer-tools/inspecting-ios
In VS Code, add breakpoints to the test code. Then open up package.json
, hover over
the "test" script, and select 'Debug Script'.
- Press Boot then Reset, type some characters, click on File save button, verify
apple2ts.a2ts
is downloaded. - Refresh browser, click on File open button, choose downloaded
apple2ts.at2s
, verify state is restored. - Refresh browser, click on Choose Disk Image (with all the thumbnails), click on
Total Replay
, verify it loads in hard drive 1. - Click on Choose Disk Image, click on
MECC Inspector
, verify hard drive is now empty,MECC
is in floppy drive 1, boots, and loads. - Click on Choose Disk Image, click on
ProDOS
, verify floppy drive is now empty,ProDOS
is in hard drive 1, boots, and loads. - Left click on hard drive, choose Save Disk to Device, pick a new name like
Test.po
, press OK, verify that the disk label changes to the new name. - Use down arrow to move down to
BASIC.SYSTEM
, press Enter/Return, verify that system goes to basic prompt. - Type:
10 PRINT "HELLO" SAVE TEST
- Confirm that the disk label briefly turns red with an asterisk. After a second or less, the label turns white again, with no asterisk.
- Refresh browser, click on hard drive 1, choose Load Disk from Device (Read/Write), choose your
Test.po
. After disk boots, verify that yourTEST
file is at the bottom of the file list.
- Click on hard drive 1, choose either Save Disk to OneDrive or Google Drive (whichever is easier to test). Choose a folder on your cloud drive, verify that blue spinner spins and then stops.
- Refresh browser, click on hard drive 1, choose Load Disk from OneDrive/GoogleDrive, pick your
Test.po
disk. Verify that disk boots and loads. - Using same steps as earlier, create a new BASIC program called
CLOUD
. Verify that the disk label turns red with an asterisk. After a minute or less, the label turns white again, with no asterisk. - Refresh browser, click on hard drive 1, choose Load Disk from OneDrive/GoogleDrive, pick your
Test.po
disk. Verify that disk boots and loads, and theCLOUD
file is at the bottom of the file list. - Click on hard drive 1, select Add Disk to Collection.
- Refresh browser, click on Choose Disk Image, select the
Test.po
from the list of starred items, confirm authentication from the cloud server, then verify that the disk boots. - Click on Choose Disk Image, click on the "filled star" for
Test.po
to remove it from the list. The disk should immediately disappear from the list.
- Refresh browser, click on hard drive 1, choose Load Disk from Internet Archive, choose Apple II Library: Games, then choose one of the games by clicking on the thumbnail image. Verify that the game boots.
- Refresh browser, click on hard drive 1, choose Load Disk from Internet Archive, choose Apple II Library: Games, then on one of the disk images, click on the bottom portion (tooltip should say Click to view details). Verify the IA page for that game opens up in a new tab.
- Back in the emulator, in the Internet Archive dialog, click on the "unfilled star" for one of the games. Click somewhere else to dismiss dialog. Click on Choose Disk Image, verify that the game is at the top of the list. Select it and verify that the game boots.
- Click on Choose Disk Image, click on the "filled star" for the game to remove the game from the list. The game should immediately disappear from the list.
Gamepads will only work with a secure (https) context. To enable https when running from localhost, you need to generate a certificate and install it on your system.
To enable https with vite, use the @vitejs/plugin-basic-ssl plugin.
Install the Github Changelog Generator by running:
gem install github_changelog_generator
You may need to update to Ruby v3.x to install this gem.
Go through the commits, and add any missing tags. For a given commit sha (say 1befdec
), checkout the commit, force the date to be the commit date, and then add the tag:
git checkout 1befdec
GIT_COMMITTER_DATE="$(git show --format=%aD | head -1)"
git tag -a v2.8 -m"v2.8"
git push origin --tags
git checkout main
If you don't already have one, generate a Github token to run the Changelog Generator script with authentication. You only need "repo" scope for private repositories.
Now run the script:
github_changelog_generator --token xxxxx -u ct6502 -p apple2ts
To make a ROM image, save the raw binary data from the C000-FFFF ROM in a single file. Then convert the file to a Base64 encoding. On the Mac, you can use the following command:
openssl base64 -in rom_2e.bin -out rom_2e.base64.ts
Finally, edit the .ts
file, and change the file to be an exported string variable by prepending:
export const rom=`
Don't forget to append the trailing back quote ` at the end of the file.