Simulator

We provide an easily customizable Minecraft simulator that is developed based on MineRL. We designed a Gym-style Minecraft Wrapper, which supports a callbacks mechanism, allowing users to customize their own environment, including custom reward functions, environment initialization, trajectory recording, and more.

MineStudio Simulator

• General Information
  • Observation Space
  • Action Space
  • Information
• Design Principles
  • Simulator Lifecycle
  • Callbacks
• Graphical User Interfaces
  • Hello World
  • Command Mode

Quick Start

Here is a minimal example of how to use the simulator:

from minestudio.simulator import MinecraftSim

sim = MinecraftSim(action_type="env")
obs, info = sim.reset()
for _ in range(100):
    action = sim.action_space.sample()
    obs, reward, terminated, truncated, info = sim.step(action)
sim.close()

Also, you can customize the environment by chaining multiple callbacks. Here is an example:

import numpy as np
from minestudio.simulator import MinecraftSim
from minestudio.simulator.callbacks import (
    SpeedTestCallback, 
    RecordCallback, 
    SummonMobsCallback, 
    MaskActionsCallback, 
    RewardsCallback, 
    CommandsCallback, 
    FastResetCallback
)

sim = MinecraftSim(
    action_type="env",
    callbacks=[
        SpeedTestCallback(50), 
        SummonMobsCallback([{'name': 'cow', 'number': 10, 'range_x': [-5, 5], 'range_z': [-5, 5]}]),
        MaskActionsCallback(inventory=0, camera=np.array([0., 0.])), 
        RecordCallback(record_path="./output", fps=30),
        RewardsCallback([{
            'event': 'kill_entity', 
            'objects': ['cow', 'sheep'], 
            'reward': 1.0, 
            'identity': 'kill sheep or cow', 
            'max_reward_times': 5, 
        }]),
        CommandsCallback(commands=[
            '/give @p minecraft:iron_sword 1',
            '/give @p minecraft:diamond 64',
        ]), 
        FastResetCallback(
            biomes=['mountains'],
            random_tp_range=1000,
        )
    ]
)
obs, info = sim.reset()
print(sim.action_space)
for i in range(100):
    action = sim.action_space.sample()
    obs, reward, terminated, truncated, info = sim.step(action)
sim.close()

Basic Arguments

The simulator has several arguments that can be used to customize the environment.

Argument	Default	Description
action_type	“agent”	The style of the action space
obs_size	(224, 224)	The resolution of the observation (cv2 resize)
render_size	(640, 360)	The original resolution of the game is 640x360
seed	0	The seed of the minecraft world
inventory	{}	The initial inventory of the agent
preferred_spawn_biome	None	The preferred spawn biome when call reset
num_empty_frames	20	The number of empty frames to skip when calling reset
callbacks	[]	The callbacks to customize the environment (advanced)

Using Callbacks

Callbacks can be used to customize the environment in a flexible way. We provide several built-in callbacks, and users can also implement their own callbacks.

Here is some examples of how to use callbacks:

Note

All the callbacks are optional, and you can use them in any combination.

Test Speed

We provide a callback to test the speed of the simulator by hooking into the before_step and after_step methods.

from minestudio.simulator.callbacks import SpeedTestCallback

sim = MinecraftSim(callbacks=[SpeedTestCallback(interval=50)])

If you run the above code, you will see the following output:

Speed Test Status: 
Average Time: 0.03 
Average FPS: 38.46 
Total Steps: 50 

Speed Test Status: 
Average Time: 0.02 
Average FPS: 45.08 
Total Steps: 100 

Send Chat Commands

We provide a callback to send chat commands to the Minecraft server when the environment is reset. This enable users to customize the environment initialization.

from minestudio.simulator.callbacks import CommandsCallback

sim = MinecraftSim(callbacks=[CommandsCallback(commands=[
    "/time set day", 
    "/weather clear",
    "/give @p minecraft:iron_sword 1",
    "/give @p minecraft:diamond 64",
])])

Hint

The commands will be executed in the order they are provided.

Custom Reward Function

We provide a simple callback to customize the reward function. This callback will be called after each step, and detect the event in info to calculate the reward.

from minestudio.simulator.callbacks import RewardsCallback

sim = MinecraftSim(callbacks=[
    RewardsCallback([{
        'event': 'kill_entity', 
        'objects': ['cow', 'sheep'], 
        'reward': 1.0, 
        'identity': 'kill sheep or cow', 
        'max_reward_times': 5, 
    }])
])

Hint

This example will give a reward of 1.0 when the agent kills a sheep or cow. The maximum reward times is 5.

Fast Reset

Generally, the environment reset is slow because it needs to restart the Minecraft server. We provide a callback to speed up the reset process by hooking into the before_reset method. This would be pretty useful when you want to reset the environment frequently, like in RL training.

from minestudio.simulator.callbacks import FastResetCallback

sim = MinecraftSim(callbacks=[
    FastResetCallback(
        biomes=['mountains'],
        random_tp_range=1000,
    ), 
])

Hint

Fast reset is implemented by killing the agent and teleporting it to a random location.

Record Trajectories

We provide a callback to record trajectories. It will records the observation, action, info at each step, and save them to a specified path.

from minestudio.simulator.callbacks import RecordCallback

sim = MinecraftSim(callbacks=[RecordCallback(record_path="./output", fps=30)])

Hint

You can use this callback to record the agent’s behavior and analyze it later. Or you can use it to generate a dataset for imitation learning.

Learn more about MineStudio Simulator callbacks