MASSim Protocol Documentation
The MASSim protocol defines sequences of XML messages which are exchanged between the agents and the MASSim server. Agents communicate with the server using standard TCP sockets.
An agent may initiate communication by sending an
AUTH-REQUEST message, containing its login credentials.
The server tries to authenticate the agent and answers with an
If the result was positive, the server now sends various messages over the socket depending on its state:
SIM-STARTmessage, whenever a new simulation starts
REQUEST-ACTIONmessage right before each simulation step
SIM-ENDmessage after each simulation
BYEmessage when all matches have been run, just before the server closes all sockets
An agent should respond with an
ACTION message to all
REQUEST-ACTION messages it receives (within the time limit).
If an agent loses the connection to the server, it may reconnect using the standard
AUTH-REQUEST message. Auhtentication proceeds as before. If authentication was successful and the agent reconnects into a running simulation, the
SIM-START message is sent again. If it coincides with a new simulation step, the order of
REQUEST-ACTION messages is not guaranteed however.
Each message is terminated by a separate
0 byte. The server buffers everything up to the 0 byte and tries to parse an XML string from that.
Used by agents to initiate communication with the server.
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message type="auth-request"> <auth-request username="agentA1" password="1"/> </message>
All messages are enclosed in
<message> tags and have a
type attribute describing what kind of protocol message they represent.
This message has one
<auth-request> element with the attributes
Sent by the server in reply to
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message timestamp="1489514144783" type="auth-response"> <auth-response result="ok"/> </message>
- timestamp: is the server time of when the message was created (in ms since 1970)
- result: the result of the authentication; either ok or fail
<message timestamp="1489514141992" type="sim-start"> <simulation id="2017-TestSim-1of1" steps="1000" team="A"> ... </simulation> </message>
Also contains a timestamp. The content of the simulation element, as well as further attributes, depend on the scenario (see Percepts section of scenario.md).
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message timestamp="1489514146201" type="request-action"> <percept deadline="1489514150201" id="1"> <simulation step="1"/> ... </percept> </message>
REQUEST-ACTION message also contains a server timestamp and its type as attribute. The main element is
<percept>, containing the current simulation state as perceived by the agent (i.e. its percepts).
- deadline: the time at which the server stops waiting for an
ACTIONmessage; the time between timestamp and deadline should be the timeout specified in the server config
- id: the action-id; this id must be used in the
ACTIONmessage so that it can be associated with the correct request (which prevents older actions from being executed if they arrive too late); in case multiple actions are sent for the same action-id, the first action is processed
- simulation: contains global simulation information
- step: the current simulation step
The remaining content of the percept element, as well as further attributes, depend on the scenario (see Percepts section of scenario.md).
The response to a
REQUEST-ACTION message; sent by agents to the server.
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message type="action"> <action id="0" type="goto"> <p>51.6</p> <p>11.4</p> </action> </message>
- id: the action-id that the agent received in the
- type: the type of the action; depends on the current scenario
- p: a number of parameters for the action, which depend on the action that is used
Contains the result of 1 simulation for the team.
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message timestamp="1489575032814" type="sim-end"> <sim-result ranking="1" score="50000"/> </message>
- ranking: the team's rank at the end of the simulation
- score: the score the team achieved in the simulation
This message indicates that the server has run all simulations it was configured for and will close the socket afterwards.
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message timestamp="1489575049861" type="bye"> <bye/> </message>