Merge pull request #132 from hidehisaakiyama/master

Split soccerserver.rst to section files.

source/soccerserver/action-models-attentionto-model.rst

@@ -0,0 +1,21 @@
+
+.. _sec-attentiontomodel:
+
+--------------------------------------------------
+Attentionto Model
+--------------------------------------------------
+
+Version 8 and above players can send ``attentionto`` commands to focus their attention on a particular player.
+The command has the form:
+
+  (attentionto <TEAM> <UNUM>) | (attentionto off)
+
+Where ``<TEAM>`` is
+
+  ``opp`` | ``our`` | ``l`` | ``r`` | ``left`` | ``right`` | <TEAM_NAME>
+
+and ``<UNUM>`` is integer identifying a member of the team specified.
+Players can only focus on one player at a time (each attentionto command
+overrides the previous) and cannot focus on themselves.
+
+See :ref:`sec-sensormodels` in detail about the aural sensor.

source/soccerserver/action-models-change-focus-model.rst

@@ -0,0 +1,30 @@
+--------------------------------------------------
+Change Focus Model
+--------------------------------------------------
+
+The focus point is a feature developed in server v.18, which can be
+used by all versions of players.
+It represents a position inside a player's view angle, and can be up
+to 40.0 meters away from the player's position.
+The focus point affects the visual sensor noise model, with the noise
+of observed objects increasing as the distance between the focus point
+and the object increases.
+
+.. The initial position of the focus point is the player's position,
+   and if a player does not change the focus point position, the
+   server visual noise model behaves as in server v.17.
+
+The initial position of the focus point is the player's position.
+Players can change the position of the focus point by sending a
+**change_focus** command.
+This command takes two parameters, *dist_moment* and *dir_moment*, and
+changes the position of the focus point relative to the player's neck
+angle.
+
+It is important to note that players are not allowed to move the focus
+point outside of their view angle.
+Additionally, if a player changes their view angle to a smaller one,
+the server will automatically move the focus point back into the
+player's view angle.
+
+See :ref:`sec-visionsensor` in detail about the vison sensor.

source/soccerserver/action-models-move-model.rst

@@ -0,0 +1,14 @@
+--------------------------------------------------
+Move Model
+--------------------------------------------------
+
+The *move command* can be used to place a player directly onto a desired position on the field. move exists to set up the team and does not work during normal play. It is available at the beginning of each half (play mode ``before_kick_off``’) and after a goal has been scored (play modes ``goal_l_?`` or ``goal_r_?`` ’). In these situations, players can be placed on any position in their own half (i.e. X < 0) and can be moved any number of times, as long as the play mode does not change. Players moved to a position on the opponent half will be set to a random position on their own side by the server.
+A second purpose of the *move command* is to move the goalie within the penalty area after the goalie caught the ball. If the goalie caught the ball, it can move together with the ball within the penalty area. The goalie is allowed to move *goalie_max_moves* times before it kicks the ball. Additional *move commands* do not have any effect and the server will respond with (error too_many_moves).
+
+.. table:: Parameter for the move_command
+
+   +-------------------------------------------------+-----------+
+   |Parameter in ``server.conf``                     | Value     |
+   +=================================================+===========+
+   |goalie_max_moves                                 |2          |
+   +-------------------------------------------------+-----------+

source/soccerserver/action-models-pointto-model.rst

@@ -0,0 +1,69 @@
+--------------------------------------------------
+Pointto Model
+--------------------------------------------------
+
+Players can send commands to point to a spot on the field of the form:
+
+  (pointto <DIST> <DIR>)
+
+or
+
+  (pointto off)
+
+The first form will cause the arm to point to the spot DIST meters
+from the player in DIR direction, relative to the player's current
+face direction.
+The player will continue to point to the same location on the field
+independent of an motion or rotation of the player for at least
+**server::point_to_ban** cycles, and until another ``pointto`` command is
+issued or **server::point_to_duration** cycles pass.
+The second form disables a previous call of pointto.
+
+.. table:: Parameter for the pointto command
+
+   +-------------------------------------------------+-----------+
+   |Parameter in ``server.conf``                     | Value     |
+   +=================================================+===========+
+   |point_to_ban                                     |  5        |
+   +-------------------------------------------------+-----------+
+   |point_to_duration                                |  20       |
+   +-------------------------------------------------+-----------+
+
+Version 8+ clients can see where a player is pointing, if the player is pointing, the player is in view and they are close enough to determine their team name.
+In these cases the player part of the ``see`` message has the form (without the newline):
+
+    (p "<TEAMNAME>" <UNUM>) <DIST> <DIR> <DISTCHG> <DIRCHG>
+                            <BDIR> <HDIR> <POINTDIR>)
+
+  or
+
+    (p "<TEAMNAME>") <DIST> <DIR> <POINTDIR>)
+
+Where ``POINTDIR`` is the direction the players are is pointing with random Gaussian (normal)noise added to the actual direction, with a mean of zero and a standard deviation calculated as follows:
+
+    sigma = pow(dist / team_too_far_length, 4) * 178.25 + 1.75
+
+This means that sigma is a minimum of 1.75 deg and reaches 180 deg
+when the player is observing a pointing arm from a distance of team_too_far_length.
+Since 95% of values in a normal distributionare within two standard deviations,
+then 95% of the time the noise will be in the range +- 2.5 deg when the player is very close and in the range +- 360.0 deg
+when the player is team_too_far_length away.
+
+``sense_body`` messages for version 8+ clients contain information about the arm actuator.
+The following has been inserted into the sense_body message, just before the last ')', without the new line:
+
+    (arm (movable <MOVABLE>) (expires <EXPIRES>)
+         (target <DIST> <DIR>) (count <COUNT>))
+
+Where:
+
+- <MOVABLE> is the number of cycles till the arm is movable. 0 indicates the arm is movable now
+- <EXPIRES> is the number of cycles till the arm stops pointing. 0 indicates that the arm is no longer pointing,
+- <DIST> and <DIR> are the distance and direction of the point the player is pointing to, relative to the players location, orientation and neck angle, accurate to 10cm or 0.1 deg.
+- <COUNT> is the number of times the ``pointto`` command has been successfully executed by the player.
+
+Fullstate messages have both <POINTDIST> and <POINTDIR> included between neck angle and stamina.
+The players own arm state has the same format as in sense body (see below) and can be found between the count and score part.
+
+Version 8+ coaches (on and offline) can see where a player is pointing to if the player is pointing.
+The direction the player is pointing comes just after the players neck angle.

source/soccerserver/action-models-say-model.rst

@@ -0,0 +1,21 @@
+--------------------------------------------------
+Say Model
+--------------------------------------------------
+
+Using the *say command*, players can broadcast messages to other players. Messages can be say_msg_size characters long, where valid characters for say messages are from the set sth (without the square brackets). Messages players say can be heard within a distance of *audio_cut_dist* by members of both teams . **Say messages** sent to the server will be sent back to players within that distance immediately. The use of the *say command* is only restricted by the limited capacity of the players of hearing messages.
+
+.. table:: Parameter for the say command
+
+   +-------------------------------------------------+-----------+
+   |Parameter in ``server.conf``                     | Value     |
+   +=================================================+===========+
+   |say_msg_size                                     |10         |
+   +-------------------------------------------------+-----------+
+   |audio_cut_dist                                   |50         |
+   +-------------------------------------------------+-----------+
+   |hear_max                                         |1          |
+   +-------------------------------------------------+-----------+
+   |hear_inc                                         |1          |
+   +-------------------------------------------------+-----------+
+   |hear_decay                                       |1          |
+   +-------------------------------------------------+-----------+

source/soccerserver/action-models-tackle-model.rst

@@ -0,0 +1,70 @@
+
+--------------------------------------------------
+Tackle Model
+--------------------------------------------------
+
+The tackle command is to accelerate the ball towards the player's
+body(**TODO:new tackle model [12.0.0 pre-20080210]**).
+Players can kick the ball that can not be kicked with the kick command
+by executing the tackle command.
+The success of tackle depends on a random probability related to the
+position of the ball. It can be obtained by the following formula.
+
+The probability of a tackle failure when the ball is in front of the player is:
+
+.. math::
+
+  {\mathrm fail\_prob = (player\_to\_ball.x \div tackle\_dist)^{tackle\_exponent} + (player\_to\_ball.y \div tackle\_width)^{tackle\_exponent}}
+
+The probability of a tackle failure when the ball is behind the player is:
+
+.. math::
+
+  {\mathrm fail\_prob = (player\_to\_ball.x \div tackle\_back\_dist)^{tackle\_exponent} + (player\_to\_ball.y \div tackle\_back\_width)^{tackle\_exponent}}
+
+The probability of processing success is:
+
+.. math::
+
+  {\mathrm tackle\_prob = 1.0 – fail\_prob}
+
+In this case, when the ball is in front of the player, it is used to *tackle_dist* (default is 2.0), otherwise it is used to **tackle_back_dist** (default is 0.5); **player_to_ball** is a vector from the player to the ball, relative to the body direction of the player. When the tackle command is successful, it will give the ball an acceleration in its own body direction.
+
+The execution effect of tackle is similar to that of kick, which is obtained by multiplying the parameter **tackle_power_rate** (default is 0.027) with power. It can be expressed by the following formula:
+
+.. math::
+
+  {\mathrm effective\_power} = {\mathrm power} \times {\mathrm tackle\_power\_rate}
+
+Once the player executes the tackle command, whether successful or not, the player can no longer move within 10 cycles. The following table shows the parameters used in tackle command.
+
+**TODO**
+
+- [12.0.0 pre-20080210] new kick/tackle noise model
+- [12.0.0 pre-20080210] max_back_tackle_power
+- [13.0.0] forbid backward tackle
+- [14.0.0] increasing tackle noise using server::tackle_rand_factor
+
+.. table:: Parameters for the tackle command
+
+   +-------------------------------------------------+-----------+
+   |Parameter in ``server.conf``                     | Value     |
+   +=================================================+===========+
+   |tackle_dist                                      |2          |
+   +-------------------------------------------------+-----------+
+   |tackle_back_dist                                 |0          |
+   +-------------------------------------------------+-----------+
+   |tackle_width                                     |1.25       |
+   +-------------------------------------------------+-----------+
+   |tackle_cycles                                    |10         |
+   +-------------------------------------------------+-----------+
+   |tackle_exponent                                  |6          |
+   +-------------------------------------------------+-----------+
+   |tackle_power_rate                                |0.027      |
+   +-------------------------------------------------+-----------+
+   |max_tackle_power                                 |100        |
+   +-------------------------------------------------+-----------+
+   |max_back_tackle_power                            |0          |
+   +-------------------------------------------------+-----------+
+   |tackle_rand_factor                               |2          |
+   +-------------------------------------------------+-----------+

source/soccerserver/action-models-turn-model.rst

@@ -0,0 +1,47 @@
+--------------------------------------------------
+Turn Model
+--------------------------------------------------
+
+While *dash* is used to accelerate the player in direction of its
+body, the *turn command* is used to change the players body direction.
+The argument for the turn command is the moment; valid values for the
+moment are between **server::minmoment** and **server::maxmoment**.
+If the player does not move, the moment is equal to the angle the
+player will turn. However, there is a concept of inertia that makes it
+more difficult to turn when you are moving.
+Specifically, the actual angle the player is turned is as follows:
+
+.. math::
+
+   {\mathrm actual\_angle} = {\mathrm moment \div (1.0 + inertia\_moment} \times {\mathrm player\_speed)}
+
+**server::inertia_moment** is a server.conf parameter with default
+value 5.0.
+Therefore (with default values), when the player is at speed 1.0, the
+*maximum effective* turn he can do is :math:`\pm30`.
+However, notice that because you can not dash and turn during the same
+cycle, the fastest that a player can be going when executing a turn is
+:math:`player\_speed\_max \times player\_decay`, which means the effective turn for a default player
+(with default values) is :math:`\pm60`.
+
+For heterogeneous players, the inertia moment is the default inertia
+value plus a value between
+:math:`{\mathrm player\_decay\_delta\_min \times inertia\_moment\_delta\_factor}` and
+:math:`{\mathrm player\_decay\_delta\_max \times inertia\_moment\_delta\_factor}`.
+
+.. table:: Turn Model Parameter
+
+   +-----------------------+------------------------+--------------------------------------+--------+
+   || Default Parameters   || Default Value (Range) || Heterogeneous Player Parameters     || Value |
+   ||  ``server.conf``     |                        ||  ``player.conf``                    |        |
+   +=======================+========================+======================================+========+
+   |       Name            |                        |         Name                         |        |
+   +-----------------------+------------------------+--------------------------------------+--------+
+   |server::minmoment      | -180                   |                                      |        |
+   +-----------------------+------------------------+--------------------------------------+--------+
+   |server::maxmoment      |  180                   |                                      |        |
+   +-----------------------+------------------------+--------------------------------------+--------+
+   |server::inertia_moment | 5.0([2.5, 7.5])        || player::player_decay_delta_min      || -0.1  |
+   |                       |                        || player::player_decay_delta_max      || 0.1   |
+   |                       |                        || player::inertia_moment_delta_factor || 25    |
+   +-----------------------+------------------------+--------------------------------------+--------+

source/soccerserver/action-models-turnneck-model.rst

@@ -0,0 +1,37 @@
+.. _sec-turnneckmodel:
+
+--------------------------------------------------
+TurnNeck Model
+--------------------------------------------------
+
+With *turn_neck*, a player can turn its neck somewhat independently of
+its body.
+The angle of the head of the player is the viewing angle of the
+player.
+The *turn command* changes the angle of the body of the player while
+turn_neck changes the neck angle of the player relative to its body.
+The **minimum** and **maximum** relative angle for the player’s neck
+are given by **server::minneckang** and **server::maxneckang** in
+server.conf.
+Remember that the neck angle is relative to the body of the player so
+if the client issues a *turn command*, the viewing angle changes even
+if no turn_neck command was issued.
+Also, *turn_neck commands* can be executed during the same cycle as
+turn, dash, and *kick commands*.
+turn_neck is not affected by momentum like turn is.
+The argument for a *turn_neck command* must be in the range between
+**server::minneckmoment** and **server::maxneckmoment**.
+
+.. table:: Parameter for the turn neck command
+
+   +-------------------------------------------------+-----------+
+   |Parameter in ``server.conf``                     | Value     |
+   +=================================================+===========+
+   |minneckang                                       | -90       |
+   +-------------------------------------------------+-----------+
+   |maxneckang                                       |  90       |
+   +-------------------------------------------------+-----------+
+   |minneckmoment                                    | -180      |
+   +-------------------------------------------------+-----------+
+   |maxneckmoment                                    |  180      |
+   +-------------------------------------------------+-----------+