Lugo Bots

Quick start ( 3 min)

How to develop your bot

Download the template source code

My bot template
My operational system

This is a template of a trainable bot for training models. Use the simple template to build the bot.

Windows

  • 1

    Download The Learners Py project

  • 2

    Unzip the file contents

  • 3

    Open the Powershell at the project directory ( hold shift and right click, and then click on 'Open Powershell window here')

Linux or Mac

Use the below commands to create a bot cloning the default bot repository (The Learners Py):

git clone https://github.com/lugobots/the-learners-py.git

cd the-learners-py

Install requirements

virtualenv venv --python=python3.9

source venv/bin/activate

pip install -r requirements.txt

Running the game

1

docker run -p 8080:8080 -p 5000:5000 lugobots/server:latest play --dev-mode --timer-mode=remote

2

Open another terminal and start the game.}

python3 main.py

3

Now, watch the game in a browser http://localhost:8080/

How to edit the bot

If you want to change the bot behaviour, follow the project's instructions here

This is a template of a trainable bot for training models. Use the simple template to build the bot.

Windows

  • 1

    Download The Learners JS project

  • 2

    Unzip the file contents

  • 3

    Open the Powershell at the project directory ( hold shift and right click, and then click on 'Open Powershell window here')

Linux or Mac

Use the below commands to create a bot cloning the default bot repository (The Learners JS):

git clone https://github.com/lugobots/the-learners-js.git

cd the-learners-js

Running the game

1

npm install

2

If you have edited any file started the watcher to compile the TypeScript source.

npm run watch

3

Open another terminal and start the game server.

docker run -p 8080:8080 -p 5000:5000 lugobots/server:v1.0.0-beta.6-rc.2 play --dev-mode --timer-mode=remote

4

Open another terminal and start the training session.

npm run start

5

Now, watch the game in a browser http://localhost:8080/

How to edit the bot

If you want to change the bot behaviour, follow the project's instructions here

Setting up the environment

  • 1

    Open the terminal on an empty directory that will host your bot's source code (Use Powershell on Windows)

  • 2

    Run the following command to set up the project quick start kit

    # on Lunix or Mac
    docker run -v $(pwd):/output lugobots/setup-env-py:latest

    # on Windows
    docker run -v ${PWD}:/output lugobots/setup-env-py:latest

  • 3

    (only Linux and Mac) Fix the file permissions running

    chown $USER -R .

  • Or, you may download the code directly from the repository

How to use this source code

  • 1

    (optional to speed up next steps) Download the images that you will need

    docker pull lugobots/server
    docker pull lugobots/the-dummies-go:latest
    docker pull python:3.9-slim-buster

  • 2

    Run the builder service that will install the dependencies you need (wait for the service to finish):

    docker compose up builder

  • 3

    Running the game

    docker compose up

  • 4

    Now, watch the game in a browser http://localhost:8080/

How to edit the bot

If you want to change the bot behaviour, follow the project's instructions here

Setting up the environment

  • 1

    Open the terminal on an empty directory that will host your bot's source code (Use Powershell on Windows)

  • 2

    Run the following command to set up the project quick start kit

    # on Lunix or Mac
    docker run -v $(pwd):/output lugobots/setup-env-js:latest

    # on Windows
    docker run -v ${PWD}:/output lugobots/setup-env-js:latest

  • 3

    (only Linux and Mac) Fix the file permissions running

    chown $USER -R .

  • Or, you may download the code directly from the repository

How to use this source code

  • 1

    (optional to speed up next steps) Download the images that you will need

    docker pull lugobots/server
    docker pull lugobots/the-dummies-go:latest
    docker pull node:18

  • 2

    Running the game

    docker compose up

  • 3

    Now, watch the game in a browser http://localhost:8080/

How to edit the bot

If you want to change the bot behaviour, follow the project's instructions here

Windows

  • 1

    Download The Dummies Go project

  • 2

    Unzip the file contents

  • 3

    Open the Powershell at the project directory ( hold shift and right click, and then click on 'Open Powershell window here')

Linux or Mac

Use the below commands to create a bot cloning the default bot repository (The Dummies Go):

git clone https://github.com/lugobots/the-dummies-go.git

cd the-dummies-go

Running the game

1

docker compose up

2

Now, watch the game in a browser http://localhost:8080/

How to edit the bot

If you want to change the bot behaviour, follow the project's instructions here

1 - Download Logo Studio to help you program your bot.
2 - Use your favorite IDE on your machine to code your bot.
3 - When your bot is ready to compete, publish your bot!

Lugo Studio - Beta

Lugo Studio is a desktop application created to help you build your bot, save positions, switch sides of the field, reset the match, speed up the game, and more. The version is still in beta phase and bugs may occur

screenshot of lugo studio

External dependencies

You will need these dependencies to run the game. They are quite popular and largely used, so if you are a dev, you probably already have them.

FAQ

Regardless of the programming language you adopt, your bot must implement the following methods.

All methods receive 2 parameters, and the goalkeeper method receives an extra param.

The first parameter is the OrderSet. That is the object where your bot should set the orders it wants to send to the server in the current turn.

The second parameter is the GameSnapshot. That brings the current game state and its elements. Players positions, speed, direction, ball position, score, etc...

The goalkeeper receives a third param that indicates the goalkeeper state (holding the ball, defending, disputing, or supporting).

class Bot:
    
#on_disputing is called when no one has the ball possession def on_disputing(self, order_set: lugo.OrderSet, snapshot: lugo.GameSnapshot) -> lugo.OrderSet: pass #on_defending is called when an opponent player has the ball possession def on_defending(self, order_set: lugo.OrderSet, snapshot: lugo.GameSnapshot) -> lugo.OrderSet: pass #on_holding is called when this bot has the ball possession def on_holding(self, order_set: lugo.OrderSet, snapshot: lugo.GameSnapshot) -> lugo.OrderSet: pass #on_supporting is called when a teammate player has the ball possession def on_supporting(self, order_set: lugo.OrderSet, snapshot: lugo.GameSnapshot) -> lugo.OrderSet: pass #This method is called on every turn, and the player state is passed at the last parameter. def as_goalkeeper(self, order_set: lugo.OrderSet, snapshot: lugo.GameSnapshot, state: PLAYER_STATE) -> lugo.OrderSet: pass
export interface Bot {
{

    /**
    * OnDisputing is called when no one has the ball possession
    */
    onDisputing: (orderSet: OrderSet, snapshot: GameSnapshot) => OrderSet | null

    /**
    * OnDefending is called when an opponent player has the ball possession
    */
    onDefending: (orderSet: OrderSet, snapshot: GameSnapshot) => OrderSet | null

    /**
    * OnHolding is called when this bot has the ball possession
    */
    onHolding: (orderSet: OrderSet, snapshot: GameSnapshot) => OrderSet | null


    /**
    * OnSupporting is called when a teammate player has the ball possession
    */
    onSupporting: (orderSet: OrderSet, snapshot: GameSnapshot) => OrderSet | null

    /**
    * AsGoalkeeper is only called when this bot is the goalkeeper (number 1). This method is called on every turn,
    * and the player state is passed at the last parameter.
    */
    asGoalkeeper: (orderSet: OrderSet, snapshot: GameSnapshot, state: PLAYER_STATE) => OrderSet | null


}
type Bot interface {
    
    // OnDisputing is called when no one has the ball possession
    OnDisputing(ctx context.Context, sender TurnOrdersSender, snapshot *proto.GameSnap

shot) error

    // OnDefending is called when an opponent player has the ball possession
    OnDefending(ctx context.Context, sender TurnOrdersSender, snapshot *proto.GameSnap

shot) error

    // OnHolding is called when this bot has the ball possession
    OnHolding(ctx context.Context, sender TurnOrdersSender, snapshot *proto.GameSnap
        
shot) error

    // OnSupporting is called when a teammate player has the ball possession
    OnSupporting(ctx context.Context, sender TurnOrdersSender, snapshot *proto.GameSnap

shot) error
    // AsGoalkeeper is only called when this bot is the goalkeeper (number 1). This method is called on every turn,
    // and the player state is passed at the last parameter.
    AsGoalkeeper(ctx context.Context, sender TurnOrdersSender, snapshot *proto.GameSnap
        
shot, state PlayerState) error

}

See below and example of the stringified version of a GameSnapshot object.

However, all bot's methods will receive the GameSnapshot as an object based on the programing language you are using.

We strongly do not convert it to JSON since the object is a representation of a gRPC response.

Regardless the programing language you are using, though, there will be a GameSnapshot reader class that implements most part of the common operations you will need (e.g. fetch your team mates, fetch a specific player, etc)

Note that the vectors are normalized and multiplied by 100 (see documentation for further details)

{
"state": "LISTENING",
"turn": 47,
"home_team": {
"players": [
{
"number": 1,
"position": {
"x": 9048,
"y": 3245
},
velocity": {
"direction": {
"x": -99.95606441193794,
"y": -2.963981659273956
},
"speed": 100
},
"init_position": {
"x": 7000,
"y": 1875
}
},
{
"number": 2 ...
},
{
"number": 3 ...
}
],
"name": "Team A", "side": "AWAY"
},
"away_team": {
"players": [
...
],
"name": "VS Code",
"side": "AWAY"
},
"ball": {
"position": {
"x": 9740,
"y": 5223
},
"velocity": {
"direction": {
"x": -99.79061148317571,
"y": -6.467910003539166
},
"speed": 100
},
"holder": {
"number": 8,
"position": {
"x": 9940,
"y": 5236
},
"velocity": {
"direction": {
"x": -99.79061148317571,
"y": -6.467910003539166
},
"speed": 100
},
"init_position": {
"x": 7000,
"y": 4375
}
}
},
"shot_clock": {
"remaining_turns": 300
}
}

You do not need to study the documentation. All client implementations bring the specs in it.

As an example, in the Python client, the IDE will list all game specs from the lugo4py packages:

It only depends on your creativity!

Differently of the ACM International Collegiate Programming Contest questions, in a game like Lugo, there is no expected output, but expected outcome.

That means you may decide to get an outcome (e.g. pass the ball to the safest team mate) that requires knowledge on a particular algorithm, while another programmer may want to get an different outcome (e.g. pass the ball to the most advanced team mate). And the new outcome may require a totally different algorithm.

Therefore, if you are a good ICPC programmer, you will definitly have some good results to find the outcome you want. But if you are not getting good results on ICPC competitions, you still have good chances to find in Lugo a nice place to shine.

It's an Artificial Intelligence game that won't require AI expertise. If you are not familiar with AI, don't worry.

Lugo will be a great place to practice your techniques if you have experience in AI, machine learning or reinforcement learning experience.

But if you have no experience yet, Lugo is a great way to start from scratch on the AI field.

As a matter of fact, the best bots in the raking so far (2023) were developed by junior developers that have no experience with AI algorithms yet.

It has already started!

You may submit your bot whenever you want. Then, you can subscribe your bot to the tournaments and wait for the official games to happen.

Lugo is not a game like racing, mining, searching, etc. Where there is a performance/efficiency/metric to be overcome. No, it's all about strategy

There will always be a way to defeat a bot, but not to defeat all bots. If you don't agree with this statement, prove me wrong. :-)

However, we may reach a point where bots become very mature and the most common strategies are well known. Whenever this happens, matches can end in a draw very often, if not constantly. Then, as most real sports do, we will change the rules to make it more competitive.