Skip to content

Commit 233b6dc

Browse files
naderzarenaderzare
authored
Update README.md
1 parent 88d5eb7 commit 233b6dc

File tree

1 file changed

+83
-113
lines changed

1 file changed

+83
-113
lines changed

‎README.md

Lines changed: 83 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -1,167 +1,137 @@
1-
# Sample Python Playmaker Server - Thrift
1+
# Sample Python Base Code (thrift)
22

3-
This repository contains a sample Playmaker server written in Python using Thrift, designed to facilitate the development of a Soccer Simulation 2D team.
3+
[![Documentation Status](https://readthedocs.org/projects/clsframework/badge/?version=latest)](https://clsframework.github.io/docs/introduction/)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
45

5-
Traditionally, teams in the Soccer Simulation 2D league are implemented in C++ using existing base codes. Each agent in the team receives observations from the Soccer Simulation 2D server and sends actions back to it. However, with the Cross Language Soccer Framework (CLSF), we have enhanced the Helios base code([SoccerSimulationProxy](https://github.com/CLSFramework/soccer-simulation-proxy)) to interact with a Thrift/gRPC server(PlaymakerServer).
6+
This repository contains a sample decision-making server for the RoboCup 2D Soccer Simulation, which allows you to create a team by using Python. This server is compatible with the [Cross Language Soccer Framework](https://arxiv.org/pdf/2406.05621). This server is written in Python and uses thrift to communicate with the [proxy](https://github.com/CLSFramework/soccer-simulation-proxy).
67

7-
This server-based approach allows the simulation to send the necessary information for decision-making to a rpc server and receive the corresponding actions, which are then communicated back to the Soccer Simulation 2D server.
8+
The Soccer Simulation Server sends the observations to the proxy, which processes the data, create state message and sends it to the decision-making server. The decision-making server then sends the actions to the proxy, and then the proxy convert actions to the server commands and sends them to the server.
89

9-
This flexibility enables you to develop your team in any programming language of your choice, breaking the constraints of C++.
10+
For more information, please refer to the [documentation](https://clsframework.github.io/).
1011

11-
This repository provides a sample server implemented in Python using Thrift. You can use this server as a starting point to develop and customize your own team.
12+
## Quick start
1213

13-
Also, you can find some scripts to download the RCSSServer, SoccerSimulationProxy, and run the sample server and proxy. To use this framework, you need to have Ubuntu or WSL.
14+
### Preparation
1415

15-
To learn more about the Cross Language Soccer Framework, visit the [official repository](https://github.com/CLSFramework/cross-language-soccer-framework/wiki)
16+
Install the pre-requisites using the command below:
1617

17-
![cls](https://github.com/user-attachments/assets/4daee216-1479-4acd-88f2-9e772b8c7837)
18-
19-
## Preparation
20-
21-
To run a Soccer Simulation 2D game using the CLSF, you need to have RCSSServer, SoccerSimulationProxy, and Monitor to visualize the game.
22-
23-
### RCSSServer
24-
To download the latest AppImage of the RCSSServer, you can run the following command:
25-
26-
```bash
27-
cd scripts
28-
./download-rcssserver.sh
29-
```
30-
31-
To run the RCSSServer AppImage, you need to install FUSE. You can install it by running the following command:
32-
33-
```bash
34-
sudo apt-get install fuse
18+
``` Bash
19+
sudo apt-get install fuse #Used to run AppImages
3520
```
3621

37-
<u>Notes:</u>
38-
- You can build the RCSSServer from the source code. For more information, visit the [official repository](https://github.com/rcsoccersim/rcssserver).
39-
- The RCSSServer should be run on <u>Linux (preferably Ubuntu) or WSL</u>.
22+
Clone this repository & install the required python libraries (such as thrift). Don't forget to activate your virtual environment!
4023

24+
``` Bash
25+
git clone https://github.com/CLSFramework/sample-playmaker-server-python-thrift.git
26+
cd sample-playmaker-server-python-thrift
27+
# Activate venv/anaconda before this step!
28+
pip install -r requirements.txt
4129

42-
43-
### SoccerSimulationProxy
44-
45-
To download the latest AppImage of the SoccerSimulationProxy, you can run the following command:
46-
47-
```bash
48-
cd scripts
49-
./download-proxy.sh
30+
./generate.sh # Generate the thrift files
5031
```
5132

52-
To run the SoccerSimulationProxy AppImage, you need to install FUSE. You can install it by running the following command:
33+
To download RoboCup Soccer 2D Server using the commands below:
5334

54-
```bash
55-
sudo apt-get install fuse
35+
``` Bash
36+
pushd scripts
37+
sh download-rcssserver.sh # Download the soccer simulation server
38+
popd
5639
```
5740

58-
<u>Notes:</u>
59-
- You can build the SoccerSimulationProxy from the source code. For more information, visit the [official repository](https://github.com/CLSFramework/soccer-simulation-proxy)
60-
- The SoccerSimulationProxy should be run on <u>Linux (preferably Ubuntu) or WSL</u>.
61-
62-
### Monitor
63-
64-
To download the latest AppImage of the Monitor, you can download it from the [official repository](https://github.com/rcsoccersim/rcssmonitor/releases).
65-
66-
To run the monitor, you need to install FUSE. You can install it by running the following command:
41+
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.
6742

68-
```bash
69-
sudo apt-get install fuse
43+
``` Bash
44+
pushd scripts
45+
sh download-proxy.sh #install C++ proxy
46+
popd
7047
```
7148

72-
### Create Python Virtual Environment and Install Dependencies
49+
Finally, to watch the game, download the monitor from [the original repository](https://github.com/rcsoccersim/rcssmonitor/releases) in order to view the games.
7350

74-
To create a Python virtual environment and install the dependencies, you can run the following commands:
51+
### Running a game
7552

76-
```bash
77-
python3 -m venv venv
78-
source venv/bin/activate
79-
pip install -r requirements.txt
80-
./generate.sh # To generate thrift python files
81-
```
82-
83-
## Running a game
84-
85-
To run a game, you need to run the RCSSServer and then the SoccerSimulationProxy and the sample server. To visualize the game, you can run the Monitor.
53+
This section assumes you have installed the server & proxy using the scripts (as mentioned above)
54+
We must first run a RoboCup Server, in order to host the game:
8655

87-
### Running the RCSSServer
88-
If you have downloaded the RCSSServer AppImage, you can run it by running the following command:
89-
90-
```bash
56+
``` Bash
9157
cd scripts/rcssserver
9258
./rcssserver
9359
```
9460

95-
Otherwise, you built and install the RCSSServer from the source code, you can run the server by running the following command:
61+
Then we must run the proxy & the decisionmaking server:
9662

97-
```bash
98-
rcssserver
63+
``` Bash
64+
./start-team.sh
9965
```
10066

101-
## Running the Sample Server and Proxy
102-
103-
There are three different ways to run the sample server:
67+
### Options
10468

105-
- Using start-team.py
106-
- Using start-team.sh
107-
- Running the server and client separately
69+
- `-t team_name`: Specify the team name.
70+
- `--rpc-port PORT`: Specify the RPC port (default: 50051).
71+
- `-d`: Enable debug mode.
10872

109-
### Using start-team.py (This script can be used in Ubuntu or WSL)
73+
Launch the opponent team, start the monitor app image. press <kbd>Ctrl</kbd> + <kbd>C</kbd> to connect to the server, and <kbd>Ctrl</kbd> + <kbd>K</kbd> for kick-off!
11074

111-
Note: To use this script you need to download the proxy by using `scripts/download-proxy.sh`.
75+
### Tutorial Video (English)
11276

113-
Run the `start-team.py` script:
77+
[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/hH-5rkhiQHg/0.jpg)](https://www.youtube.com/watch?v=hH-5rkhiQHg)
11478

115-
```bash
116-
python start-team.py
117-
```
118-
119-
You can pass the following arguments to the script:
120-
- `--team-name`: The name of the team (default: `CLSF`)
121-
- `--rpc-port`: The port number for the RPC server (default: `50051`)
79+
### Tutorial Video (Persian)
12280

123-
### Using start-team.sh (This script can be used in Linux)
81+
[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/97YDEumcVWU/0.jpg)](https://www.youtube.com/watch?v=97YDEumcVWU&t=0s)
12482

125-
Note: To use this script you need to download the proxy by using `scripts/download-proxy.sh`.
83+
## How to change the code
12684

127-
Run the `start-team.sh` script:
85+
The `server.py` file contains the logic in 3 main functions:
86+
`GetPlayerActions` receives a game state, and returns a list of actions for a player for for that cycle.
87+
The actions we can output are equivalent to the Helios Base (Proxy), which are abstracted into multiple levels.
88+
You can use actions such as `DoDash`, `DoTurn`, `DoKick` which directly apply force, or use actions such as `GoToPoint`, `SmartKick`, `Shoot` or [more](https://clsframework.github.io/docs/idl/).
12889

129-
```bash
130-
./start-team.sh
131-
```
90+
Similarly, you can change `GetCoachActions` which is responsible for coach communication & substitutions.
13291

133-
You can pass the following arguments to the script:
134-
- `--team-name`: The name of the team (default: `CLSF`)
135-
- `--rpc-port`: The port number for the RPC server (default: `50051`)
92+
You can also use `GetTrainerActions` to move the players & the ball to make repeatable scenarios (when the server is in trainer mode).
13693

137-
### Running the server and client separately
94+
## Why & How it works
13895

139-
(This method can be used in Windows and Linux, but the proxy can only be run in Linux)
96+
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.
97+
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.
98+
However, using python alone was too slow as preprocessing sensor information & tasks such as localization took too long.
14099

141-
To run the server, you can run the following command:
100+
For this reason we have split up the code into two segments:
101+
The data processing section in proxy, which creates a World Model (state), and passes it to python for planning to occur. This repository uses thrift to pass along the World Model, but there is a sister-repo which is compatible with thrift.
142102

143-
```bash
144-
python server.py
103+
```mermaid
104+
sequenceDiagram
105+
participant SS as SoccerSimulationServer
106+
participant SP as SoccerSimulationProxy
107+
participant PM as PlayMakerServer
108+
Note over SS,PM: Run
109+
SP->>SS: Connect
110+
SS->>SP: OK, Unum
111+
SP->>PM: Register
112+
PM->>SP: OK, ClientID
113+
SS->>SP: Observation
114+
Note over SP: Convert observation to State
115+
SP->>PM: State
116+
PM->>SP: Actions
117+
Note over SP: Convert Actions to Low-Level Commands
118+
SP->>SS: Commands
145119
```
146120

147-
You can pass the following arguments to the server:
148-
- `--rpc-port`: The port number for the RPC server (default: `50051`)
121+
![cls](https://github.com/user-attachments/assets/4daee216-1479-4acd-88f2-9e772b8c7837)
122+
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.
149123

150-
If you want to run the proxy agents, you can run the following command:
124+
## Configuration
151125

152-
```bash
153-
cd scripts/proxy
154-
./start.sh
155-
```
126+
### RoboCup Server configuration
127+
128+
You can change the configuration of the RoboCup server and change parameters such as players' stamina, game length, field length, etc. by modifying `~/.rcssserver/server.conf`. Refer to the server's documents and repo for a more detailed guide.
156129

157-
To learn more about the Soccer Simulation Proxy, arguments you can pass, and how to run it, build it from source, visit the [official repository](https://github.com/CLSFramework/soccer-simulation-proxy)
130+
### Modifying Proxy & Running proxy and server seperately
158131

159-
#### Running the playmaker server in Windows (Not recommended)
160-
If you want to run the playmaker server in Windows, you need to somehow connect the proxy to the playmaker server. You can find ip of your local machine(Windows) and use it in the proxy.
161-
<u>Right now due to some issues with Python multiprocessing, the playmaker server can't be run in Windows.</u>
132+
If you want to modify the algorithms of the base (such as ball interception, shooting, localization, etc.) you must modify the code of the [proxy repo](https://github.com/CLSFramework/soccer-simulation-proxy). After re-building from source, you can run the proxy by using `./start.sh --rpc-type thrift` in the bin folder of the proxy, and run the thrift server with `python3 server.py` in this repo's directory. It is highly recommended to launch the python server before the proxy.
162133

163-
## How does it work?
164-
Berifly, the Soccer Simulation 2D server sends the observations to the proxy, which forwards them to the playmaker server. The playmaker server processes the observations and sends the actions back to the proxy, which forwards them to the Soccer Simulation 2D server.
134+
You can modify the rpc port by adding the argument `--rpc-port [VALUE]`, where the default is 50051.
165135

166136
## Citation
167137

0 commit comments

Comments
 (0)