Skip to content

Commit 040e08b

Browse files
naderzarenaderzare
committed
update docs
1 parent 0f9f00a commit 040e08b

File tree

27 files changed

+612
-0
lines changed

27 files changed

+612
-0
lines changed

‎docs/0-introduction/index.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
sidebar_position: 0
3+
title: Introduction
4+
---
5+
6+
# Introduction
7+
8+
## RoboCup and Soccer Simulation 2D
9+
10+
RoboCup is an international robotics competition that focuses on promoting research and development in the field of autonomous robots. The competition aims to advance the state of the art in robotics and artificial intelligence by challenging teams to develop robots capable of playing soccer, rescue, and other tasks against other teams in a real-world or simulated environment.
11+
12+
RoboCup Soccer Simulation 2D is a league in the RoboCup competition that focuses on developing autonomous soccer-playing agents. The goal of the league is to develop intelligent agents that can play soccer in a simulated environment. The agents must be able to perceive the game state, make decisions based on that information, and execute actions to play the game effectively.
13+
14+
![image](https://github.com/Cross-Language-Soccer-Framework/cross-language-soccer-framework/assets/25696836/7b0b1d49-7001-479c-889f-46a96a8802c4)
15+
16+
## Cross Language Soccer Framework
17+
18+
Cross Language Soccer Framework (CLSFramework) is a new approach to enhance the flexibility and interoperability of RoboCup Soccer Simulation 2D (SS2D).
19+
This framework is designed to allow the development of RoboCup Soccer Simulation 2D agents in different programming languages.
20+
The Soccer Simulation Proxy is an extended version of the Helios base that can send decision-making information to a PlayMaker Server. It can receive high-level/low-level actions from the PlayMaker Server and send them to the RoboCup Soccer Simulation Server and/or SoccerWindow2.
21+
On the other hand, the PlayMaker Server receives information from the client(Modified version of Helios base/Soccer Simulation Proxy) and selects the appropriate actions to be sent back to the client. We have implemented some sample servers in C\#, Python, and JavaScript, but it can also be implemented in other languages to make use of their features.
22+
23+
24+
![image](https://github.com/user-attachments/assets/0c22d0e5-a1ad-4a43-8cba-a9fc70c6ed5b)
25+
26+
![image](https://github.com/user-attachments/assets/b4484095-0913-4434-bf1f-35f11e8bf629)
27+
28+
## How To Use The Framework?
29+
30+
To run a normal soccer simulation 2D game without using the proxy, you need to run the Soccer Simulation Server (RCSSServer) and the Soccer Simulator Monitor (RCSSMonitor). The Soccer Simulation Server will host the game, and the Soccer Simulator Monitor will display the game. Also, you need to run two teams to play the game. Each team should have a coach and eleven players (and trainer for training proposes and controlling the server). All of the clients connect to the RCSSServer by using UDP to send action and receive information.
31+
32+
To run a game by using the framework, you need to run the Soccer Simulation Server to host a game, the Soccer Simulator Monitor, Soccer Simulation Proxy, and a Playmaker Server. We provide some different solution to build, install, and run these components on Linux(Ubuntu) [Build From Source, AppImage, Docker] and Windows[WSL, Docker]. Also, there are some solutions that you can run some of the components together.
33+
34+
There are three different solutions to use the framework:
35+
36+
- Use the implemented Sample PlayMaker Servers in C\#, Python, and JavaScript and implement the decision-making part.
37+
- [PlaymakerServer-Python](https://github.com/CLSFramework/playmaker-server-python)
38+
- [Sample-PlaymakerServer-Python-GRPC](https://github.com/CLSFramework/sample-playmaker-server-python-grpc)
39+
- [Sample-PlaymakerServer-Python-THRIFT](https://github.com/CLSFramework/sample-playmaker-server-python-thrift)
40+
- [PlaymakerServer-NodeJs-GRPC](https://github.com/CLSFramework/playmaker-server-nodejs)
41+
- [PlaymakerServer-CSharp-GRPC](https://github.com/CLSFramework/playmaker-server-csharp)
42+
- Use the implemented base code and complete the decision-making part.
43+
- [Starter-PlaymakerServer-Python-THRIFT](https://github.com/CLSFramework/starter-playmaker-server-python-thrift)
44+
- Implement a PlayMaker Server in your favorite language and use the Soccer Simulation Proxy to connect to the RCSSServer.
45+
- [Soccer Simulation Proxy](https://github.com/CLSFramework/soccer-simulation-proxy)
46+
47+
## Cpp base problems
48+
49+
The base code provided by the RoboCup Soccer Simulation 2D community is written in C++ and is very complex. It is difficult to understand and modify, and it is not easy to implement new features or algorithms. Learning C++ language and understanding the base code requires a lot of time and effort, which can be a barrier for new researchers and developers who want to work on the RoboCup Soccer Simulation 2D league. Also, C++ does not AI/ML libraries like Python, which makes it difficult to implement new algorithms and models.
50+
51+
## Why not develop a base code for each language?
52+
53+
Developing a base code for each language is a time-consuming task that requires a lot of effort. The RCSSServer sends noisy observations to players and receives low-level actions such as Dash, Turn, and Kick. Therefore, a sample base code should process the received information, denoise it, create a model, make a decision, convert high-level decisions like BodySmartKick and BodyGoToPoint to low-level actions, and send them to the RCSSServer. However, developing a base code for each language is a time-consuming task, and some languages may not have the high-performance capabilities of C++, which can perform all tasks within a cycle of 0.1 seconds.
54+
55+
To overcome these challenges, the CLSFramework can denoise information, create models, and send them to the PlayMaker-Server. The PlayMaker-Server can be developed in any language supported by gRPC and is responsible for making decisions and sending actions to the SoccerSimulationProxy, which then sends the actions to the RCSSServer. This approach simplifies the development process and allows for more efficient implementation of the required functionalities.
56+
57+
## Work floW
58+
59+
```mermaid
60+
sequenceDiagram
61+
participant SS as SoccerSimulationServer
62+
participant SP as SoccerSimulationProxy
63+
participant PM as PlayMakerServer
64+
Note over SS,PM: Run
65+
SP->>SS: Connect
66+
SS->>SP: OK, Unum
67+
SP->>PM: Register
68+
PM->>SP: OK, ClientID
69+
SS->>SP: Observation
70+
Note over SP: Convert observation to State
71+
SP->>PM: State
72+
PM->>SP: Actions
73+
Note over SP: Convert Actions to Low-Level Commands
74+
SP->>SS: Commands
75+
```

‎docs/1-definitions/index.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Definitions
6+
7+
## [RoboCup](https://www.robocup.org/)
8+
9+
RoboCup is an international robotics competition that focuses on promoting research and development in the field of autonomous robots. The competition aims to advance the state of the art in robotics and artificial intelligence by challenging teams to develop robots capable of playing soccer, rescue, and other tasks against other teams in a real-world or simulated environment.
10+
11+
## [RoboCup Soccer Simulation 2D](https://rcsoccersim.github.io/)
12+
13+
RoboCup Soccer Simulation 2D is a league in the RoboCup competition that focuses on developing autonomous soccer-playing agents. The goal of the league is to develop intelligent agents that can play soccer in a simulated environment. The agents must be able to perceive the game state, make decisions based on that information, and execute actions to play the game effectively.
14+
15+
![image](https://github.com/Cross-Language-Soccer-Framework/cross-language-soccer-framework/assets/25696836/7b0b1d49-7001-479c-889f-46a96a8802c4)
16+
17+
## [RoboCup Soccer Simulation Server](https://github.com/rcsoccersim/rcssserver)
18+
19+
The RCSSServer is a soccer server for the RoboCup Soccer Simulation 2D. It is a program that simulates a soccer game between two teams of eleven players and one coach each. The server provides a complete simulation of the game, including the physics of the ball, the field, and the players, as well as the dynamics of the game, such as the rules, the referee, and the game clock.
20+
21+
## [RoboCup Soccer Simulator Monitor](https://github.com/rcsoccersim/rcssmonitor)
22+
23+
RoboCup Soccer Simulator Monitor (rcssmonitor) is used to view the simulation as it takes place by connecting to the RoboCup Soccer Simulator Server (rcssserver) or to view the playback of a simulation by loading game log files.
24+
25+
## [Helios Base Code](https://github.com/helios-base/helios-base)
26+
27+
The Helios Base Code is a framework for the RoboCup Soccer Simulation 2D. It is a collection of software components that provide a common infrastructure for developing soccer simulation 2D teams. The base code is designed to be easy to use and extend, and it provides a number of features that make it easier to develop teams.
28+
29+
## [RPC](https://en.wikipedia.org/wiki/Remote_procedure_call)
30+
31+
A remote procedure call (RPC) is an inter-process communication that allows a computer program to cause a subroutine or procedure to execute in another address space (commonly on another computer on a shared network) without the programmer explicitly coding the details for this remote interaction.
32+
33+
## [gRPC](https://grpc.io/docs/what-is-grpc/)
34+
35+
gRPC is a high-performance, open-source, general-purpose RPC framework that puts mobile and HTTP/2 first. gRPC is based on the HTTP/2 standard, which is the next generation of HTTP. HTTP/2 is a binary protocol that is more efficient than HTTP/1.1, which is the current version of HTTP. HTTP/2 is also more secure than HTTP/1.1, because it uses TLS encryption by default.
36+
37+
## [Thrift](https://thrift.apache.org/)
38+
39+
Apache Thrift is a software framework for scalable cross-language services development. It combines a software stack with a code generation engine to build services that work efficiently and seamlessly between C++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C#, Cocoa, JavaScript, Node.js, Smalltalk, OCaml, Delphi, and other languages.
40+
41+
## Cross Language Soccer Framework
42+
43+
Cross Language Soccer Framework is a new approach to enhance the flexibility and interoperability of RoboCup Soccer Simulation 2D (SS2D). The Soccer Simulation Proxy is an extended version of the Helios base that can send decision-making information to the PlayMaker Server. It can receive high-level actions from the PlayMaker Server and send them to RoboCup Soccer Simulation Server and/or SoccerWindow2.
44+
On the other hand, the PlayMaker Server receives information from the client and selects the appropriate actions to be sent back to the client. We have implemented some sample servers in C\#, Python, and JavaScript, but it can also be implemented in other languages to make use of their features.
45+
46+
![image](https://github.com/Cross-Language-Soccer-Framework/cross-language-soccer-framework/assets/25696836/d152797b-53f0-490f-a8dd-b8c0ef667317)
47+
48+
## [Soccer Simulation Proxy](https://github.com/Cross-Language-Soccer-Framework/soccer-simulation-proxy)
49+
50+
We have modified the Helios base code to enhance its interaction capabilities with the gRPC server. Specifically, the base code now transmits detailed information about each game cycle to the server, which in response, sends back a series of potential actions. This bidirectional communication enables the PlayMaker Server to effectively process and make strategic decisions based on the incoming data.
51+
52+
To facilitate this enhanced functionality, the client is designed to serialize various data types—such as the WorldModel, FullState WorldModel, Server Parameters, Player Parameters, and Player Types—into gRPC messages during each game cycle. Conversely, it also deserializes incoming gRPC action messages back into Helios base actions.
53+
54+
These improvements ensure that the Helios base maintains its inherent efficiency and performance, while now being able to seamlessly interact with a diverse array of programming languages through gRPC. This modification not only preserves the robustness of the original system but also expands its utility and applicability in multi-language research environments.
55+
56+
## Playmaker Server
57+
58+
The Playmaker Server acts as the decision-making hub within our framework, receiving and processing messages from the Soccer Simulation Proxy. Based on the detailed information conveyed in these messages, it evaluates the current game state and strategically generates corresponding actions to be executed in the simulation.
59+
60+
To demonstrate the versatility and language-agnostic design of our framework, we have developed initial implementations of the Playmaker Server in three different programming languages: C#, Python, and JavaScript. These examples serve to showcase the server’s capability to operate effectively across diverse programming environments. Looking ahead, we aim to extend this functionality by developing additional server implementations in other languages, further broadening the framework's accessibility and appeal to a global research community.
61+
62+
- [Sample Playmaker Server - CSharp - gRPC](https://github.com/CLSFramework/playmaker-server-csharp)
63+
- [Sample Playmaker Server - Python - gRPC](https://github.com/CLSFramework/sample-playmaker-server-python-grpc)
64+
- [Sample Playmaker Server - Python - Thrift](https://github.com/CLSFramework/sample-playmaker-server-python-thrift)
65+
- [Sample Playmaker Server - NodeJs - gRPC](https://github.com/CLSFramework/playmaker-server-nodejs)
66+
67+
![image](https://github.com/Cross-Language-Soccer-Framework/cross-language-soccer-framework/assets/25696836/8ae17787-8bf8-4796-92f2-e20066e3175f)

‎docs/2-sampleserver/index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
sidebar_position: 2
3+
title: Playmaker server
4+
---
5+
6+
- Samples
7+
- Starter

‎docs/3-idl/actions.md‎

Whitespace-only changes.

‎docs/3-idl/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
sidebar_position: 3
3+
title: IDL
4+
---

‎docs/3-idl/messages.md‎

Whitespace-only changes.

‎docs/3-idl/services.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Services
6+
7+
## gRPC
8+
9+
```protobuf
10+
service Game {
11+
rpc GetPlayerActions(State) returns (PlayerActions) {}
12+
rpc GetCoachActions(State) returns (CoachActions) {}
13+
rpc GetTrainerActions(State) returns (TrainerActions) {}
14+
rpc SendInitMessage(InitMessage) returns (Empty) {}
15+
rpc SendServerParams(ServerParam) returns (Empty) {}
16+
rpc SendPlayerParams(PlayerParam) returns (Empty) {}
17+
rpc SendPlayerType(PlayerType) returns (Empty) {} //should be PlayerTypes
18+
rpc Register(RegisterRequest) returns (RegisterResponse) {}
19+
rpc SendByeCommand(RegisterResponse) returns (Empty) {}
20+
rpc GetBestPlannerAction(BestPlannerActionRequest) returns (BestPlannerActionResponse) {}
21+
}
22+
```
23+
24+
## Thrift
25+
26+
```thrift
27+
service Game {
28+
PlayerActions GetPlayerActions(1: State state),
29+
CoachActions GetCoachActions(1: State state),
30+
TrainerActions GetTrainerActions(1: State state),
31+
Empty SendInitMessage(1: InitMessage init_message),
32+
Empty SendServerParams(1: ServerParam server_param),
33+
Empty SendPlayerParams(1: PlayerParam player_param),
34+
Empty SendPlayerType(1: PlayerType player_type),
35+
RegisterResponse Register(1: RegisterRequest request),
36+
Empty SendByeCommand(1: RegisterResponse register_response),
37+
BestPlannerActionResponse GetBestPlannerAction(1: BestPlannerActionRequest best_planner_action_request)
38+
}
39+
```
40+
41+
**GetPlayerActions** - Get the actions of the players. Each proxy player agent will call this method to get the actions of the players in each cycle of the game.
42+
43+
**GetCoachActions** - Get the actions of the coach. The coach agent will call this method to get the actions of the coach in each cycle of the game.
44+
45+
**GetTrainerActions** - Get the actions of the trainer. The trainer agent will call this method to get the actions of the trainer in each cycle of the game.
46+
47+
TODO: Add more information about the services and messages in the IDL section.
48+
49+
TODO: Add mermaid diagram to show the work flow of the services.

‎docs/3-idl/state.md‎

Whitespace-only changes.

‎docs/4-proxy/app-image.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# Use App Image
6+
7+
## Download
8+
9+
You can download the AppImage of the Soccer Simulation Proxy from the [release page](https://github.com/CLSFramework/soccer-simulation-proxy/releases).
10+
11+
Or download the latest version by using the following command:
12+
13+
```bash
14+
wget $(curl -s "https://api.github.com/repos/clsframework/soccer-simulation-proxy/releases/latest" | grep -oP '"browser_download_url": "\K[^"]*' | grep "soccer-simulation-proxy.tar.gz")
15+
```
16+
17+
## Extract
18+
19+
```bash
20+
tar -xvf soccer-simulation-proxy.tar.gz
21+
```
22+
23+
## Run
24+
25+
```bash
26+
cd SoccerSimulationProxy
27+
./start.sh
28+
```
29+
30+
You can download the AppImage of the Soccer Simulation Proxy from the #### and run it.

‎docs/4-proxy/build.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
# Build From Source
6+
7+
## Build from source, install, and run (Linux, WSL)
8+
9+
To build the soccer simulation proxy, you need to install the following dependencies:
10+
11+
### LibRCSC
12+
13+
```bash
14+
git clone [email protected]:helios-base/librcsc.git
15+
cd librcsc
16+
git checkout 19175f339dcb5c3f61b56a8c1bff5345109f22ef
17+
mkdir build
18+
cd build
19+
cmake ..
20+
make
21+
make install
22+
```
23+
24+
### gRPC - follow the instructions provided in the [repository](https://grpc.io/docs/languages/cpp/quickstart/)
25+
26+
```bash
27+
export MY_INSTALL_DIR=$HOME/.local
28+
mkdir -p $MY_INSTALL_DIR
29+
export PATH="$MY_INSTALL_DIR/bin:$PATH"
30+
sudo apt install -y build-essential autoconf libtool pkg-config
31+
git clone --recurse-submodules -b v1.62.0 --depth 1 --shallow-submodules https://github.com/grpc/grpc
32+
cd grpc/
33+
mkdir -p cmake/build
34+
pushd cmake/build
35+
cmake -DgRPC_INSTALL=ON -DgRPC_BUILD_TESTS=OFF -DCMAKE_INSTALL_PREFIX=$MY_INSTALL_DIR ../..
36+
make -j 4
37+
make install
38+
```
39+
40+
then, add the following lines at the end of $HOME/.bashrc
41+
42+
```bash
43+
export MY_INSTALL_DIR=$HOME/.local
44+
export PATH="$MY_INSTALL_DIR/bin:$PATH"
45+
```
46+
47+
then, run the following command
48+
49+
```bash
50+
source $HOME/.bashrc
51+
```
52+
53+
To test grpc, go to grpc directory (in this example it is in $HOME/grpc) and run the following commands:
54+
55+
```bash
56+
cd examples/cpp/helloworld
57+
mkdir -p cmake/build
58+
cd cmake/build/
59+
cmake -DCMAKE_PREFIX_PATH=$MY_INSTALL_DIR ../..
60+
make
61+
run ./greeter_server in one tab
62+
run ./greeter_client in another tab
63+
```
64+
65+
### Thirft
66+
67+
TODO
68+
69+
### SoccerSimulationProxy
70+
71+
```bash
72+
git clone [email protected]:CLSFramework/soccer-simulation-proxy.git
73+
cd soccer-simulation-proxy
74+
mkdir build
75+
cd build
76+
cmake ..
77+
make
78+
```
79+
80+
## Run Soccer Simulation Proxy
81+
82+
To run the Soccer Simulation Proxy, you can use the following command: (You should run the Soccer Simulation Server and a PlayMaker Server before running the Soccer Simulation Proxy)
83+
84+
```bash
85+
cd build/bin
86+
./start.sh
87+
```
88+
89+
To run the Soccer Simulation Proxy in debug mode, you can use the following command:
90+
91+
```bash
92+
cd build/bin
93+
./start-debug.sh
94+
```

0 commit comments

Comments
 (0)