{"id":18282576,"url":"https://github.com/rafael-santiago/cp-8","last_synced_at":"2025-04-09T05:25:32.257Z","repository":{"id":80005643,"uuid":"77791580","full_name":"rafael-santiago/CP-8","owner":"rafael-santiago","description":"A minimalist CHIP-8 interpreter/emulator (ANSI/TERM).","archived":false,"fork":false,"pushed_at":"2017-01-28T13:01:05.000Z","size":210,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-14T23:48:04.375Z","etag":null,"topics":["c","chip8-emulator","chip8-interpreter","diycode","emulator","interpreter","pure-c","retrocomputing","retroprogramming"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rafael-santiago.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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":"2017-01-01T18:39:47.000Z","updated_at":"2023-01-31T23:21:32.000Z","dependencies_parsed_at":"2023-05-26T04:30:44.040Z","dependency_job_id":null,"html_url":"https://github.com/rafael-santiago/CP-8","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafael-santiago%2FCP-8","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafael-santiago%2FCP-8/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafael-santiago%2FCP-8/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafael-santiago%2FCP-8/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rafael-santiago","download_url":"https://codeload.github.com/rafael-santiago/CP-8/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247983031,"owners_count":21028232,"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":["c","chip8-emulator","chip8-interpreter","diycode","emulator","interpreter","pure-c","retrocomputing","retroprogramming"],"created_at":"2024-11-05T13:05:37.637Z","updated_at":"2025-04-09T05:25:32.227Z","avatar_url":"https://github.com/rafael-santiago.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CP-8\n\nThis code is a work in progress and yes, it is about a ``CHIP-8`` emulator that uses ``ANSI/TERM`` stuff to emulate\nthe screen output.\n\nWell, here follows some ``CHIP-8 ROMs`` emulated with this software:\n\n|  **INVADERS**  |    **TIC-TAC**   |   **WIPE-OFF**   |\n|:--------------:|:----------------:|:----------------:|\n|![INVADERS](https://github.com/rafael-santiago/CP-8/blob/master/etc/invaders.jpeg)|![TIC-TAC](https://github.com/rafael-santiago/CP-8/blob/master/etc/tictac.jpeg)|![WIPE-OFF](https://github.com/rafael-santiago/CP-8/blob/master/etc/wipeoff.jpeg)|\n|   **MERLIN**   |      **UFO**     |     **TANK**     |\n|![MERLIN](https://github.com/rafael-santiago/CP-8/blob/master/etc/merlin.jpeg)|![UFO](https://github.com/rafael-santiago/CP-8/blob/master/etc/ufo.jpeg)|![TANK](https://github.com/rafael-santiago/CP-8/blob/master/etc/tank.jpeg)|\n|   **TETRIS**   |     **HIDDEN**   |    **MISSILE**   |\n|![TETRIS](https://github.com/rafael-santiago/CP-8/blob/master/etc/tetris.jpeg)|![HIDDEN](https://github.com/rafael-santiago/CP-8/blob/master/etc/hidden.jpeg)|![MISSILE](https://github.com/rafael-santiago/CP-8/blob/master/etc/missile.jpeg)|\n\n## How to clone this repo?\n\nWell, I use some ``git-submodules`` here so:\n\n```\nwatson@BakerStreet221B:~/src/clues/rafael-santiago# git clone \\\n\u003e https://github.com/rafael-santiago/CP-8\nwatson@BakerStreet221B:~/src/clues/rafael-santiago# cd CP-8\nwatson@BakerStreet221B:~/src/clues/rafael-santiago/CP-8# git \\\n\u003e submodule update --init\n```\n\nIf the incantations above are trickier for you, try:\n\n```\nwatson@BakerStreet221B:~/src/clues/rafael-santiago# git clone \\\n\u003e https://github.com/rafael-santiago/CP-8 --recursive\n```\n\nDone.\n\n## How to build it?\n\nMy code my rules. I use my own [build system](https://github.com/rafael-santiago/hefesto). Once ``Hefesto`` well-installed and working\non your system you should move to CP-8's ``src`` sub-directory and invoke ``hefesto`` from there... Something like:\n\n```\nwatson@BakerStreet221B:~/src/clues/rafael-santiago/src/CP-8# cd src\nwatson@BakerStreet221B:~/src/clues/rafael-santiago/src/CP-8/src# hefesto\n(...)\nwatson@BakerStreet221B:~/src/clues/rafael-santiago/src/CP-8/src# _\n```\n\nAfter invoking \"hefesto\" you will get the binary ``cp8`` under ``../bin`` sub-directory.\n\n## How to install/uninstall it?\n\nFirstly all should be done under ``src`` sub-directory and then...\n\n### Install\n\n```\nwatson@BakerStreet221B:~/src/clues/rafael-santiago/src/CP-8/src# hefesto --install\n```\n\n### Uninstall\n\n```\nwatson@BakerStreet221B:~/src/clues/rafael-santiago/src/CP-8/src# hefesto --uninstall\n```\n\nAnswer the questions confirming your choice and you will get this software installed on your environment.\n\n## How to use it?\n\nThis application works based on tasks. So you need to inform the ``task`` and its ``--arguments=(...)``. Each task\nrequires its own specific arguments.\n\nThe ``emulate`` task is pretty obvious, you will use it to play the ``CHIP-8`` games on the following way:\n\n```\nsherlock@BakerStreet221B:~/src/clues/rafael-santiago/src/CP-8/src# ../bin/cp8 emulate \\\n\u003e --rom=/home/sherlock/rom/PUZZLE\n```\n\nThis emulation task does not re-map any key. However, you have some special keys, look the **Table 1**.\n\n**Table 1**: Special keys recognized during an emulation task.\n\n|     **Key**         |              **Action**              |\n|:-------------------:|:------------------------------------:|\n|      ``R``          |  Reset/Restart the ``ROM`` execution |\n|      ``P``          |  Pause the ``ROM`` execution         |\n|      ``ESC``        |  Exit the program                    |\n\n## Additional tasks\n\nIn spite of being mainly a ``CHIP-8`` emulator I have written some minor tasks for this software.\nHere in this section you can find information about them.\n\n### The umount task\n\nThis task should be useful to anyone who wants to probe the code of a ``CHIP-8 ROM``. Using it you are able\nto disassemble the machine code.\n\nThe usage is pretty straightforward:\n\n```\nsherlock@BakerStreet221B:~/src/clues/rafael-santiago/src/CP-8/src# cp8 umount \\\n\u003e --rom=/home/sherlock/rom/PUZZLE\n```\n\nThe default output is the ``stdout`` if you want to spit the assembly mnemonics to another file:\n\n```\nsherlock@BakerStreet221B:~/src/clues/rafael-santiago/src/CP-8/src# cp8 umount \\\n\u003e --rom=/home/sherlock/rom/PUZZLE --out=Elementary.c8\n```\n\nA \"umounted\" ``ROM`` looks like it:\n\n```assembly\nLD VA, 0x12\nLD VB, 0x01\nLD V1, 0x10\nLD V2, 0x00\nLD V0, 0x00\nLD I, 0x2b0\nDRW V1, V2, 0x7\nLD F, V0\nSE V0, 0x00\nDRW VA, VB, 0x5\nADD V1, 0x08\nADD VA, 0x08\nSE V1, 0x30\nJP 0x224\nLD V1, 0x10\nADD V2, 0x08\nLD VA, 0x12\nADD VB, 0x08\nLD I, 0x300\nADD I, V0\nLD [I], V0\nADD V0, 0x01\nSE V0, 0x10\nJP 0x20a\nLD VA, 0x12\nLD VB, 0x01\nLD VC, 0x00\nLD V2, 0xff\nRND V0, 0x06\nADD V0, 0x02\nCALL 0x252\n(...)\n```\n\nAs you can see the ``CHIP-8 Assembly`` is pretty simple with a short processor's instruction set.\n\nIf you started to write code when people usually had to compile, worry about memory, program size, etc... You may know that is\nnot a good idea let a data chunk in the middle of a instruction chunk... Due to it this disassembler skips the first data\nchunk when the first instruction is a jump. I said \"data chunk\" because in the old days was common you pick up a ``ROM`` with\nsome copyright disclaimer before the real program \"text\". Then a ``ROM`` that mixes data and instructions at random in any\nplace will produce a \"screwed up\" output. However, it is considered a bad practice and uncommon because it could be dangerous\nin that days...\n\n## Issues, limitations, known bugs, raptors, etc, .*\n\n((( Coming soon... work in progress... )))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frafael-santiago%2Fcp-8","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frafael-santiago%2Fcp-8","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frafael-santiago%2Fcp-8/lists"}