Craftax

In Craftax (Matthews et al., 2024), an open-ended 2D survival game in JAX, the agent gathers resources, crafts tools, fights creatures and explores. The four classes cover Craftax and its Crafter-style Classic version, each with pixel or symbolic observations.

# needs the craftax extra
import stable_envs as snv

with snv.CraftaxClassicPixels(num_envs=8, device="cpu") as env:
    state = env.reset(seed=0)
    frames = env.render()

Install

The classes need the craftax extra, and device="cuda" needs the craftax-gpu extra, which installs the CUDA build of JAX.

Without the craftax-gpu extra, device="auto" selects the CPU, also on a host with CUDA.

When you build a Craftax environment, stable-envs sets XLA_PYTHON_CLIENT_PREALLOCATE=false if it is not set and JAX has not started, so that JAX does not reserve most of the GPU memory. Importing stable-envs does not set it. JAX reads this variable when it starts its GPU backend. If JAX code ran on the GPU before you built the first Craftax environment, set the variable before you start Python.

Task

Craftax-Classic reimplements Crafter (Hafner, 2021), and Craftax adds more levels, items and creatures. The task has no success criterion. The reward counts achievements, for example "collect wood" or "make a stone pickaxe", and the episode ends when the agent dies or reaches the game's step limit.

The Pixels and Symbolic classes use the same game, but a Symbolic class returns the game's symbolic vector as observation.

Simulation

The whole batch is one stacked JAX pytree that one jitted vmap steps. Batch row i follows the stable-worldmodel CraftaxWrapper with seed seed + i. When the environment is built, stable-envs turns off JAX's GPU memory preallocation, so that Torch keeps its GPU memory. See JAX GPU memory.

On the CPU, one XLA program uses only a few cores. So the batch rows are split evenly over XLA host devices, one device for each CPU that the process can use (its CPU affinity, limited by a cgroup CPU quota). Each device steps its rows in the same program. The results are equal bit for bit to the results on one device. When the rows do not divide evenly, the last device also steps copies of the first row, and their results are discarded.

Each split adds a fixed cost to each call, for each device. So a device gets at least 32 rows (MIN_ENVS_PER_HOST_DEVICE in stable_envs/envs/craftax/kernel.py), and a smaller batch uses fewer devices or one device. The value was measured on 15 November 2026 on two CPU hosts with 8 CPUs each (Intel Xeon Platinum 8268 and 8358), for Craftax-Classic and Craftax, with one step per call and no frames, at batches 1 to 256 on 1, 2, 4 and 8 devices. Below 32 rows for each device, a split was not faster than one device on at least one of the hosts. Nothing is timed when you build an environment.

The number of host devices is a JAX setting for the whole process, and JAX reads it when it starts its CPU backend. Craftax sets it when you make the first Craftax environment on the CPU, before Craftax imports its game code. A Craftax environment on CUDA does not change it. Thus:

  • If you set the number (XLA_FLAGS=--xla_force_host_platform_device_count=N, JAX_NUM_CPU_DEVICES=N or jax.config.update("jax_num_cpu_devices", N)), Craftax keeps it and uses up to N devices.
  • If JAX code ran before you made the first CPU Craftax environment, JAX has one CPU device. Then the CPU environments step on one device, and Craftax logs a warning. To prevent this, make the first CPU Craftax environment before other JAX code runs, or set the number before you start Python. The same occurs with a JAX version that has no jax_num_cpu_devices setting.
  • After Craftax sets the number, other JAX code in the process also sees the extra CPU devices in jax.devices("cpu"). Code that does not place its arrays on them still runs on the first CPU device.
  • device="auto" starts JAX to find its GPU backend only when a JAX GPU plugin is installed. If JAX then has no GPU, the environment steps on the CPU with one device.

A sequence of actions, step with actions of shape (B, T, 1), runs in one jitted call that steps the game T times with lax.scan. The results are equal to T single steps. The call is padded to a length that is a power of two, so a new T compiles again only when it passes a power of two. Every selection of states and frames uses this call: the last state and the last frame come from the end of the scan, and other selections take their steps from the states or the frames of every step.

Actions from the host are checked before the step, all the actions of a sequence before its first step. Actions in a CUDA tensor are checked on the device, so that the host does not wait for the step. A step or a sequence with an action outside the range leaves every environment unchanged, and the next step, reset, set_state or close raises ValueError. The rejected step or sequence itself returns valid set to true for each environment, zero rewards and observations, no ends, and the unchanged state.

The state has three leaves, one for each dtype: craftax/bool, craftax/float32 and craftax/int32 (craftax_classic/... for the Classic classes), with one row per environment. Each field is a slice of one of them. The fields are each leaf of the upstream EnvState under engine, such as engine/player_health, the variation values of the environment under physics, such as physics/zombie/health, and the wrapper's PRNG key, key. Fields that are uint32 PRNG words are stored bit for bit as int32. Read a field with snv.get_field(state, "engine/player_health") and write a field with snv.set_field.

Rendering

Both the Pixels and the Symbolic classes draw the same frames from their state. A frame is Craftax's pixel observation scaled to uint8, as stable-worldmodel renders it.

The renderer is a port of the game's pixel renderer. The game paints each block type and each item type over the whole frame in turn. The port reads the block texture and the item texture of each pixel with one lookup each, and draws the player, creatures, light, night, sleep and inventory as the game does. The frames are equal to the game's frames bit for bit, on CPU and on CUDA.

When step returns a frame, the same jitted call steps the game and draws the frame.

Variation

The variation leaves set fields of the upstream EnvParams for each environment. All of them change the game, not the frames. An environment takes its values at reset, and its state keeps them under physics, so set_state restores them with the rest of the game. A change with set_variation takes effect at the next reset. reset(options={"variation_values": {...}}) sets values for one episode, and reset(options={"variation": [...]}) samples them for each environment.

Leaf EnvParams field Classic default Craftax default Range
world.day_length day_length 300 300 50 to 1000
world.always_diamond always_diamond 1 0 0 or 1
mobs.despawn_distance mob_despawn_distance 14 14 6 to 30
zombie.health zombie_health 5 1 to 9
cow.health cow_health 3 1 to 9
skeleton.health skeleton_health 3 1 to 9
spawn.cow spawn_cow_chance 0.1 0 to 1
spawn.zombie_base spawn_zombie_base_chance 0.02 0 to 1
spawn.zombie_night spawn_zombie_night_chance 0.1 0 to 1
spawn.skeleton spawn_skeleton_chance 0.05 0 to 1
player.max_attribute max_attribute 5 1 to 10

When every environment has the default values, the step uses the upstream defaults as constants, as upstream does, and the states are the same as upstream's bit for bit. Other values go to upstream's step as arguments.

Classes

CraftaxClassicPixels

Random actions
Property Value
Reference Craftax-Classic-Pixels-v1
Devices CPU, CUDA (needs the craftax-gpu extra)
Requires CUDA no
Renderer on CPU Craftax pixel renderer (JAX)
Renderer on CUDA Craftax pixel renderer (JAX)
Default frame 63 × 63 × 3, uint8
Native size 63 px, the only size
Action int64 (1,), [0, 16]
Clips rendered on CPU at 63 px, then resized

State (1 top-level keys)

Key Shape dtype
craftax_classic 3 leaves, 8355 values bool, float32, int32

Variation space (10 leaves)

Path Type Bounds or choices Default Sampled at reset
cow.health Discrete 9 choices from 1 3
mobs.despawn_distance Discrete 25 choices from 6 14
skeleton.health Discrete 9 choices from 1 3
spawn.cow Box (1,) [0, 1] 0.1
spawn.skeleton Box (1,) [0, 1] 0.05
spawn.zombie_base Box (1,) [0, 1] 0.02
spawn.zombie_night Box (1,) [0, 1] 0.1
world.always_diamond Discrete 2 choices from 0 1
world.day_length Discrete 951 choices from 50 300
zombie.health Discrete 9 choices from 1 5

CraftaxClassicSymbolic

Random actions
Property Value
Reference Craftax-Classic-Symbolic-v1
Devices CPU, CUDA (needs the craftax-gpu extra)
Requires CUDA no
Renderer on CPU Craftax pixel renderer (JAX)
Renderer on CUDA Craftax pixel renderer (JAX)
Default frame 63 × 63 × 3, uint8
Native size 63 px, the only size
Action int64 (1,), [0, 16]
Clips rendered on CPU at 63 px, then resized

State (1 top-level keys)

Key Shape dtype
craftax_classic 3 leaves, 8355 values bool, float32, int32

Variation space (10 leaves)

Path Type Bounds or choices Default Sampled at reset
cow.health Discrete 9 choices from 1 3
mobs.despawn_distance Discrete 25 choices from 6 14
skeleton.health Discrete 9 choices from 1 3
spawn.cow Box (1,) [0, 1] 0.1
spawn.skeleton Box (1,) [0, 1] 0.05
spawn.zombie_base Box (1,) [0, 1] 0.02
spawn.zombie_night Box (1,) [0, 1] 0.1
world.always_diamond Discrete 2 choices from 0 1
world.day_length Discrete 951 choices from 50 300
zombie.health Discrete 9 choices from 1 5

CraftaxPixels

Random actions
Property Value
Reference Craftax-Pixels-v1
Devices CPU, CUDA (needs the craftax-gpu extra)
Requires CUDA no
Renderer on CPU Craftax pixel renderer (JAX)
Renderer on CUDA Craftax pixel renderer (JAX)
Default frame 130 × 110 × 3, uint8
Native size 130 px, the only size
Action int64 (1,), [0, 42]
Clips rendered on CPU at 130 px, then resized

State (1 top-level keys)

Key Shape dtype
craftax 3 leaves, 84039 values bool, float32, int32

Variation space (4 leaves)

Path Type Bounds or choices Default Sampled at reset
mobs.despawn_distance Discrete 25 choices from 6 14
player.max_attribute Discrete 10 choices from 1 5
world.always_diamond Discrete 2 choices from 0 0
world.day_length Discrete 951 choices from 50 300

CraftaxSymbolic

Random actions
Property Value
Reference Craftax-Symbolic-v1
Devices CPU, CUDA (needs the craftax-gpu extra)
Requires CUDA no
Renderer on CPU Craftax pixel renderer (JAX)
Renderer on CUDA Craftax pixel renderer (JAX)
Default frame 130 × 110 × 3, uint8
Native size 130 px, the only size
Action int64 (1,), [0, 42]
Clips rendered on CPU at 130 px, then resized

State (1 top-level keys)

Key Shape dtype
craftax 3 leaves, 84039 values bool, float32, int32

Variation space (4 leaves)

Path Type Bounds or choices Default Sampled at reset
mobs.despawn_distance Discrete 25 choices from 6 14
player.max_attribute Discrete 10 choices from 1 5
world.always_diamond Discrete 2 choices from 0 0
world.day_length Discrete 951 choices from 50 300

Limitations

Craftax draws at its own frame size, and the constructor refuses other values of size.