MiniWorld Documentation

MiniWorld uses an OpenGL-style right-handed coordinate system.

• Axes: The ground plane is defined by the X and Z axes. The Y axis points up.
• Units: Coordinate units are in meters.
• Angles: Specified in degrees. A positive angle corresponds to a counter-clockwise (leftward) rotation. By convention, an angle of 0 points towards the positive X axis.

Rewards in MiniWorld are typically sparse and fall within the [0, 1] range.

• Success: A reward is given for completing the task, with a small penalty applied based on the number of time steps taken.
• Failure/Timeout: If the task is not completed within the max_episode_steps limit, the episode terminates with a reward of 0.

Implementation details for the reward logic can be found in the _reward() method of the MiniWorldEnv class.

Miniworld environments are compatible with the Gymnasium API. You can initialize an environment using gym.make(), reset it with an optional seed, and interact with it using the standard step() loop. Use render_mode="human" to visualize the 3D environment.

import gymnasium as gym

env = gym.make("MiniWorld-OneRoom-v0", render_mode="human")

observation, info = env.reset(seed=42)
for _ in range(1000):
   action = policy(observation)  # User-defined policy function
   observation, reward, terminated, truncated, info = env.step(action)

   if terminated or truncated:
      observation, info = env.reset()
env.close()

When running MiniWorld in environments without a physical display (like remote clusters or Google Colab), you must use offscreen rendering.

Option 1: EGL (Recommended) Set the PYOPENGL_PLATFORM environment variable to egl before executing your script.

Option 2: Xvfb If EGL is not working, use xvfb-run to create a virtual framebuffer.

# Using EGL
PYOPENGL_PLATFORM=egl python3 your_script.py

# Using Xvfb
xvfb-run -a -s "-screen 0 1024x768x24 -ac +extension GLX +render -noreset" python3 your_script.py

Install the miniworld package using pip to access the 3D interior environment simulator.

pip install miniworld

To install miniworld in development mode (an editable install), use the -e flag. This is useful if you want to modify the source code and have your changes take effect immediately without re-installing the package.

python3 -m pip install -e .

If you intend to build on top of miniworld, you should install it from the source repository.

1. Clone the repository:

   git clone https://github.com/Farama-Foundation/Miniworld.git

2. Install the package:

   cd Miniworld
   python3 -m pip install .

To build the Miniworld documentation locally, you need to install the required dependencies and PettingZoo, then use make or sphinx-autobuild within the docs directory.

One-time build

Use make dirhtml to generate the documentation once.

Live rebuild

Use sphinx-autobuild to automatically rebuild the documentation whenever changes are detected.

# Install dependencies
pip install -r docs/requirements.txt
pip install -e .

# Build once
cd docs
make dirhtml

# Rebuild automatically on change
cd docs
sphinx-autobuild -b dirhtml . _build

MiniWorld supports loading .obj mesh files. To include a 3D model in your environment, create a MeshEnt object and specify the model name.

Requirements & Tips:

• Polygon Type: MiniWorld only supports triangle polygons. If your mesh contains non-triangular polygons, you must triangulate it (e.g., using the 'triangulate mesh' option in Blender) before exporting.
• Scaling: Use the height parameter in the MeshEnt constructor to scale the model to a specific height in meters.
• Resources: You can find compatible models on OpenGameArt (filter by OBJ) or create your own using tools like Wings 3D or Blender.

To create a new environment, define a class that inherits from MiniWorldEnv. You must initialize the environment and define the action_space.

In the __init__ method, call super().__init__(self, **kwargs) to ensure the base environment is correctly set up. You can define custom action spaces using gym.spaces.Discrete. For example, to allow only movement actions (turn left, turn right, move forward, move backward), you can set the action space based on the number of movement actions available in the base class.

def __init__(self, size=10, **kwargs):
    # Size of environment
    self.size = size

    super().__init__(self, **kwargs)

    # Allow only the movement actions
    self.action_space = spaces.Discrete(self.actions.move_forward + 1)

You can install MiniWorld via PyPI or from source.

Requirements:

• Python 3.7+
• Gymnasium
• NumPy
• Pyglet (for OpenGL 3D graphics)
• Optional: GPU for 3D graphics acceleration

Note: This project has been deprecated as of August 11, 2025, and is no longer receiving updates or support.

# Install via PyPI
python3 -m pip install miniworld

# Or install from source
git clone https://github.com/Farama-Foundation/Miniworld.git
cd Miniworld
python3 -m pip install -e .