Task Customization¶

In addition to the defined benchmarking suite, users can leverage MineDojo meta task API to customize tasks through the same minedojo.make() entrypoint. We provide meta task API for four groups of tasks: Harvest, Combat, Tech Tree, and Survival. Meta task API supports to customize task goal, spawning condition, global condition, inventory, and more. We detail the usage of this API to customize tasks in following subsections.

Harvest¶

A Harvest task can be created by passing task_id = "Harvest" or task_id = "harvest" to minedojo.make(). As usual, it takes argument image_size as well. Users can control several axes.

Goal and Reward¶

Users can specify the targets to harvest by passing argument target_names: str | list[str]. It takes either the name of target item or a list of target items.

To specify the target quantity, users should pass argument target_quantities: int | list[int] | dict[str, int]. When a single integer is provided, it sets the same target quantities for all target items. Users can opt to specify different target quantities for different target items by passing a list of target quantities or a dict mapping target item to quantity.

To specify the reward weight of harvesting each item, users can pass the argument reward_weights: int | float | dict[str, int | float]. When a single integer or float is provided, it sets the same weight for all target items. Users can opt to specify different weights for different target items by passing a dict mapping target item to quantity.

Note

When multiple target items are specified, the task is considered to be successful only if all targets are satisfied.

The code block below demonstrates how to create a Harvest task with 64 wood logs as the target. The agent receives 1 reward every time a new wood log is collected.

env = minedojo.make(
    task_id="harvest",
    image_size=image_size,
    target_names="log",
    target_quantities=64,
    reward_weights=1
)

Spawn Control¶

Users can control the spawn of initial mobs as well as the spawn rate of target items. For example, if the target item is diamond, users can control the spawn rate of diamond ore.

To spawn initial mobs, users can pass the name of mob or a list of mobs names to initial_mobs. To specify the region where initial mobs will spawn, users can set spanw_range_low: tuple[int, int, int] and spawn_range_high: tuple[int, int, int]. They represent the lower bound and upper bound in XYZ relative to the agent. For example, spawn_range_low = (-3, -3, -3) and spawn_range_high = (3, 3, 3) mean that mobs will be randomly spawned in a 7x7x7 region with the agent at the center.

Users can set spawn_rate to control the spawn rate of target item. When a single float is provided, it sets the same spawn rate for all target items. Users can opt to specify different spawn rates for different target items by passing a list of spawn rates or a dict mapping target item to spawn rate. Users can follow the similar behavior as initial_mob_spawn_range_low and initial_mob_spawn_range_high to set spawn_range_low and spawn_range_high, which determine the spawn region of target items relative to the agent.

The following code block demonstrates how to create a task to harvest diamond with an initial sheep spawned nearby and extra spawn of diamond ore.

env = minedojo.make(
    task_id="harvest",
    image_size=image_size,
    target_names="diamond",
    target_quantities=1,
    initial_mobs="sheep",
    initial_mob_spawn_range_low=(-3, 1, -3),
    initial_mob_spawn_range_high=(3, 3, 3),
    spawn_rate=0.1,
    spawn_range_low=(-10, -10, -10),
    spawn_range_high=(10, 10, 10)
)

Initial Conditions¶

Users can customize initial conditions including initial inventory, position, health and food, weather, and lighting condition.

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¶

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 and Lighting¶

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.

Users can opt to start at night by passing start_at_night = True.

Global Conditions¶

Users can customize global condition such as biome, time passage, and breaking speed. Select one biome from the list below and pass it to argument specified_biome to specify biome. Users can stop time passage through allow_time_passage = False.

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

Warning

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

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.

Randomness¶

seed and world_seed determine the randomness of task instances. seed: int controls extra spawning of mobs and materials. world_seed: int | str controls the procedurally generated Minecraft world. Using the same world_seed guarantees the same world every time.

Reset Mode¶

The conventional way to reset an environment instance is to re-generate the whole world, re-spawn the agent, and re-initialize initial conditions if necessary. However, a Minecraft world takes a non-negligible amount of time to generate, which can cause low throughput if training agents involves online environment interaction. We use fast reset by default to bypass this problem. Under the hood, the fast reset utilizes Minecraft commands to only re-spawn the agent and re-initialize initial conditions. It is roughly 100x faster than doing normal reset. To disable fast reset, set fast_reset = False.

Warning

There are three known side effects caused by not re-generating new worlds.

Changes to the world will not be reset. For example, if all trees in the world are chooped, calling fast reset will not restore them. Another example is that if the agent digs lots of holes, calling fast reset will not fill them.
If you specify agent starting health and food, these conditions will only be respected at the first reset (i.e., generating a new world) but will not be respected in the following resets (i.e., fast reset). Be careful to use if your usages require specific initial health/food.
Statistics will not be reset. Therefore, we maintain a property info_prev_reset. If your tasks use stat for evaluation, please retrieve this property and calculate differences.

Combat¶

A Combat task can be created by passing task_id = "Combat" or task_id = "combat" to minedojo.make(). As usual, it takes argument image_size as well. API for Combat tasks shares similar arguments and mechanism with that for Harvest tasks. We explain API that is unique to Combat tasks.

Global Conditions: Always Night¶

When fighting against monsters that can only appear at night such as zombies and creepers, the argument always_night becomes handy. Set always_night = True will disallow time passage and the world will remain at night.

Global Conditions: Allow 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.

Tech Tree¶

A TechTree task can be created by passing task_id = "TechTree" or task_id = "techtree" to minedojo.make(). As usual, it takes argument image_size as well. API for Tech Tree tasks also shares similar arguments and mechanism with those for Harvest and Combat tasks. We explain API that is unique to Tech Tree tasks.

Goal and Reward¶

To specify the goal, users can either choose to unlock the entire technology level (i.e., obtain and use all items under that technology level) or unlock a single item (i.e., obtain and use a single item).

To choose to unlock the entire technology level, users can pass tech = target_tech_level where all possible tech levels and corresponding items are listed below. To choose to only unlock a single item, users can pass tech_item = target_tech_item. Note that users should not provide tech and tech_item at the same time.

Note

All tech levels and their items

wooden: wooden_axe, wooden_hoe, wooden_pickaxe, wooden_shovel, wooden_sword
leather: leather_boots, leather_chestplate, leather_helmet, leather_leggings
chainmail: chainmail_boots, chainmail_chestplate, chainmail_helmet, chainmail_leggings
golden: golden_axe, golden_hoe, golden_pickaxe, golden_shovel, golden_sword, golden_boots, golden_chestplate, golden_helmet, golden_leggings
stone: stone_axe, stone_hoe, stone_pickaxe, stone_shovel, stone_sword
iron: iron_axe, iron_hoe, iron_pickaxe, iron_shovel, iron_sword, iron_boots, iron_chestplate, iron_helmet, iron_leggings
diamond: diamond_axe, diamond_hoe, diamond_pickaxe, diamond_shovel, diamond_sword, diamond_boots, diamond_chestplage, diamond_helmet, diamond_leggings
archecy: bow
explosives: tnt
redstone: redstone_block, clock, compass, dispenser, dropper, observer, piston, redstone_lamp, redstone_torch, repeater, detector_rail, comparator, activator_rail

Users can configure rewards for obtaining an item through obtain_items_reward_weights and using an item through use_items_reward_weights. When a single integer or float number is provided, it sets reward weights for all target items. Users can opt to specify different weights for different target items by providing a dict mapping item name to reward weight.

Survival¶

A Survival task can be created by passing task_id = "Survival" or task_id = "survival" to minedojo.make(). As usual, it takes argument image_size as well. API for Survival tasks shares similar arguments and mechanism with those for other tasks. We explain API that is unique to Survival tasks.

Goal and Reward¶

The goal in Survival tasks are to survive as long as possible. Therefore, the target is measured in the number of in-game days survived. Users can pass target_days: int to specify the target number of days. To configure the reward for successfully surviving each day, users can set per_day_reward: int | float. To configure the success reward, users can set success_reward: int | float. By default, the success reward equals to the reward for surviving each day multiplied by the target number of days.