{"id":44788063,"url":"https://github.com/pevans/erc","last_synced_at":"2026-04-02T12:02:57.094Z","repository":{"id":78798067,"uuid":"147973025","full_name":"pevans/erc","owner":"pevans","description":"A small program for the emulation of retro computers","archived":false,"fork":false,"pushed_at":"2026-04-02T01:01:40.000Z","size":1893,"stargazers_count":13,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-02T09:28:47.108Z","etag":null,"topics":["appleii","emulation","emulator","go","mos6502"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pevans.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-09-08T22:00:50.000Z","updated_at":"2026-04-02T00:56:11.000Z","dependencies_parsed_at":"2026-03-12T03:05:17.581Z","dependency_job_id":null,"html_url":"https://github.com/pevans/erc","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/pevans/erc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pevans%2Ferc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pevans%2Ferc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pevans%2Ferc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pevans%2Ferc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pevans","download_url":"https://codeload.github.com/pevans/erc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pevans%2Ferc/sbom","scorecard":{"id":729655,"data":{"date":"2025-08-11","repo":{"name":"github.com/pevans/erc","commit":"95dc8bb60f1318098bf7c1340f52e86cadaed055"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.5,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/codeql-analysis.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"SAST","score":10,"reason":"SAST tool detected: CodeQL","details":["Info: SAST configuration detected: CodeQL","Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:38: update your workflow using https://app.stepsecurity.io/secureworkflow/pevans/erc/codeql-analysis.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:42: update your workflow using https://app.stepsecurity.io/secureworkflow/pevans/erc/codeql-analysis.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:53: update your workflow using https://app.stepsecurity.io/secureworkflow/pevans/erc/codeql-analysis.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:67: update your workflow using https://app.stepsecurity.io/secureworkflow/pevans/erc/codeql-analysis.yml/main?enable=pin","Info:   0 out of   4 GitHub-owned GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-22T14:03:00.921Z","repository_id":78798067,"created_at":"2025-08-22T14:03:00.921Z","updated_at":"2025-08-22T14:03:00.921Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31305971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T09:48:21.550Z","status":"ssl_error","status_checked_at":"2026-04-02T09:48:19.196Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["appleii","emulation","emulator","go","mos6502"],"created_at":"2026-02-16T10:44:10.491Z","updated_at":"2026-04-02T12:02:57.069Z","avatar_url":"https://github.com/pevans.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# erc\n\nThe _erc_ (**e**mulator of **r**etro **c**omputers) system is designed to\nemulate an Apple IIe (enhanced) computer and run software for it. It is\nwritten to be flexible enough to handle multiple machine architectures, and\nmay be extended to do just that in the future.\n\nErc's goals are to:\n1. Emulate old software in a way that feels as native and natural as can be\n   achieved on modern hardware. It is not a goal to precisely emulate every\n   facet of the older device.\n2. Be written in a clear and straightforward manner, so that others may study\n   and learn from how emulation works generally or how some specific older\n   machine works in particular.\n\nIt's a rewrite of an older project (https://github.com/pevans/erc-c), by\nthe same name, that was written in C code. This project is instead\nwritten in Go, which has much better tooling for code formatting and\ntesting--something that I felt was lacking in the previous iteration. I\nalso just really like Go! I regret nothing.\n\nThe soul of the work here, which is emulation of the Apple II, has been\na hobby of mine going back more than a decade.\n\n## Installation\n\nTo install Erc, you must have at least Go 1.25 installed on your system.\n\nIf you have `just` installed, then you can run `just build`. If not, you can\nrun `go build -o erc .`. Either way, you'll be left with an executable named\n`erc`, which you can install in a path you can execute from (like\n`$HOME/bin`).\n\n## Features\n\nErc can run most Apple II software successfully. It supports:\n\n- Most visual modes, including:\n  - Text mode (40 characters)\n  - Low resolution graphics\n  - High resolution graphics\n  - Double high resolution graphics\n  - Monochrome color graphics in (green and amber)\n- Graphical shaders to simulate the output of a CRT monitor (a soft CRT shader\n  is used by default)\n- DOS 3.3 (.DSK, .DO) and Nibble (.NIB) disk images\n- Basic speaker support\n- Save states: load and save the state of your emulation at any time (up to 10\n  state slots available)\n- Accurate clock cycle emulation: run software at the normal speed of the\n  computer, or run it faster (up to 5x the original clock speed).\n\nPlus, lots of features for folks who want to peek under the hood at what the\nemulation is doing:\n\n- An inline debugger to peek at memory, change state, etc.\n- A large variety of debug files to look at what's being written to disk, the\n  assembly that's been executed, how visuals and audio are produced, and more.\n  Available when running with the `--debug-image` flag.\n- Encode logical disk images to physical images so you can see how those are\n  structured with the `erc encode` command.\n- Look at disk image metadata with the `erc info` command.\n\n## Running\n\nTo run Erc, you need to issue a command like `erc run \u003csomefile\u003e`, where\n`\u003csomefile\u003e` is a valid disk image. Erc is validated to run with DOS3.3 disk\nimages file, which often have a file extension ending in `.dsk`. There are\nother commands you can explore with `erc help`.\n\nMany Apple II softwares have more than one disk. If so, you need to tell `erc`\nabout them when you first run the emulator. You can do this like so:\n\n```\nerc run disk1.dsk disk2.dsk disk3.dsk\n```\n\nThis will load with `disk1.dsk` first. You can use a shortcut to swap disk1\nfor disk2; disk2 for disk3; disk3 for disk1; and so forth.\n\nErc is designed to run with the set of disk images you tell it when first\nexecuted. There's no load modal to let you load some other disk image later;\nyou can only swap disks from within that set.\n\n(If you're truly adventurous, you can still load a disk from outside the\ninitial disk set if you invoke the inline debugger and use its `load`\ncommand.)\n\n## Floppy disks and disk images\n\nErc works with _disk images,_ which are files that are a byte-for-byte copy of\nwhat was stored on a floppy disk. There are two kinds of disk images:\n\n- Logical images. These files contain the bytes that represent software data,\n  software code, etc. that would have been stored on a disk. Logical disk\n  images often have extensions like `.dsk` and `.do`.\n- Physical, or _nibblized,_ images. These contain the literal bytes _as they\n  would have been written_ on the floppy disks. Apple IIs used an encoding\n  scheme so that they could detect errors on disk data, and this scheme made\n  the size of the data look different (and larger!) than if they had loaded\n  the raw software code and data onto the disk. Physical disk images often\n  have an extension like `.nib`.\n\nWhen loading a logical disk image (which is the most common format), Erc must\nencode that data so that it looks like it would have been written on a floppy\ndisk. After that, the Apple II's disk code would expect to _decode_ that data\ninto the correct software code to run!\n\n## Save states\n\nErc can save the state of whatever software you're emulating. Think of this as\na quick save of your progress that you can instantly revert to whenever you\nwant. Loading up some slow software and you want to skip back to where you\nleft off? Save states are great for that.\n\nErc can keep up to 10 save states. It does so with _slots_, numbered 0-9. The\ndefault state slot is 0. Any save-state you create will save to the current\nstate slot, and text will flash by on the screen to remind you what the slot\nwould be.\n\nAny state you want to save or load can be done so with keyboard shortcuts.\nRead below to learn what those shortcuts are.\n\n## Sound\n\nErc can emulate sound. On an Apple II, the builtin speaker was very basic, and\nthe sounds that software might make (like a game) will sound tinny compared to\nanything modern.\n\nIf you would prefer not to hear sound, you can toggle it off using the\n**CTRL-A V** shortcut (see more on keyboard shortcuts below). You can also\nadjust the volume up or down using other shortcuts.\n\n## Monochrome\n\nYou can emulate software in a monochrome color by passing the CLI flag,\n`--monochrome=x` where `x` is either `green` or `amber`. This feature is\ndesigned to provide the same feeling of running under such a monitor.\n\n## Shaders\n\nErc uses shaders to try provide different visual effects to the software being\nemulated. Those shaders are:\n\n- **softcrt.** The default shader. Adds a very light scanline effect to the\n  graphics in an effort to mimic the look that graphics had on monitors of the\n  time.\n- **curvedcrt.** Like softcrt, this shader adds a light scanline effect, but\n  also adds a kind of curvature to the edges of the screen. Use this shader if\n  you want to pretend that you were plugged into a cheap television.\n- **hardcrt.** This adds a harder scanline effect to the graphics. Oddly,\n  \"better\" CRT screens had more pronounced scanlines than did cheaper\n  displays.\n\nYou can use the CLI flag, `--shader=x`, where `x` is one of the above shaders,\nto configure Erc to use that shader. See `erc run help` for more information\non what flags are available when running a disk image.\n\n## Keyboard shortcuts\n\nAll keyboard shortcuts are a combination of keys. You must hit Control-A, then\nsome other key, which is the shortcut. You don't need to hit these keys all at\nthe same time.\n\nWhen you hit Control-A, the screen will highlight the edge of the screen to\nindicate that it's waiting for the next key. Once a shortcut is completed,\nyou'll see a graphic in the top left that will fade out to indicate what's\nhappening.\n\nShortcuts available:\n\n- **CTRL-A Escape: Pause emulation until you hit Escape again.** Any other\n  keypress will show the Pause icon to indicate it's still paused. You don't\n  need to hit CTRL-A Escape to resume; just Escape.\n- **CTRL-A 0-9: Set the current state slot to N, where N is some number key on\n  your keyboard.** This will tell Erc what slot to use when loading and saving\n  state. See more information in the Save State section of this file.\n- **CTRL-A +: Increase the speed so emulation runs faster.** Up to a maximum\n  of 5x the normal speed of emulation.\n- **CTRL-A -: Decrease the speed of emulation so things run slower.** The\n  emulator will not go any slower than 1x the normal speed.\n- **CTRL-A ]: Increase the sound volume by 10%.** Up to 100%.\n- **CTRL-A [: Decrease the sound volume by 10%.** Down to 0% (muted).\n- **CTRL-A B: Start the debugger in the console where you ran Erc from.** From\n  the debugger, type `help` to see a list of commands available there, or type\n  `resume` to resume emulation and leave the debugger.\n- **CTRL-A L: Load a saved state from the current slot into the emulator.**\n  See more information in the Save State section of this file.\n- **CTRL-A N: Swap the disk currently in the drive with the _next_ disk\n  available.** If you're on disk 1, you'll swap to disk 2; if you're on\n  disk 2, you'll swap to disk 3. And so forth until you're back to disk 1.\n  Any changes made to the disk being swapped out will be written back to the\n  image file.\n- **CTRL-A P: Swap the disk currently in the drive with the _previous_ disk\n  available.** If you're on disk 3, you'll swap to disk 2, and so forth. Any\n  changes made to the disk being swapped out will be written back to the image\n  file.\n- **CTRL-A Q: Quit the emulator and save all changes to the disk image.** (If\n  you're on a Mac, CMD-Q should also work.)\n- **CTRL-A S: Save the state the emulator in the current state slot.** See\n  more information in the Save State section of this file.\n- **CTRL-A V: Toggle volume on or off.**\n- **CTRL-A W: Toggle write-protect for the disk.** Write-protection will prevent\n  data on the disk from being overwritten. Some software cannot run with\n  write-protect enabled, and some software cannot run _without_ write-protect\n  enabled -- exactly which is the case depends on the software. By default,\n  write-protect is always off.\n\n_Note: if you really need to send a literal control-A to the software\nbeing emulated, you can do so by typing CTRL-A twice._\n\n## What's in here?\n\n- The main command (erc) is located in this directory (`erc.go`).\n- Code for the MOS 65c02 processor is in `mos`.\n- Code for the Apple II architecture is in `a2`.\n\nMost other packages are there to support the work to run/render/etc. the\nsupporting elements that make emulation possible.\n\n## Credits\n\n- I am enormously grateful for a bunch of books:\n  - Rodney Zaks for his book _Programming the 6502_;\n  - Jim Sather for his work _Understanding the Apple II_;\n  - Don Worth and Pieter Lechner's book, _Beneath Apple DOS_;\n  - And Apple's fantastic own technical reference manuals, which were a huge\n    help.\n- To Linapple/AppleWin and everyone who contributed to those -- their work was\n  a great resource for me while trying to figure out why things weren't\n  working.\n- To Steve Wozniak, whose Apple II is the device that introduced me to\n  computers and to my love of computing generally. Apple could never be what\n  it is today without Steve's dedication and craftsmenship.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpevans%2Ferc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpevans%2Ferc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpevans%2Ferc/lists"}