diff --git a/docs/2-sampleserver/2-sample-go-base-code-gRPC/index.md b/docs/2-sampleserver/2-sample-go-base-code-gRPC/index.md new file mode 100644 index 0000000..44d7ae2 --- /dev/null +++ b/docs/2-sampleserver/2-sample-go-base-code-gRPC/index.md @@ -0,0 +1,143 @@ +# Sample Go Base Code (gRPC) + +[![Documentation Status](https://readthedocs.org/projects/clsframework/badge/?version=latest)](https://clsframework.github.io/docs/introduction/) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + +This repository contains a sample decision-making server for the RoboCup 2D Soccer Simulation, which allows you to create a team by using Go. This server is compatible with the [Cross Language Soccer Framework](https://arxiv.org/pdf/2406.05621). This server is written in Golang and uses gRPC to communicate with the [proxy](https://github.com/CLSFramework/soccer-simulation-proxy). + +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. + +For more information, please refer to the [documentation](https://clsframework.github.io/). + +You can find more information about the services and messages in the [IDL section](../../3-idl/protobuf.md). + +## Quick start + +### Preparation + +Install the pre-requisites using the command below: + +``` Bash +sudo apt-get install fuse #Used to run AppImages +``` + +Clone this repository & install the required Golang libraries (such as gRPC). Don't forget to activate your virtual environment! + +``` Bash +git clone #add repo link +cd sample-playmaker-server-go-grpc + +go mod tidy # Install the required Golang libraries + + +./generate.sh # Generate the gRPC files +``` + +To download RoboCup Soccer 2D Server using the commands below: + +``` Bash +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 Golang server (this project) for decision-making. + +``` Bash +pushd scripts +sh download-proxy.sh #install C++ proxy +popd +``` + +Finally, to watch the game, download the monitor from [the original repository](https://github.com/rcsoccersim/rcssmonitor/releases) in order to view the games. + +### Running a game + +This section assumes you have installed the server & proxy using the scripts (as mentioned above) +We must first run a RoboCup Server, in order to host the game: + +``` Bash +cd scripts/rcssserver +./rcssserver +``` + +Then we must run the proxy & the decisionmaking server: + +``` Bash +./start-team.sh +``` + +### Options + +- `-t team_name`: Specify the team name. +- `--rpc-port PORT`: Specify the RPC port (default: 50051). +- `-d`: Enable debug mode. + + +Launch the opponent team, start the monitor app image. press Ctrl + C to connect to the server, and Ctrl + K for kick-off! + +### Tutorial Video (English) + +[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/hH-5rkhiQHg/0.jpg)](https://www.youtube.com/watch?v=hH-5rkhiQHg) + +### Tutorial Video (Persian) + +[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/97YDEumcVWU/0.jpg)](https://www.youtube.com/watch?v=97YDEumcVWU&t=0s) + +## How to change the code + +The `server.go` file contains the logic in 3 main functions: +`GetPlayerActions` receives a game state, and returns a list of actions for a player for for that cycle. +The actions we can output are equivalent to the Helios Base (Proxy), which are abstracted into multiple levels. +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/). + +Similarly, you can change `GetCoachActions` which is responsible for coach communication & substitutions. + +You can also use `GetTrainerActions` to move the players & the ball to make repeatable scenarios (when the server is in trainer mode). + +## Why & How it works + +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 Golang we decided to create a Golang platform which would be equivalent to Agent 2D. +However, using Golang 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 Golang 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. + +```mermaid +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 +``` + +![cls](https://github.com/user-attachments/assets/4daee216-1479-4acd-88f2-9e772b8c7837) +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. + +## Configuration + +### RoboCup Server configuration + +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. + +### Modifying Proxy & Running proxy and server seperately + +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 `go run server.go` in this repo's directory. It is highly recommended to launch the Golang server before the proxy. + +You can modify the rpc port by adding the argument `--rpc-port [VALUE]`, where the default is 50051. + +## Citation + +- [Cross Language Soccer Framework](https://arxiv.org/pdf/2406.05621) +- Zare, N., Sayareh, A., Sadraii, A., Firouzkouhi, A. and Soares, A., 2024. Cross Language Soccer Framework \ No newline at end of file diff --git a/docs/2-sampleserver/index.md b/docs/2-sampleserver/index.md index 35d767f..24dbd3c 100644 --- a/docs/2-sampleserver/index.md +++ b/docs/2-sampleserver/index.md @@ -12,6 +12,7 @@ Playmaker servers are the decision-making servers that control the agents in the - Sample Playmaker Servers in Python by using Thrift [GitHub](https://github.com/CLSFramework/sample-playmaker-server-python-thrift) - Sample Playmaker Servers in C# by using gRPC [GitHub](https://github.com/CLSFramework/playmaker-server-csharp) - Sample Playmaker Servers in NodeJs by using gRPC [GitHub](https://github.com/CLSFramework/playmaker-server-nodejs) +- Sample Playmaker Servers in Go by using gRPC [GitHub](https://github.com/CLSFramework/sample-playmaker-server-go-gRPC) ## Base Code diff --git a/docs/3-idl/index.md b/docs/3-idl/index.md index 2cb5eef..e995f38 100644 --- a/docs/3-idl/index.md +++ b/docs/3-idl/index.md @@ -1,4 +1,4 @@ --- -sidebar_position: 3 +sidebar_position: 4 title: IDL --- \ No newline at end of file diff --git a/docs/4-proxy/index.md b/docs/4-proxy/index.md index f20a902..1313f71 100644 --- a/docs/4-proxy/index.md +++ b/docs/4-proxy/index.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 title: Soccer Simulation Proxy --- # Soccer Simulation Proxy diff --git a/docs/5-soccersimulation/index.md b/docs/5-soccersimulation/index.md index 1a1c31f..17842c4 100644 --- a/docs/5-soccersimulation/index.md +++ b/docs/5-soccersimulation/index.md @@ -1,5 +1,12 @@ --- -sidebar_position: 5 +sidebar_position: 6 title: Soccer Simulation --- +To use the **CLSFramework**, you need two additional components: + +- **Soccer Simulation Server** + - This is the core server [`rcssserver`](/docs/5-soccersimulation/0-server/index.md) that connects the agents and runs the simulation. + +- **Monitor** + - A monitor is used to visualize the game. You can use either[`rcssmonitor`](/docs/5-soccersimulation/1-monitor/index.md) or [`soccerwindow2`](/docs/5-soccersimulation/2-soccerwindow/index.md) for this purpose. \ No newline at end of file diff --git a/docs/6-basecode/index.md b/docs/6-basecode/index.md index f4f0d74..8056f89 100644 --- a/docs/6-basecode/index.md +++ b/docs/6-basecode/index.md @@ -1,18 +1,11 @@ --- -sidebar_position: 2 +sidebar_position: 3 title: Base Codes --- -In this section, we will cover the Playmaker servers. -Playmaker servers are the decision-making servers that control the agents in the RoboCup Soccer 2D simulation environment. You can choose one of the sample servers provided in this documentation or create your own server [from scratch](/docs/proxy/develop-playmaker). - -## Sample Playmaker Servers - -- Sample Playmaker Servers in Python by using gRPC [GitHub](https://github.com/CLSFramework/sample-playmaker-server-python-grpc) [Docs](/docs/sampleserver/sample-python-base-code-gRPC/) -- Sample Playmaker Servers in Python by using Thrift [GitHub](https://github.com/CLSFramework/sample-playmaker-server-python-thrift) -- Sample Playmaker Servers in C# by using gRPC [GitHub](https://github.com/CLSFramework/playmaker-server-csharp) -- Sample Playmaker Servers in NodeJs by using gRPC [GitHub](https://github.com/CLSFramework/playmaker-server-nodejs) +In this section, we will cover the Base Codes that developed by the CLSFramework. ## Base Code +- PY2D Base Code in Python by using gRPC [GitHub](https://github.com/CLSFramework/py2d) - Starter Base Code in Python by using Thrift [GitHub](https://github.com/CLSFramework/starter-playmaker-server-python-thrift) diff --git a/docs/6-sampleteam/index.md b/docs/6-sampleteam/index.md deleted file mode 100644 index 045d9b0..0000000 --- a/docs/6-sampleteam/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_position: 2 -title: Base Codes ---- - -In this section, we will cover the Base Codes that developed by the CLSFramework. - -## Base Code - -- PY2D Base Code in Python by using gRPC [GitHub](https://github.com/CLSFramework/py2d) -- Starter Base Code in Python by using Thrift [GitHub](https://github.com/CLSFramework/starter-playmaker-server-python-thrift) diff --git a/docs/ToturialVideos/index.md b/docs/ToturialVideos/index.md index 11429b8..b785877 100644 --- a/docs/ToturialVideos/index.md +++ b/docs/ToturialVideos/index.md @@ -1,5 +1,9 @@ --- -sidebar_position: 6 +sidebar_position: 7 title: Tutorial Videos --- +In this section, we will cover the tutorial videos that developed for the CLSFramework. + +## Tutorial Videos +There are 2 languages available for the tutorial videos. You can watch the tutorial videos in [English](/docs/ToturialVideos/english.md) or [Persian](/docs/ToturialVideos/persian.md). \ No newline at end of file diff --git a/docusaurus.config.ts b/docusaurus.config.ts old mode 100644 new mode 100755 index 78a8c84..794169c --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -73,10 +73,52 @@ const config: Config = { }, items: [ { - type: 'docSidebar', - sidebarId: 'tutorialSidebar', + type: 'dropdown', + to: 'docs/introduction/', position: 'left', label: 'Tutorial', + items: [ + { + type: 'doc', + docId: 'introduction/index', + label: 'Introduction', + }, + { + type: 'doc', + docId: 'definitions/index', + label: 'Defenitions', + }, + { + type: 'doc', + docId: 'sampleserver/index', + label: 'Playmaker Server', + }, + { + type: 'doc', + docId: "basecode/index", + label: 'Base Code', + }, + { + type: 'doc', + docId: 'idl/index', + label: 'IDL', + }, + { + type: 'doc', + docId: 'proxy/index', + label: 'Soccer Simulation Proxy', + }, + { + type: 'doc', + docId: 'soccersimulation/index', + label: 'Soccer Simulation', + }, + { + type: 'doc', + docId: 'ToturialVideos/index', + label: 'Tutorial Videos', + }, + ] }, {to: '/blog', label: 'Blog', position: 'left'}, {to: '/release', label: 'Release', position: 'left'},