PY2D Soccer Simulation Base Code is a base code for RoboCup 2D Soccer Simulation teams, which is written in Python.
This base code is powered by the Cross Language Soccer Framework, which allows you to create a team by using any programming language that supports gRPC or Thrift.
This base code uses Helios Base
as a proxy to communicate with the RoboCup 2D Soccer Simulation server.
PY2D base is the most power full base code for RoboCup 2D Soccer Simulation which developed in Python.
For more information, please refer to the documentation.
You can find more information about the services and messages in the IDL section.
there are many different ways to run the base code, in the next section, we will explain the easiest way to run the base code.
| Summary Statistics
- Game Count: 100
- Goals: 223 : 78 (diff: 145)
- Points: 229 : 52 (diff: 177)
- Average Goals: 2.23 : 0.78 (diff: 1.45)
- Average Points: 2.29 : 0.52 (diff: 1.77)
- Win: 70, Draw: 19, Lost: 11
- Win Rate: 70.00%
- Expected Win Rate: 86.42%
| Goals Distribution
xychart-beta
title "Diff Goals Distribution"
x-axis [-8,-7,-6,-5,-4,-3,-2,-1,0,1,2,3,4,5,6,7,8]
y-axis "Percentage"
bar [0,0,0,0,1.00, 0.00, 2.00, 8.00, 19.00, 22.00, 25.00, 13.00, 5.00, 2.00, 2.00, 0.00, 1.00]
line [0,0,0,0,1.00, 0.00, 2.00, 8.00, 19.00, 22.00, 25.00, 13.00, 5.00, 2.00, 2.00, 0.00, 1.00]
Install the pre-requisites using the command below:
sudo apt-get install fuse #Used to run AppImages (Proxy, Monitor and RoboCup Server)
Clone this repository & install the required python libraries (such as gRPC). Don't forget to activate your virtual environment!
git clone https://github.com/CLSFramework/py2d.git
cd py2d
# Activate venv/anaconda before this step!
pip install -r requirements.txt
./generate.sh # Generate the gRPC files
To download RoboCup Soccer 2D Server using the commands below:
pushd scripts
sh download-rcssserver.sh # Download the soccer simulation server
popd
Next, download the soccer proxy, which uses C++ to read and pre-processes state data and passes them to the Python server (this project) for decision-making.
pushd scripts
sh download-proxy.sh #install C++ proxy
popd
Finally, to watch the game, download the monitor from the original repository in order to view the games.
This section assumes you have download (installed) the server & proxy using the scripts (as mentioned above).
To run a game, you must first run the RoboCup Soccer Server, then your team and opponent team, and finally the monitor.
We must first run a RoboCup Server, in order to host the game:
| Running the RoboCup Soccer Server
cd scripts/rcssserver
./rcssserver
| Running your team
We must run the proxy, and rpc server, you can run start.py
or start.sh
to run both the proxy and the server.
python3 start.py
// or
./start.sh
This script, by default, will run a gRPC server on port 50051, and 12 proxy agents (11 players and 1 coach). In each cycle of the game, the soccer server sends the state of the game to the proxy, which processes the state, creates state message and sends it to the rpc server. The rpc server receives the state message, processes it, and sends the actions to the proxy. The proxy receives the actions, processes them, and sends the commands to the soccer server.
| Running the opponent team
You can download an opponent team binary from the RoboCup Soccer Simulation Repository for example CYRUS
team from here. After extracting the binary, you can run the team using the command below:
cd CYRUS_SS2D_RC2023_D4_BIN/bin
./start.sh
| Running the monitor
To watch the game, you must run the rcssmonitor or soccerwindow2. press Ctrl + C to connect to the server, and Ctrl + K for kick-off!
| Team and Name Customization
Argument | Short | Description | Default Value |
---|---|---|---|
--team_name |
-t |
The name of the team. | CLS |
--use-random-name |
Use a randomly generated team name. | False |
| RPC Server Configuration
Argument | Short | Description | Default Value |
---|---|---|---|
--rpc-port |
The port used by the RPC server. | 50051 |
|
--use-random-rpc-port |
Use a randomly assigned port for the RPC server. | False |
|
--use-different-rpc-port |
Use a different port for the RPC server (useful for multi-server setups). By using this option, the script will run a rpc server for each agents | False |
|
--auto-close-rpc-server |
Automatically close the RPC server after finishing agent processing. | False |
| RoboCup Soccer Server Configuration
Argument | Short | Description | Default Value |
---|---|---|---|
--server-host |
The host of the RoboCup Soccer server. | localhost |
|
--server-port |
The port of the RoboCup Soccer server. | 6000 |
| Agent Proxies
Argument | Short | Description | Default Value |
---|---|---|---|
--player |
Run a proxy for a single player agent. | False |
|
--coach |
Run a proxy for a single coach agent. | False |
|
--goalie |
Run a proxy for a single goalie agent. | False |
|
--debug |
-d |
Enable debug mode for the agents. | False |
| Debug and Logging Options
Argument | Short | Description | Default Value |
---|---|---|---|
--disable-log-file |
Disable logging to a file. | False |
|
--log-dir |
The directory where logs are stored. If not provided, logs are stored in the default directory with a timestamp. | None |
Originally the RoboCup 2D Soccer Simulation teams used C++, as the main code base (Agent2D aka Helios Base) was written in this language due to its performance. Due to the popularity of python in Machine Learning & AI spaces we decided to create a python platform which would be equivalent to Agent 2D. However, using python alone was too slow as preprocessing sensor information & tasks such as localization took too long.
For this reason we have split up the code into two segments: The data processing section in proxy, which creates a World Model (state), and passes it to python for planning to occur. This repository uses gRPC to pass along the World Model, but there is a sister-repo which is compatible with thrift.
sequenceDiagram
participant SS as SoccerSimulationServer
participant SP as SoccerSimulationProxy
participant PM as PlayMakerServer
Note over SS,PM: Run
SP->>SS: Connect
SS->>SP: OK, Unum
SP->>PM: Register
PM->>SP: OK, ClientID
SS->>SP: Observation
Note over SP: Convert observation to State
SP->>PM: State
PM->>SP: Actions
Note over SP: Convert Actions to Low-Level Commands
SP->>SS: Commands
As seen in the figure, the proxy handles connecting to the server, receiving sensor information and creating a world-model, and finds the action to take via a remote procedure call to a decision-making server, which is this repository.
In soccer simulation 2D games (official competitions), each agents (players and coach) should be run in a separate process. So, you need to connect each agent to a rpc server (each agent has a separate rpc server). In this case, you need to run the rpc server for each agent separately. You can use the following commands to run the rpc server for each agent for debugging purposes.
| Note: For official competitions, tournament script will run each player/coach with separate command, so it will be like the next section, but the result will be the same as this section because the rpc server will be run for each agent separately.
python3 start.py --use-different-rpc-port
// or
./start.sh --use-different-rpc-port
In soccer simulation 2D games (official competitions), each agents (players and coach) should be run in a separate process. So, you need to connect each agent to a rpc server (each agent has a separate rpc server). You can use the following commands to run each agent and rpc server separately.
python3 start.py --goalie
python3 start.py --player (you need to run this command 11 times)
python3 start.py --coach
// or
./start.sh --goalie
./start.sh --player (you need to run this command 11 times)
./start.sh --coach
To run the rpc server and proxy separately, you can use the following commands.
python3 server.py
cd scripts/proxy
./start.sh --rpc-type=grpc
As you know python is an interpreted language and it is slow in comparison to C++. In official tournaments, an agent should send actions to the server in less than 100ms. Also, python may not be installed on the tournament server. So, you need to create a binary from your python code. You can use the following commands to create a binary from your python code.
cd scripts
./create_binary.sh
After creating the binary, you can find it in the scripts/binary
directory. In this directory, you can find the following files and directories:
start.bin
: The binary file that behaves like thestart.py
script. So, by running this file, you can run one rpc server and 12 proxy agents (11 players and 1 coach).start
: The tournament script will run this file to run your team in the tournament. This file will run one agent and one rpc server on random port.startAll
: This script is available for testing purposes. By running this file, it will call thestart
file 12 times to run 12 agents and 12 rpc servers.scripts
: This directory contains the necessary files to run the proxy.src
: This directory contains the formations of your team.
There are three different solution for debugging your team:
You can use the logging module to log the information in rpc server code. By default, the logs are stored in the logs
directory. For example, agentX_Y.log
is the log file for the agent with unum X
and Y
is the unique id of the agent in rpc server (This one is not important for you). proxy.log
is the log file for the proxy for all agents. start-team.log
is the log file for the start.py
script.
If you enable the debug mode, the proxy agents will be run in debug mode, so you can check graphical logs in soccerwindow2
application. You can use message Log
or message DebugClient
to send the debug information to the proxy and then proxy will save them in file or send them directly to the soccerwindow2
application to show them in the graphical interface. For more information, you can check the IDL section in the documentation.
TODO
TODO
TODO
flowchart TD
subgraph SamplePlayerAgent
SamplePlayerAgent_update_actions[update_actions]
end
subgraph FormationStrategy
FormationStrategy_update[update]
end
subgraph StarterStrategy
StarterStrategy_update[update]
end
subgraph DecisionMaker
DecisionMaker_make_decision[make_decision]
end
subgraph PlayOnDecisionMaker
PlayOnDecisionMaker_make_decision[make_decision]
end
subgraph SetPlayDecisionMaker
SetPlayDecisionMaker_make_decision[make_decision]
end
subgraph PenaltyDecisionMaker
PenaltyDecisionMaker_make_decision[make_decision]
end
subgraph GoalieDecisionMaker
GoalieDecisionMaker_make_decision[make_decision]
end
subgraph KickDecisionMaker
KickDecisionMaker_make_decision[make_decision]
end
subgraph MoveDecisionMaker
MoveDecisionMaker_make_decision[make_decision]
end
subgraph BhvKickPlanner
BhvKickPlanner_execute[execute]
end
subgraph BhvStarterKickPlanner
BhvStarterKickPlanner_execute[execute]
end
subgraph BhvSetPlay
BhvSetPlay_execute[execute]
end
subgraph BhvStarterSetPlay
BhvStarterSetPlay_execute[execute]
end
subgraph BhvPenalty
BhvPenalty_execute[execute]
end
subgraph BhvStarterPenalty
BhvStarterPenalty_execute[execute]
end
SamplePlayerAgent_update_actions --> A{is starter?}
A -->|yes| StarterStrategy_update
A -->|no| FormationStrategy_update
SamplePlayerAgent_update_actions --> DecisionMaker_make_decision
DecisionMaker_make_decision --> B{status?}
B --> PlayOnDecisionMaker_make_decision
B --> SetPlayDecisionMaker_make_decision
B --> PenaltyDecisionMaker_make_decision
B --> GoalieDecisionMaker_make_decision
PlayOnDecisionMaker_make_decision --> C{is kickable?}
C -->|yes| KickDecisionMaker_make_decision
C -->|no| MoveDecisionMaker_make_decision
KickDecisionMaker_make_decision --> D{is starter?}
D -->|yes| BhvStarterKickPlanner_execute
D -->|no| BhvKickPlanner_execute
SetPlayDecisionMaker_make_decision --> E{is starter?}
E -->|yes| BhvStarterSetPlay_execute
E -->|no| BhvSetPlay_execute
PenaltyDecisionMaker_make_decision --> F{is starter?}
F -->|yes| BhvStarterPenalty_execute
F -->|no| BhvPenalty_execute
- Cross Language Soccer Framework
- Zare, N., Sayareh, A., Sadraii, A., Firouzkouhi, A. and Soares, A., 2024. Cross Language Soccer Framework: An Open Source Framework for the RoboCup 2D Soccer Simulation. arXiv preprint arXiv:2406.05621.