Privileged Observation¶

Privileged observations such as voxels and lidar are restricted in favor of fairness. However, in some cases such as collecting expert trajectories, we may want to utilize privileged observations. For example, we can use lidar to script a tree chopping bot. This section details how to customize these privileged observations.

Voxels¶

Our native observation space already includes 3x3x3 voxel observations. This resembles how human players perceive their surrounding blocks. Furthermore, it is also possible to cover a larger region (e.g., a 10x10x10 region around the agent), which may become helpful when designing a navigation bot leveraging search algorithms.

Users first need to set use_voxel = True to enable voxel observations. After that users can configure the region to be scanned by passing voxel_size: dict[str, int]. It should include six keys, xmin, xmax, ymin, ymax, zmin, and zmax. The code block below demonstrates how to set up voxel observations with a 9x9x9 region.

env = minedojo.make(
    "open-ended",
    ...,
    use_voxel=True,
    voxel_size=dict(xmin=-4, ymin=-4, zmin=-4, xmax=4, ymax=4, zmax=4),
    ...
)

Lidar¶

When lidar is enabled, several rays will emit from the agent. Agent then receives information about any entities and blocks traced by rays. This can be used to develop, for example, smart tree chopping bots.

Configuration¶

Set use_lidar = True to enable lidar observations. Then we need to configure lidar rays. lidar_rays: list[tuple[float, float, float]] takes a list of tuples with each tuple specifying one ray in the format of (pitch, yaw, distance). Pitch and yaw are in radians and are relative to agent’s looking vector. Distance in meters represents the maximum distance to trace. The code block below demonstrates how to enable lidar observation and create rays covering all directions with an interval of 15 degree.

env = minedojo.make(
    "open-ended",
    ...,
    use_lidar=True,
    lidar_rays=[
            (np.pi * pitch / 180, np.pi * yaw / 180, 999)
            for pitch in np.arange(-180, 180, 15)
            for yaw in np.arange(-180, 180, 15)
    ]
    ...
)

Warning

Using lidar can cause slow down in simulation speed. More rays will further decrease the simulation throughput.

Lidar Observations¶

Lidar observations are grouped under obs["rays"]. It includes three parts: information about traced entities, properties of traced blocks, and directions of lidar rays themselves.

Information about Traced Entities¶

Information about traced entities includes names of and distances to entities.

Entity Name¶

Names of traced entities.

Data type: str
Shape: (num_rays,)
Access: obs["rays"]["entity_name"]

Note

The name is “null” if no entity traced.

Entity Distance¶

Distances to traced entities.

Data type: numpy.float32
Shape: (num_rays,)
Access: obs["rays"]["entity_distance"]

Properties of Traced Blocks¶

Properties of traced blocks include blocks’ names, locations, distances, and so on.

Block Name¶

Names of traced blocks in natural language, such as “dirt”, “air”, and “water”.

Data type: str
Shape: (num_rays,)
Access: obs["rays"]["block_name"]

Block Distance¶

Distances to traced blocks.

Data type: numpy.float32
Shape: (num_rays,)
Access: obs["rays"]["block_distance"]

Block Variant¶

Variants of traced blocks. See here for a full listing of variants.

Data type: numpy.int64
Shape: (num_rays,)
Access: obs["rays"]["block_meta"]

Block Movement¶

It means if the traced block can move. For example, sand blocks can drop caused by gravity.

Data type: boolean
Shape: (num_rays,)
Access: obs["rays"]["blocks_movement"]

Can Burn¶

It tells if a traced block can burn. For example, leaves and grass can burn.

Data type: boolean
Shape: (num_rays,)
Access: obs["rays"]["can_burn"]

Harvest Level¶

It tells the requirement on tool’s level to harvest the block. For example, diamond ore cannot be harvested with a pickaxe less advanced than diamond pickaxe.

Data type: numpy.int64
Shape: (num_rays,)
Access: obs["rays"]["harvest_level"]

Is Liquid¶

It tells if the traced block is liquid. For example, water and lava are liquid blocks.

Data type: boolean
Shape: (num_rays,)
Access: obs["rays"]["is_liquid"]

Is Solid¶

It tells if the traced block is solid. Liquid blocks are not solid. Air block is not solid as well.

Data type: boolean
Shape: (num_rays,)
Access: obs["rays"]["is_solid"]

Is Tool Required¶

It means if any tool is required to mine a block. E.g., to mine metal we must use a pickaxe.

Data type: boolean
Shape: (num_rays,)
Access: obs["rays"]["is_tool_not_required"]

Block Position¶

XYZ position of a traced block.

Data type: numpy.float32
Shape: (num_rays,)
Access: obs["rays"]["traced_block_x"], obs["rays"]["traced_block_y"], and obs["rays"]["traced_block_z"]

Directions of Rays¶

Yaw and pitch of lidar rays relative to agent’s looking vector.

Data type: numpy.float32
Shape: (num_rays,)
Access: obs["rays"]["ray_yaw"] and obs["rays"]["ray_pitch"]

Example Usage¶

Lidar can be used in many ways. For example, we can utilize them to script tree chopping bots and combat bots. Here we show how to use them to provide dense reward shaping for navigating to an entity.

In our example, we want to engineer a dense reward shaping to encourage the agent to approach a sheep. First we want to configure rays that only emit from agent’s front side.

env = minedojo.make(
    "open-ended",
    ...,
    use_lidar=True,
    lidar_rays=[
            (np.pi * pitch / 180, np.pi * yaw / 180, 999)
            for pitch in np.arange(-30, 30, 10)
            for yaw in np.arange(-30, 30, 10)
    ]
    ...
)

Then at every step, we can query the distance to a sheep if it appears in agent’s sight.

entities, distances = obs["rays"]["entity_name"], obs["rays"]["entity_distance"]
sheep_idx = np.where(entities == "sheep")[0]

if len(sheep_idx) > 0:
    sheep_distance = np.min(distances[sheep_idx])

With sheep_distance we can then write a dense reward shaping that encourages the agent gets closer to the sheep.