Effectors allow agents to perform actions within the simulation. Agents control them by sending messages to the server, and the server changes the game state accordingly. Effectors are the logical dual of perceptors.
Effector control messages are sent via the network protocol. Details of each message type are shown in each section below.
There are both general effectors that apply to all simulations, and soccer effectors that are specific to the soccer simulation.
The effectors described in this subsection are available to all types of simulation. In other words they are not specific to the soccer simulation.
When an agent initially connects to the server it is invisible and cannot take affect a simulation in any meaningful way. It only possesses a so-called CreateEffector. An agent uses this effector to advice the server to construct it according to a scene description file it passes as a parameter. This file is used to construct the physical representation and all further effectors and perceptors.
|Message format||(scene <filename>)|
|Example message||(scene rsg/agent/nao/nao.rsg)|
After the agent representation is constructed in the server the agent should do further simulation specific setup. For example in the soccer simulation each agent is required to register to a team and acquire a unique player number. For these tasks usually a special effector like the Soccer Init Effector is used.
Effector for all axis with a single degree of freedom. The first parameter is the name of the axis. The second parameter is a speed value, passed in radians per second. Setting a speed value on a hinge means that the speed will be maintained until a new value is provided. Even if the hinge meets its extremity, it will bounce around at the extremity until a new speed value is requested.
|Message format||(<name> <ax>)|
|Example message||(lae3 5.3)|
This effector's dual is the HingeJoint Perceptor.
Effector for all axis with a two degrees of freedom. The first parameter is the name of the axis. The second and third parameters contain the change in angle of the two joints. The order of the joints is the same as in the name.
|Message format||(<name> <ax1> <ax2>)|
|Example message||(lae1 2 -2.3 1.2)|
This effector's dual is the UniversalJoint Perceptor.
Agents running in Agent Sync Mode must send this command at the end of each simulation cycle. Note that the server ignores this command if it is received in Real-Time Mode, so it is safe to configure your agent to always append this command to your agent's responses.
The following effectors are soccer specific and only available in the soccer simulation. Remember that although SimSpark is primarily used by the RoboCup 3D simulation league, it is a generic simulator, suited to other purposes. rcssserver3d provides support for the following effectors.
The init command is sent once for each agent after the create effector sent the scene command. It registers this agent as a member of the passed team with the passed number. All players of one team have to use the same teamname and different playernumber values. If an agent sends 0 as playernumber, the number is assigned automatically by the server to the next free number. The maximum amount of teams is two, the maximal amount of players is currently six per side. The side on which a team starts to play depends on which team connected first.
Note that teamname cannot contain spaces. It is safe to use [A-Za-z_-] (regex character ranges).
|Message format||(init (unum <playernumber>)(teamname <yourteamname>))|
|Example message||(init (unum 1)(teamname FHO))|
The beam effector allows a player to position itself on the field before the start of each half. The x and y coordinates define the position on the field with respect to the field's coordinate system, where (0,0) is the absolute center of the field. The rot specifies the facing angle of the player in degrees. Zero points to positive x-axis, 90 to positive y-axis.
|Message format||(beam <x> <y> <rot>)|
|Example message||(beam 10.0 -10.0 0.0)|
The say effector permits communication among agents by broadcasting messages. In order to say something, the following command has to be employed:
|Message format||(say <message>)|
|Example message||(say helloworld)|
Be sure to read about this effector's dual, the Hear Perceptor, as it details restrictions upon what message content may be sent, and under what circumstances other agents will actually hear your messages.