Miniworld¶
MiniWorldMovingBlockWorld is a 3D room of moving colored blocks, the Dynamic Blockworld of Flow Equivariant World Models (Lillemark et al., 2026). It runs MovingBlockWorld from the hlillemark/Miniworld fork of Miniworld, pinned to the fork's flowm_release branch, which holds the code frozen for the paper. All environments step together in a batched port of the fork's step, in Numba on CPU and in Triton on CUDA, and pyglet OpenGL draws the frames.
# needs the Miniworld fork and the miniworld extra
import stable_envs as snv
with snv.MiniWorldMovingBlockWorld(num_envs=8, size=128, device="cpu") as env:
state = env.reset(seed=0)
frames = env.render()
Install¶
The class needs the miniworld extra, which also installs Numba for the CPU step, and the fork, which isn't on PyPI; see the Miniworld install commands. On Linux it also needs an EGL driver.
Task¶
An agent walks in a room of colored blocks. The task has no reward and no success criterion: the reward is always 0 and an episode ends only at the step limit.
The action is one of the fork's nine ids:
| Id | Action |
|---|---|
| 0, 1 | turn left, turn right |
| 2, 3 | move forward, move back |
| 4 | do nothing |
| 5, 6 | pick up, drop |
| 7, 8 | toggle, done |
Simulation¶
Every block moves by a fixed velocity each step and bounces off the walls. A preset sets the room and the motion:
| Preset | Configuration |
|---|---|
flowm (default) |
the paper's dynamic dataset: plain colored boxes in a 16 × 16 grid room, each moving one cell per step in a cardinal direction, through the agent and each other; 90° turns, unit forward steps, 500 steps |
flowm-textured |
the paper's textured split: flowm with random wall, floor and block textures, and balls among the blocks |
upstream |
MovingBlockWorld() as the fork registers it: a 12 × 12 room, continuous motion, 250 steps |
Keyword arguments override single options of a preset, for example num_blocks, blocks_static, room_size or max_episode_steps. num_blocks takes a count or a (min, max) range. With a range, each environment draws its count uniformly at every reset, as the paper's dataset script draws 6 to 10 blocks per video, and both FloWM presets use (6, 10). The state pads the block fields to max blocks, and blocks.present marks the blocks an environment has.
Physics backends¶
The simulation_backend argument selects the step:
| Value | Step | Device |
|---|---|---|
"auto" (default) |
"numba" on CPU. On CUDA, "numba" for small batches and "triton" for large batches |
|
"numba" |
a Numba kernel, from 64 environments on several CPU threads | CPU; on a CUDA device it returns the state on CUDA |
"triton" |
a Triton kernel, one environment per GPU thread, in a CUDA graph | CUDA |
"torch" |
Torch operations on the whole batch | any |
None means "auto". The class ships a switch point measured on RTX 3090 and RTX A5000 hosts. The large_backend_min_envs tuning setting and stable-envs tune can change it (see Physics backends). env.simulation_backend reports the selected backend.
The Numba step follows the fork's MiniWorldEnv.step and MovingBlockWorld.step operation by operation in float64, and from the same state it gives the fork's values bit for bit. The Triton and Torch steps use the same rules. On CUDA, the cosine and sine round differently and the Triton step compares squared distances, so continuous motion (preset="upstream") agrees to 1e-9 per step in the tests, while the grid motion of the FloWM presets gives equal values.
Resets sample the fork's reset distribution: block count, colors, textures, kinds, sizes, positions, headings and velocities. Draw k of an episode is a hash of the environment's seed, its episode number and k, so every backend draws the same numbers. reset(seed) gives environment i the seed seed + i, and reset() starts the next episode of each environment. The state holds the seed and the episode number (rng.seed, rng.episode), so a restored state continues with the same episodes.
Actions on the host are checked, and an id outside [0, 8] raises ValueError. Actions on CUDA aren't read back, and there an id out of range does nothing, as in the fork.
State¶
The state folds its fields into one array for each dtype: float64, int64 and bool. The arrays are the leaves of the state, under the key moving_block_world. snv.get_field(state, "blocks/pos") reads one field by name, and snv.schema_of(state).names lists them. The fields are agent/pos, agent/dir, agent/carrying, room/textures, the blocks/ fields, rng/seed, rng/episode and lifecycle/elapsed_steps.
with snv.MiniWorldMovingBlockWorld(num_envs=2, size=64, device="cpu") as env:
state = env.reset(seed=0)
print(list(state.keys(True, True))) # three leaves, one for each dtype
print(snv.get_field(state, "blocks/present").shape) # torch.Size([2, 10])
Rendering¶
Frames are the agent view that Miniworld draws with OpenGL through pyglet. On Linux the family uses pyglet's headless EGL mode, which needs an EGL driver. Mesa's llvmpipe is one that works without a GPU.
Variation¶
This class has no variation leaves. The presets and keyword arguments above set the room instead.
Classes¶
MiniWorldMovingBlockWorld¶
| Property | Value |
|---|---|
| Reference | MiniWorld-MovingBlockWorld-v0 |
| Physics | native Numba on CPU, native Triton on CUDA |
| Devices | CPU, CUDA |
| Requires CUDA | no |
| Renderer on CPU | opengl (Miniworld, pyglet) |
| Renderer on CUDA | opengl (Miniworld) on CPU, frames copied to CUDA |
| Default frame | 64 × 64 × 3, uint8 |
| Action | int64 (1,), [0, 8] |
| Clips | rendered on CPU at 160 px, then resized |
State (1 top-level keys)
| Key | Shape | dtype |
|---|---|---|
moving_block_world |
3 leaves, 151 values | bool, float64, int64 |
This class has no variation leaves.
Limitations¶
Resets don't use the fork's PCG64 generator, and the paper's dataset script draws the block count with Python's random. The episodes here follow the same distribution but not the same sequence.