minerl.herobraine

Handlers

In addition to the default environments MineRL provides, you can use a variety of custom handlers to build your own. See the Custom Environment Tutorial to understand how to use these handlers. The following is documentation on all handlers which MineRL currently supports.

Agent Handlers

Agent Handlers allow you to modify various properties of the agent (e.g. items in inventory, starting health, what gives the agent reward).

Agent Start Handlers

Agent start handlers define agent start conditions such as inventory items and health.

When used to create a Gym environment, they should be passed to create_agent_start

class minerl.herobraine.hero.handlers.agent.start.AgentStartBreakSpeedMultiplier(multiplier=1.0)

Bases: minerl.herobraine.hero.handler.Handler

Sets the break speed multiplier (how fast the agent can break blocks)

See here for more information: https://minecraft.fandom.com/el/wiki/Breaking

Example usage:

AgentStartBreakSpeedMultiplier(2.0)
to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.agent.start.AgentStartNear(anchor_name='MineRLAgent0', min_distance=2, max_distance=10, max_vert_distance=3)

Bases: minerl.herobraine.hero.handler.Handler

Starts agent near another agent

Example usage:

AgentStartNear("MineRLAgent0", min_distance=2, max_distance=10, max_vert_distance=3)
to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.agent.start.AgentStartPlacement(x, y, z, yaw, pitch=0.0)

Bases: minerl.herobraine.hero.handler.Handler

Sets for the agent start location

Example usage:

AgentStartPlacement(x=5, y=70, z=4, yaw=0, pitch=0)
to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.agent.start.InventoryAgentStart(inventory: Dict[int, Dict[str, Union[str, int]]])

Bases: minerl.herobraine.hero.handler.Handler

Sets the start inventory of the agent by slot id.

Example usage:

InventoryAgentStart({
    0: {'type':'dirt', 'quantity':10},
    # metadata specifies the type of planks (e.g. oak, spruce)
    1: {'type':'planks', 'metadata': 1, 'quantity':5},
    5: {'type':'log', 'quantity':1},
    6: {'type':'log', 'quantity':2},
    32: {'type':'iron_ore', 'quantity':4
})
to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.agent.start.RandomInventoryAgentStart(inventory: Dict[str, Union[str, int]], use_hotbar: bool = False)

Bases: minerl.herobraine.hero.handlers.agent.start.InventoryAgentStart

Sets the agent start inventory by randomly distributing items throughout its inventory slots. Note: This has no effect on inventory observation handlers.

Example usage:

RandomInventoryAgentStart(
    {'dirt': 10, 'planks': 5}
)
xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.agent.start.RandomizedStartDecorator

Bases: minerl.herobraine.hero.handler.Handler

to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.agent.start.SimpleInventoryAgentStart(inventory: List[Dict[str, Union[str, int]]])

Bases: minerl.herobraine.hero.handlers.agent.start.InventoryAgentStart

Sets the start inventory of the agent sequentially.

Example usage:

SimpleInventoryAgentStart([
    {'type':'dirt', 'quantity':10},
    {'type':'planks', 'quantity':5},
    {'type':'log', 'quantity':1},
    {'type':'iron_ore', 'quantity':4}
])
class minerl.herobraine.hero.handlers.agent.start.StartingFoodAgentStart(food: int = 20, food_saturation: Optional[float] = None)

Bases: minerl.herobraine.hero.handler.Handler

Sets the starting food and/or food saturation of the agent.

Example usage:

StartingFoodAgentStart(food=2.5, food_saturation=1)

:param food: The amount of food the agent starts out with :param food_saturation: Determines how fast the hunger level depletes, defaults to 5

to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.agent.start.StartingHealthAgentStart(max_health: float = 20, health: Optional[float] = None)

Bases: minerl.herobraine.hero.handler.Handler

Sets the starting health of the agent

Example usage:

StartingHealthAgentStart(max_health=20, health=2.5)

max_health sets the maximum amount of health the agent can have health sets amount of health the agent starts with (max_health if not specified)

to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

Agent Quit Handlers

These handlers cause the episode to terminate based on certain agent conditions.

When used to create a Gym environment, they should be passed to create_agent_handlers

class minerl.herobraine.hero.handlers.agent.quit.AgentQuitFromCraftingItem(items: List[Dict[str, Union[str, int]]])

Bases: minerl.herobraine.hero.handler.Handler

Terminates episode when agent crafts one of the items in items

Example usage:

AgentQuitFromCraftingItem([
    dict(type="iron_axe", amount=1), dict(type="diamond_block", amount=5)
])
to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.agent.quit.AgentQuitFromPossessingItem(items: List[Dict[str, Union[str, int]]])

Bases: minerl.herobraine.hero.handler.Handler

Terminates episode when agent obtains one of the items in items

Example usage:

AgentQuitFromPossessingItem([
    dict(type="golden_apple", amount=3), dict(type="diamond", amount=1)
])
to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.agent.quit.AgentQuitFromTouchingBlockType(blocks: List[str])

Bases: minerl.herobraine.hero.handler.Handler

Terminates episode when agent touches one of the blocks in blocks

Example usage:

AgentQuitFromTouchingBlockType([
    "gold_block", "oak_log"
])
to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

Reward Handlers

These handlers modify what things the agent gets rewarded for.

When used to create a Gym environment, they should be passed to create_rewardables

class minerl.herobraine.hero.handlers.agent.reward.ConstantReward(constant)

Bases: minerl.herobraine.hero.handlers.agent.reward.RewardHandler

A constant reward handler

from_hero(obs_dict)

By default hero will include the reward in the observation. This is just a pass through for convenience. :param obs_dict: :return: The reward

from_universal(x)

Converts a universal representation of the handler (e.g. universal action/observation)

class minerl.herobraine.hero.handlers.agent.reward.RewardForCollectingItems(item_rewards: List[Dict[str, Union[str, int]]])

Bases: minerl.herobraine.hero.handlers.agent.reward._RewardForPosessingItemBase

The standard malmo reward for collecting item.

Example usage:

RewardForCollectingItems([
    dict(type="log", amount=1, reward=1.0),
])
from_universal(x)

Converts a universal representation of the handler (e.g. universal action/observation)

class minerl.herobraine.hero.handlers.agent.reward.RewardForCollectingItemsOnce(item_rewards: List[Dict[str, Union[str, int]]])

Bases: minerl.herobraine.hero.handlers.agent.reward._RewardForPosessingItemBase

The standard malmo reward for collecting item once.

Example usage:

RewardForCollectingItemsOnce([
    dict(type="log", amount=1, reward=1),
])
from_universal(x)

Converts a universal representation of the handler (e.g. universal action/observation)

class minerl.herobraine.hero.handlers.agent.reward.RewardForDistanceTraveledToCompassTarget(reward_per_block: int, density: str = 'PER_TICK')

Bases: minerl.herobraine.hero.handlers.agent.reward.RewardHandler

Creates a reward which is awarded when the player reaches a certain distance from a target.

Example usage:

RewardForDistanceTraveledToCompassTarget(2)
from_universal(obs)

Converts a universal representation of the handler (e.g. universal action/observation)

reset()
to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.agent.reward.RewardForMissionEnd(reward: int, description: str = 'out_of_time')

Bases: minerl.herobraine.hero.handlers.agent.reward.RewardHandler

Creates a reward which is awarded when a mission ends.

Example usage:

# awards a reward of 5 when mission ends
RewardForMissionEnd(reward=5.0, description="mission termination")
from_universal(obs)

Converts a universal representation of the handler (e.g. universal action/observation)

to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.agent.reward.RewardForTouchingBlockType(blocks: List[Dict[str, Union[str, int, float]]])

Bases: minerl.herobraine.hero.handlers.agent.reward.RewardHandler

Creates a reward which is awarded when the player touches a block.

Example usage:

RewardForTouchingBlockType([
    {'type':'diamond_block', 'behaviour':'onceOnly', 'reward':'10'},
])
from_universal(obs)

Converts a universal representation of the handler (e.g. universal action/observation)

reset()
to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.agent.reward.RewardHandler

Bases: minerl.herobraine.hero.handlers.translation.TranslationHandler

Specifies a reward handler for a task. These need to be attached to tasks with reinforcement learning objectives. All rewards need inherit from this reward handler #Todo: Figure out how this interplays with Hero, as rewards are summed.

from_hero(obs_dict)

By default hero will include the reward in the observation. This is just a pass through for convenience. :param obs_dict: :return: The reward

Action Handlers

Action handlers define what actions agents are allowed to take.

When used to create a gym, you should override create_actionables and pass the action handlers to this function. See the Custom Environment Tutorial for more.

Camera

class minerl.herobraine.hero.handlers.agent.actions.camera.CameraAction

Bases: minerl.herobraine.hero.handlers.agent.action.Action

Uses <delta_pitch, delta_yaw> vector in degrees to rotate the camera. pitch range [-180, 180], yaw range [-180, 180]

from_universal(x)

Converts a universal representation of the handler (e.g. universal action/observation)

to_string()

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

Craft

class minerl.herobraine.hero.handlers.agent.actions.craft.CraftAction(items: list, _other=typing.Union[str, NoneType], _default=typing.Union[str, NoneType])

Bases: minerl.herobraine.hero.handlers.agent.action.ItemListAction

An action handler for crafting items

Note when used alongside Craft Item Nearby, block lists must be disjoint or from_universal will fire multiple times

from_universal(obs)

Converts a universal representation of the handler (e.g. universal action/observation)

to_string()

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.agent.actions.craft.CraftNearbyAction(items: list, _other=typing.Union[str, NoneType], _default=typing.Union[str, NoneType])

Bases: minerl.herobraine.hero.handlers.agent.actions.craft.CraftAction

An action handler for crafting items when agent is in view of a crafting table

Note when used along side Craft Item, item lists must be disjoint or from_universal will fire multiple times

to_string()

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

Equip

class minerl.herobraine.hero.handlers.agent.actions.equip.EquipAction(items: list, _default='none', _other='other')

Bases: minerl.herobraine.hero.handlers.agent.action.ItemWithMetadataListAction

An action handler for observing a list of equipped items

from_universal(obs) str

Converts a universal representation of the handler (e.g. universal action/observation)

logger = <Logger minerl.herobraine.hero.handlers.agent.actions.equip.EquipAction (WARNING)>
reset()
xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

Keyboard

class minerl.herobraine.hero.handlers.agent.actions.keyboard.KeybasedCommandAction(command, *keys)

Bases: minerl.herobraine.hero.handlers.agent.action.Action

A command action which is generated from human keypresses in anvil. Examples of such actions are movement actions, etc.

This is not to be confused with keyboard acitons, wehreby both anvil and malmo simulate and act on direct key codes.

Combinations of KeybasedCommandActions yield actions like:

{
    “move” : 1,
    “jump”: 1
}

where move and jump are the commands, which correspond to keys like ‘W’, ‘SPACE’, etc.

This is as opposed to keyboard actions (see the following class definition in keyboard.py) which yield actions like:

{
    "keyboard" : {
        "W" : 1,
        "A": 1,
        "S": 0,
        "E": 1,
        ...
    }
}

More information can be found in the unification document (internal).

from_universal(x)

Converts a universal representation of the handler (e.g. universal action/observation)

to_string()

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Notice how all of the instances of keybased command actions, of which there will be typically many in an environment spec, correspond to exactly the same XML stub.

This is discussed at length in the unification proposal and is a chief example of where manifest consolidation is needed.

Place

class minerl.herobraine.hero.handlers.agent.actions.place.PlaceBlock(blocks: list, _other=typing.Union[str, NoneType], _default=typing.Union[str, NoneType])

Bases: minerl.herobraine.hero.handlers.agent.action.ItemListAction

An action handler for placing a specific block

from_universal(obs)

Converts a universal representation of the handler (e.g. universal action/observation)

to_string()

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

Smelt

class minerl.herobraine.hero.handlers.agent.actions.smelt.SmeltItemNearby(items: list, _other=typing.Union[str, NoneType], _default=typing.Union[str, NoneType])

Bases: minerl.herobraine.hero.handlers.agent.actions.craft.CraftAction

An action handler for crafting items when agent is in view of a crafting table

Note when used along side Craft Item, block lists must be disjoint or from_universal will fire multiple times

from_universal(obs)

Converts a universal representation of the handler (e.g. universal action/observation)

to_string()

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

Observation Handlers

Observation handlers define what observation data agents receive (e.g. POV image, lifestats)

When used to create a gym, you should override create_observables and pass the observation handlers to this function. See the Custom Environment Tutorial for more.

Compass

class minerl.herobraine.hero.handlers.agent.observations.compass.CompassObservation(angle=True, distance=False)

Bases: minerl.herobraine.hero.handlers.translation.TranslationHandlerGroup

Defines compass observations.

Parameters
  • angle (bool, optional) – Whether or not to include angle observation. Defaults to True.

  • distance (bool, optional) – Whether or not ot include distance observation. Defaults to False.

Example usage:

# A compass observation object which gives angle and distance information
CompassObservation(True, True)
to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

Damage Source

class minerl.herobraine.hero.handlers.agent.observations.damage_source.ObservationFromDamageSource

Bases: minerl.herobraine.hero.handlers.translation.TranslationHandlerGroup

Includes the most recent damage event including the amount, type, location, and other properties.

to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

Equipped Item

class minerl.herobraine.hero.handlers.agent.observations.equipped_item.EquippedItemObservation(items: Sequence[str], mainhand: bool = True, offhand: bool = False, armor: bool = False, _default: str = 'none', _other: str = 'other')

Bases: minerl.herobraine.hero.handlers.translation.TranslationHandlerGroup

Enables the observation of equipped items in the main, offhand, and armor slots of the agent.

to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

Inventory

class minerl.herobraine.hero.handlers.agent.observations.inventory.FlatInventoryObservation(item_list: Sequence[str], _other='other')

Bases: minerl.herobraine.hero.handlers.translation.TranslationHandler

Handles GUI Container Observations for selected items

add_to_mission_spec(mission_spec)
from_hero(obs)

Converts the Hero observation into a one-hot of the inventory items for a given inventory container. Ignores variant / color :param obs: :return:

from_universal(obs)

Converts a universal representation of the handler (e.g. universal action/observation)

logger = <Logger minerl.herobraine.hero.handlers.agent.observations.inventory.FlatInventoryObservation (WARNING)>
to_string()

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

Lifestats

class minerl.herobraine.hero.handlers.agent.observations.lifestats.ObservationFromLifeStats

Bases: minerl.herobraine.hero.handlers.translation.TranslationHandlerGroup

Groups all of the lifestats observations together to correspond to one XML element.

to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

Location Stats

class minerl.herobraine.hero.handlers.agent.observations.location_stats.ObservationFromCurrentLocation

Bases: minerl.herobraine.hero.handlers.translation.TranslationHandlerGroup

Includes the current biome, how likely rain and snow are there, as well as the current light level, how bright the sky is, and if the player can see the sky.

Also includes x, y, z, roll, and pitch

to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

Base Stats

class minerl.herobraine.hero.handlers.agent.observations.mc_base_stats.ObserveFromFullStats(stat_key)

Bases: minerl.herobraine.hero.handlers.translation.TranslationHandlerGroup

Includes the use_item statistics for every item in MC that can be used

to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

POV

class minerl.herobraine.hero.handlers.agent.observations.pov.POVObservation(video_resolution: Tuple[int, int], include_depth: bool = False)

Bases: minerl.herobraine.hero.handlers.translation.KeymapTranslationHandler

Handles POV observations.

from_hero(obs)

Converts a “hero” representation of an instance of this handler to a member of the space.

to_string()

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

Server Handlers

Server Start Handlers

Server start handlers allow you to set the initial state of the World (e.g. weather, time)

When used to create a Gym environment, they should be passed to create_server_initial_conditions

class minerl.herobraine.hero.handlers.server.start.SpawningInitialCondition(allow_spawning: bool)

Bases: minerl.herobraine.hero.handler.Handler

to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.server.start.TimeInitialCondition(allow_passage_of_time: bool, start_time: Optional[int] = None)

Bases: minerl.herobraine.hero.handler.Handler

Sets the initial world time as well as whether time can pass.

Example usage:

# Sets time to morning and stops passing of time
TimeInitialCondition(False, 23000)
to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.server.start.WeatherInitialCondition(weather: str)

Bases: minerl.herobraine.hero.handler.Handler

Sets the initial weather condition in the world.

Example usage:

# Sets weather to thunder
WeatherInitialCondition("thunder")
to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

Server Quit Handlers

These handlers allow episode termination based on server conditions (e.g. time passed)

When used to create a Gym environment, they should be passed to create_server_quit_producers

class minerl.herobraine.hero.handlers.server.quit.ServerQuitFromTimeUp(time_limit_ms: int, description='out_of_time')

Bases: minerl.herobraine.hero.handler.Handler

Forces the server to quit after a certain time_limit_ms also specifies a description parameter for the xml.

Example usage

ServerQuitFromTimeUp(50000)
to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.server.quit.ServerQuitWhenAnyAgentFinishes

Bases: minerl.herobraine.hero.handler.Handler

Forces the server to quit if any of the agents involved quits. Has no parameters.

Example usage:

ServerQuitWhenAnyAgentFinishes()
to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

World Handlers

World handlers provide a number of ways to generate and modify the Minecraft world (e.g. specifying the type of world to be created, like Superflat, or drawing shapes and blocks in the world).

When used to create a Gym environment, they should be passed to create_server_world_generators

class minerl.herobraine.hero.handlers.server.world.BiomeGenerator(biome: Union[int, str], force_reset: bool = True)

Bases: minerl.herobraine.hero.handler.Handler

to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.server.world.DefaultWorldGenerator(force_reset=True, generator_options: str = '{}')

Bases: minerl.herobraine.hero.handler.Handler

Generates a world using minecraft procedural generation (this is the default world type in minecraft).

Parameters
  • force_reset (bool, optional) – If the world should be reset every episode.. Defaults to True.

  • generator_options – A JSON object specifying parameters to the procedural generator.

Example usage:

# Generates a default world that does not reset every episode (e.g. if blocks get broken in one episode
# they will not be replaced in the next)
DefaultWorldGenerator(False, "")
to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.server.world.DrawingDecorator(to_draw: str)

Bases: minerl.herobraine.hero.handler.Handler

Draws shapes (e.g. spheres, cuboids) in the world.

Example usage:

# draws an empty square of gold blocks
DrawingDecorator('
    <DrawCuboid x1="3" y1="4" z1="3" x2="3" y2="6" z2="-3" type="gold_block"/>
    <DrawCuboid x1="3" y1="4" z1="3" x2="-3" y2="6" z2="3" type="gold_block"/>
    <DrawCuboid x1="-3" y1="4" z1="-3" x2="3" y2="6" z2="-3" type="gold_block"/>
    <DrawCuboid x1="-3" y1="4" z1="-3" x2="-3" y2="6" z2="3" type="gold_block"/>
')

See Project Malmo for more

to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.server.world.FileWorldGenerator(filename: str, destroy_after_use: bool = True)

Bases: minerl.herobraine.hero.handler.Handler

Generates a world from a file.

to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.server.world.FlatWorldGenerator(force_reset: bool = True, generatorString: str = '')

Bases: minerl.herobraine.hero.handler.Handler

Generates a world that is a flat landscape.

Example usage:

to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.

class minerl.herobraine.hero.handlers.server.world.VillageSpawnDecorator

Bases: minerl.herobraine.hero.handler.Handler

to_string() str

The unique identifier for the agent handler. This is used for constructing action/observation spaces and unioning different env specifications.

xml_template() str

Generates an XML representation of the handler.

This XML representation is templated via Jinja2 and has access to all of the member variables of the class.

Note: This is not an abstract method so that handlers without corresponding XML’s can be combined in handler groups with group based XML implementations.