Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
MichaelTMatthews committed Mar 26, 2024
1 parent 5281be4 commit 6e13a93
Showing 1 changed file with 9 additions and 8 deletions.
17 changes: 9 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@



# Craftax
# ⛏️ Craftax
Craftax is an RL environment written entirely in <a href="https://github.com/google/jax">JAX</a>. Craftax reimplements and significantly extends the game mechanics of <a href="https://danijar.com/project/crafter/">Crafter</a>, taking inspiration from roguelike games such as <a href="https://github.com/facebookresearch/nle">NetHack</a>.
Craftax conforms to the <a href="https://github.com/RobertTLange/gymnax">gymnax</a> interface, allowing easy integration with existing JAX-based frameworks like <a href="https://chrislu.page/blog/meta-disco/">PureJaxRL</a> and [JaxUED](https://github.com/DramaCow/jaxued).

Expand All @@ -34,9 +34,9 @@ Craftax conforms to the <a href="https://github.com/RobertTLange/gymnax">gymnax<
<img src="https://raw.githubusercontent.com/MichaelTMatthews/Craftax/main/images/mining.gif" width="200" />
</p>

# 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)
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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).

Expand Down

0 comments on commit 6e13a93

Please sign in to comment.