{"id":13578004,"url":"https://github.com/taniarascia/chip8","last_synced_at":"2025-04-05T05:05:20.106Z","repository":{"id":34069040,"uuid":"163930227","full_name":"taniarascia/chip8","owner":"taniarascia","description":"🎮 ‎ A Chip-8 emulator written in JavaScript for web, CLI, and native UI.","archived":false,"fork":false,"pushed_at":"2022-05-11T17:50:45.000Z","size":469,"stargazers_count":442,"open_issues_count":2,"forks_count":41,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-03-29T04:05:55.833Z","etag":null,"topics":["chip-8","chip-8-emulator","emulator","javascript","node"],"latest_commit_sha":null,"homepage":"https://taniarascia.github.io/chip8/","language":"JavaScript","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/taniarascia.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}},"created_at":"2019-01-03T06:06:16.000Z","updated_at":"2025-03-27T13:49:57.000Z","dependencies_parsed_at":"2022-07-16T09:46:16.026Z","dependency_job_id":null,"html_url":"https://github.com/taniarascia/chip8","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taniarascia%2Fchip8","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taniarascia%2Fchip8/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taniarascia%2Fchip8/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taniarascia%2Fchip8/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/taniarascia","download_url":"https://codeload.github.com/taniarascia/chip8/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289426,"owners_count":20914464,"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","emulator","javascript","node"],"created_at":"2024-08-01T15:01:26.226Z","updated_at":"2025-04-05T05:05:20.086Z","avatar_url":"https://github.com/taniarascia.png","language":"JavaScript","funding_links":[],"categories":["Home Game Console Emulators","JavaScript","Chip-8 and related system emulators/interpreters"],"sub_categories":["Chip-8 and related system emulators/interpreters"],"readme":"# Chip8.js\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![chip8js on NPM](https://img.shields.io/npm/v/chip8js.svg?color=green\u0026label=chip8js)](https://www.npmjs.com/package/chip8js) [![Build Status](https://travis-ci.org/taniarascia/chip8.svg?branch=master)](https://travis-ci.org/taniarascia/chip8) [![Coverage Status](https://coveralls.io/repos/github/taniarascia/chip8/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/taniarascia/chip8?branch=master)\n\nA Chip-8 emulator written in JavaScript.\n\n\u003e [Chip-8](https://en.wikipedia.org/wiki/CHIP-8) is a simple, interpreted, programming language which was first used on some do-it-yourself computer systems in the late 1970s and early 1980s.\n\n### [View the demo](https://taniarascia.github.io/chip8/) | [Read the article](https://www.taniarascia.com/writing-an-emulator-in-javascript-chip8/)\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Web](#web)\n  - [Terminal](#terminal)\n  - [Native](#native)\n- [Motivation](#motivation)\n- [Testing](#testing)\n  - [Instruction tests](#instruction-tests)\n  - [CPU tests](#cpu-tests)\n- [Acknowlegdements](#acknowledgements)\n- [License](#license)\n\n## Installation\n\n\u003e This guide assumes you already have [Node.js](https://nodejs.org/en/) and npm installed.\n\nPrior to installing Chip8.js, you must have CMake installed.\n\n```bash\nbrew install cmake\n```\n\nClone the repository and install.\n\n```bash\ngit clone git@github.com:taniarascia/chip8.git\ncd chip8\nnpm i\n```\n\n## Usage\n\nChip8.js can be run on the web, in a terminal, or using native keybindings.\n\n### Web\n\n- [Chip8.js emulator for the web](https://taniarascia.github.io/chip8/)\n\n#### Development\n\nSpin up a local server during development.\n\n```bash\n# watch for changes and rebuild\nnpm run watch:web\n\n# spin up server on localhost:8080\ncd web \u0026\u0026 http-server \n```\n\n#### Deployment\n\nBuild and bundle the code for the web.\n\n```bash\nnpm run build:web\n```\n\nDeploy to GitHub.\n\n```bash\n# remove web/bundle.js from .gitignore\ngit add web \u0026\u0026 git commit -m \"update web version\"\n\n# delete gh-pages branch from origin before push\ngit subtree push --prefix web origin gh-pages\n```\n\n### Terminal\n\nRun Chip8.js in the terminal by selecting a ROM.\n\n```bash\nnpm run play:terminal roms/\u003cROM\u003e\n```\n\n### Native\n\nRun Chip8.js natively with [raylib](https://www.npmjs.com/package/raylib) (experimental).\n\n```bash\nnpm run play:native roms/\u003cROM\u003e\n```\n\n## Motivation\n\nChip8.js is a project to write a Chip-8 emulator in JavaScript. The main motivation is to learn lower level programming concepts and to increase familiarity with the Node.js environment.\n\nHere are some of the concepts I learned while writing this program:\n\n- The base system: specifically base 2 (binary), base 10 (decimal), base 16 (hexadecimal), how they interact with each other and the concept of abstract numbers in programming\n- Bits, nibbles, bytes, ASCII encoding, and big and little endian values\n- Bitwise operators - AND (`\u0026`), OR (`|`), XOR (`^`), left shift (`\u003c\u003c`), right shift (`\u003e\u003e`) and how to use them for masking, setting, and testing values\n- Using the Node built-in file system ([fs](https://www.npmjs.com/package/fs))\n- The concept of a raw data buffer and how to work with it, how to convert an 8-bit buffer to a 16-bit big endian array\n- Writing and understanding a 8-bit and 16-bit hex dump\n- How to disassemble and decode an opcode into instructions a CPU can use\n- How a CPU can utilize memory, stack, program counters, stack pointers, memory addresses, and registers\n- How a CPU implements fetch, decode, and execute\n\nAnd here are some articles I wrote based on those concepts:\n\n- [Understanding Bits, Bytes, Bases, and Writing a Hex Dump in JavaScript (Node)](https://www.taniarascia.com/bits-bytes-bases-and-a-hex-dump-javascript/)\n- [Writing an Emulator in JavaScript (with Multiple UIs)](https://www.taniarascia.com/writing-an-emulator-in-javascript-chip8/)\n\n## Testing\n\nThe unit tests for Chip8.js use the Jest testing framework. You can run all test suites with or without displaying coverage.\n\n```bash\n# Run test suites\nnpm run test\n\n# Run test suites and view coverage\nnpm run test --coverage\n```\n\nChip8.js has two suites of unit tests:\n\n- Opcode instruction masks and arguments\n- CPU implementation of instructions\n\n### Instruction tests\n\nThe [instruction tests](tests/instructions.test.js) cover the `INSTRUCTION_SET` found in `data/instructionSet.js`. Each instruction has:\n\n- A `key`: for internal use\n- An `id`: for a unique name\n- A `name`: for the type of instruction)\n- A `mask`: to filter out arguments from instruction signifiers)\n- A `pattern`: to match the mask to the specific instruction pattern\n- `arguments`, each of which contain:\n  - A `mask`: to filter the nibble(s) to arguments\n  - A `shift`: to shift it by location\n  - A `type`: to signify the type of argument\n\n```js\n// data/instructionSet.js\n\n{\n  key: 6,\n  id: 'SE_VX_NN',\n  name: 'SE',\n  mask: 0xf000,\n  pattern: 0x3000,\n  arguments: [{ mask: 0x0f00, shift: 8, type: 'R' }, { mask: 0x00ff, shift: 0, type: 'NN' }],\n}\n```\n\nEach unit test checks an opcode to an instruction and tests:\n\n- The unique `id` to ensure the correct instruction is running for the mask/pattern\n- The number of arguments\n- The value of the arguments\n\n```js\n// tests/instructions.test.js\n\ntest('6: Expect disassembler to match opcode 3xnn to instruction SE_VX_NN', () =\u003e {\n  expect(Disassembler.disassemble(0x3abb).instruction).toHaveProperty('id', 'SE_VX_NN')\n  expect(Disassembler.disassemble(0x3abb).args).toHaveLength(2)\n  expect(Disassembler.disassemble(0x3abb).args[0]).toBe(0xa)\n  expect(Disassembler.disassemble(0x3abb).args[1]).toBe(0xbb)\n})\n```\n\nThere are 35 instruction tests for 35 opcodes (the first instruction, `CLS`, is no longer implemented).\n\n### CPU tests\n\nThe CPU decodes the opcode and returns the instruction object from `data/instructionSet.js`. Each instruction performs a specific, unique action in the `case`. The [CPU tests](tests/cpu.test.js) test the state of the CPU after an executing an instruction.\n\nIn the below example, the instruction is skipping an instruction if `Vx === nn`, otherwise it's going to the next instruction as usual.\n\n```js\n// classes/CPU.js\n\ncase 'SE_VX_NN':\n  // Skip next instruction if Vx = nn.\n  if (this.registers[args[0]] === args[1]) {\n    this._skipInstruction()\n  } else {\n    this._nextInstruction()\n  }\n  break\n```\n\nEach CPU test:\n\n- Loads a `RomBuffer` containing the data of a single opcode\n- Sets up the state to make the instruction testable (if necessary)\n- Executes the `step` method\n- Tests all possible outcomes of an instruction and state updates\n\nIn this example, the instruction can either be skipped or not skipped depending on the arguments, and both cases are tested.\n\n```js\n// tests/cpu.test.js\n\ntest('6: SE_VX_NN (3xnn) - Program counter should increment by two bytes if register x is not equal to nn argument', () =\u003e {\n  cpu.load({ data: [0x3abb] })\n  cpu.step()\n\n  expect(cpu.PC).toBe(0x202)\n})\n\ntest('6: SE_VX_NN (3xnn) - Program counter should increment by four bytes if register x is equal to nn argument', () =\u003e {\n  cpu.load({ data: [0x3abb] })\n  cpu.registers[0xa] = 0xbb\n\n  cpu.step()\n\n  expect(cpu.PC).toBe(0x204)\n})\n```\n\n## Acknowledgements\n\n- Inspiration, guidance, and mentorship from [Vanya Sergeev](https://sergeev.io).\n- [Cowgod's Chip-8 Technical Reference](http://devernay.free.fr/hacks/chip8/C8TECH10.HTM#8xy3), made by Thomas P. Greene.\n- [CHIP-8 - Wikipedia](https://en.wikipedia.org/wiki/CHIP-8).\n\n## Author\n\n- [Tania Rascia](https://www.taniarascia.com)\n\n## License\n\nThis project is open source and available under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaniarascia%2Fchip8","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaniarascia%2Fchip8","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaniarascia%2Fchip8/lists"}