Apple2TS - Apple II Emulator in Typescript
Created by Chris Torrence (chris<at>ct6502<dot>org), with significant contributions from Michael Morrison (codebythepound<at>gmail<dot>com).
This project was originally create using Create React App and was then migrated to vite following these steps.
Development
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, run:
npm install
To run the app in development mode:
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.
Emulator Settings
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.
Testing
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
Building the Package
npm run build
Builds the app for production to the build 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.
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.
Deployment
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.
Upgrade Packages
https://www.hostingadvice.com/how-to/update-npm-packages/
Install npm-check-updates package
npm install -g npm-check-updates
npm outdated
ncu --upgrade
npm install
VS Code Chrome Debugging
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.
Android Chrome Debugging
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".
iOS Debugging
https://developer.apple.com/documentation/safari-developer-tools/inspecting-ios
Jest Test Debugging in VS Code
In VS Code, add breakpoints to the test code. Then open up package.json, hover over
the "test" script, and select 'Debug Script'.
Localhost Certificates
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.
Apple II ROMs
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.tsFinally, 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.
Apple II 6502 References
Assembly Lines: The Complete Book
Flowcharts for Apple II Emulator
Additional Info and Sponsors
