Lugo - Lugo Tech Specification

Introduction

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

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:

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.
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
Then, the ball position is checked. If the ball is in one of the goals, the opponent team has scored.
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).

Important

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

Disregard

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

Element specs

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

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

All specs

Units

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/f²	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

Communication

Protocol

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.

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:

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