Skip to main content
Version: 1.8.1

Built-in Skills

This file is automatically generated from java files. Do Not Edit It.

Introduction​

Skills are built-in modules, written in Java, that provide a set of related built-in variables and built-in actions (in addition to those already provided by GAMA) to the species that declare them. A declaration of skill is done by filling the skills attribute in the species definition:

species my_species skills: [skill1, skill2] {
    ...
}

Skills have been designed to be mutually compatible so that any combination of them will result in a functional species. An example of skill is the moving skill.

So, for instance, if a species is declared as:

species foo skills: [moving]{
...
}

Its agents will automatically be provided with the following variables : speed, heading, destination and the following actions: move, goto, wander, follow in addition to those built-in in species and declared by the modeller. Most of these variables, except the ones marked read-only, can be customized and modified like normal variables by the modeller. For instance, one could want to set a maximum for the speed; this would be done by redeclaring it like this:

float speed max:100 min:0;

Or, to obtain a speed increasing at each simulation step:

float speed max:100 min:0  <- 1 update: speed * 1.01;

Or, to change the speed in a behavior:

if speed = 5 {
    speed <- 10;
}

Table of Contents​

advanced_driving, driving, fipa, MDXSKILL, messaging, moving, moving3D, network, physics, skill_road, skill_road_node, SQLSKILL,

advanced_driving​

Variables​

  • current_index (int): the current index of the agent target (according to the targets list)
  • current_lane (int): the current lane on which the agent is
  • current_path (path): the current path that tha agent follow
  • current_road (agent): current road on which the agent is
  • current_target (point): the current target of the agent
  • distance_to_goal (float): euclidean distance to the next point of the current segment
  • final_target (point): the final target of the agent
  • max_acceleration (float): maximum acceleration of the car for a cycle
  • max_speed (float): maximal speed of the vehicle
  • min_safety_distance (float): the minimal distance to another driver
  • min_security_distance (float): the minimal distance to another driver
  • on_linked_road (boolean): is the agent on the linked road?
  • proba_block_node (float): probability to block a node (do not let other driver cross the crossroad)
  • proba_lane_change_down (float): probability to change lane to a lower lane (right lane if right side driving) if necessary
  • proba_lane_change_up (float): probability to change lane to a upper lane (left lane if right side driving) if necessary
  • proba_respect_priorities (float): probability to respect priority (right or left) laws
  • proba_respect_stops (list): probability to respect stop laws - one value for each type of stop
  • proba_use_linked_road (float): probability to change lane to a linked road lane if necessary
  • real_speed (float): the actual speed of the agent (in meter/second)
  • right_side_driving (boolean): are drivers driving on the right size of the road?
  • safety_distance_coeff (float): the coefficient for the computation of the the min distance between two drivers (according to the vehicle speed - security_distance =max(min_security_distance, security_distance_coeff * min(self.real_speed, other.real_speed) )
  • security_distance_coeff (float): the coefficient for the computation of the the min distance between two drivers (according to the vehicle speed - safety_distance =max(min_safety_distance, safety_distance_coeff * min(self.real_speed, other.real_speed) )
  • segment_index_on_road (int): current segment index of the agent on the current road
  • speed (float): the speed of the agent (in meter/second)
  • speed_coeff (float): speed coefficient for the speed that the driver want to reach (according to the max speed of the road)
  • targets (list): the current list of points that the agent has to reach (path)
  • vehicle_length (float): the length of the vehicle (in meters)

Actions​

advanced_follow_driving​

moves the agent towards along the path passed in the arguments while considering the other agents in the network (only for graph topology)

  • returns: float
  • path (path): a path to be followed.
  • target (point): the target to reach
  • speed (float): the speed to use for this move (replaces the current value of speed)
  • time (float): time to travel

compute_path​

action to compute a path to a target location according to a given graph

  • returns: path
  • graph (graph): the graph on wich compute the path
  • target (agent): the target node to reach
  • source (agent): the source node (optional, if not defined, closest node to the agent location)
  • on_road (agent): the road on which the agent is located (optional)

die​

remove the driving agent from its current road and make it die

  • returns: void

drive​

action to drive toward the final target

  • returns: void

drive_random​

action to drive by chosen randomly the next road

  • returns: void
  • proba_roads (map): a map containing for each road (key), the probability to be selected as next road (value)

external_factor_impact​

action that allows to define how the remaining time is impacted by external factor

  • returns: float
  • new_road (agent): the road on which to the driver wants to go
  • remaining_time (float): the remaining time

is_ready_next_road​

action to test if the driver can take the given road at the given lane

  • returns: bool
  • new_road (agent): the road to test
  • lane (int): the lane to test

lane_choice​

action to choose a lane

  • returns: int
  • new_road (agent): the road on which to choose the lane

path_from_nodes​

action to compute a path from a list of nodes according to a given graph

  • returns: path
  • graph (graph): the graph on wich compute the path
  • nodes (list): the list of nodes composing the path

speed_choice​

action to choose a speed

  • returns: float
  • new_road (agent): the road on which to choose the speed

test_next_road​

action to test if the driver can take the given road

  • returns: bool
  • new_road (agent): the road to test

driving​

Variables​

  • lanes_attribute (string): the name of the attribut of the road agent that determine the number of road lanes
  • living_space (float): the min distance between the agent and an obstacle (in meter)
  • obstacle_species (list): the list of species that are considered as obstacles
  • speed (float): the speed of the agent (in meter/second)
  • tolerance (float): the tolerance distance used for the computation (in meter)

Actions​

follow_driving​

moves the agent along a given path passed in the arguments while considering the other agents in the network.

  • returns: path
  • speed (float): the speed to use for this move (replaces the current value of speed)
  • path (path): a path to be followed.
  • return_path (boolean): if true, return the path followed (by default: false)
  • move_weights (map): Weigths used for the moving.
  • living_space (float): min distance between the agent and an obstacle (replaces the current value of living_space)
  • tolerance (float): tolerance distance used for the computation (replaces the current value of tolerance)
  • lanes_attribute (string): the name of the attribut of the road agent that determine the number of road lanes (replaces the current value of lanes_attribute)

goto_driving​

moves the agent towards the target passed in the arguments while considering the other agents in the network (only for graph topology)

  • returns: path
  • target (geometry): the location or entity towards which to move.
  • speed (float): the speed to use for this move (replaces the current value of speed)
  • on (any type): list, agent, graph, geometry that restrains this move (the agent moves inside this geometry)
  • return_path (boolean): if true, return the path followed (by default: false)
  • move_weights (map): Weigths used for the moving.
  • living_space (float): min distance between the agent and an obstacle (replaces the current value of living_space)
  • tolerance (float): tolerance distance used for the computation (replaces the current value of tolerance)
  • lanes_attribute (string): the name of the attribut of the road agent that determine the number of road lanes (replaces the current value of lanes_attribute)

fipa​

The fipa skill offers some primitives and built-in variables which enable agent to communicate with each other using the FIPA interaction protocol.

Variables​

  • accept_proposals (list): A list of 'accept_proposal' performative messages in the agent's mailbox
  • agrees (list): A list of 'agree' performative messages.
  • cancels (list): A list of 'cancel' performative messages.
  • cfps (list): A list of 'cfp' (call for proposal) performative messages.
  • conversations (list): A list containing the current conversations of agent. Ended conversations are automatically removed from this list.
  • failures (list): A list of 'failure' performative messages.
  • informs (list): A list of 'inform' performative messages.
  • proposes (list): A list of 'propose' performative messages .
  • queries (list): A list of 'query' performative messages.
  • refuses (list): A list of 'propose' performative messages.
  • reject_proposals (list): A list of 'reject_proposal' performative messages.
  • requests (list): A list of 'request' performative messages.
  • requestWhens (list): A list of 'request-when' performative messages.
  • subscribes (list): A list of 'subscribe' performative messages.

Actions​

accept_proposal​

Replies a message with an 'accept_proposal' performative message.

  • returns: unknown
  • message (24): The message to be replied
  • contents (list): The content of the replying message

agree​

Replies a message with an 'agree' performative message.

  • returns: unknown
  • message (24): The message to be replied
  • contents (list): The content of the replying message

cancel​

Replies a message with a 'cancel' peformative message.

  • returns: unknown
  • message (24): The message to be replied
  • contents (list): The content of the replying message

cfp​

Replies a message with a 'cfp' performative message.

  • returns: unknown
  • message (24): The message to be replied
  • contents (list): The content of the replying message

end_conversation​

Reply a message with an 'end_conversation' peprformative message. This message marks the end of a conversation. In a 'no-protocol' conversation, it is the responsible of the modeler to explicitly send this message to mark the end of a conversation/interaction protocol.

  • returns: unknown
  • message (24): The message to be replied
  • contents (list): The content of the replying message

failure​

Replies a message with a 'failure' performative message.

  • returns: unknown
  • message (24): The message to be replied
  • contents (list): The content of the replying message

inform​

Replies a message with an 'inform' performative message.

  • returns: unknown
  • message (24): The message to be replied
  • contents (list): The content of the replying message

propose​

Replies a message with a 'propose' performative message.

  • returns: unknown
  • message (24): The message to be replied
  • contents (list): The content of the replying message

query​

Replies a message with a 'query' performative message.

  • returns: unknown
  • message (24): The message to be replied
  • contents (list): The content of the replying message

refuse​

Replies a message with a 'refuse' performative message.

  • returns: unknown
  • message (24): The message to be replied
  • contents (list): The contents of the replying message

reject_proposal​

Replies a message with a 'reject_proposal' performative message.

  • returns: unknown
  • message (24): The message to be replied
  • contents (list): The content of the replying message

reply​

Replies a message. This action should be only used to reply a message in a 'no-protocol' conversation and with a 'user defined performative'. For performatives supported by GAMA (i.e., standard FIPA performatives), please use the 'action' with the same name of 'performative'. For example, to reply a message with a 'request' performative message, the modeller should use the 'request' action.

  • returns: unknown
  • message (24): The message to be replied
  • performative (string): The performative of the replying message
  • contents (list): The content of the replying message

request​

Replies a message with a 'request' performative message.

  • returns: unknown
  • message (24): The message to be replied
  • contents (list): The content of the replying message

send​

Starts a conversation/interaction protocol.

  • returns: msi.gaml.extensions.fipa.FIPAMessage
  • to (list): A list of receiver agents
  • contents (list): The content of the message. A list of any GAML type
  • performative (string): A string, representing the message performative
  • protocol (string): A string representing the name of interaction protocol

start_conversation​

Starts a conversation/interaction protocol.

  • returns: msi.gaml.extensions.fipa.FIPAMessage
  • to (list): A list of receiver agents
  • contents (list): The content of the message. A list of any GAML type
  • performative (string): A string, representing the message performative
  • protocol (string): A string representing the name of interaction protocol

subscribe​

Replies a message with a 'subscribe' performative message.

  • returns: unknown
  • message (24): The message to be replied
  • contents (list): The content of the replying message

MDXSKILL​

This skill allows agents to be provided with actions and attributes in order to connect to MDX databases

Variables​

Actions​

select​

  • returns: list<unknown>
  • params (map): Connection parameters
  • onColumns (string): select string with question marks
  • onRows (list): List of values that are used to replace question marks
  • from (list): List of values that are used to replace question marks
  • where (list): List of values that are used to replace question marks
  • values (list): List of values that are used to replace question marks

testConnection​

  • returns: bool
  • params (map): Connection parameters

timeStamp​

  • returns: float

messaging​

A simple skill that provides agents with a mailbox than can be filled with messages

Variables​

  • mailbox (list): The list of messages that can be consulted by the agent

Actions​

send​

  • returns: msi.gama.extensions.messaging.GamaMessage
  • to (any type): The agent, or server, to which this message will be sent to
  • contents (any type): The contents of the message, an arbitrary object

moving​

The moving skill is intended to define the minimal set of behaviours required for agents that are able to move on different topologies

Variables​

  • current_edge (geometry): Represents the agent/geometry on which the agent is located (only used with a graph)
  • current_path (path): Represents the path on which the agent is moving on (goto action on a graph)
  • destination (point): Represents the next location of the agent if it keeps its current speed and heading (read-only). ** Only correct in continuous topologies and may return nil values if the destination is outside the environment **
  • heading (float): Represents the absolute heading of the agent in degrees.
  • location (point): Represents the current position of the agent
  • real_speed (float): Represents the actual speed of the agent (in meter/second)
  • speed (float): Represents the speed of the agent (in meter/second)

Actions​

follow​

moves the agent along a given path passed in the arguments.

  • returns: path
  • speed (float): the speed to use for this move (replaces the current value of speed)
  • path (path): a path to be followed.
  • move_weights (map): Weights used for the moving.
  • return_path (boolean): if true, return the path followed (by default: false)

goto​

moves the agent towards the target passed in the arguments.

  • returns: path
  • target (geometry): the location or entity towards which to move.
  • speed (float): the speed to use for this move (replaces the current value of speed)
  • on (any type): graph, topology, list of geometries or map of geometries that restrain this move
  • recompute_path (boolean): if false, the path is not recompute even if the graph is modified (by default: true)
  • return_path (boolean): if true, return the path followed (by default: false)
  • move_weights (map): Weights used for the moving.

move​

moves the agent forward, the distance being computed with respect to its speed and heading. The value of the corresponding variables are used unless arguments are passed.

  • returns: path
  • speed (float): the speed to use for this move (replaces the current value of speed)
  • heading (float): the angle (in degree) of the target direction.
  • bounds (geometry): the geometry (the localized entity geometry) that restrains this move (the agent moves inside this geometry

wander​

Moves the agent towards a random location at the maximum distance (with respect to its speed). The heading of the agent is chosen randomly if no amplitude is specified. This action changes the value of heading.

  • returns: void
  • speed (float): the speed to use for this move (replaces the current value of speed)
  • amplitude (float): a restriction placed on the random heading choice. The new heading is chosen in the range (heading - amplitude/2, heading+amplitude/2)
  • bounds (geometry): the geometry (the localized entity geometry) that restrains this move (the agent moves inside this geometry)
  • on (graph): the graph that restrains this move (the agent moves on the graph
  • proba_edges (map): When the agent moves on a graph, the probability to choose another edge. If not defined, each edge has the same probability to be chosen

moving3D​

The moving skill 3D is intended to define the minimal set of behaviours required for agents that are able to move on different topologies

Variables​

  • destination (point): continuously updated destination of the agent with respect to its speed and heading (read-only)
  • heading (float): the absolute heading of the agent in degrees (in the range 0-359)
  • pitch (float): the absolute pitch of the agent in degrees (in the range 0-359)
  • roll (float): the absolute roll of the agent in degrees (in the range 0-359)
  • speed (float): the speed of the agent (in meter/second)

Actions​

move​

moves the agent forward, the distance being computed with respect to its speed and heading. The value of the corresponding variables are used unless arguments are passed.

  • returns: path
  • speed (float): the speed to use for this move (replaces the current value of speed)
  • heading (int): int, optional, the direction to take for this move (replaces the current value of heading)
  • pitch (int): int, optional, the direction to take for this move (replaces the current value of pitch)
  • heading (int): int, optional, the direction to take for this move (replaces the current value of roll)
  • bounds (geometry): the geometry (the localized entity geometry) that restrains this move (the agent moves inside this geometry

network​

The network skill provides new features to let agents exchange message through network.

Variables​

  • network_groups (list): The set of groups the agent belongs to
  • network_name (string): Net ID of the agent
  • network_server (list): The list of all the servers to which the agent is connected

Actions​

connect​

Action used by a networking agent to connect to a server or as a server.

  • returns: void
  • protocol (string): protocol type (MQTT (by default), TCP, UDP): the possible value ares 'udp_server', 'udp_emitter', 'tcp_server', 'tcp_client', otherwise the MQTT protocol is used.
  • port (int): Port number
  • with_name (string): ID of the agent (its name) for the simulation
  • login (string): login for the connection to the server
  • password (string): password associated to the login
  • force_network_use (boolean): force the use of the network even interaction between local agents
  • to (string): server URL (localhost or a server URL)
  • size_packet (int): For UDP connection, it sets the maximum size of received packets (deafault = 1024bits).

execute​

  • returns: string
  • command (string): command to execute

fetch_message​

  • returns: msi.gama.extensions.messaging.GamaMessage

has_more_message​

  • returns: bool

join_group​

allow an agent to join a group of agents in order to broadcast messages to other membersor to receive messages sent by other members. Note that all members of the group called : "ALL".

  • returns: void
  • with_name (string): name of the group

leave_group​

leave a group of agents. The leaving agent will not receive any message from the group. Overwhise, it can send messages to the left group

  • returns: void
  • with_name (string): name of the group the agent wants to leave

simulate_step​

Simulate a step to test the skill. It must be used for Gama-platform test only

  • returns: void

physics​

Variables​

  • ang_damping (float): angular dampling
  • collisionBound (map): map describing the shape of the agent. format for sphere: ['shape'::'sphere', 'radius'::10.0]; for floor: ['shape'::'floor', 'x'::100.0, 'y'::100.0, 'z'::2.0]; if not defined, the shape attribute of the agent is used.
  • friction (float): coefficient of friction of the agent
  • lin_damping (float): linear dampling
  • mass (float): mass of the agent
  • restitution (float): coefficient of restitution force of the agent
  • velocity (list): velocity of the agent

Actions​

skill_road​

Variables​

  • agents_on (list): for each lane of the road, the list of agents for each segment
  • all_agents (list): the list of agents on the road
  • lanes (int): the number of lanes
  • linked_road (-199): the linked road: the lanes of this linked road will be usable by drivers on the road
  • maxspeed (float): the maximal speed on the road
  • source_node (agent): the source node of the road
  • target_node (agent): the target node of the road

Actions​

register​

register the agent on the road at the given lane

  • returns: void
  • agent (agent): the agent to register on the road.
  • lane (int): the lane index on which to register; if lane index >= number of lanes, then register on the linked road

unregister​

unregister the agent on the road

  • returns: void
  • agent (agent): the agent to unregister on the road.

update_lanes​

change the number of lanes of the road

  • returns: void
  • lanes (int): the new number of lanes.

skill_road_node​

Variables​

  • block (map): define the list of agents blocking the node, and for each agent, the list of concerned roads
  • priority_roads (list): the list of priority roads
  • roads_in (list): the list of input roads
  • roads_out (list): the list of output roads
  • stop (list): define for each type of stop, the list of concerned roads

Actions​

SQLSKILL​

This skill allows agents to be provided with actions and attributes in order to connect to SQL databases

Variables​

Actions​

executeUpdate​

  • returns: int
  • params (map): Connection parameters
  • updateComm (string): SQL commands such as Create, Update, Delete, Drop with question mark
  • values (list): List of values that are used to replace question mark

getCurrentDateTime​

  • returns: string
  • dateFormat (string): date format examples: 'yyyy-MM-dd' , 'yyyy-MM-dd HH:mm:ss'

getDateOffset​

  • returns: string
  • dateFormat (string): date format examples: 'yyyy-MM-dd' , 'yyyy-MM-dd HH:mm:ss'
  • dateStr (string): Start date
  • offset (string): number on day to increase or decrease

insert​

  • returns: int
  • params (map): Connection parameters
  • into (string): Table name
  • columns (list): List of column name of table
  • values (list): List of values that are used to insert into table. Columns and values must have same size

list2Matrix​

  • returns: matrix
  • param (list): Param: a list of records and metadata
  • getName (boolean): getType: a boolean value, optional parameter
  • getType (boolean): getType: a boolean value, optional parameter

select​

  • returns: list
  • params (map): Connection parameters
  • select (string): select string with question marks
  • values (list): List of values that are used to replace question marks

testConnection​

  • returns: bool
  • params (map): Connection parameters

timeStamp​

  • returns: float