malmo::MissionSpec Class Reference

Specifies a mission to be run. More...

#include <MissionSpec.h>

Public Member Functions
	MissionSpec ()
	Constructs a mission with default parameters: a flat world with a 10 seconds time limit and continuous movement.
	MissionSpec (const std::string &xml, bool validate)
	Constructs a mission from the supplied XML as specified here: Schemas/Mission.html More...
std::string	getAsXML (bool prettyPrint) const
	Gets the mission specification as an XML string. More...
void	setSummary (const std::string &summary)
	Sets the summary description of the mission. More...
void	timeLimitInSeconds (float s)
	Sets the time limit for the mission. More...
void	createDefaultTerrain ()
	Instead of the default flat world, make a world using Minecraft's terrain generator. More...
void	setWorldSeed (const std::string &seed)
	Set the seed used for Minecraft's terrain generation. More...
void	forceWorldReset ()
	Force Minecraft to reload the world rather than use the current one (if appropriate). More...
void	setTimeOfDay (int t, bool allowTimeToPass)
	Sets the time of day for the start of the mission. More...
void	drawBlock (int x, int y, int z, const std::string &blockType)
	Draw a Minecraft block in the world. More...
void	drawCuboid (int x1, int y1, int z1, int x2, int y2, int z2, const std::string &blockType)
	Draw a solid cuboid in the world. More...
void	drawItem (int x, int y, int z, const std::string &itemType)
	Draw a Minecraft item in the world. More...
void	drawSphere (int x, int y, int z, int radius, const std::string &blockType)
	Draw a solid sphere of blocks in the world. More...
void	drawLine (int x1, int y1, int z1, int x2, int y2, int z2, const std::string &blockType)
	Draw a line of blocks in the world. More...
void	startAt (float x, float y, float z)
	Sets the start location for the agent. More...
void	startAtWithPitchAndYaw (float x, float y, float z, float pitch, float yaw)
	Sets the start location and angles for the agent. More...
void	endAt (float x, float y, float z, float tolerance)
	Sets the end location for the agent. More...
void	setModeToCreative ()
	Sets the player mode for the agent to creative, allowing them to fly and to not sustain damage. Only supports single agent missions.
void	setModeToSpectator ()
	Sets the player mode for the agent to spectator, allowing them to fly and pass through objects. Only supports single agent missions.
void	requestVideo (int width, int height)
	Asks for image data to be sent from Minecraft for the agent. More...
void	requestVideoWithDepth (int width, int height)
	Asks for image data and depth data to be sent from Minecraft for the agent. More...
void	setViewpoint (int viewpoint)
	Sets the camera position. More...
void	rewardForReachingPosition (float x, float y, float z, float amount, float tolerance)
	Asks for a reward to be sent to the agent when it reaches a certain position. More...
void	observeRecentCommands ()
	Asks for the list of commands acted upon since the last timestep to be returned in the observations. More...
void	observeHotBar ()
	Asks for the contents of the player's hot-bar to be included in the observations. More...
void	observeFullInventory ()
	Asks for the full item inventory of the player to be included in the observations. More...
void	observeGrid (int x1, int y1, int z1, int x2, int y2, int z2, const std::string &name)
	Asks for observations of the block types within a cuboid relative to the agent's position. More...
void	observeDistance (float x, float y, float z, const std::string &name)
	Asks for the Euclidean distance to a location to be included in the observations. More...
void	observeChat ()
	Asks for chat messages to be included in the observations.
void	removeAllCommandHandlers ()
	Remove any existing command handlers from the mission specification. More...
void	allowAllContinuousMovementCommands ()
	Adds a continuous movement command handler if none present, with neither an allow-list or a deny-list, thus allowing any command to be sent. More...
void	allowContinuousMovementCommand (const std::string &verb)
	Adds an allow-list to the continuous movement command handler if none present. More...
void	allowAllDiscreteMovementCommands ()
	Adds a discrete movement command handler if none present, with neither an allow-list or a deny-list, thus allowing any command to be sent. More...
void	allowDiscreteMovementCommand (const std::string &verb)
	Adds an allow-list to the discrete movement command handler if none present. More...
void	allowAllAbsoluteMovementCommands ()
	Adds an absolute movement command handler if none present, with neither an allow-list or a deny-list, thus allowing any command to be sent. More...
void	allowAbsoluteMovementCommand (const std::string &verb)
	Adds an allow-list to the absolute movement command handler if none present. More...
void	allowAllInventoryCommands ()
	Adds an inventory command handler if none present, with neither an allow-list or a deny-list, thus allowing any command to be sent. More...
void	allowInventoryCommand (const std::string &verb)
	Adds an allow-list to the inventory command handler if none present. More...
void	allowAllChatCommands ()
	Adds a chat command handler if none present, with neither an allow-list or a deny-list, thus allowing any command to be sent. More...
std::string	getSummary () const
	Returns the short description of the mission. More...
int	getNumberOfAgents () const
	Returns the number of agents involved in this mission. More...
bool	isVideoRequested (int role) const
	Gets whether video has been requested for one of the agents involved in this mission. More...
int	getVideoWidth (int role) const
	Returns the width of the requested video for one of the agents involved in this mission. More...
int	getVideoHeight (int role) const
	Returns the height of the requested video for one of the agents involved in this mission. More...
int	getVideoChannels (int role) const
	Returns the number of channels in the requested video for one of the agents involved in this mission. More...
std::vector< std::string >	getListOfCommandHandlers (int role) const
	Returns a list of the names of the active command handlers for one of the agents involved in this mission. More...
std::vector< std::string >	getAllowedCommands (int role, const std::string &command_handler) const
	Returns a list of the names of the allowed commands for one of the agents involved in this mission. More...

Friends
class	MissionInitSpec
std::ostream &	operator<< (std::ostream &os, const MissionSpec &ms)

Detailed Description

Specifies a mission to be run.

Constructor & Destructor Documentation

MissionSpec()

malmo::MissionSpec::MissionSpec	(	const std::string &	xml,
		bool	validate
	)

Constructs a mission from the supplied XML as specified here: Schemas/Mission.html

Parameters

xml	The full XML of the mission.
validate	If true, then throws an xml_schema::exception if the XML is not compliant with the schema.

Member Function Documentation

allowAbsoluteMovementCommand()

void malmo::MissionSpec::allowAbsoluteMovementCommand

(

const std::string &

verb

)

Adds an allow-list to the absolute movement command handler if none present.

Adds the specified verb to the allow-list. Note that when an allow-list is present, only the commands listed are allowed. Adds an absolute movement command handler if none present. Removes the deny-list from the absolute movement command handler if present. Only applies to the first agent in the mission. For multi-agent missions, specify the command handlers for each in the XML.

Parameters

verb	The command verb, e.g. "tpx".

allowAllAbsoluteMovementCommands()

void malmo::MissionSpec::allowAllAbsoluteMovementCommands

(

)

Adds an absolute movement command handler if none present, with neither an allow-list or a deny-list, thus allowing any command to be sent.

Only applies to the first agent in the mission. For multi-agent missions, specify the command handlers for each in the XML.

allowAllChatCommands()

void malmo::MissionSpec::allowAllChatCommands

(

)

Adds a chat command handler if none present, with neither an allow-list or a deny-list, thus allowing any command to be sent.

Only applies to the first agent in the mission. For multi-agent missions, specify the command handlers for each in the XML.

allowAllContinuousMovementCommands()

void malmo::MissionSpec::allowAllContinuousMovementCommands

(

)

Adds a continuous movement command handler if none present, with neither an allow-list or a deny-list, thus allowing any command to be sent.

Only applies to the first agent in the mission. For multi-agent missions, specify the command handlers for each in the XML.

allowAllDiscreteMovementCommands()

void malmo::MissionSpec::allowAllDiscreteMovementCommands

(

)

Adds a discrete movement command handler if none present, with neither an allow-list or a deny-list, thus allowing any command to be sent.

Only applies to the first agent in the mission. For multi-agent missions, specify the command handlers for each in the XML.

allowAllInventoryCommands()

void malmo::MissionSpec::allowAllInventoryCommands

(

)

Adds an inventory command handler if none present, with neither an allow-list or a deny-list, thus allowing any command to be sent.

Only applies to the first agent in the mission. For multi-agent missions, specify the command handlers for each in the XML.

allowContinuousMovementCommand()

void malmo::MissionSpec::allowContinuousMovementCommand

(

const std::string &

verb

)

Adds an allow-list to the continuous movement command handler if none present.

Adds the specified verb to the allow-list. Note that when an allow-list is present, only the commands listed are allowed. Adds a continuous movement command handler if none present. Removes the deny-list from the continuous movement command handler if present. Only applies to the first agent in the mission. For multi-agent missions, specify the command handlers for each in the XML.

Parameters

verb	The command verb, e.g. "move".

allowDiscreteMovementCommand()

void malmo::MissionSpec::allowDiscreteMovementCommand

(

const std::string &

verb

)

Adds an allow-list to the discrete movement command handler if none present.

Adds the specified verb to the allow-list. Note that when an allow-list is present, only the commands listed are allowed. Adds a discrete movement command handler if none present. Removes the deny-list from the discrete movement command handler if present. Only applies to the first agent in the mission. For multi-agent missions, specify the command handlers for each in the XML.

Parameters

verb	The command verb, e.g. "movenorth".

allowInventoryCommand()

void malmo::MissionSpec::allowInventoryCommand

(

const std::string &

verb

)

Adds an allow-list to the inventory command handler if none present.

Adds the specified verb to the allow-list. Note that when an allow-list is present, only the commands listed are allowed. Adds an inventory command handler if none present. Removes the deny-list from the inventory command handler if present. Only applies to the first agent in the mission. For multi-agent missions, specify the command handlers for each in the XML.

Parameters

verb	The command verb, e.g. "selectInventoryItem".

createDefaultTerrain()

void malmo::MissionSpec::createDefaultTerrain

(

)

Instead of the default flat world, make a world using Minecraft's terrain generator.

Calling this will reset the world seed and forceReset flag - see setWorldSeed() and forceWorldReset().

drawBlock()

void malmo::MissionSpec::drawBlock	(	int	x,
		int	y,
		int	z,
		const std::string &	blockType
	)

Draw a Minecraft block in the world.

Parameters

x	The east-west location.
y	The up-down location.
z	The north-south location.
blockType	A string corresponding to one of the Minecraft block types.

drawCuboid()

void malmo::MissionSpec::drawCuboid	(	int	x1,
		int	y1,
		int	z1,
		int	x2,
		int	y2,
		int	z2,
		const std::string &	blockType
	)

Draw a solid cuboid in the world.

Parameters

x1	The west-most location.
y1	The down-most location.
z1	The north-most location.
x2	The east-most location.
y2	The up-most location.
z2	The south-most location.
blockType	A string corresponding to one of the Minecraft block types.

drawItem()

void malmo::MissionSpec::drawItem	(	int	x,
		int	y,
		int	z,
		const std::string &	itemType
	)

Draw a Minecraft item in the world.

Parameters

x	The east-west location.
y	The up-down location.
z	The north-south location.
itemType	A string corresponding to one of the Minecraft item types.

drawLine()

void malmo::MissionSpec::drawLine	(	int	x1,
		int	y1,
		int	z1,
		int	x2,
		int	y2,
		int	z2,
		const std::string &	blockType
	)

Draw a line of blocks in the world.

Parameters

x1	The east-west location of the first end.
y1	The up-down location of the first end.
z1	The north-south location of the first end.
x2	The east-west location of the second end.
y2	The up-down location of the second end.
z2	The north-south location of the second end.
blockType	A string corresponding to one of the Minecraft block types.

drawSphere()

void malmo::MissionSpec::drawSphere	(	int	x,
		int	y,
		int	z,
		int	radius,
		const std::string &	blockType
	)

Draw a solid sphere of blocks in the world.

Parameters

x	The east-west location of the center.
y	The up-down location of the center.
z	The north-south location of the center.
radius	The radius of the sphere.
blockType	A string corresponding to one of the Minecraft block types.

endAt()

void malmo::MissionSpec::endAt	(	float	x,
		float	y,
		float	z,
		float	tolerance
	)

Sets the end location for the agent.

Only supports single agent missions. Can be called more than once if there are multiple positions that end the mission for this agent. Integer coordinates are at the corners of blocks, so to end in the center of a block, use e.g. 4.5 instead of 4.0.

Parameters

x	The east-west location.
y	The up-down location.
z	The north-south location.
tolerance	The radius that the agent must be within. Euclidean distance.

forceWorldReset()

void malmo::MissionSpec::forceWorldReset

(

)

Force Minecraft to reload the world rather than use the current one (if appropriate).

Call this after the world generator has been set (eg after calling createDefaultTerrain() ).

getAllowedCommands()

std::vector<std::string> malmo::MissionSpec::getAllowedCommands	(	int	role,
		const std::string &	command_handler
	)		const

Returns a list of the names of the allowed commands for one of the agents involved in this mission.

Parameters

role	The agent index. Zero based.
command_handler	The name of the command handler, as returned by getListOfCommandHandlers().

Returns

The list of allowed commands: 'move', 'turn', 'attack' etc.

getAsXML()

std::string malmo::MissionSpec::getAsXML

(

bool

prettyPrint

)

const

Gets the mission specification as an XML string.

Only use if you want to save the mission to file.

Parameters

prettyPrint

If true, add indentation and newlines to the XML to make it more readable.

Returns

The mission specification as an XML string.

getListOfCommandHandlers()

std::vector<std::string> malmo::MissionSpec::getListOfCommandHandlers

(

int

role

)

const

Returns a list of the names of the active command handlers for one of the agents involved in this mission.

Parameters

role	The agent index. Zero based.

Returns

The list of command handler names: 'ContinuousMovement', 'DiscreteMovement', 'Chat', 'Inventory' etc.

getNumberOfAgents()

int malmo::MissionSpec::getNumberOfAgents

(

)

const

Returns the number of agents involved in this mission.

Returns

The number of agents.

getSummary()

std::string malmo::MissionSpec::getSummary

(

)

const

Returns the short description of the mission.

Returns

A string containing the summary.

getVideoChannels()

int malmo::MissionSpec::getVideoChannels

(

int

role

)

const

Returns the number of channels in the requested video for one of the agents involved in this mission.

Parameters

role	The agent index. Zero based.

Returns

The number of channels in the requested video: 3 for RGB, 4 for RGBD.

getVideoHeight()

int malmo::MissionSpec::getVideoHeight

(

int

role

)

const

Returns the height of the requested video for one of the agents involved in this mission.

Parameters

role	The agent index. Zero based.

Returns

The height of the video in pixels.

getVideoWidth()

int malmo::MissionSpec::getVideoWidth

(

int

role

)

const

Returns the width of the requested video for one of the agents involved in this mission.

Parameters

role	The agent index. Zero based.

Returns

The width of the video in pixels.

isVideoRequested()

bool malmo::MissionSpec::isVideoRequested

(

int

role

)

const

Gets whether video has been requested for one of the agents involved in this mission.

Parameters

role	The agent index. Zero based.

Returns

True if video was requested.

observeDistance()

void malmo::MissionSpec::observeDistance	(	float	x,
		float	y,
		float	z,
		const std::string &	name
	)

Asks for the Euclidean distance to a location to be included in the observations.

Only supports single agent missions. Integer coordinates are at the corners of blocks, so for distances from the center of a block, use e.g. 4.5 instead of 4.0. The commands are returned in a JSON element 'distanceFromNAME', where NAME is replaced with the name of the point. Documentation link: Schemas/MissionHandlers.html

Parameters

x	The east-west location.
y	The up-down location.
z	The north-south location.
name	A label for this observation. The observation will be called "distanceFrom<name>".

observeFullInventory()

void malmo::MissionSpec::observeFullInventory

(

)

Asks for the full item inventory of the player to be included in the observations.

Only supports single agent missions. The commands are returned in JSON entries 'Inventory_0_size', 'Inventory_0_item', etc. Documentation link: Schemas/MissionHandlers.html

observeGrid()

void malmo::MissionSpec::observeGrid	(	int	x1,
		int	y1,
		int	z1,
		int	x2,
		int	y2,
		int	z2,
		const std::string &	name
	)

Asks for observations of the block types within a cuboid relative to the agent's position.

Only supports single agent missions. The commands are returned in a JSON entry 'Cells'. Documentation link: Schemas/MissionHandlers.html

Parameters

x1	The west-most location.
y1	The down-most location.
z1	The north-most location.
x2	The east-most location.
y2	The up-most location.
z2	The south-most location.
name	An name to identify the JSON array that will be returned.

observeHotBar()

void malmo::MissionSpec::observeHotBar

(

)

Asks for the contents of the player's hot-bar to be included in the observations.

Only supports single agent missions. The commands are returned in JSON entries 'Hotbar_0_size', 'Hotbar_0_item', etc. Documentation link: Schemas/MissionHandlers.html

observeRecentCommands()

void malmo::MissionSpec::observeRecentCommands

(

)

Asks for the list of commands acted upon since the last timestep to be returned in the observations.

Only supports single agent missions. The commands are returned in a JSON entry called 'CommandsSinceLastObservation'. Documentation link: Schemas/MissionHandlers.html

removeAllCommandHandlers()

void malmo::MissionSpec::removeAllCommandHandlers

(

)

Remove any existing command handlers from the mission specification.

Use with other functions to add exactly the command handlers you want. Only applies to the first agent in the mission. For multi-agent missions, specify the command handlers for each in the XML.

requestVideo()

void malmo::MissionSpec::requestVideo	(	int	width,
		int	height
	)

Asks for image data to be sent from Minecraft for the agent.

Only supports single agent missions. Data will be delivered in a TimestampedVideoFrame structure as RGBRGBRGB... The default camera viewpoint will be used (first-person view) - use setViewpoint to change this.

Parameters

width	The width of the image in pixels. Ensure this is divisible by 4.
height	The height of the image in pixels. Ensure this is divisible by 2.

requestVideoWithDepth()

void malmo::MissionSpec::requestVideoWithDepth	(	int	width,
		int	height
	)

Asks for image data and depth data to be sent from Minecraft for the agent.

Only supports single agent missions. Data will be delivered in a TimestampedVideoFrame structure as RGBDRGBDRGBD... If saving the video to file only the depth will be recorded, as greyscale.

Parameters

width	The width of the image in pixels. Ensure this is divisible by 4.
height	The height of the image in pixels. Ensure this is divisible by 2.

rewardForReachingPosition()

void malmo::MissionSpec::rewardForReachingPosition	(	float	x,
		float	y,
		float	z,
		float	amount,
		float	tolerance
	)

Asks for a reward to be sent to the agent when it reaches a certain position.

Only supports single agent missions. Integer coordinates are at the corners of blocks, so for rewards in the center of a block, use e.g. 4.5 instead of 4.0.

Parameters

x	The east-west location.
y	The up-down location.
z	The north-south location.
amount	The reward value to send.
tolerance	The radius that the agent must be within to receive the reward. Euclidean distance.

setSummary()

void malmo::MissionSpec::setSummary

(

const std::string &

summary

)

Sets the summary description of the mission.

Parameters

summary

The string describing the mission. Shorter strings display best.

setTimeOfDay()

void malmo::MissionSpec::setTimeOfDay	(	int	t,
		bool	allowTimeToPass
	)

Sets the time of day for the start of the mission.

Parameters

t	The time of day, in Minecraft ticks (thousandths of an hour since dawn). eg. 0 = Dawn, 6000 = Noon, 12000 = Sunset, 18000 = Midnight.
allowTimeToPass	If false then the sun does not move.

setViewpoint()

void malmo::MissionSpec::setViewpoint

(

int

viewpoint

)

Sets the camera position.

Modifies the existing video request, so call this after requestVideo or requestVideoWithDepth.

Parameters

viewpoint

The camera position to use. 0 = first person, 1 = behind, 2 = facing.

setWorldSeed()

void malmo::MissionSpec::setWorldSeed

(

const std::string &

seed

)

Set the seed used for Minecraft's terrain generation.

Call this after the world generator has been set (eg after calling createDefaultTerrain() ).

startAt()

void malmo::MissionSpec::startAt	(	float	x,
		float	y,
		float	z
	)

Sets the start location for the agent.

Only supports single agent missions. Integer coordinates are at the corners of blocks, so to start in the center of a block, use e.g. 4.5 instead of 4.0.

Parameters

x	The east-west location.
y	The up-down location.
z	The north-south location.

startAtWithPitchAndYaw()

void malmo::MissionSpec::startAtWithPitchAndYaw	(	float	x,
		float	y,
		float	z,
		float	pitch,
		float	yaw
	)

Sets the start location and angles for the agent.

Only supports single agent missions. Integer coordinates are at the corners of blocks, so to start in the center of a block, use e.g. 4.5 instead of 4.0.

Parameters

x	The east-west location.
y	The up-down location.
z	The north-south location.
yaw	The yaw in degrees (180 = north, 270 = east, 0 = south, 90 = west)
pitch	The pitch in degrees (-90 = straight up, 90 = straight down, 0 = horizontal)

timeLimitInSeconds()

void malmo::MissionSpec::timeLimitInSeconds

(

float

s

)

Sets the time limit for the mission.

Parameters

s	The time limit in seconds.

---

The documentation for this class was generated from the following file:

• Malmo/src/MissionSpec.h