{"id":17976655,"url":"https://github.com/bzier/gym-mupen64plus","last_synced_at":"2025-03-05T11:12:42.905Z","repository":{"id":39969536,"uuid":"84015460","full_name":"bzier/gym-mupen64plus","owner":"bzier","description":"An OpenAI Gym environment wrapper for the Mupen64Plus N64 emulator","archived":false,"fork":false,"pushed_at":"2024-08-30T23:49:11.000Z","size":48519,"stargazers_count":93,"open_issues_count":25,"forks_count":41,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-02-26T10:11:21.047Z","etag":null,"topics":["ai","gym","gym-environment","gym-library","machine-learning","mupen64plus","n64","nintendo-64","openai-gym","reinforcement-learning"],"latest_commit_sha":null,"homepage":"","language":"Python","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/bzier.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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-03-06T01:10:03.000Z","updated_at":"2025-01-27T03:02:05.000Z","dependencies_parsed_at":"2025-01-13T06:05:41.631Z","dependency_job_id":"17ca4198-cea9-4e81-af11-d6f70bacdb21","html_url":"https://github.com/bzier/gym-mupen64plus","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/bzier%2Fgym-mupen64plus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzier%2Fgym-mupen64plus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzier%2Fgym-mupen64plus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzier%2Fgym-mupen64plus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bzier","download_url":"https://codeload.github.com/bzier/gym-mupen64plus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242014715,"owners_count":20057879,"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":["ai","gym","gym-environment","gym-library","machine-learning","mupen64plus","n64","nintendo-64","openai-gym","reinforcement-learning"],"created_at":"2024-10-29T17:24:37.324Z","updated_at":"2025-03-05T11:12:42.861Z","avatar_url":"https://github.com/bzier.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gym-mupen64plus\n\nThis project is an [OpenAI Gym](https://github.com/openai/gym/) environment wrapper for the [Mupen64Plus](http://www.mupen64plus.org/) N64 emulator. The goal of this project is to provide a platform for reinforcement learning agents to be able to easily interface with N64 games using the OpenAI gym library. This should allow for easier adaptation of existing agents that have been built using the gym library to play Atari games, for example.\n\nCurrently, only MarioKart64 and SuperSmashBros have been wrapped, but the core environment has been built to support any game. This top-level README will be used to describe the basic setup instructions, architecture of the environment, etc. Each game that gets wrapped will have its own README file within its respective subdirectory. This top-level README will link to each of the games' README file as well.\n\n#### Thanks:\nMany of the core concepts for this wrapper were borrowed/adapted directly from [@kevinhughes27](https://github.com/kevinhughes27)'s fantastic [TensorKart](https://github.com/kevinhughes27/TensorKart) project (self-driving MarioKart with TensorFlow). A huge thanks goes out to him for inspiring the foundation of this project.\n\nAnother big thanks to everyone who has contributed to the project so far. I appreciate the help, from the small typo/bug fixes to the large implementations.\n\n## Contributing\n\nPlease create issues as you encounter them. Future work and ideas will be captured as issues as well, so if you have any ideas of things you'd like to see, please add them. Also, feel free to fork this repository and improve upon it. If you come up with something you'd like to see incorporated, submit a pull request. Adding support for additional games would be a great place to start. If you do decide to implement support for a game, please create an issue mentioning what game you are working on. This will help organize the project and prevent duplicate work.\n\n## Setup\n\nThe easiest, cleanest, most consistent way to get up and running with this project is via [`Docker`](https://docs.docker.com/). These instructions will focus on that approach.\n\n### Running with docker-compose\n\n**Pre-requisites:**\n- Docker \u0026 docker-compose\n- Ensure you have a copy of the ROMs you wish to use. See the [Games](#Games) section below for details.\n\n**Steps:**\n1. Run the following command to build \u0026 run the project via `docker-compose`.\n\n    ```sh\n    docker-compose up --build -d\n    ```\n\n    This will start the following 4 containers:\n    - `xvfbsrv` runs XVFB\n    - `vncsrv` runs a VNC server connected to the Xvfb container\n    - `agent` runs the example python script\n    - `emulator` runs the mupen64plus emulator\n\n2. Then you can use your favorite VNC client (e.g., [VNC Viewer](https://www.realvnc.com/en/connect/download/viewer/)) to connect to `localhost` to watch the XVFB display in real-time. Note that running the VNC server and client can cause some performance overhead.\n\n3. ### That's it!\n\n    ...wait... that's it??\n\n    Yup... Ah, the beauty of Docker.\n\n\u003cbr/\u003e\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eMiscelaneous notes (click to expand):\u003c/b\u003e\u003c/summary\u003e\n\n- After connecting with a VNC client, depending how quickly you connected, you should see the environment navigate the menus to select the track/character, then Mario will wait for the green light, drive straight briefly and then start doing doughnuts.\n\n- The script will run for a bit more than 10,000 steps before prompting for input. Without an interactive terminal, if you waited until the end, this will hit an EOF and exit. Mario will appear to have frozen since the XVFB screen is no longer being updated.\n\n- You can view the output from the `example.py` script by tailing the agent container logs. You can see sample output [here](docs/example_script_output.md).\n    ```\n    docker logs -f gym-mupen64plus_agent_1\n    ```\n- You can clean up with:\n    ```\n    docker-compose down\n    ```\n\n\u003c/details\u003e\u003cbr/\u003e\n\n### Building the Docker image\n\nIf you would like to build the docker image on its own (outside of docker-compose), you can:\n\n1. Run the following command to build the project's docker image\n\n    \u003e You should substitute the placeholders between `\u003c \u003e` with your own values.\n\n    ```sh\n    docker build -t \u003cimage_name\u003e:\u003ctag\u003e .\n    ```\n    ```sh\n    # Example:\n    docker build -t bz/gym-mupen64plus:0.0.5 .\n    ```\n\n### Without Docker\n\n\u003cdetails\u003e\n  \u003csummary\u003e:( click to expand :(\u003c/summary\u003e\n  \n  \u003e It is possible to run without Docker, but there isn't a compelling reason to and it just introduces a significant amount of setup work and potential complications.\n  \u003e\n  \u003e **`Fair warning:`** I likely will ***not*** be testing manual setup or maintaining its documentation going forward so it may become stale over time.\n  \u003e\n  \u003e However, if you really do want to, here are the [old instructions](docs/manual_setup.md).\n\n\u003c/details\u003e\u003cbr/\u003e\n\n## Example Agents\n\n### Simple Test:\n\nThe docker-compose steps above are the easiest approach to get started. However, if you build the image separately and would like to test without using docker-compose, you can.\n\nA simple [example](./example.py) to test if the environment is up-and-running:\n```sh\n# Note: if you have placed your ROMs in a different location, be sure to update the source path in the command.\ndocker run -it \\\n  --name test-gym-env \\\n  -p 5900 \\\n  --mount source=\"$(pwd)/gym_mupen64plus/ROMs\",target=/src/gym-mupen64plus/gym_mupen64plus/ROMs,type=bind \\\n  bz/gym-mupen64plus:0.0.5 \\ # This should match the image \u0026 tag you used during setup above\n  python gym-mupen64plus/example.py\n```\n\nThe example script will repeat doughnuts for 10,000 steps. You can see sample output [here](docs/example_script_output.md).\n\n**Clean up:**\n\nYou can kill the process (and exit the container) by hitting `ctrl`+`c` (probably a few times), and you can remove the container with:\n```sh\ndocker rm test-gym-env\n```\n\n### AI Agent (supervised learning):\nThe original inspiration for this project has now been updated to take advantage of this gym environment. It is an example of using supervised learning to train an AI Agent that is capable of interacting with the environment (Mario Kart). It utilizes the TensorFlow library for its machine learning. Check out TensorKart [here](https://github.com/kevinhughes27/TensorKart).\n\n\n### AI Agent (reinforcement learning):\nAn adaptation of the A3C algorithm has been applied to this environment (Mario Kart) and is capable of training from scratch (zero knowledge) to successfully finish races. Check out that agent [here](https://github.com/bzier/universe-starter-agent/tree/mario-kart-agent).\n\n\n## Games\n\n**ROM files:**\n\n*Links to ROM files will not be included here. Use your ninja skills as appropriate.*\n\nROM files can be placed in `./gym_mupen64plus/ROMs/`. If you wish to place them elsewhere, update your `.env` file with the path. See the game READMEs below for details about specific games, including specifying the proper ROM file name.\n\n**Game docs:**\n\nHere is a list of games that have been wrapped. Each game may support multiple 'modes' with different levels or missions configured. See each of the games' pages for more details.\n* [MarioKart64](gym_mupen64plus/envs/MarioKart64/README.md)\n* [Super Smash Bros](gym_mupen64plus/envs/Smash/README.md)\n\n\u003cbr/\u003e\n\n# Additional Documentation:\n\n* [Architecture](docs/architecture.md)\n* [Thread Synchronization](docs/threadSynchronization.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbzier%2Fgym-mupen64plus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbzier%2Fgym-mupen64plus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbzier%2Fgym-mupen64plus/lists"}