Skip to content

Commit 63b5039

Browse files
actions-useractions-user
committed
Update py2d documentation from README
1 parent d293dc3 commit 63b5039

File tree

1 file changed

+143
-1
lines changed

1 file changed

+143
-1
lines changed

‎docs/6-basecode/py2d/index.md

Lines changed: 143 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,151 @@
11
---
2-
custom_edit_url: 'https://github.com/CLSFramework/sample-playmaker-server-python-thrift/blob/main/README.md'
2+
custom_edit_url: 'https://github.com/CLSFramework/py2d/blob/main/README.md'
33
---
44

55
# PY2D Base Code
66

77

88
[![Documentation Status](https://readthedocs.org/projects/clsframework/badge/?version=latest)](https://clsframework.github.io/docs/introduction/)
99
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
10+
11+
![alt text](image.png)
12+
PY2D Soccer Simulation Base Code is a base code for RoboCup 2D Soccer Simulation teams, which is written in Python.
13+
This base code is powered by the [Cross Language Soccer Framework](https://arxiv.org/pdf/2406.05621), which allows you to create a team by using any programming language that supports gRPC or Thrift.
14+
This base code uses `Helios Base` as a proxy to communicate with the RoboCup 2D Soccer Simulation server.
15+
PY2D base is the most power full base code for RoboCup 2D Soccer Simulation which developed in Python.
16+
17+
For more information, please refer to the [documentation](https://clsframework.github.io/).
18+
19+
You can find more information about the services and messages in the [IDL section](../../3-idl/protobuf.md).
20+
21+
## Quick start
22+
23+
### Preparation
24+
25+
Install the pre-requisites using the command below:
26+
27+
``` Bash
28+
sudo apt-get install fuse #Used to run AppImages
29+
```
30+
31+
Clone this repository & install the required python libraries (such as gRPC). Don't forget to activate your virtual environment!
32+
33+
``` Bash
34+
git clone https://github.com/CLSFramework/py2d.git
35+
cd py2d
36+
# Activate venv/anaconda before this step!
37+
pip install -r requirements.txt
38+
39+
./generate.sh # Generate the gRPC files
40+
```
41+
42+
To download RoboCup Soccer 2D Server using the commands below:
43+
44+
``` Bash
45+
pushd scripts
46+
sh download-rcssserver.sh # Download the soccer simulation server
47+
popd
48+
```
49+
50+
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.
51+
52+
``` Bash
53+
pushd scripts
54+
sh download-proxy.sh #install C++ proxy
55+
popd
56+
```
57+
58+
Finally, to watch the game, download the monitor from [the original repository](https://github.com/rcsoccersim/rcssmonitor/releases) in order to view the games.
59+
60+
### Running a game
61+
62+
This section assumes you have installed the server & proxy using the scripts (as mentioned above)
63+
We must first run a RoboCup Server, in order to host the game:
64+
65+
``` Bash
66+
cd scripts/rcssserver
67+
./rcssserver
68+
```
69+
70+
Then we must run the proxy & the decisionmaking server:
71+
72+
``` Bash
73+
./start.sh
74+
// or
75+
python3 start.py
76+
```
77+
78+
### Options
79+
80+
- `-t team_name`: Specify the team name.
81+
- `--rpc-port PORT`: Specify the RPC port (default: 50051).
82+
- `-d`: Enable debug mode.
83+
84+
85+
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!
86+
87+
### Tutorial Video (English)
88+
89+
[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/hH-5rkhiQHg/0.jpg)](https://www.youtube.com/watch?v=hH-5rkhiQHg)
90+
91+
### Tutorial Video (Persian)
92+
93+
[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/97YDEumcVWU/0.jpg)](https://www.youtube.com/watch?v=97YDEumcVWU&t=0s)
94+
95+
## How to change the code
96+
97+
The `server.py` file contains the logic in 3 main functions:
98+
`GetPlayerActions` receives a game state, and returns a list of actions for a player for for that cycle.
99+
The actions we can output are equivalent to the Helios Base (Proxy), which are abstracted into multiple levels.
100+
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/).
101+
102+
Similarly, you can change `GetCoachActions` which is responsible for coach communication & substitutions.
103+
104+
You can also use `GetTrainerActions` to move the players & the ball to make repeatable scenarios (when the server is in trainer mode).
105+
106+
## Why & How it works
107+
108+
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.
109+
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.
110+
However, using python alone was too slow as preprocessing sensor information & tasks such as localization took too long.
111+
112+
For this reason we have split up the code into two segments:
113+
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.
114+
115+
```mermaid
116+
sequenceDiagram
117+
participant SS as SoccerSimulationServer
118+
participant SP as SoccerSimulationProxy
119+
participant PM as PlayMakerServer
120+
Note over SS,PM: Run
121+
SP->>SS: Connect
122+
SS->>SP: OK, Unum
123+
SP->>PM: Register
124+
PM->>SP: OK, ClientID
125+
SS->>SP: Observation
126+
Note over SP: Convert observation to State
127+
SP->>PM: State
128+
PM->>SP: Actions
129+
Note over SP: Convert Actions to Low-Level Commands
130+
SP->>SS: Commands
131+
```
132+
133+
![cls](https://github.com/user-attachments/assets/4daee216-1479-4acd-88f2-9e772b8c7837)
134+
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.
135+
136+
## Configuration
137+
138+
### RoboCup Server configuration
139+
140+
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.
141+
142+
### Modifying Proxy & Running proxy and server seperately
143+
144+
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 grpc` in the bin folder of the proxy, and run the gRPC server with `python3 server.py` in this repo's directory. It is highly recommended to launch the python server before the proxy.
145+
146+
You can modify the rpc port by adding the argument `--rpc-port [VALUE]`, where the default is 50051.
147+
148+
## Citation
149+
150+
- [Cross Language Soccer Framework](https://arxiv.org/pdf/2406.05621)
151+
- 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

Comments
 (0)