Simulation Customization

MineDojo supports to customize an open-ended simulation. To create an open-ended simulation, users can pass task_id = "Open-Ended" or task_id = "open-ended" to minedojo.make(). We elaborate customizability in following subsections.

Initial Conditions

Initial conditions include initial inventory, weather, time, location, and more.

Initial Inventory

We utilize minedojo.sim.InventoryItem API to set initial inventory. It can be imported in the following way:

from minedojo.sim import InventoryItem

An InventoryItem takes four arguments to instantiate. slot means which slot the item will occupy. It should be an integer ranging from 0 to 40 (inclusive). To provide convenient access to equipment slots, users can instead pass a string from “mainhand”, “offhand”, “head”, “chest”, “legs”, and “feet”. name means the technical name of an item to initialize such as diamond_pickaxe and flint_and_steel. variant means the variant index of the item. See here for a full listing of variants. By default, no variant will be used. quantity means the number of items to initialize. It will be set to 1 by default.

Note

Slots 0 - 9 are for hotbars. Slots 10 - 35 are for inventory. Slots 36 - 40 are for equipment.

Note

When passing item’s name, use techincal name for argument name. I.e., use underscores (“diamond_sword”) instead of white spaced (“diamond sword”).

Note

Quantity ranges from 0 to 64. 64 means a stack of items.

The following code block demonstrates how to initialize the agent with a shield, a diamond sword, and a full suite of diamond armors.

initial_inventory = [
    InventoryItem(slot=0, name="diamond_sword", variant=None, quantity=1),
    InventoryItem(slot=36, name="diamond_boots", variant=None, quantity=1),
    InventoryItem(slot=37, name="diamond_leggings", variant=None, quantity=1),
    InventoryItem(slot=38, name="diamond_chestplate", variant=None, quantity=1),
    InventoryItem(slot=39, name="diamond_helmet", variant=None, quantity=1),
    InventoryItem(slot=40, name="shield", variant=None, quantity=1),
]

Initial Position and Pose

To specify the starting position and pose, users should pass start_position: dict[str, float | int]. It expects a dict with keys x, y, z, yaw, and pitch.

Initial Health and Food

To specify the initial health and food, users should pass start_health and start_food. Both are within the range of [0, 20].

Initial Weather

To specify the initial weather, users should pass initial_weather. It can be one of “normal”, “clear”, “rain”, and “thunder”. “normal” means that using the default Minecraft weather mechanism.

Starting Time

Users can choose the exact in-game time to start the simulation by setting start_time. For example, set start_time = 1000 to start the simulation in the morning. Set start_time = 6000 to start at noon. Set start_time = 13000 to start at night. Commonly used starting time is listed below. Refer to this Wiki page for full details.

Description	Time Value
Starting of a day	1000
Noon, sun is at its peak	6000
Sunset	12000
Beginning of night	13000
Midnight, moon is at its peak	18000
Beginning of sunrise	23000

Spawn in Village

Users can spawn the agent in a village by setting spawn_in_village = True. Villages can provide shelters and crops food.

Spawn Structures

Users can even spawn structures by setting drawing_str. The example below demonstrates how to spawn a nether portal frame around the agent.

env = minedojo.make(
    "open-ended",
    image_size=image_size,
    world_seed="Enter the Nether",
    start_position=dict(x=-260, y=86, z=173, yaw=0, pitch=0),
    drawing_str="""
    <DrawCuboid x1="-262" y1="86" z1="175" x2="-258" y2="86" z2="175" type="obsidian"/>
    <DrawCuboid x1="-262" y1="86" z1="175" x2="-262" y2="91" z2="175" type="obsidian"/>
    <DrawCuboid x1="-258" y1="86" z1="175" x2="-258" y2="91" z2="175" type="obsidian"/>
    <DrawCuboid x1="-262" y1="91" z1="175" x2="-258" y2="91" z2="175" type="obsidian"/>
    """
)

As shown in the example, to draw cuboids users should pass inclusive coordinates and block types. Because a Nether Portal frame has four sides, we pass four strings one by one.

Global Conditions

Users can configure global conditions such as time passage, turning on/off monster spawn, and the breaking speed.

Time Passage

Users can stop time passage through allow_time_passage = False. If time passage is disabled, the world will remain at the starting time forever.

Monster Spawn

Users can turn off monster spawning by passing allow_mob_spawn = False. This setting will disable the monster spawning in the Overworld, The Nether, and The End.

Set Breaking Speed

Different values for break_speed_multiplier (default is 1.0) allows the agent to break blocks with different speeds. Qualitatively, with the bare hand, under the normal speed the agent needs to repeatedly attack for four or five times to mine a wood log. However, under 10x faster speed, the agent only needs to attack once to mine a wood log.

World Generation

Customization on world generation includes the type of the generated world, world seed, and biome specification.

Generated World Type

Users can choose to generate world with three types: “default”, “flat”, and “specified biome” by setting generate_world_type: Literal["default", "flat", "specified_biome"].

A default world is the normal Minecraft world with procedurally generated landscapes, biomes, and structures. A flat world is an extremely simplified world only with grass block and flat terrain. Choosing “specified_biome” will generate a world that only contains the selected biome.

Warning

If the biome is specified, the entire world will only have the specified biome.

World Seed

world_seed: int | str controls the procedurally generated Minecraft world. Using the same world_seed guarantees the same world every time. It can be either an integer such as 42 or a string such as MineDojo.

If a flat world is selected, users can further provide flat_world_seed_string to customize layers of the flat world. This tool is helpful to generate such a seed string.

Specified Biome

Users can select one biome from the list below and pass it to argument specified_biome to specify biome.

Note

Supported biomes

• ice_plains

• ice_plains_spikes

• cold_taiga

• cold_taiga_m

• frozen_river

• cold_beach

• extreme_hills

• extreme_hills_m

• extreme_hills_plus

• extreme_hills_plus_m

• taiga

• taiga_m

• mega_taiga

• mega_spruce_taiga

• stone_beach

• plains

• sunflower_plains

• forest

• flower_forest

• birch_forest

• birch_forest_m

• roofed_forest

• roofed_forest_m

• swampland

• swampland_m

• jungle

• jungle_m

• jungle_edge

• jungle_edge_m

• river

• beach

• mushroom_island

• mushroom_island_shore

• desert

• desert_m

• savanna

• savanna_m

• mesa

• mesa_bryce

• mesa_plateau_f

• mesa_plateau_f_m

• savanna_plateau

• mesa_plateau

• savanna_plateau_m

• mesa_plateau_m

• ocean

• deep_ocean

• ice_mountains

• desert_hills

• forest_hills

• taiga_hills

• jungle_hills

• birch_forest_hills

• cold_taiga_hills

• mega_taiga_hills

• tall_birch_hills

• mega_spruce_taiga_hills

• plains_m

• frozen_ocean

• extreme_hills_edge

• the_end

• nether

• the_void

On-the-fly Customization

Orthogonal to “one-time” initial conditions configured by arguments, MineDojo also supports “on-the-fly” customization. This feature allows users to customize the running world with a great flexibility. It is mainly powered by Minecraft native command functionalities.

Spawn Mobs

Users can spawn mobs in real time by invoking env.spawn_mobs(). It takes three arguments, mobs, rel_positions, and an optional action.

mobs: str | list[str] takes the mob name (e.g., "sheep") or a list of names to spawn (e.g., ["sheep", "cow"]). rel_positions: numpy.ndarray | list means the xyz position relative to the agent to spawn the mob. Because each env.spawn_mobs() will call a backend forward under the hood, users can also provide an optional action to be executed concurrently with spawning mob.

The code block below demonstrates how to spawn a sheep with X and Z coordinates one uint larger than the agent’s.

env.spawn_mobs("sheep", [1, 0, 1])

Note

In Minecraft, Y-axis is the vertical axis. X and Z axes are for the horizontal plane.

Set Block

Users can set blocks in real time at a specific location by invoking env.set_block(). It takes three arguments, blocks, rel_positions, and an optional action.

blocks: str | list[str] takes the block name (e.g., "obsidian") or a list of names to set (e.g., ["obsidian", "diamond_ore"]). rel_positions: numpy.ndarray | list means the xyz position relative to the agent to set the block. Because each env.set_block() will call a backend forward under the hood, users can also provide an optional action to be executed concurrently with setting block.

The code block below demonstrates how to set a diamond ore in front of the agent.

env.set_block("diamond_ore", [5, 0, 0])

Clear Inventory

Users can remove all items in the agent’s inventory by invoking env.clear_inventory(). Because each time it will call a backend forward under the hood, users can also provide an optional action to be executed concurrently.

Set Inventory

Users can set agent’s inventory in real time by invoking env.set_inventory(). It takes two arguments inventory_list and an optional action.

Similar to how we configure initial inventory, we use the minedojo.sim.InventoryItem API. The following code block demonstrates how to set 64 torches to agent’s main hand.

env.set_inventory(
    [InventoryItem(slot="mainhand", name="torch", quantity=64)]
)

Teleport Agent

Users can teleport the agent to a specific location by invoking env.teleport_agent(). It takes arguments of x, y, z, yaw, pitch, and an optional action. The first five arguments determine agent’s position and pose after teleporting. Users can also provide action to be executed concurrently.

Kill Agent

Users can kill the agent by invoking env.kill_agent(). The agent is then re-spawned with empty inventory and refreshed states.

Set Time

Users can set the in-game time by invoking env.set_time(). It takes two arguments time and an optional action. Refer to Starting Time for more details. Users can also provide action to be executed concurrently.

Set Weather

Users can set the in-game weather by invoking env.set_weather(). It takes two arguments weather and an optional action. Refer to Initial Weather for more details. Users can also provide action to be executed concurrently.

Random Teleport

Users can spread (randomly teleport) the agent by invoking env.random_teleport(). It takes two arguments max_range and an optional action.

max_range determines the maximum distance on each horizontal axis from the center of the area to spread agent (thus, the area is square, not circular). Users can also provide action to be executed concurrently. See here for more details about the mechanism of spreading. The code block below demonstrates how to spread the agent within a maximum distance of 200.

env.random_teleport(200)

Execute Command

All real-time customizations illustrated above rely on execute_cmd(). They can be understood as wrapped versions with dedicated functionalities. In addition, MineDojo also provides the possibility to directly execute a Minecraft native command through env.execute_cmd(). It takes two arguments cmd and an optional action.

The cmd argument takes a native Minecraft command represented in string, such as “/summon zombie ~ ~ ~” (it means spawning a zombie exactly at agent’s location). Please refer to the Wiki page for syntax. Because each env.execute_cmd() will call a backend forward under the hood, users can also provide an optional action to be executed concurrently.

Note

Executing commands is considered as “cheating” in Minecraft game playing. We still do so in favor of customizability and flexibility. That being said, we still restrict types of commands that are allowed to execute to “summon”, “kill”, “time”, “weather”, “replaceitem”, “tp”, “clear”, “setblock”, and “spreadplayers”.