Last updated: May 14th, 2022


As much you work on improving a bot, you may need to understand deeper details about the game behaviour. You do not need to know every single specification to create a great bot. So you probably do not read this document, unless your are developing a client (brainless bot).

This content is here, however, to give you answer in case you have questions.

Game cycle

Differently of the traditional bot games where the server continuously listens for instructions sent by bots, Lugo defines the phase when all bots have a time window to send their instructions (called orders). That phase is called listening phase.

This format is designed to minimize possible the impact of network concurrency problems since the bots are not embedded to the server.

This format also avoid that bots get out of date game status due network latency.

The bots orders, however, are processed in the same sequence as the server got them. So, in in particular cases (e.g. catching or kicking the ball), there is an advantage for quicker responses.

Game States

Phases during the game
State Description What the bot should do? Duration
waiting The server is waiting for players. All player should connect to the server during this state. Open the gRPC connection to the server. Until both teams have all players connected.
get-ready The server announces that everything is ready to start a new game cycle Reset to its initial position Irrelevant
listening The server waits for players orders (described on Communication section) Sending a message with a list of orders 50ms (configurable)
playing The server executes the orders in the same sequence they arrived Sending a message with a list of orders Irrelevant
results The server announces a change in the score. Nothing Irrelevant
game-over The server announces the end of the game. Nothing Permanently
pause The server is on debug mode, and waiting for the next step signal Nothing Until the next step signal be sent
Game cycle

Processing sequence

The sequence of the actions taken during the Playing state has a huge impact on the game. You must know who it is to understand this state results:

  1. First at all, the ball position is updated. However, if the ball is been holden by a player or if its speed is zero, the ball position is not changed.
  2. Then, the players' order messages are processed in the same sequence as they has arrived during the listening state. First come first served
    1. Each order message may bring more then one order. So, the orders will be executed in the sequence as they are in the message.
    2. If there is no MOVE order and the player speed is greater than zero, the player's position will be updated after all of his orders have been executed.
    3. If there is a MOVE order in the orders message, then the player position is updated as soon as the MOVE order has been executed
  3. Then, the ball position is checked. If the ball is in one of the goals, the opponent team has scored.
  4. Finally, if the ball is not in a goal, but it is in a Goal zone for longer than the max time allowed, the ball is kicked towards the center of the field. (See Ball max time in a goal zone spec in the All specs section).


Note that the sequence move and then kick or move and then catch has different results of kick and then move or catch and then move

Measurements and units

Field specs


In this beta version, the frontend will not always draw the elements in their precise size.

Field specifications

Element specs

The ball and the players are elements in the field. All of them have:

  1. A coordinate (X and Y) that is a point at the field;
  2. A velocity the indicates the direction (a vector) and the speed (a scalar) of the element
Elements specifications

All specs


There is no equivalent units for distance and time from the real world. So, we are adopting "d" for distance and "t" (turns) for time.

Name Value Description
Field Width 20001 d Distance between the two goals. Coordinates from 0 to 20000. The line 10000 is neutral, which means it is neither in one team field nor in the other.
Field Height 10001 d Distance between the two lateral sides. Coordinates from 0 to 10000.
Ball size 200 d Ball diameter.
Ball max speed 400 d/f Max distance the ball travels during a turn.
Ball min speed 2 d/f Minimum speed to consider the ball in movement.
Ball deceleration 10 d/f2 Speed deceleration after by turn.
Ball max time in a goal zone 15 f Since a player cannot enter in the opponent goal zone, the ball cannot stay in there longer than 15 turns.
Goal width 3000d Distance between the two poles of the goal.
Goal zone range 1400d Minimum distance that an opponent player can stay from the goal.
Player size 400 d Player diameter (the player is considered a circle).
Player max speed 100 d/f Max distance the player travels during a turn.
Max goalkeeper's jump speed 200 d/f Max speed the goalkeeper may reach when jumps
Max goalkeeper's jump duration 3 f When the goalkeeper jumps, that movement will take 3 frames, and cannot be interrupted.
Game duration 1200 turns Number of turns (also called frames) during the game



The communication protocol between the Game Server and the bots are define by protobuf files in Protos repository.

The player can only talk to the server. There are two moments when the player can (and should) talk to the server: at the beginning of the game when the connection is being opened, and during the Listening state.

During the Listening phase, the player must send the orders within the time window of this state (see the state duration on its specification). Otherwise the game will ignore that player during the next turn.

Message sent by the bots

The bots must send Order Sets to the server during each turn.

Please see the Protos repository to find more details about that message format.

Player Orders

There are four types of orders that the bot may send to the server:

Name Action Description
Move Changes the player velocity (direction and speed). If present, this order makes the player position be updated immediately after the order be executed.
Catch Tries to catch the ball The player must be touching the ball to catch it. Only the first catch order is executed by turn, which means that if there are two players touching the ball and both try to catch it, the first one to request will catch the ball.
Jump Changes the goalkeepers velocity in a higher speed The goalkeeper may move kicker than other players when they jump, however the jum movement cannot be interrupted after triggered.
Kick Release the ball and changes its velocity (direction and speed)

The kick is a sum of vectors. The current ball velocity is a vector (where the vector magnitude is the speed).

Said that, keep in mind the the final direction will not be the same as the direction of the kick, unless the ball holder is stopped OR the kick is towards the same direction as the player movement.

  • The player must be the ball's holder to kick the ball
  • The ball speed will be affected by the player direction.
    If the player is going towards the same direction of the kick, the ball speed will be 100% of the speed requested by the order.
    If the player is going towards the opposite direction (180 degrees) of the kick, the ball speed will be 50% of the speed requested by the order.
    Any other direction will be affect proportionally: SpeedReducerFactor = 0.5 + (0.5 * ((180 - ang) / 180))
  • The final ball speed is calculated before the sum of vectors.


Although the server accepts precise vector values (see the vector protobuf spec), the bot clients (e.g. Lugo4go) may create wrappers that limits the directions for simplicity, e.g. forward, left, right, etc.

Goalkeeper particularities

There are three particularities in the goalkeeper behaviour:

  1. The goalkeepers cannot move freely. They are always between the poles of their team goal.
  2. The goalkeepers are always looking towards the field center, so when they catch the ball they will not score own goal accidentally.