{"id":15036042,"url":"https://github.com/baekalfen/pyboy","last_synced_at":"2025-05-15T00:00:31.428Z","repository":{"id":32906774,"uuid":"36501634","full_name":"Baekalfen/PyBoy","owner":"Baekalfen","description":"Game Boy emulator written in Python","archived":false,"fork":false,"pushed_at":"2025-05-07T19:09:01.000Z","size":46207,"stargazers_count":4862,"open_issues_count":35,"forks_count":500,"subscribers_count":76,"default_branch":"master","last_synced_at":"2025-05-07T23:29:19.246Z","etag":null,"topics":["cython","emulator","gameboy","gameboy-emulator","gameboy-emulator-library","pypy","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Baekalfen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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}},"created_at":"2015-05-29T11:58:11.000Z","updated_at":"2025-05-07T19:05:50.000Z","dependencies_parsed_at":"2023-10-23T11:36:03.807Z","dependency_job_id":"c989503d-c4fc-4393-a321-2d12a58918e8","html_url":"https://github.com/Baekalfen/PyBoy","commit_stats":{"total_commits":740,"total_committers":37,"mean_commits":20.0,"dds":0.7608108108108108,"last_synced_commit":"8cf3f1f11dd34e6838174ac3680553bf962e4171"},"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Baekalfen%2FPyBoy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Baekalfen%2FPyBoy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Baekalfen%2FPyBoy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Baekalfen%2FPyBoy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Baekalfen","download_url":"https://codeload.github.com/Baekalfen/PyBoy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254249199,"owners_count":22039029,"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":["cython","emulator","gameboy","gameboy-emulator","gameboy-emulator-library","pypy","python"],"created_at":"2024-09-24T20:29:59.006Z","updated_at":"2025-05-15T00:00:31.341Z","avatar_url":"https://github.com/Baekalfen.png","language":"Python","readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"extras/README/pyboy.svg\" width=\"480\"\u003e\n\u003c/p\u003e\n\n__If you have any questions, or just want to chat, [join us on Discord](https://discord.gg/wUbag3KNqQ).__\n\n[![Discord](https://img.shields.io/discord/584149554132418570?style=for-the-badge\u0026logo=Discord\u0026label=PyBoy)](https://discord.gg/wUbag3KNqQ)\n\n\u003c!---\nGenerate GIF with the layout and captions\n--\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd colspan=2 align=\"center\"\u003e\u003ca href=https://github.com/PWhiddy/PokemonRedExperiments\u003eTrain RL agents to play Pokemon Red\u003c/a\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\u003ca href=https://github.com/Baekalfen/PyBoy/wiki/Experimental-and-optional-features#rewind-time\u003eRewind any game\u003c/a\u003e\u003cbr\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd colspan=2 align=\"center\"\u003e\n        \u003cdiv align=\"center\"\u003e\n        \u003ca href=\"http://www.youtube.com/watch?feature=player_embedded\u0026v=DcYLT37ImBY\" target=\"_blank\"\u003e\n        \u003cimg src=\"http://img.youtube.com/vi/DcYLT37ImBY/maxresdefault.jpg\" alt=\"Watch the video\" width=\"500\" border=\"10\" /\u003e\n        \u003c!-- \u003cimg src=\"http://img.youtube.com/vi/DcYLT37ImBY/hqdefault.jpg\" alt=\"Watch the video\" width=\"500\" border=\"10\" /\u003e --\u003e\n        \u003c/a\u003e\n        \u003c!-- https://www.youtube.com/watch?v=DcYLT37ImBY --\u003e\n        \u003c!-- \u003cimg src=\"extras/README/8.gif\" width=\"400\"\u003e\u003cbr\u003e --\u003e\n        \u003c/div\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003cimg src=\"extras/README/5.gif\" width=\"250\"\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\"\u003ePlay the classics\u003cbr\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\u003ca href=https://github.com/lixado/PyBoy-RL\u003eCreate your own AI\u003c/a\u003e\u003cbr\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\u003ca href=https://github.com/uiucanh/tetris\u003eBeat world records with AI\u003c/a\u003e\u003cbr\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003cimg src=\"extras/README/1.gif\" width=\"250\"\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003cimg src=\"extras/README/6.gif\" width=\"250\"\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003cimg src=\"extras/README/7.gif\" width=\"250\"\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\nGetting Started\n===============\nThe instructions are simple:\n\n```sh\n$ pip install pyboy\n```\n\nFor details, see [installation instructions](https://github.com/Baekalfen/PyBoy/wiki/Installation).\n\nNow you're ready! Either use PyBoy directly from the terminal\n```sh\n$ pyboy game_rom.gb\n```\n\nOr use it in your Python scripts:\n```python\nfrom pyboy import PyBoy\npyboy = PyBoy('game_rom.gb')\nwhile pyboy.tick():\n    pass\npyboy.stop()\n```\n\n\u003c!-- Or using the context manager:\n```python\nfrom pyboy import PyBoy\nwith PyBoy('game_rom.gb') as pyboy:\n    while pyboy.tick():\n        pass\n``` --\u003e\n\n\nThe API\n=======\n\nIf you are looking to make a bot or AI, then these resources are a good place to start:\n * [PyBoy API Documentation](https://baekalfen.github.io/PyBoy/index.html)\n * [Wiki Pages](https://github.com/Baekalfen/PyBoy/wiki/)\n   * [Using PyBoy with Gym](https://github.com/Baekalfen/PyBoy/wiki/Using-PyBoy-with-Gym)\n   * [Example: Kirby](https://github.com/Baekalfen/PyBoy/wiki/Example-Kirby)\n   * [Example: Tetris](https://github.com/Baekalfen/PyBoy/wiki/Example-Tetris)\n   * [Example: Super Mario Land](https://github.com/Baekalfen/PyBoy/wiki/Example-Super-Mario-Land)\n   * [Code Examples](https://github.com/Baekalfen/PyBoy/tree/master/extras/examples)\n * [Discord](https://discord.gg/wUbag3KNqQ)\n\n\nWhen the emulator is running, you can easily access [PyBoy's API](https://baekalfen.github.io/PyBoy/index.html):\n```python\npyboy.set_emulation_speed(0) # No speed limit\npyboy.button('down')\npyboy.button('a')\npyboy.tick() # Process at least one frame to let the game register the input\nvalue_of_interest = pyboy.memory[0xC345]\n\npil_image = pyboy.screen.image\npil_image.save('screenshot.png')\n```\n\nThe [Wiki](https://github.com/Baekalfen/PyBoy/wiki) shows how to interface with PyBoy from your own project.\n\nPerformance\n===========\n\nPerformance is a priority for PyBoy, to make your AI training and scripts as fast as possible.\n\nThe easiest way to improve your performance, is to skip rendering of unnecessary frames. If you know your\ncharacter takes X frames to move, or the game doesn't take input every frame, you can skip those to potentially triple\nyour performance. All game logic etc. will still process.\n\nHere is a simple comparison of rendering every frame, rendering every 15th frame, and not rendering any frames (higher is better). See [`pyboy.tick`](https://docs.pyboy.dk/#pyboy.PyBoy.tick) for how it works. Your performance will depend on the game.\n\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\"\u003e\n        Full rendering\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        Frame-skip 15\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        No rendering\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\n      x124 realtime\n      \u003c/td\u003e\n      \u003ctd\u003e\n      x344 realtime\n      \u003c/td\u003e\n      \u003ctd\u003e\n      x395 realtime\n      \u003c/td\u003e\n    \u003c/tr\u003e\n\u003ctr\u003e \u003c!-- Markdown/HTML broken after this --\u003e\n\u003ctd\u003e\n\n```python\nfor _ in range(target):\n    pyboy.tick()\n\n```\n\u003c/td\u003e\n\u003ctd \u003e\n\n```python\nfor _ in range(target//15):\n    pyboy.tick(15)\n\n```\n\u003c/td\u003e\n\u003ctd \u003e\n\n```python\npyboy.tick(target, False)\n\n```\n\u003c/td\u003e\n\u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\nThe Game Boy was originally running at 60 frames per second, so a speed-up of 100x realtime is 6,000 frames per\nsecond. And trivially from the table above, simulating 395 hours of gameplay can be done in 1 hour with no rendering.\n\nIt's also recommended to be running multiple instances of PyBoy in parallel. On an 8-core machine, you could potentially\ndo 3160 hours of gameplay in 1 hour.\n\nContributing\n============\nAny contribution is appreciated. The currently known problems are tracked in [the Issues tab](https://github.com/Baekalfen/PyBoy/issues). Feel free to take a swing at any one of them. If you have something original in mind, come and [discuss it on on Discord](https://discord.gg/wUbag3KNqQ).\n\n[![Discord](https://img.shields.io/discord/584149554132418570?style=for-the-badge\u0026logo=Discord\u0026label=PyBoy)](https://discord.gg/wUbag3KNqQ)\n\nFor the more major features, there are the following that you can give a try. They are also described in more detail in the [project list in the Wiki](https://github.com/Baekalfen/PyBoy/wiki/Student-Projects):\n* Hacking games\n* Link Cable\n* Debugger (VSCode, GDB, terminal or otherwise)\n* AI - [use the `api`](https://baekalfen.github.io/PyBoy/index.html) or game wrappers to train a neural network\n* Game Wrappers - make wrappers for popular games\n\nIf you want to implement something which is not on the list, feel free to do so anyway. If you want to merge it into our repo, then just send a pull request and we will have a look at it.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaekalfen%2Fpyboy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbaekalfen%2Fpyboy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaekalfen%2Fpyboy/lists"}