{"id":22122736,"url":"https://github.com/timendus/thumby-silicon8","last_synced_at":"2025-07-25T14:31:08.785Z","repository":{"id":39165136,"uuid":"432843568","full_name":"Timendus/thumby-silicon8","owner":"Timendus","description":"An interpreter for CHIP-8, SCHIP and XO-CHIP in MicroPython for the Thumby playable keychain by TinyCircuits","archived":false,"fork":false,"pushed_at":"2022-09-09T12:20:55.000Z","size":1840,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2023-08-02T06:47:07.439Z","etag":null,"topics":["chip-8","emulator","interpreter","micropython","schip","thumby","tinycircuits","vm","xo-chip"],"latest_commit_sha":null,"homepage":"","language":"Python","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}},"created_at":"2021-11-28T22:49:42.000Z","updated_at":"2023-08-02T06:47:07.439Z","dependencies_parsed_at":"2023-01-17T18:15:22.989Z","dependency_job_id":null,"html_url":"https://github.com/Timendus/thumby-silicon8","commit_stats":null,"previous_names":[],"tags_count":2,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Timendus%2Fthumby-silicon8","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Timendus%2Fthumby-silicon8/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Timendus%2Fthumby-silicon8/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Timendus%2Fthumby-silicon8/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Timendus","download_url":"https://codeload.github.com/Timendus/thumby-silicon8/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227584474,"owners_count":17789702,"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","emulator","interpreter","micropython","schip","thumby","tinycircuits","vm","xo-chip"],"created_at":"2024-12-01T15:27:33.884Z","updated_at":"2024-12-01T15:27:34.519Z","avatar_url":"https://github.com/Timendus.png","language":"Python","funding_links":["https://ko-fi.com/T6T0DOOWP"],"categories":[],"sub_categories":[],"readme":"[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/T6T0DOOWP)\n\n# Silicon8 for Thumby\n\n**Silicon8 for Thumby** is an interpreter for the CHIP-8, SCHIP and XO-CHIP\nprogramming languages. It allows you to run games made for those platforms on your [Thumby](https://thumby.us/).\n\n![3D VIP'r Maze, running on the Thumby](./pictures/hardware-3d-vipr-maze.jpg)\n\n**[CHIP-8](https://en.wikipedia.org/wiki/CHIP-8)** is an interpreted programming\nlanguage, going back to the '70s. It was initially used on the COSMAC VIP and\nTelmac 1800 8-bit microcomputers and was made to allow video games to be more\neasily programmed for and shared among these computers. In 1990 CHIP-8 saw a\nrevival in the form or **SCHIP** on HP-48 graphing calculators, and in more\nrecent years the **XO-CHIP** extension has given it more colours, memory and\nbetter sound. Many people still write new software for this platform, not in the\nleast at the yearly [Octojam](https://itch.io/jam/octojam-8).\n\nAs such, there is an impressive library of programs and games available for\nCHIP-8 and friends. And we can now run almost all of them on Thumby too! 👾🕹\n\n![Silicon8 running in the Thumby emulator](./pictures/emu-video2.gif)\n\u003cbr/\u003e_Note: Runs faster and with less flicker on hardware_\n\nDue to the limited computing power and low screen resolution of CHIP-8, I\nthought this is a great fit for the Thumby, and also a testament of how far\ncomputers have come. What was once the pinnacle of computer gaming for hobbyists\nnow runs easily on a cheap keychain, with pixels and memory to spare 😄\n\n(The original [Silicon8](https://github.com/Timendus/silicon8) is written in Go,\nand targeted mainly at WebAssembly. It can be [run in your web browser\nhere](https://timendus.github.io/silicon8/). This version of it is a port to\nMicroPython for the Thumby playable keychain.)\n\n## Caveats and warnings\n\nThis is my first experiment with MicroPython and the Thumby, so it's probably an\ninefficient mess in the eyes of a \"real\" MicroPython developer. But this is a\nfun learning project for me 😄\n\nThere are a couple of small known issues, [see below](#known-issues) if you run\ninto trouble.\n\n## Installation\n\nSilicon8 is in the Thumby \"Arcade\". You can install it with a couple of clicks\nby going to [arcade.thumby.us](https://arcade.thumby.us).\n\nHowever, the arcade sometimes glitches out, in which case you follow the steps\nbelow to install Silicon8 manually on your device.\n\nGet the MicroPython files from this Github repository if you know your way\naround git or download the ZIP file for the latest version on the [releases\npage](https://github.com/Timendus/thumby-silicon8/releases). Put the `*.py`\nfiles in `/Games/Silicon8` on your Thumby using the [Thumby Code\nEditor](https://code.thumby.us/):\n\n1. Connect your Thumby, wait for the file system tree to load\n2. Right-click on \"Games\" in the file system tree and select \"New folder\"\n3. Type in `Silicon8` and press Enter\n4. Click \"Upload\" at the bottom of the file system panel, select all the `.py`\n   files from [`/Games/Silicon8` in this repository](./Games/Silicon8)\n5. Select `/Games/Silicon8` as the destination path (\"Final Path\") on the Thumby\n   and click \"Ok\"\n6. Continue below to add some actual games\n\n### Getting CHIP-8 ROMs into Silicon8 for Thumby\n\nCHIP-8 ROMs should be placed on your Tumby in the `/Games/Silicon8/chip8`\ndirectory. To get you started, you can copy the games in this repository to your\ndevice:\n\n1. Right-click on \"Silicon8\" in the file system tree and select \"New folder\"\n2. Type in `chip8` and press Enter\n3. Click \"Upload\" at the bottom of the file system panel, select all the `.ch8`\n   and `.ch8.json` files from the [`/Games/Silicon8/chip8` folder in this\n   repository](./Games/Silicon8/chip8)\n4. Select `/Games/Silicon8/chip8` as the destination path (\"Final Path\") on the\n   Thumby and click \"Ok\"\n5. Disconnect and reboot your Thumby, you should now see \"Silicon8\" in the menu.\n   Starting it should show you all the game ROMs you copied.\n6. Select a ROM file and start playing!\n\nYou can quit a running CHIP-8 ROM and return to the Silicon8 menu at any time by\nholding down the key combination `LEFT`, `A` and `B`.\n\n#### Adding more CHIP-8 ROMs\n\nYou can put any `*.ch8` file in your CHIP-8 ROMs directory and it will be picked\nup by Silicon8. You can find many ROMs on the Internet and in particular on the\n[CHIP-8 Archive](https://johnearnest.github.io/chip8Archive/). If you want to,\nor if you need to change the controls or interpreter type, you can add a JSON\nfile with the same name but an added extension `.json` (so `somegame.ch8` would\nbecome `somegame.ch8.json`) to configure your ROM.\n\nThe JSON config file accepts this structure:\n\n```json\n{\n  \"name\": \"The Classic Game of Pong\",\n  \"link\": \"https://a-link-to.some/info/if-available\",\n  \"desc\": \"A short and clear description of the game and its controls\",\n  \"type\": \"SCHIP\",\n  \"keys\": {\n    \"up\": 1,\n    \"down\": 4\n  }\n}\n```\n\nAll fields are optional. Valid options for `type` are `AUTO` (default), `VIP`,\n`SCHIP` or `XOCHIP`. Valid options for the keys are `up`, `down`, `left`,\n`right`, `a` and `b` for all the buttons on the Thumby. The numeric values are\nthe corresponding keys to be pressed on the CHIP-8 keypad (0 - 15).\n\n## Known issues\n\nThe interpretation of CHIP-8, SCHIP and XO-CHIP should be pretty close to the\noriginals. However, there are a few issues to be aware of. If you find issues\nthat are not described below, please [file an\nissue](https://github.com/Timendus/thumby-silicon8/issues/new).\n\n### Display limitations\n\nDue to the small screen size and the limited colours of the Thumby, Silicon8 for\nThumby is currently limited to `lowres` mode (64x32 pixels) in monochrome. If\nyour ROM uses `hires` mode, the central 72x40 pixels will be shown and the rest\ndiscarded, which doesn't make for great gameplay. When using XO-CHIP's four\ncolour mode, only plane 1 will be rendered to the screen.\n\nI have some ideas on how to improve this in the future, but I will need to play\nwith the physical hardware some more to see if those ideas are feasible.\n\n### Sound limitations\n\nThe Thumby has a very simple speaker. Silicon8 uses it for the CHIP-8 beeper\nsound. The full XO-CHIP audio capabilities are not (yet) supported though.\n\nThe current Thumby library does not expose the speaker in a more complicated way\nthan setting a frequency and a duty cycle. You can, however, bypass the library\nand talk to the pin directly. Implementing XO-CHIP audio on this low a level\nwill be a bit of a chore, that I have not yet felt like doing 😄🎶\n\n### Speed\n\nThis interpreter is not particularly fast in the Thumby emulator. It's a lot\nfaster, and quite playable, on the actual hardware though. If you have any ideas\nor suggestions on how to boost the speed, please let me know. An issue or pull\nrequest on this repository will get my attention.\n\n### Type \"AUTO\"\n\nLike the original Silicon8, Silicon8 for Thumby has a mode \"AUTO\" that tries to\nauto-detect the right interpreter type. This doesn't always correctly identify\nSCHIP and XO-CHIP programs when they do rely on quirks for those platforms, but\ndon't use any of the features of those platforms. You can easily work around\nthis issue by specifying the interpreter type explicitly in the JSON config\nfile that corresponds to your wrongly detected ROM.\n\n## Screenshots from the emulator\n\n![The Silicon8 for Thumby splash screen](./pictures/emu-splash.png) ![Silicon8 for Thumby in action](./pictures/emu-video.gif)\n\n![The Silicon8 for Thumby ROM selection screen](./pictures/emu-menu.png) ![The Silicon8 for Thumby ROM details screen](./pictures/emu-details.png)\n\n![Gameplay of the game PONG](./pictures/emu-pong.png) ![Gameplay of the game Space Invaders](./pictures/emu-space.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimendus%2Fthumby-silicon8","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimendus%2Fthumby-silicon8","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimendus%2Fthumby-silicon8/lists"}