Project Malmo  0.17.0
Public Member Functions | Friends | List of all members
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 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

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

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

Parameters
xmlThe full XML of the mission.
validateIf true, then throws an xml_schema::exception if the XML is not compliant with the schema.

Member Function Documentation

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
verbThe command verb, e.g. "tpx".
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.

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.

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.

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.

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.

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
verbThe command verb, e.g. "move".
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
verbThe command verb, e.g. "movenorth".
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
verbThe command verb, e.g. "selectInventoryItem".
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().

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

Draw a Minecraft block in the world.

Parameters
xThe east-west location.
yThe up-down location.
zThe north-south location.
blockTypeA string corresponding to one of the Minecraft block types.
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
x1The west-most location.
y1The down-most location.
z1The north-most location.
x2The east-most location.
y2The up-most location.
z2The south-most location.
blockTypeA string corresponding to one of the Minecraft block types.
void malmo::MissionSpec::drawItem ( int  x,
int  y,
int  z,
const std::string &  itemType 
)

Draw a Minecraft item in the world.

Parameters
xThe east-west location.
yThe up-down location.
zThe north-south location.
itemTypeA string corresponding to one of the Minecraft item types.
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
x1The east-west location of the first end.
y1The up-down location of the first end.
z1The north-south location of the first end.
x2The east-west location of the second end.
y2The up-down location of the second end.
z2The north-south location of the second end.
blockTypeA string corresponding to one of the Minecraft block types.
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
xThe east-west location of the center.
yThe up-down location of the center.
zThe north-south location of the center.
radiusThe radius of the sphere.
blockTypeA string corresponding to one of the Minecraft block types.
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
xThe east-west location.
yThe up-down location.
zThe north-south location.
toleranceThe radius that the agent must be within. Euclidean distance.
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() ).

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
roleThe agent index. Zero based.
command_handlerThe name of the command handler, as returned by getListOfCommandHandlers().
Returns
The list of allowed commands: 'move', 'turn', 'attack' etc.
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
prettyPrintIf true, add indentation and newlines to the XML to make it more readable.
Returns
The mission specification as an XML string.
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
roleThe agent index. Zero based.
Returns
The list of command handler names: 'ContinuousMovement', 'DiscreteMovement', 'Chat', 'Inventory' etc.
int malmo::MissionSpec::getNumberOfAgents ( ) const

Returns the number of agents involved in this mission.

Returns
The number of agents.
std::string malmo::MissionSpec::getSummary ( ) const

Returns the short description of the mission.

Returns
A string containing the summary.
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
roleThe agent index. Zero based.
Returns
The number of channels in the requested video: 3 for RGB, 4 for RGBD.
int malmo::MissionSpec::getVideoHeight ( int  role) const

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

Parameters
roleThe agent index. Zero based.
Returns
The height of the video in pixels.
int malmo::MissionSpec::getVideoWidth ( int  role) const

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

Parameters
roleThe agent index. Zero based.
Returns
The width of the video in pixels.
bool malmo::MissionSpec::isVideoRequested ( int  role) const

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

Parameters
roleThe agent index. Zero based.
Returns
True if video was requested.
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
xThe east-west location.
yThe up-down location.
zThe north-south location.
nameA label for this observation. The observation will be called "distanceFrom<name>".
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

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
x1The west-most location.
y1The down-most location.
z1The north-most location.
x2The east-most location.
y2The up-most location.
z2The south-most location.
nameAn name to identify the JSON array that will be returned.
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

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

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.

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
widthThe width of the image in pixels. Ensure this is divisible by 4.
heightThe height of the image in pixels. Ensure this is divisible by 2.
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
widthThe width of the image in pixels. Ensure this is divisible by 4.
heightThe height of the image in pixels. Ensure this is divisible by 2.
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
xThe east-west location.
yThe up-down location.
zThe north-south location.
amountThe reward value to send.
toleranceThe radius that the agent must be within to receive the reward. Euclidean distance.
void malmo::MissionSpec::setSummary ( const std::string &  summary)

Sets the summary description of the mission.

Parameters
summaryThe string describing the mission. Shorter strings display best.
void malmo::MissionSpec::setTimeOfDay ( int  t,
bool  allowTimeToPass 
)

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

Parameters
tThe time of day, in Minecraft ticks (thousandths of an hour since dawn). eg. 0 = Dawn, 6000 = Noon, 12000 = Sunset, 18000 = Midnight.
allowTimeToPassIf false then the sun does not move.
void malmo::MissionSpec::setViewpoint ( int  viewpoint)

Sets the camera position.

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

Parameters
viewpointThe camera position to use. 0 = first person, 1 = behind, 2 = facing.
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() ).

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
xThe east-west location.
yThe up-down location.
zThe north-south location.
void malmo::MissionSpec::timeLimitInSeconds ( float  s)

Sets the time limit for the mission.

Parameters
sThe time limit in seconds.

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