Craftax Documentation

Chests contain potions of six different colors. Potions provide either +8 or -3 to one of three stats: health, mana, or energy.

Note: The effect associated with each color is permuted every time a new game is run. Players must use trial and error to determine which color corresponds to which effect in their current session.

Spellcasting

Books found in chests on Floor 3 (Sewers) allow the player to learn random spells (e.g., fireball or iceball).

• Cost: 2 mana per cast.
• Damage Types: Spells deal fire or ice damage. This is critical for later levels where creatures have high resistance to physical damage.

Enchanting

Enchantment tables (Ice in Floor 3, Fire in Floor 4) allow players to enchant swords, armor, or bows by standing adjacent to the table and consuming 9 mana plus a specific gemstone:

• Sapphires: Used for ice enchantments.
• Rubies: Used for fire enchantments.

Enchantment Benefits:

• Sword/Bow: +50% damage of the respective type.
• Armor: Reduces damage of that type by 20% per armor piece.

When creating environments with auto_reset=False (via make_craftax_env_from_name or make_craftax_env_from_args), the environment will not automatically reset. If you do not handle this, episodes will continue into invalid states.

To use these high-performance 'optimistic' environments correctly, you should wrap them in one of the following:

• OptimisticResetVecEnvWrapper: For efficient resets in vectorized environments.
• AutoResetEnvWrapper: To restore the standard gymnax auto-reset behavior.

Upon descending to a new floor for the first time, the player is awarded an experience point. These points can be permanently assigned to one of three attributes (starting at level 1, maximum level 5):

• Dexterity: Increases maximum food, water, and energy reserves; slows their decay; and increases bow damage.
• Strength: Increases melee damage and maximum health.
• Intelligence: Increases maximum mana, reduces mana decay, increases spell damage, and increases enchantment effectiveness.

The Craftax symbolic observation is a flat array of shape (8268,). This array contains all the information the agent perceives about its environment, including the local map, inventory, player stats, and world state.

To process the map data, you must reshape the first 8217 elements of the array into a (9, 11, 83) tensor. This represents a 9x11 subset of the map visible to the agent.

You can interact with the environment directly using the provided CLI commands. Note that because Craftax is written in JAX, there will be a significant compilation delay (approx. 30s for the first frame and 20s for the first action) before gameplay becomes responsive.

# Play standard Craftax
play_craftax

# Play Craftax-Classic
play_craftax_classic

Resting

If the player is at low health, they can block themselves in with blocks (like stone) and:

1. Sleep: Replenishes energy.
2. Rest: If energy is already at maximum, resting causes the player to execute no-op actions until an intrinsic decays to 0, the player is attacked, or the player recovers to full health.

Environmental Hazards

• Darkness: In levels like the Gnomish Mines (Floor 2), players must place torches (crafted from wood and coal) to see.
• Water/Lava: In the Fire Realm (Floor 6), players can build bridges across lava by placing and mining stone. In the Sewers (Floor 3), water patches can be filled by placing and mining stone.

Craftax follows the gymnax interface. To use it, you need to create an environment using make_craftax_env_from_name, manage JAX PRNG keys for randomness, and use the reset and step methods. Note that env_params (retrieved from env.default_params) must be passed to most environment methods.

import jax

# Setup RNG keys
rng = jax.random.PRNGKey(0)
rng, _rng = jax.random.split(rng)
_rngs = jax.random.split(_rng, 3)

# Create environment
env = make_craftax_env_from_name("Craftax-Symbolic-v1", auto_reset=True)
env_params = env.default_params

# Get an initial state and observation
obs, state = env.reset(_rngs[0], env_params)

# Pick random action
action = env.action_space(env_params).sample(_rngs[1])

# Step environment
obs, state, reward, done, info = env.step(_rngs[2], state, action, env_params)

You can install the latest stable release of Craftax from PyPI using pip. For the most recent development version, install directly from the main branch of the GitHub repository.

# Install latest stable release
pip install craftax

# Install latest commit from main branch
pip install git+https://github.com/MichaelTMatthews/Craftax.git@main

To contribute to or extend the Craftax codebase, clone the repository and install it in editable mode with development dependencies.

# Ensure pip >= 23.0
git clone https://github.com/MichaelTMatthews/Craftax.git
cd Craftax
pip install -e ".[dev]"
pre-commit install

By default, the standard installation installs JAX for CPU. To run Craftax on an NVIDIA GPU, you must install the appropriate JAX CUDA wheel for your system.

pip install -U "jax[cuda12]"