`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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: _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: _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: 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: 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: 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: 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: 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: 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: 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: 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: 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 actions, whereby 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: 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: 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.

Chat

class minerl.herobraine.hero.handlers.agent.actions.chat.ChatAction

Bases: Action

Handler which lets agents send Minecraft chat messages

Note: this may currently be limited to the first agent sending messages (check Malmo for this)

This can be used to execute MINECRAFT COMMANDS !!!

Example usage:

ChatAction()

To summon a creeper, use this action dictionary:

{"chat": "/summon creeper"}

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.

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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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.

minerl.herobraine

Handlers

Agent Handlers

Agent Start Handlers

Agent Quit Handlers

Reward Handlers

Action Handlers

Camera

Craft

Equip

Keyboard

Place

Smelt

Chat

Observation Handlers

Compass

Damage Source

Equipped Item

Inventory

Lifestats

Location Stats

Base Stats

POV

Server Handlers

Server Start Handlers

Server Quit Handlers

World Handlers

`minerl.herobraine`