10.2 Effectors
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.
10.2.1 General Effectors
The effectors described in this subsection are available to all types of simulation. In other words they are not specific to the soccer simulation.
10.2.1.1 Create Effector
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.
10.2.1.2 HingeJoint Effector
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) |
- Nao has 22 hinge joint effectors
- Soccerbot has 8 hinge joint effectors
This effector’s dual is the HingeJoint Perceptor.
10.2.1.3 UniversalJoint Effector
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) |
- Nao does not have any universal joints
- Soccerbot has 6 universal joints
This effector’s dual is the UniversalJoint Perceptor.
10.2.1.4 Synchronize Effector
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.
| Message format | (syn) |
|---|
10.2.2 Soccer Effectors
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.
10.2.2.1 Init Effector
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)) |
10.2.2.2 Bean Effector
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) |
10.2.2.3 Say Effector
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.