From 6e13a93c5ac6b0b34ccc3ac0410a9be200dd84fb Mon Sep 17 00:00:00 2001 From: MichaelTMatthews Date: Tue, 26 Mar 2024 16:26:20 +0000 Subject: [PATCH] Update README --- README.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 359d4b0..1b4cb2f 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ -# Craftax +# ⛏️ Craftax Craftax is an RL environment written entirely in JAX. Craftax reimplements and significantly extends the game mechanics of Crafter, taking inspiration from roguelike games such as NetHack. Craftax conforms to the gymnax interface, allowing easy integration with existing JAX-based frameworks like PureJaxRL and [JaxUED](https://github.com/DramaCow/jaxued). @@ -34,9 +34,9 @@ Craftax conforms to the gymnax<

-# Basic Usage +# 📜 Basic Usage Craftax conforms to the gymnax interface: -``` +```python rng = jax.random.PRNGKey(0) rng, _rng = jax.random.split(rng) rngs = jax.random.split(_rng, 3) @@ -55,7 +55,7 @@ action = env.action_space(env_params).sample(rngs[1]) obs, state, reward, done, info = env.step(rngs[2], state, action, env_params) ``` -# Installation +# ⬇️ Installation The latest Craftax release can be installed from PyPi: ``` pip install craftax @@ -80,7 +80,7 @@ For NVIDIA GPU the command is: pip install -U "jax[cuda12_pip]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html ``` -# Play +# 🎮 Play To play Craftax run: ``` play_craftax @@ -90,7 +90,8 @@ or to play Craftax-Classic run: play_craftax_classic ``` Since 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. -# Experiment + +# 📈 Experiment To run PPO with default hyperparameters run: ``` python -m craftax.ppo @@ -102,7 +103,7 @@ python -m craftax.ppo_rnn To use ICM or E3B with the default parameters use the `--train_icm` and `--use_e3b` flags. Use the `env_name` parameter to control which environment is used. It can be set to `"Craftax-Symbolic-v1"`, `"Craftax-Pixels-v1"`, `"Craftax-Classic-Symbolic-v1"` or `"Craftax-Classic-Pixels-v1"` -# Gotchas +# 🔪 Gotchas ### Optimistic Resets Craftax provides the option to use optimistic resets to improve performance, which means that (unlike regular gymnax environments) it **does not auto-reset** by default. This means that the environment should always be wrapped either in `OptimisticResetVecEnvWrapper` (for efficient resets) or `AutoResetEnvWrapper` (to recover the default gymnax auto-reset behaviour). See `ppo.py` for correct usage of both wrappers. @@ -113,7 +114,7 @@ We use a texture cache to avoid recreating the texture atlas every time Craftax export CRAFTAX_RELOAD_TEXTURES=true ``` -# Scoreboard +# 📋 Scoreboard If you would like to add an algorithm please open a PR and provide a reference to the source of the results. We report reward as a % of the maximum (226).