matrx.api.api

Module Contents

get_info()

Provides the general information on the world, contained in the world object.

API Path: http://>MATRX_core_ip<:3001/get_info

Returns

MATRX world object, containing general information on the world and scenario.

get_latest_state_and_messages()

Provides all most recent information from MATRX for 1 agent: The state from the latest tick, and any new messages and chatrooms.

API Path: http://>MATRX_core_ip<:3001/get_latest_state_and_messages

Parameters should be passed via GET URL parameters.

A combination of get_latest_state() and get_messages(). See those two functions for their respective documentation.

Parameters
agent_id(required GET URL parameter, default {})

The ID of the targeted agent. Only the state of that agent, and chatrooms in which that agent is part will be sent.

chat_offsets(optional GET URL parameter, default {})

It is not efficient to send every message every tick. With this offsets dict the requestee can indicate for every chatroom, which messages they already have, such that only new messages can be sent. The offsets URL parmaeter should be a dict with as keys the chatroom ID, and as values the message offset. The message offset is the index of the message. Example of a valid dict: {“0”: “10”, “3”: “5”}. This returns the message with index 10+ for the chatroom with ID 0 (global chat), and messages with index 5+ for chatroom with ID 3.

Returns
A dictionary containing the states under the “states” key, and the chatrooms with messages under the

“chatrooms” key.

get_states(tick)

Provides the states of all agents (including the god view) from tick tick onwards to current tick.

API Path: http://>MATRX_core_ip<:3001/get_states/<tick>

Parameters
tick

integer indicating from which tick onwards to send the states.

Returns
Returns a list of length tick to current_tick. For each tick (item in the list), a dictionary contains the

state for each agent existing in the simulation, indexed by their agent ID.

get_states_specific_agents(tick, agent_ids)

Provides the states starting from tick tick to current_tick, for the agents specified in agent_ids.

API Path: http://>MATRX_core_ip<:3001/get_states/<tick>/<agent_ids>

Parameters
tick

integer indicating from which tick onwards to send the states.

agent_ids

One agent ID, or a List of agent IDs for which the states should be returned. God view = “god”

Returns
Returns a list of length tick to current_tick. For each tick (item in the list), a dictionary contains the

state for each agent as specified in agent_ids, indexed by their agent ID.

get_latest_state(agent_ids)

Provides the latest state of one or multiple agents

API Path: http://>MATRX_core_ip<:3001/get_latest_state/<agent_ids>

Parameters
agent_ids

IDs of agents for which to send the latest state. Either a single agent ID, or a list of agent IDs. God view = “god”

Returns
Returns a list of length tick to current_tick. For each tick, a dictionary contains the states for each

agent as specified in agent_ids, indexed by their agent ID.

get_filtered_latest_state(agent_ids)

Return a state for a set of agent IDs, filtered to only return the specified properties

get_messages_apicall()

Returns chatrooms and chat messages for one agent, or all agents.

Per chatroom, an offset can be passed from which will only return messages with a higher index than that

offset.

API Path: http://>MATRX_core_ip<:3001/get_messages/

Parameters should be passed via GET URL parameters.

Parameters
agent_id(optional URL parameter, default None)

Agent ID string that will make this function only return chatrooms of which that agent is part. Defaults to None, returning all chatsrooms and all chat messages.

chat_offsets(optional URL parameter, default None)

It is not efficient to send every message every tick. With this chat_offsets dict the requestee can indicate for every chatroom, which messages they already have, such that only new messages can be sent. The chat_offsets URL parmaeter should be a dict with as keys the chatroom ID, and as values the message offset. The message offset is the index of the message. Example of a valid dict: {“0”: “10”, “3”: “5”}. This returns the message with index 10+ for the chatroom with ID 0 (global chat), and messages with index 5+ for chatroom with ID 3.

Returns
——-

Returns a dictionary with chatrooms and per chatroom a list per with messages. The dict is in the shape of: {chatroom_ID: [Message1, Message2, ..], chatroom_ID2 : ….}

Also see the documentation of the fetch_messages() and fetch_chatrooms() functions.

send_userinput(agent_ids)

Can be used to send user input from the user (pressed keys) to the specified human agent(s) in MATRX

API Path: http://>MATRX_core_ip<:3001/send_userinput/<agent_ids>

Parameters
agent_ids

ID(s) of the human agent(s) to which the data should be passed.

Returns
returns True if the data was valid (right now always)
send_message()

Send a message containing information to one or multiple specific agent, the agent’s team, or all agents.

Message as defined in matrx.utils.message

API Path: http://>MATRX_core_ip<:3001/send_message

Returns
Error if api call invalid, or True if valid.
fetch_context_menu_of_self()

Fetch the context menu opened for a specific object/location of the agent being controlled by the user.

API Path: http://>MATRX_core_ip<:3001/fetch_context_menu_of_self

fetch_context_menu_of_other()

Fetch the context menu opened for a specific object/location of the agent being controlled by the user.

API Path: http://>MATRX_core_ip<:3001/fetch_context_menu_of_other

send_message_pickled()

This function makes it possible to send a custom message to a MATRX agent via the API as a jsonpickle object. For instance, sending a custom message when a context menu option is clicked. The pre-formatted CustomMessage instance can be jsonpickled and sent via the API. This API call can handle that request and send the CustomMessage to the MATRX agent

API Path: http://>MATRX_core_ip<:3001/send_message_pickled

Returns
Error if api call invalid, or True if valid.
pause_MATRX()

Pause the MATRX simulation

API Path: http://>MATRX_core_ip<:3001/pause

Returns

True if paused, False if already paused

start_MATRX()

Starts / unpauses the MATRX simulation

API Path: http://>MATRX_core_ip<:3001/start

Returns

True if it has been started, False if it is already running

stop_MATRX()

Stops MATRX scenario

API Path: http://>MATRX_core_ip<:3001/stop

Returns

True

change_MATRX_speed(tick_dur)

Change the tick duration / simulation speed of MATRX

API Path: http://>MATRX_core_ip<:3001/change_tick_duration/<tick_dur>

Parameters
tick_dur

The duration of 1 tick in seconds

Returns
True if successfully changed tick speed (400 error if tick_duration not valid)
shutdown()

Shuts down the api by stopping the Flask thread

API Path: http://>MATRX_core_ip<:3001/shutdown_API

Returns

True