|
1 | | -# Sample Python Base Code (Thrift) |
| 1 | +# Sample Python Base Code (thrift) |
2 | 2 |
|
3 | 3 | [](https://clsframework.github.io/docs/introduction/) |
4 | 4 | [](https://opensource.org/licenses/MIT) |
5 | 5 |
|
6 | | -This repository contains a sample Playmaker server written in Python using Thrift, designed to facilitate the development of a Soccer Simulation 2D team. |
| 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). |
7 | 7 |
|
8 | | -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). |
| 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. |
9 | 9 |
|
10 | | -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. |
| 10 | +For more information, please refer to the [documentation](https://clsframework.github.io/). |
11 | 11 |
|
12 | | -This flexibility enables you to develop your team in any programming language of your choice, breaking the constraints of C++. |
| 12 | +## Quick start |
13 | 13 |
|
14 | | -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. |
| 14 | +### Preparation |
15 | 15 |
|
16 | | -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. |
| 16 | +Install the pre-requisites using the command below: |
17 | 17 |
|
18 | | -To learn more about the Cross Language Soccer Framework, visit the [official repository](https://github.com/CLSFramework/cross-language-soccer-framework/wiki) |
19 | | - |
20 | | - |
21 | | - |
22 | | -## Preparation |
23 | | - |
24 | | -To run a Soccer Simulation 2D game using the CLSF, you need to have RCSSServer, SoccerSimulationProxy, and Monitor to visualize the game. |
25 | | - |
26 | | -### RCSSServer |
27 | | -To download the latest AppImage of the RCSSServer, you can run the following command: |
28 | | - |
29 | | -```bash |
30 | | -cd scripts |
31 | | -./download-rcssserver.sh |
| 18 | +``` Bash |
| 19 | +sudo apt-get install fuse |
| 20 | +#Used to run AppImages |
32 | 21 | ``` |
33 | 22 |
|
34 | | -To run the RCSSServer AppImage, you need to install FUSE. You can install it by running the following command: |
35 | | - |
36 | | -```bash |
37 | | -sudo apt-get install fuse |
38 | | -``` |
39 | | - |
40 | | -<u>Notes:</u> |
41 | | -- You can build the RCSSServer from the source code. For more information, visit the [official repository](https://github.com/rcsoccersim/rcssserver). |
42 | | -- The RCSSServer should be run on <u>Linux (preferably Ubuntu) or WSL</u>. |
43 | | - |
44 | | - |
45 | | - |
46 | | -### SoccerSimulationProxy |
47 | | - |
48 | | -To download the latest AppImage of the SoccerSimulationProxy, you can run the following command: |
49 | | - |
50 | | -```bash |
51 | | -cd scripts |
52 | | -./download-proxy.sh |
53 | | -``` |
| 23 | +Clone this repository & install the required python libraries (such as thrift). Don't forget to activate your virtual environment! |
54 | 24 |
|
55 | | -To run the SoccerSimulationProxy AppImage, you need to install FUSE. You can install it by running the following command: |
| 25 | +``` Bash |
| 26 | +git clone https://github.com/CLSFramework/sample-playmaker-server-python-thrift.git |
| 27 | +cd sample-playmaker-server-python-thrift |
| 28 | +# Activate venv/anaconda before this step! |
| 29 | +pip install -r requirements.txt |
56 | 30 |
|
57 | | -```bash |
58 | | -sudo apt-get install fuse |
| 31 | +./generate.sh |
| 32 | +# Generate the thrift files |
59 | 33 | ``` |
60 | 34 |
|
61 | | -<u>Notes:</u> |
62 | | -- You can build the SoccerSimulationProxy from the source code. For more information, visit the [official repository](https://github.com/CLSFramework/soccer-simulation-proxy) |
63 | | -- The SoccerSimulationProxy should be run on <u>Linux (preferably Ubuntu) or WSL</u>. |
64 | | - |
65 | | -### Monitor |
66 | | - |
67 | | -To download the latest AppImage of the Monitor, you can download it from the [official repository](https://github.com/rcsoccersim/rcssmonitor/releases). |
68 | | - |
69 | | -To run the monitor, you need to install FUSE. You can install it by running the following command: |
| 35 | +To download RoboCup Soccer 2D Server using the commands below: |
70 | 36 |
|
71 | | -```bash |
72 | | -sudo apt-get install fuse |
| 37 | +``` Bash |
| 38 | +pushd scripts |
| 39 | +sh download-rcssserver.sh # Download the soccer simulation server |
| 40 | +popd |
73 | 41 | ``` |
74 | 42 |
|
75 | | -### Create Python Virtual Environment and Install Dependencies |
| 43 | +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. |
76 | 44 |
|
77 | | -To create a Python virtual environment and install the dependencies, you can run the following commands: |
78 | | - |
79 | | -```bash |
80 | | -python3 -m venv venv |
81 | | -source venv/bin/activate |
82 | | -pip install -r requirements.txt |
83 | | -./generate.sh # To generate thrift python files |
| 45 | +``` Bash |
| 46 | +pushd scripts |
| 47 | +sh download-proxy.sh #install C++ proxy |
| 48 | +popd |
84 | 49 | ``` |
85 | 50 |
|
86 | | -## Running a game |
| 51 | +Finally, to watch the game, download the monitor from [the original repository](https://github.com/rcsoccersim/rcssmonitor/releases) in order to view the games. |
87 | 52 |
|
88 | | -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 | +### Running a game |
89 | 54 |
|
90 | | -### Running the RCSSServer |
91 | | -If you have downloaded the RCSSServer AppImage, you can run it by running the following command: |
| 55 | +This section assumes you have installed the server & proxy using the scripts (as mentioned above) |
| 56 | +We must first run a RoboCup Server, in order to host the game: |
92 | 57 |
|
93 | | -```bash |
| 58 | +``` Bash |
94 | 59 | cd scripts/rcssserver |
95 | 60 | ./rcssserver |
96 | 61 | ``` |
97 | 62 |
|
98 | | -Otherwise, you built and install the RCSSServer from the source code, you can run the server by running the following command: |
| 63 | +Then we must run the proxy & the decisionmaking server: |
99 | 64 |
|
100 | | -```bash |
101 | | -rcssserver |
| 65 | +``` Bash |
| 66 | +./start-team.sh |
102 | 67 | ``` |
103 | 68 |
|
104 | | -## Running the Sample Server and Proxy |
| 69 | +### Options |
105 | 70 |
|
106 | | -There are three different ways to run the sample server: |
| 71 | +- `-t team_name`: Specify the team name. |
| 72 | +- `--rpc-port PORT`: Specify the RPC port (default: 50051). |
| 73 | +- `-d`: Enable debug mode. |
107 | 74 |
|
108 | | -- Using start-team.py |
109 | | -- Using start-team.sh |
110 | | -- Running the server and client separately |
| 75 | +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! |
111 | 76 |
|
112 | | -### Using start-team.py (This script can be used in Ubuntu or WSL) |
| 77 | +### Tutorial Video (English) |
113 | 78 |
|
114 | | -Note: To use this script you need to download the proxy by using `scripts/download-proxy.sh`. |
| 79 | +TDB |
115 | 80 |
|
116 | | -Run the `start-team.py` script: |
| 81 | +### Tutorial Video (Persian) |
117 | 82 |
|
118 | | -```bash |
119 | | -python start-team.py |
120 | | -``` |
| 83 | +[](https://www.youtube.com/watch?v=97YDEumcVWU&t=0s) |
121 | 84 |
|
122 | | -You can pass the following arguments to the script: |
123 | | -- `--team-name`: The name of the team (default: `CLSF`) |
124 | | -- `--rpc-port`: The port number for the RPC server (default: `50051`) |
| 85 | +## How to change the code |
125 | 86 |
|
126 | | -### Using start-team.sh (This script can be used in Linux) |
| 87 | +The `server.py` file contains the logic in 3 main functions: |
| 88 | +`GetPlayerActions` receives a game state, and returns a list of actions for a player for for that cycle. |
| 89 | +The actions we can output are equivalent to the Helios Base (Proxy), which are abstracted into multiple levels. |
| 90 | +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/). |
127 | 91 |
|
128 | | -Note: To use this script you need to download the proxy by using `scripts/download-proxy.sh`. |
| 92 | +Similarly, you can change `GetCoachActions` which is responsible for coach communication & substitutions. |
129 | 93 |
|
130 | | -Run the `start-team.sh` script: |
| 94 | +You can also use `GetTrainerActions` to move the players & the ball to make repeatable scenarios (when the server is in trainer mode). |
131 | 95 |
|
132 | | -```bash |
133 | | -./start-team.sh |
134 | | -``` |
135 | | - |
136 | | -You can pass the following arguments to the script: |
137 | | -- `--team-name`: The name of the team (default: `CLSF`) |
138 | | -- `--rpc-port`: The port number for the RPC server (default: `50051`) |
139 | | - |
140 | | -### Running the server and client separately |
| 96 | +## Why & How it works |
141 | 97 |
|
142 | | -(This method can be used in Windows and Linux, but the proxy can only be run in Linux) |
| 98 | +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. |
| 99 | +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. |
| 100 | +However, using python alone was too slow as preprocessing sensor information & tasks such as localization took too long. |
143 | 101 |
|
144 | | -To run the server, you can run the following command: |
| 102 | +For this reason we have split up the code into two segments: |
| 103 | +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. |
145 | 104 |
|
146 | | -```bash |
147 | | -python server.py |
| 105 | +```mermaid |
| 106 | +sequenceDiagram |
| 107 | + participant SS as SoccerSimulationServer |
| 108 | + participant SP as SoccerSimulationProxy |
| 109 | + participant PM as PlayMakerServer |
| 110 | + Note over SS,PM: Run |
| 111 | + SP->>SS: Connect |
| 112 | + SS->>SP: OK, Unum |
| 113 | + SP->>PM: Register |
| 114 | + PM->>SP: OK, ClientID |
| 115 | + SS->>SP: Observation |
| 116 | + Note over SP: Convert observation to State |
| 117 | + SP->>PM: State |
| 118 | + PM->>SP: Actions |
| 119 | + Note over SP: Convert Actions to Low-Level Commands |
| 120 | + SP->>SS: Commands |
148 | 121 | ``` |
149 | 122 |
|
150 | | -You can pass the following arguments to the server: |
151 | | -- `--rpc-port`: The port number for the RPC server (default: `50051`) |
| 123 | + |
| 124 | +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. |
152 | 125 |
|
153 | | -If you want to run the proxy agents, you can run the following command: |
| 126 | +## Configuration |
154 | 127 |
|
155 | | -```bash |
156 | | -cd scripts/proxy |
157 | | -./start.sh |
158 | | -``` |
| 128 | +### RoboCup Server configuration |
| 129 | + |
| 130 | +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. |
159 | 131 |
|
160 | | -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) |
| 132 | +### Modifying Proxy & Running proxy and server seperately |
161 | 133 |
|
162 | | -#### Running the playmaker server in Windows (Not recommended) |
163 | | -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. |
164 | | -<u>Right now due to some issues with Python multiprocessing, the playmaker server can't be run in Windows.</u> |
| 134 | +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. |
165 | 135 |
|
166 | | -## How does it work? |
167 | | -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. |
| 136 | +You can modify the rpc port by adding the argument `--rpc-port [VALUE]`, where the default is 50051. |
168 | 137 |
|
169 | 138 | ## Citation |
170 | 139 |
|
171 | 140 | - [Cross Language Soccer Framework](https://arxiv.org/pdf/2406.05621) |
172 | | -- 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. |
| 141 | +- 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. |
0 commit comments