{"id":13528859,"url":"https://github.com/Timendus/chip8-test-suite","last_synced_at":"2025-04-01T14:33:23.743Z","repository":{"id":38031723,"uuid":"506392654","full_name":"Timendus/chip8-test-suite","owner":"Timendus","description":"A collection of ROM images with tests that will aid you in developing your own CHIP-8, SUPER-CHIP or XO-CHIP interpreter (or \"emulator\")","archived":false,"fork":false,"pushed_at":"2024-08-30T21:25:20.000Z","size":3773,"stargazers_count":455,"open_issues_count":4,"forks_count":8,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-24T07:34:49.455Z","etag":null,"topics":["chip-8","chip-8-emulator","chip-8-interpreter","chip-8-roms","chip8","chip8-emulator","chip8-interpreter","chip8-programs","chip8emu","debugging","ibm-logo","octo","schip","test-suite","testing","xo-chip"],"latest_commit_sha":null,"homepage":"","language":"Roff","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Timendus.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2022-06-22T20:15:10.000Z","updated_at":"2025-03-23T11:37:10.000Z","dependencies_parsed_at":"2024-11-02T15:31:34.561Z","dependency_job_id":null,"html_url":"https://github.com/Timendus/chip8-test-suite","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Timendus%2Fchip8-test-suite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Timendus%2Fchip8-test-suite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Timendus%2Fchip8-test-suite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Timendus%2Fchip8-test-suite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Timendus","download_url":"https://codeload.github.com/Timendus/chip8-test-suite/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246655367,"owners_count":20812623,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["chip-8","chip-8-emulator","chip-8-interpreter","chip-8-roms","chip8","chip8-emulator","chip8-interpreter","chip8-programs","chip8emu","debugging","ibm-logo","octo","schip","test-suite","testing","xo-chip"],"created_at":"2024-08-01T07:00:26.484Z","updated_at":"2025-04-01T14:33:18.725Z","avatar_url":"https://github.com/Timendus.png","language":"Roff","funding_links":["https://ko-fi.com/T6T0DOOWP"],"categories":["Emulator/interpreter development"],"sub_categories":["Testing"],"readme":"[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/T6T0DOOWP)\n\n# CHIP-8 test suite\n\n_A collection of ROM images with tests that will aid you in developing your own\nCHIP-8, SUPER-CHIP or XO-CHIP interpreter (or \"emulator\")_\n\n## Table of contents\n\n- [Introduction](#introduction)\n- [Baseline](#baseline)\n- [Available tests](#available-tests)\n  - [CHIP-8 splash screen](#chip-8-splash-screen)\n  - [IBM logo](#ibm-logo)\n  - [Corax+ opcode test](#corax-opcode-test)\n  - [Flags test](#flags-test)\n  - [Quirks test](#quirks-test)\n  - [Keypad test](#keypad-test)\n  - [Beep test](#beep-test)\n  - [Scrolling test](#scrolling-test)\n- [Contributing](#contributing)\n- [Community response 😄](#community-response-)\n\n# Introduction\n\nI found it hard to find reliable sources on what is the right behaviour and what\nis not, especially with the subtle differences between the original \"Cosmac VIP\"\nCHIP-8 and the HP48's SUPER-CHIP (or \"S-CHIP\"). Now that I have written and\nported a couple of interpreters as well as a few programs and games for the\nplatform, I thought it was time to put that knowledge into code.\n\nIf you're having issues with your interpreter, you can find help in the [EmuDev\ndiscord channel `#chip-8`](https://discord.gg/dkmJAes). Every test has a clearly\nvisible version number, which will help people to diagnose your problems if you\nshare a screenshot. If you discover a problem with this test ROM itself, feel\nfree to file an issue or open a pull request. It's open source, licensed under\nthe GPLv3, and you're welcome to [contribute](#contributing).\n\n# Baseline\n\nMost tests have been written to run equally well on all three major CHIP-8\nplatforms, unless otherwise specified. The [quirks test](#quirks-test) is the\nmost interesting one, since it was designed to test the differences between\nthose three platforms. If the test suite itself is wrong, we're not helping\nanyone. So what are we testing the test suite against?\n\n## CHIP-8\n\nThere are several good Cosmac VIP emulators, so we can quite faithfully run the\noriginal CHIP-8 interpreter and check the results. We use [Emma\nO2](https://www.emma02.hobby-site.com/) and/or\n[Cadmium](https://github.com/gulrak/cadmium) in `VIP-CHIP-8` mode to validate\nthe test suite.\n\nIf you have an actual, physical Cosmac VIP and would like to verify the test\nsuite, let me know! 😄\n\n## SUPER-CHIP\n\nFor SUPER-CHIP, the test suite has been tested against real HP48 graphing\ncalculators, in the various interpreters that exist for that system.\n[Gulrak](https://github.com/gulrak) from the CHIP-8 community has both an HP48SX\nand an HP48GX, and has been so kind as to check if the test suite ROMs behave as\nexpected.\n\n## XO-CHIP\n\nThe XO-CHIP extension was written by [John\nEarnest](https://github.com/johnearnest) and was first implemented in his IDE\nslash interpreter Octo. As such, we treat [Octo](http://octo-ide.com/) as the\ngold standard for how an XO-CHIP system should behave, and test against that.\n\n# Available tests\n\n## CHIP-8 splash screen\n\n- [Download ROM](https://github.com/Timendus/chip8-test-suite/raw/main/bin/1-chip8-logo.ch8)\n  (source code available [here](./src/tests/1-chip8-logo.8o))\n- [Run this ROM in Octo](https://timendus.github.io/chip8-test-suite/1-chip8-logo.html)\n  to see what's supposed to happen\n\nThe first test is a very simple splash screen. It is very similar to the often\nused [IBM ROM](#ibm-logo), but it is actually a bit easier to get running.\nFirst, it doesn't use the \"add value to register\" opcode (`7XNN`) and second it\nonly draws aligned sprites to the screen (the X coordinate is always a multiple\nof 8). So if you use an array of bytes for your display buffer, you don't have\nto shift the bits of the sprite to align with the buffer.\n\n![CHIP-8 logo, shown on the display](./pictures/chip-8-logo.png)\n\nRun the ROM for 39 cycles to see this splash screen on the display. This first\ntest can tell you if you're interpreting these opcodes properly:\n\n- `00E0` - Clear the screen\n- `6xnn` - Load normal register with immediate value\n- `Annn` - Load index register with immediate value\n- `Dxyn` - Draw sprite to screen (only aligned)\n\nIf you run the ROM for more than 39 cycles, it will enter an endless loop. If\nthat also works as expected, you've also correctly interpreted the jump opcode:\n\n- `1nnn` - Jump\n\n## IBM logo\n\n- [Download ROM](https://github.com/Timendus/chip8-test-suite/raw/main/bin/2-ibm-logo.ch8)\n  (source code available [here](./src/tests/2-ibm-logo.8o))\n- [Run this ROM in Octo](https://timendus.github.io/chip8-test-suite/2-ibm-logo.html)\n  to see what's supposed to happen\n\nThe second test is the classic IBM ROM. If the splash screen works as expected,\nthis test should be pretty easy to pass, but it is a rite of passage for any\nCHIP-8 developer.\n\nI did not write this ROM, it's probably decades old and I'm not sure who wrote\nit so I can't really credit them. The code in this suite is a re-implementation\nin Octo-mnemonics by my own hand, but it compiles to the exact same bytes as the\noriginal (except for the version number).\n\n![IBM logo, shown on the display](./pictures/ibm-logo.png)\n\nRun the ROM for 20 cycles to see the IBM logo on the display. If you can see the\nIBM logo, you are properly interpreting these opcodes:\n\n- `00E0` - Clear the screen\n- `6xnn` - Load normal register with immediate value\n- `Annn` - Load index register with immediate value\n- `7xnn` - Add immediate value to normal register\n- `Dxyn` - Draw sprite to screen (un-aligned)\n\nIf you run the ROM for more than 20 cycles, it will enter an endless loop. If\nthat also works as expected, you've also correctly interpreted the jump opcode:\n\n- `1nnn` - Jump\n\n## Corax+ opcode test\n\n- [Download ROM](https://github.com/Timendus/chip8-test-suite/raw/main/bin/3-corax+.ch8)\n  (source code available [here](./src/tests/3-corax+.8o))\n- [Run this ROM in Octo](https://timendus.github.io/chip8-test-suite/3-corax+.html)\n  to see what's supposed to happen\n\nThis ROM is an adaptation of another famous one, the [CHIP-8 test rom written by\ncorax89](https://github.com/corax89/chip8-test-rom). Many people use corax89's\nROM to prove to themselves that their interpreter runs as it should. However,\nthere are a couple of [minor issues with the\nROM](https://github.com/corax89/chip8-test-rom/pulls) and corax89 doesn't really\nseem to be maintaining this ROM anymore.\n\nSo I've taken the liberty to fix those issues, add a few new tests and make some\ncosmetic changes for this test suite.\n\nThis test needs the opcodes listed above for the IBM logo as well as the\nconditional skip opcodes (`3XNN`, `4XNN` and `5XY0`) to be working properly to\nactually show you some sane results.\n\n![Corax89's opcode test](./pictures/corax+.png)\n\nThe codes on the screen correspond to the functioning of these opcodes:\n\n```\n3xnn    2nnn    8xy4    Fx55\n4xnn    00EE    8xy5    Fx33\n5xy0    8xy0    8xy7    Fx1E\n7xnn    8xy1    8xy6    Registers\n9xy0    8xy2    8xyE\n1nnn    8xy3    Fx65\n```\n\nIf you see a checkmark, they're at least somewhat functional in the happy path.\nIf you see a cross you can be sure that you have an issue with that opcode.\n\nHere's a rough description of what these opcodes should do to pass the tests:\n\n- `3xnn` - if `vX == nn`, skip next opcode\n- `4xnn` - if `vX != nn`, skip next opcode\n- `5xy0` - if `vX == vY`, skip next opcode\n- `7xnn` - `vX += nn`\n- `9xy0` - if `vX != vY`, skip next opcode\n- `1nnn` - `jump nnn` (goto)\n- `2nnn` - `call nnn` (subroutine)\n- `00EE` - `return` from subroutine\n- `8xy0` - `vX = vY`\n- `8xy1` - `vX |= vY`\n- `8xy2` - `vX \u0026= vY`\n- `8xy3` - `vX ^= vY`\n- `8xy4` - `vX += vY`\n- `8xy5` - `vX -= vY`\n- `8xy7` - `vX = vY - vX`\n- `8xy6` - `vX = vY \u003e\u003e 1` or `vX = vX \u003e\u003e 1` depending on quirks\n- `8xyE` - `vX = vY \u003c\u003c 1` or `vX = vX \u003c\u003c 1` depending on quirks\n- `Fx65` - load registers `v0` - `vX` from memory starting at `i`\n- `Fx55` - save registers `v0` - `vX` to memory starting at `i`\n- `Fx33` - store binary-coded decimal representation of `vX` to memory at `i`,\n  `i + 1` and `i + 2`\n- `Fx1E` - `i += vX`\n- `Registers` - The `v0` - `vF` registers should be 8 bits wide. This tests to\n  see if it can overflow your registers.\n\nIf you are having trouble figuring out how each opcode is supposed to behave,\ncheck out [Tobias'\nguide](https://tobiasvl.github.io/blog/write-a-chip-8-emulator/#instructions) or\n[Gulrak's table of opcodes](https://chip8.gulrak.net) (but make sure you only check \"CHIP-8\" if you are just starting out).\n\n## Flags test\n\n- [Download ROM](https://github.com/Timendus/chip8-test-suite/raw/main/bin/4-flags.ch8)\n  (source code available [here](./src/tests/4-flags.8o))\n- [Run this ROM in Octo](https://timendus.github.io/chip8-test-suite/4-flags.html)\n  to see what's supposed to happen\n\nThis test checks to see if your math operations function properly on some given\nset of input values. But more importantly: it checks to see if you set the flag\nregister `vF` properly when running those opcodes, and if you don't mess up `vF`\ntoo early (when `vF` is used as one of the operands). This is often an issue as\nthe flags are pretty unintuitive and fairly hard to debug.\n\n![The flags test](./pictures/flags.png)\n\nWhen running this test you should see the above on your screen. Each code on the\nscreen corresponds to an opcode, and shows if the output value is correct (first\ncheckmark), if the flag in `vF` is correct (second checkmark), if `vF` can be\nused as the `vY` input (third checkmark) and if `vF` can be used as the `vX`\ninput (fourth checkmark, where present). If you see a cross instead of a\ncheckmark in any of these spots, you have an issue in your interpreter logic.\n\nFirst, a note on the third and fourth checkmarks: these check to see if an\ninstruction where `vF` is one of the operands (like `v0 += vF` / `0x80F4`) works\nas expected. It's easy to make the mistake of setting the `vF` register first,\nand then performing the mathematical operation. If you do that, however, `vF`\nwill not hold the right value anymore at calculation time and your maths will be\noff when using that register as an input.\n\nThe top part (that starts with \"HAPPY\" for \"happy path\") checks the behaviour of\nthe following opcodes, in the case where we **don't** expect an overflow, carry\nor shifted out bit:\n\n```\nHAPPY  8xy1   8xy2\n8xy3   8xy4   8xy5\n8xy6   8xy7   8xyE\n```\n\n- `8xy1` - `vX |= vY`\n- `8xy2` - `vX \u0026= vY`\n- `8xy3` - `vX ^= vY`\n- `8xy4` - `vX += vY`\n- `8xy5` - `vX -= vY`\n- `8xy6` - `vX = vY \u003e\u003e 1` or `vX = vX \u003e\u003e 1` depending on quirks\n- `8xy7` - `vX = vY - vX`\n- `8xyE` - `vX = vY \u003c\u003c 1` or `vX = vX \u003c\u003c 1` depending on quirks\n\nThe bottom part (that starts with \"CARRY\") checks behaviour of the following\nopcodes, in the case that there **is** an overflow, carry or shifted out bit:\n\n```\nCARRY  8xy4   8xy5\n8xy6   8xy7   8xyE\n```\n\n- `8xy4` - `vX += vY`\n- `8xy5` - `vX -= vY`\n- `8xy6` - `vX = vY \u003e\u003e 1` or `vX = vX \u003e\u003e 1` depending on quirks\n- `8xy7` - `vX = vY - vX`\n- `8xyE` - `vX = vY \u003c\u003c 1` or `vX = vX \u003c\u003c 1` depending on quirks\n\nThe last row (that starts with \"OTHER\") checks that the opcode `Fx1E` (`i +=\nvX`) properly adds the value of register `vX` to the index register, first for a\nregular register and then when using `vF` as the `vX` input register. For this\ntest, only the value is checked because overflow of the index register is not\nreally defined in CHIP-8 and this opcode is not supposed to influence the flag\nregister.\n\nSee [this article](https://laurencescotford.net/chip-8-on-the-cosmac-vip-arithmetic-and-logic-instructions/)\nor [this article](https://tobiasvl.github.io/blog/write-a-chip-8-emulator/#logical-and-arithmetic-instructions)\nfor more information on the arithmetic operations and the flags.\n\n## Quirks test\n\n- [Download ROM](https://github.com/Timendus/chip8-test-suite/raw/main/bin/5-quirks.ch8)\n  (source code available [here](./src/tests/5-quirks.8o))\n- [Run this ROM in Octo](https://timendus.github.io/chip8-test-suite/5-quirks.html)\n  to see what's supposed to happen\n\nCHIP-8, SUPER-CHIP and XO-CHIP have subtle differences in the way they interpret\nthe bytecode. We often call these differences quirks. This test detects which\nquirks your interpreter implements, and if those quirks match the platform\nyou're trying to target. This is one of the hardest parts to \"get right\" and\noften a reason why \"some games work, but some don't\".\n\n### The menu\n\nThe test asks you to choose the platform you are targeting. If you select\nSUPER-CHIP, if will then also ask you if you want to test for the \"modern\" or\nthe \"legacy\" behaviour. When in doubt, go for the \"modern\" one.\n\n![Choosing a target platform in the quirks test](./pictures/quirks-platform.png)\n\nYou can press any of the numbers `1` to `3` on the CHIP-8 keypad to make the\ncorresponding selection.\n\nAlternatively, you can move the cursor up and down with CHIP-8 keys `E` and `F`\nand select an item with `A`. This feature mainly exists so people implementing\ninterpreters for platforms with limited input devices (like a game controller)\ncan map their buttons to those CHIP-8 keys and have an intuitive interface too.\n\nIf you want to repeat a test often or even automate them, having to use the\ngraphical menu just gets in the way. In that case, you can force this ROM to\nselect a specific platform by loading a value between `1` and `4` into memory at\nthe address `0x1FF` (`512`).\n\n- `1` - CHIP-8\n- `2` - SUPER-CHIP with modern behaviour\n- `3` - XO-CHIP\n- `4` - SUPER-CHIP with legacy behaviour\n\n### The test\n\nThe test will now run through a couple of steps, which you will see on the\nscreen as a loading progress bar followed by some artifacts. After about three\nseconds, you should see this screen:\n\n![Showing the active quirks](./pictures/quirks.png)\n\nThe screen shows you if the following quirks are detected as active (\"on\", \"off\"\nor an error) and if that matches your chosen target platform (a checkmark or a\ncross).\n\n- `vF reset` - The AND, OR and XOR opcodes (`8xy1`, `8xy2` and `8xy3`) reset the\n  flags register to zero. Test will show `ERR1` if the AND and OR tests don't\n  behave the same and `ERR2` if the AND and XOR tests don't behave the same.\n- `Memory` - The save and load opcodes (`Fx55` and `Fx65`) increment the index\n  register. More information [here](https://laurencescotford.net/chip-8-on-the-cosmac-vip-loading-and-saving-variables/)\n  and [here](https://tobiasvl.github.io/blog/write-a-chip-8-emulator/#fx55-and-fx65-store-and-load-memory).\n  Test will show `ERR1` if reading and writing don't behave the same.\n- `Display wait` - Drawing sprites to the display waits for the vertical blank\n  interrupt, limiting their speed to max 60 sprites per second. More information\n  [here](https://laurencescotford.net/chip-8-on-the-cosmac-vip-drawing-sprites/).\n  Test will show `SLOW` if the number of cycles per frame is too low for the test\n  to be deterministic (this is not necessarily an error, but a suggestion to\n  rerun the test with a higher number of cycles per frame).\n- `Clipping` - Sprites drawn at the bottom edge of the screen get clipped\n  instead of wrapping around to the top of the screen. When clipping is off, the\n  test checks if sprites get rendered at the right coordinates on the other side\n  of the screen. This also tests that sprites drawn at coordinates of `x \u003e 63`\n  and/or `y \u003e 31` wrap around to `x % 64` and `y % 32`. More information\n  [here](https://laurencescotford.net/chip-8-on-the-cosmac-vip-drawing-sprites/).\n  Test will show `ERR1` if the clipping is inconsistent in different dimensions\n  or wrapping to the wrong coordinates and `ERR2` if sprites don't wrap around\n  as expected.\n- `Shifting` - The shift opcodes (`8xy6` and `8xyE`) only operate on `vX`\n  instead of storing the shifted version of `vY` in `vX` (more information\n  [here](https://tobiasvl.github.io/blog/write-a-chip-8-emulator/#8xy6-and-8xye-shift)).\n  Test will show `ERR1` if the shift opcodes behave differently.\n- `Jumping` - The \"jump to some address plus `v0`\" instruction (`Bnnn`) doesn't\n  use `v0`, but `vX` instead where `X` is the highest nibble of `nnn` (more\n  information [here](https://tobiasvl.github.io/blog/write-a-chip-8-emulator/#bnnn-jump-with-offset))\n\nNote that you need timer support for this test to run.\n\n### SUPER-CHIP / XO-CHIP\n\nIf you select SUPER-CHIP or XO-CHIP in the menu, half of the test will be\nexecuted in `hires` mode, and the behaviour of `Display wait` and `Clipping`\nwill be tested in both `lores` and `hires` modes. This means you will not just\nsee \"on\" or \"off\" for these quirks, but instead one of these values:\n\n- `NONE` - The quirk is disabled in both modes\n- `HRES` - The quirk is only enabled in `hires` mode\n- `LRES` - The quirk is only enabled in `lores` mode\n- `BOTH` - The quirk is enabled in both modes\n\nIf the test finds different errors for the `Clipping` test in `hires` mode\ncompared to `lores` mode, it will show `ERR3`. In that case, first make sure\nyour modes produce the same wrapping and clipping results, and see which errors\npop up after that.\n\nWondering why testing `hires` has been added, or if a quirk can ever be enabled\nin only one of the modes? Or just wondering why SUPER-CHIP has a \"legacy\" and a\n\"modern\" version of the test? You can [read the full story\nhere](./legacy-superchip.md).\n\n### More information\n\nSee this [excellent\ntable](https://chip8.gulrak.net) by Gulrak for\nan overview of all the known quirks for the relatively popular CHIP-8 versions.\nSee [this website](https://chip-8.github.io/extensions/) for a lot more\ninformation about all the historical versions of the platform and the different\nquirks among them.\n\n## Keypad test\n\n- [Download ROM](https://github.com/Timendus/chip8-test-suite/raw/main/bin/6-keypad.ch8)\n  (source code available [here](./src/tests/6-keypad.8o))\n- [Run this ROM in Octo](https://timendus.github.io/chip8-test-suite/6-keypad.html)\n  to see what's supposed to happen\n\nThis test allows you to test all three CHIP-8 key input opcodes. It shows you a\nlittle menu, asking which opcode you would like to test:\n\n![Choosing the opcode to test in the keypad test](./pictures/keypad-menu.png)\n\nYou can press any of the numbers `1` to `3` on the CHIP-8 keypad to jump to the\ncorresponding test.\n\nAlternatively, you can move the cursor up and down with CHIP-8 keys `E` and `F`\nand select an item with `A`. This feature mainly exists so people implementing\ninterpreters for platforms with limited input devices (like a game controller)\ncan map their buttons to those CHIP-8 keys and have an intuitive interface too.\n\nIf you want to repeat a test often or even automate them, having to use the\ngraphical menu just gets in the way. In that case, you can force this ROM to\nselect a specific platform by loading a value between `1` and `3` into memory at\nthe address `0x1FF` (`512`).\n\n### 1. `Ex9E DOWN`\n\n`Ex9E` skips the next instruction if the key indicated in `vX` is currently\npressed. In the test, when you press a key, the corresponding value lights up on\nthe screen.\n\n![The `Ex9E` keypad test, when pressing keys 1 and 6](./pictures/keypad-down.png)\n\n_Pressing keys 1 and 6_\n\n### 2. `ExA1 UP`\n\n`ExA1` skips the next instruction if the key indicated in `vX` is currently\n**not** pressed. In the test, when you are **not** pressing a key, the\ncorresponding value lights up on the screen.\n\n![The `ExA1` keypad test, when pressing keys 1 and 6](./pictures/keypad-up.png)\n\n_Pressing keys 1 and 6_\n\n### 3. `Fx0A GETKEY`\n\n`Fx0A` waits for a key press and returns the pressed key in `vX`.\n\nThe test asks you to press a key on the CHIP-8 keypad. When you do, it checks\nfor two issues that are easy to accidentally introduce when implementing this\nopcode. If all is well, you should be seeing a checkmark and \"all good\" on the\nscreen:\n\n![The `Fx0A` keypad test, when all is good](./pictures/keypad-getkey.png)\n\nOtherwise, you can get either of these errors:\n\n- `NOT HALTING` - Your implementation immediately returns the value of any\n  currently pressed keys in `vX`, instead of halting the interpreter until a key\n  is pressed (note that this needs timer support to be accurate - in other words,\n  the DELAY TIMER should continue to count down while awaiting a keypress)\n- `NOT RELEASED` - Your implementation doesn't wait for the pressed key to be\n  released before resuming\n\nSee [this\narticle](https://laurencescotford.net/chip-8-on-the-cosmac-vip-keyboard-input/)\nfor more information.\n\n## Beep test\n\n- [Download ROM](https://github.com/Timendus/chip8-test-suite/raw/main/bin/7-beep.ch8)\n  (source code available [here](./src/tests/7-beep.8o))\n- [Run this ROM in Octo](https://timendus.github.io/chip8-test-suite/7-beep.html)\n  to see what's supposed to happen (sound may not actually play due to browser\n  restrictions)\n\nThis test allows you to test if your buzzer is working. It will beep SOS in\nmorse code and flash a speaker icon on the display in the same pattern. If you\npress the CHIP-8 button `B` it will give you manual control over the buzzer.\nPress `B` to beep.\n\n![The beep test beeping](./pictures/beep.png)\n\n## Scrolling test\n\n- [Download ROM](https://github.com/Timendus/chip8-test-suite/raw/main/bin/8-scrolling.ch8)\n  (source code available [here](./src/tests/8-scrolling.8o))\n- [Run this ROM in Octo](https://timendus.github.io/chip8-test-suite/8-scrolling.html)\n  to see what's supposed to happen\n\nThis test is only applicable to SUPER-CHIP and XO-CHIP interpreters, since\nregular CHIP-8 does not have scrolling instructions. It will test to see if your\nscrolling opcodes scroll the display in the right directions by the right\namounts of pixels. One literal \"edge\"-case that it does **not** cover is what\nhappens at the edges of the screen.\n\n### The menu\n\nThe test asks you to choose the platform and resolution you are targeting. For\nSUPER-CHIP `lores`, it will also ask you to choose between \"modern\" or \"legacy\"\nbehaviour. When in doubt, go for the \"modern\" one.\n\n![Choosing a target platform in the scrolling test](./pictures/scrolling-platform.png)\n\nYou can press any of the numbers `1` or `2` on the CHIP-8 keypad to select the\ncorresponding entry.\n\nAlternatively, you can move the cursor up and down with CHIP-8 keys `E` and `F`\nand select an item with `A`. This feature mainly exists so people implementing\ninterpreters for platforms with limited input devices (like a game controller)\ncan map their buttons to those CHIP-8 keys and have an intuitive interface too.\n\nIf you want to repeat a test often or even automate them, having to use the\ngraphical menu just gets in the way. In that case, you can force this ROM to\nselect a specific platform by loading a value between `1` and `5` into memory at\nthe address `0x1FF` (`512`).\n\n- `1` - SUPER-CHIP `lores` with modern behaviour\n- `2` - SUPER-CHIP `lores` with legacy behaviour\n- `3` - SUPER-CHIP `hires`\n- `4` - XO-CHIP `lores`\n- `5` - XO-CHIP `hires`\n\n### The test\n\nThe test will show you a visual with arrows and boxes. If everything works as\nexpected for the target you have selected, all the arrows will end up in their\nboxes, like so:\n\n![Result of the scrolling test for `lores` SUPER-CHIP](./pictures/lores-scrolling.png)\n\nIf you have issues with one or more of your scrolling instructions, some arrows\nwill be (partially) outside their boxes. The arrows all point in the directions\nthat they should be scrolled in, so the ones that have not moved in the\ndirection that they point in represent the scrolling instructions that are not\nworking properly.\n\nFor example, this is what you see if none of the scrolling instructions have\nbeen implemented:\n\n![Result of the scrolling test with no implemented scrolling](./pictures/lores-no-scrolling.png)\n\nA note on legacy versus modern behaviour for SUPER-CHIP's `lores` mode can be\nfound in the document [Legacy SUPER-CHIP](./legacy-superchip.md).\n\n# Contributing\n\nDo you find an issue in this test suite that you think you can fix? Feel free to\nsubmit a PR! Here's how to build the project, assuming you have Nodejs and NPM\ninstalled:\n\n```bash\ngit clone git@github.com:Timendus/chip8-test-suite.git\ncd chip8-test-suite\nnpm install\n```\n\n```bash\n# Build all the tests in `src/tests/` to `bin/`:\nnpm start\n\n# Build a specific test:\nTEST=1-chip8-logo npm run build-test\nTEST=2-ibm-logo npm run build-test\nTEST=3-corax+ npm run build-test\nTEST=4-flags npm run build-test\nTEST=5-quirks npm run build-test\nTEST=6-keypad npm run build-test\nTEST=7-scrolling npm run build-test\nTEST=8-beep npm run build-test\n```\n\nNote that the `npm` scripts use the MacOS command `pbcopy` to copy\nthe resulting Octo source file to the clipboard. Depending on your OS this may\nnot work properly. Edit `package.json` and remove this part from the end of `scripts` -\u003e\n`build-test` if you get errors:\n\n```\n \u0026\u0026 cat bin/${TEST}.8o | pbcopy\n```\n\n# Community response 😄\n\n[![DUDE THANKS! I was writing a CHIP-8 emulator and THIS HELPED ME SO FRICKING MUCH, THANKS! / same here, this is amazing](./pictures/testimonial1.png)](https://github.com/Timendus/chip8-test-suite/issues/1)\n\n[![Really nice to have new tests (flags, quirks). Especially the quirks. Fixing some bugs in my impl as we speak thanks to that.](./pictures/testimonial2.png)](https://www.reddit.com/r/EmuDev/comments/viri5r/i_wrote_a_chip8_test_suite/idet6in/?utm_source=reddit\u0026utm_medium=web2x\u0026context=3)\n\n[![Really nice to have new tests (flags, quirks). Especially the quirks. Fixing some bugs in my impl as we speak thanks to that.](./pictures/testimonial3.png)](https://www.reddit.com/r/EmuDev/comments/viri5r/i_wrote_a_chip8_test_suite/idt41f1/?utm_source=reddit\u0026utm_medium=web2x\u0026context=3)\n\n[![Really nice to have new tests (flags, quirks). Especially the quirks. Fixing some bugs in my impl as we speak thanks to that.](./pictures/testimonial4.png)](https://www.reddit.com/r/EmuDev/comments/viri5r/comment/idugp4j/?utm_source=reddit\u0026utm_medium=web2x\u0026context=3)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTimendus%2Fchip8-test-suite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTimendus%2Fchip8-test-suite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTimendus%2Fchip8-test-suite/lists"}