{"id":30983046,"url":"https://github.com/michaeltmatthews/craftax","last_synced_at":"2025-10-07T02:18:03.162Z","repository":{"id":220499247,"uuid":"751798282","full_name":"MichaelTMatthews/Craftax","owner":"MichaelTMatthews","description":"(Crafter + NetHack) in JAX.  ICML 2024 Spotlight.","archived":false,"fork":false,"pushed_at":"2025-07-07T03:12:02.000Z","size":54967,"stargazers_count":331,"open_issues_count":3,"forks_count":37,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-09-12T10:42:13.564Z","etag":null,"topics":["benchmark","environment","icml-2024","machine-learning","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/MichaelTMatthews.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-02-02T10:56:30.000Z","updated_at":"2025-08-25T05:20:14.000Z","dependencies_parsed_at":"2024-02-02T12:24:41.252Z","dependency_job_id":"dc04ee2d-dc1c-4d74-967f-774b1a84f6f9","html_url":"https://github.com/MichaelTMatthews/Craftax","commit_stats":null,"previous_names":["michaeltmatthews/craftax"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/MichaelTMatthews/Craftax","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelTMatthews%2FCraftax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelTMatthews%2FCraftax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelTMatthews%2FCraftax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelTMatthews%2FCraftax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MichaelTMatthews","download_url":"https://codeload.github.com/MichaelTMatthews/Craftax/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichaelTMatthews%2FCraftax/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278708004,"owners_count":26031932,"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","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["benchmark","environment","icml-2024","machine-learning","reinforcement-learning"],"created_at":"2025-09-12T10:30:36.291Z","updated_at":"2025-10-07T02:18:03.143Z","avatar_url":"https://github.com/MichaelTMatthews.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n \u003cimg width=\"80%\" src=\"https://raw.githubusercontent.com/MichaelTMatthews/Craftax/main/images/logo.png\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n        \u003ca href= \"https://pypi.org/project/craftax/\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue\" /\u003e\u003c/a\u003e\n        \u003ca href= \"https://pypi.org/project/craftax/\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/pypi-1.5.0-green\" /\u003e\u003c/a\u003e\n        \u003ca href= \"https://pepy.tech/project/craftax\"\u003e\n        \u003cimg src=\"https://static.pepy.tech/badge/craftax\" /\u003e\u003c/a\u003e\n       \u003ca href= \"https://github.com/MichaelTMatthews/Craftax/blob/main/LICENSE\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow\" /\u003e\u003c/a\u003e\n       \u003ca href= \"https://craftaxenv.github.io/\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/blog-link-purple\" /\u003e\u003c/a\u003e\n       \u003ca href= \"https://arxiv.org/abs/2402.16801\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/arxiv-2402.16801-b31b1b\" /\u003e\u003c/a\u003e\n       \u003ca href= \"https://github.com/psf/black\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/code%20style-black-000000.svg\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\n# ⛏️ Craftax\nCraftax is an RL environment written entirely in \u003ca href=\"https://github.com/google/jax\"\u003eJAX\u003c/a\u003e.  Craftax reimplements and significantly extends the game mechanics of \u003ca href=\"https://github.com/danijar/crafter\"\u003eCrafter\u003c/a\u003e, taking inspiration from roguelike games such as \u003ca href=\"https://github.com/facebookresearch/nle\"\u003eNetHack\u003c/a\u003e.\nCraftax conforms to the \u003ca href=\"https://github.com/RobertTLange/gymnax\"\u003egymnax\u003c/a\u003e interface, allowing easy integration with existing JAX-based frameworks like \u003ca href=\"https://github.com/luchris429/purejaxrl\"\u003ePureJaxRL\u003c/a\u003e and [JaxUED](https://github.com/DramaCow/jaxued).\n\n\u003cp align=\"middle\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/MichaelTMatthews/Craftax/main/images/archery.gif\" width=\"200\" /\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/MichaelTMatthews/Craftax/main/images/building.gif\" width=\"200\" /\u003e \n  \u003cimg src=\"https://raw.githubusercontent.com/MichaelTMatthews/Craftax/main/images/dungeon_crawling.gif\" width=\"200\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"middle\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/MichaelTMatthews/Craftax/main/images/farming.gif\" width=\"200\" /\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/MichaelTMatthews/Craftax/main/images/magic.gif\" width=\"200\" /\u003e \n  \u003cimg src=\"https://raw.githubusercontent.com/MichaelTMatthews/Craftax/main/images/mining.gif\" width=\"200\" /\u003e\n\u003c/p\u003e\n\n# 📜 Basic Usage\nCraftax conforms to the gymnax interface:\n```python\nrng = jax.random.PRNGKey(0)\nrng, _rng = jax.random.split(rng)\n_rngs = jax.random.split(_rng, 3)\n\n# Create environment\nenv = make_craftax_env_from_name(\"Craftax-Symbolic-v1\", auto_reset=True)\nenv_params = env.default_params\n\n# Get an initial state and observation\nobs, state = env.reset(_rngs[0], env_params)\n\n# Pick random action\naction = env.action_space(env_params).sample(_rngs[1])\n\n# Step environment\nobs, state, reward, done, info = env.step(_rngs[2], state, action, env_params)\n```\n\n# ⬇️ Installation\nThe latest Craftax release can be installed from PyPi:\n```\npip install craftax\n```\nIf you want the most recent commit instead use:\n```\npip install git+https://github.com/MichaelTMatthews/Craftax.git@main\n```\n\n## Extending Craftax\nIf you want to extend Craftax, run (make sure you have `pip\u003e=23.0`):\n```\ngit clone https://github.com/MichaelTMatthews/Craftax.git\ncd Craftax\npip install -e \".[dev]\"\npre-commit install\n```\n\n## GPU-Enabled JAX\nBy default, both of the above methods will install JAX on the CPU.  If you want to run JAX on a GPU/TPU, you'll need to install the correct wheel for your system from \u003ca href=\"https://github.com/google/jax?tab=readme-ov-file#installation\"\u003eJAX\u003c/a\u003e.\nFor NVIDIA GPU the command is:\n```\npip install -U \"jax[cuda12]\"\n```\n\n# 🎮 Play\nTo play Craftax run:\n```\nplay_craftax\n```\nor to play Craftax-Classic run:\n```\nplay_craftax_classic\n```\nSince Craftax runs entirely in JAX, it will take some time to compile the rendering and step functions - it might take around 30s to render the first frame and then another 20s to take the first action.  After this it should be very quick.  A tutorial for how to beat the game is present in `tutorial.md`.  The controls are printed out at the beginning of play.\n\n# 📈 Experiment\nTo run experiments see the [Craftax Baselines](https://github.com/MichaelTMatthews/Craftax_Baselines) repository.\n\n# 🔪 Gotchas\n### Optimistic Resets\nCraftax provides the option to use optimistic resets to improve performance, which means that we provide access to environments that **do not auto-reset**.\nEnvironments obtained from `make_craftax_env_from_name` or `make_craftax_env_from_args` with `auto_reset=False` will not automatically reset and if not properly handled will continue episodes into invalid states.\nThese environments should always be wrapped either in `OptimisticResetVecEnvWrapper`(for efficient resets) or `AutoResetEnvWrapper` (to recover the default gymnax auto-reset behaviour).\nSee `ppo.py` in [Craftax Baselines](https://github.com/MichaelTMatthews/Craftax_Baselines) for correct usage.\nUsing `auto_reset=True` will return a regular auto-reset environment, which can be treated like any other gymnax environment.\n\n### Texture Caching\nWe use a texture cache to avoid recreating the texture atlas every time Craftax is imported. If you are just running Craftax as a benchmark this will not affect you.  However, if you are editing the game (e.g. adding new blocks, entities etc.) then a stale cache could cause errors. You can export the following environment variable to force textures to be created from scratch every run.\n```\nexport CRAFTAX_RELOAD_TEXTURES=true\n```\n\n# 📋 Scoreboard\nIf you would like to add an algorithm please open a PR and provide a reference to the source of the results.\nWe report reward as a % of the maximum (226).\nNote that all scores from outside the original Craftax paper are reported and have not been verified.\n\n## Craftax-1B\n| Algorithm | Reward (% max) |                                              Code                                               |                  Paper                  |\n|:----------|---------------:|:-----------------------------------------------------------------------------------------------:|:---------------------------------------:|\n| PPO-GTrXL |           18.3 | [TransformerXL_PPO_JAX](https://github.com/Reytuag/transformerXL_PPO_JAX)                       | [GTrXL](https://arxiv.org/abs/1910.06764)| \n| PQN-RNN   |           16.0 | [purejaxql](https://github.com/mttga/purejaxql/) | [PQN](https://arxiv.org/abs/2407.04811) |\n| PPO-RNN   |           15.3 | [Craftax_Baselines](https://github.com/MichaelTMatthews/Craftax_Baselines/blob/main/ppo_rnn.py) | [PPO](https://arxiv.org/abs/1707.06347) |\n| RND       |           12.0 | [Craftax_Baselines](https://github.com/MichaelTMatthews/Craftax_Baselines/blob/main/ppo_rnd.py) | [RND](https://arxiv.org/abs/1810.12894) |\n| PPO       |           11.9 |   [Craftax_Baselines](https://github.com/MichaelTMatthews/Craftax_Baselines/blob/main/ppo.py)   | [PPO](https://arxiv.org/abs/1707.06347) |\n| ICM       |           11.9 |   [Craftax_Baselines](https://github.com/MichaelTMatthews/Craftax_Baselines/blob/main/ppo.py)   | [ICM](https://arxiv.org/pdf/1705.05363) |\n| E3B       |           11.0 |   [Craftax_Baselines](https://github.com/MichaelTMatthews/Craftax_Baselines/blob/main/ppo.py)   | [E3B](https://arxiv.org/abs/2210.05805) |\n\n\n## Craftax-1M\n| Algorithm | Reward (% max) |                                              Code                                               |                  Paper                  |\n|:----------|---------------:|:-----------------------------------------------------------------------------------------------:|:---------------------------------------:|\n| Simulus  |       6.6 |       [Simulus](https://github.com/leor-c/Simulus)                                                    | [Simulus](https://arxiv.org/abs/2502.11537) |\n| Efficient MBRL   |            5.4 | - | [Efficient MBRL](https://arxiv.org/abs/2502.01591) |\n| PPO-RNN   |            2.3 | [Craftax_Baselines](https://github.com/MichaelTMatthews/Craftax_Baselines/blob/main/ppo_rnn.py) | [PPO](https://arxiv.org/abs/1707.06347) |\n| RND       |            2.2 | [Craftax_Baselines](https://github.com/MichaelTMatthews/Craftax_Baselines/blob/main/ppo_rnd.py) | [RND](https://arxiv.org/abs/1810.12894) |\n| PPO       |            2.2 |   [Craftax_Baselines](https://github.com/MichaelTMatthews/Craftax_Baselines/blob/main/ppo.py)   | [PPO](https://arxiv.org/abs/1707.06347) |\n| ICM       |            2.2 |   [Craftax_Baselines](https://github.com/MichaelTMatthews/Craftax_Baselines/blob/main/ppo.py)   | [ICM](https://arxiv.org/pdf/1705.05363) |\n| E3B       |            2.2 |   [Craftax_Baselines](https://github.com/MichaelTMatthews/Craftax_Baselines/blob/main/ppo.py)   | [E3B](https://arxiv.org/abs/2210.05805) |\n\n\n# 💾 Offline Dataset\n\nA small dataset of mixed-skill human trajectories is available [here](https://drive.google.com/file/d/1wCMdUIsGOWYkNW55Rs0rHkYKUZhaQdtq/view?usp=sharing).\nOnce the zip file has been extracted, the trajectories can be loaded with the `load_compressed_pickle` function.  These were gathered on an earlier version of Craftax and it is recommended you use [v1.1.0](https://github.com/MichaelTMatthews/Craftax/releases/tag/v1.1.0) or earlier to investigate them.\n`run1` is the only trajectory to complete the game.\n\n# ❌ Errata\n\n- Prior to version 1.5.0 there was a bug that made it hard/impossible for the *first* planted plant to ever grow to ripeness in both Craftax and Craftax-Classic. This should have little effect on results as `EAT_PLANT` is an extremely rare achievement, and this only affected the first plant.\n\n# 🔎 See Also\n- ⛏️ [Crafter](https://github.com/danijar/crafter) The original Crafter benchmark.\n- ⚔️ [NLE](https://github.com/facebookresearch/nle) NetHack as an RL environment.\n- ⚡ [PureJaxRL](https://github.com/luchris429/purejaxrl) End-to-end RL implementations in Jax.\n- 🌎 [JaxUED](https://github.com/DramaCow/jaxued): CleanRL style UED implementations in Jax.\n- 🌍 [Minimax](https://github.com/facebookresearch/minimax): Modular UED implementations in Jax.\n- 🏋️ [Gymnax](https://github.com/RobertTLange/gymnax): Standard Jax RL interface with classic environments.\n- 🧑‍🤝‍🧑 [JaxMARL](https://github.com/FLAIROx/JaxMARL): Multi-agent RL in Jax.\n\n# 📚 Citation\nIf you use Craftax in your work please cite it as follows:\n```\n@inproceedings{matthews2024craftax,\n    author={Michael Matthews and Michael Beukman and Benjamin Ellis and Mikayel Samvelyan and Matthew Jackson and Samuel Coward and Jakob Foerster},\n    title = {Craftax: A Lightning-Fast Benchmark for Open-Ended Reinforcement Learning},\n    booktitle = {International Conference on Machine Learning ({ICML})},\n    year = {2024}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichaeltmatthews%2Fcraftax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmichaeltmatthews%2Fcraftax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichaeltmatthews%2Fcraftax/lists"}