From b8f3bf7c40ad00fbd614861b3c0e8817243079d6 Mon Sep 17 00:00:00 2001 From: Nicolai Ommer Date: Tue, 25 Jul 2023 21:57:23 +0200 Subject: [PATCH] Update documentation --- Readme.md | 92 ++++++++++++++++++++++++++++++---------------------- build.bat | 3 -- build.gradle | 5 +++ build.sh | 3 -- run.bat | 11 ------- run.sh | 19 ----------- 6 files changed, 58 insertions(+), 75 deletions(-) delete mode 100755 build.bat delete mode 100755 build.sh delete mode 100755 run.bat delete mode 100755 run.sh diff --git a/Readme.md b/Readme.md index 52e1a008..b01b21f8 100644 --- a/Readme.md +++ b/Readme.md @@ -11,54 +11,73 @@ All dependencies will be downloaded automatically, so you need an internet conne * Java JDK 17 * Internet connection - * no limitations on OS known +* Some optional features require native libraries (like screencasting or gamepad support), so some more exotic + architectures may not fully be supported ## Build -Run `./gradlew build` to build the full application. -You can skip the tests with `./gradlew build -x test`. +Run `./gradlew build` to build the full application. + +You can skip the tests with `./gradlew build -x test`. ## Run + Start Sumatra with `./gradlew :run` or use the provided IntelliJ run configuration. -Custom Sumatra arguments can be passed with `--args="--my-arg"`. -For development, use `./gradlew :run -Pdevelopment` to enable some more runtime checks (assertions). -For a real match, use `./gradlew :run -Pproductive` to disable some checks, start recordings automatically and increase -the heap size. +Custom Sumatra arguments can be passed like this: `./gradlew :run --args="--help"`. ## Install + Sumatra can be installed into a single directory containing all dependencies: `./gradlew installDist`. The directory is located in `build/install/sumatra`. -The `run.sh` and `build.sh` scripts make use of this task. Additional JVM arguments can be passed in using the environment variable `SUMATRA_OPTS`. -Note: Install does not work with Windows due to an issue in the generated start script (set CLASSPATH line too long). +Note: Install may not work with Windows due to an issue in the generated start script (set CLASSPATH line too long). ## IntelliJ -IntelliJ reads the Gradle configuration and uses Gradle to perform the build and to start the application. -Make sure to configure Gradle for build and tests under Build, Execution, Deployment -> Build Tools -> Gradle. Sumatra makes use of Lombok. In order to detect generated code correctly you need to install the *Lombok Plugin*. -When you start Sumatra, "Run" one of the Gradle run configurations. -If you want to debug code, "Debug" Sumatra Debug afterwards. -If you "Debug" one of the other run configurations, the startup time will increase significantly, because -a new Gradle daemon is started and configuration takes longer. +## Getting Started in the UI -## Documentation -The documentation can be found in [doc](./doc). +The following steps should get you started: + +- Start Sumatra and make sure that in the menu Moduli -> sim.xml is selected +- Go to the "Ref" view and press "Force Start" (or press F4) +- Go to the "AutoReferee" view and select "Active" to enable the automatic referee ## Simulation -There is an internal simulator that can be used without any external dependencies. -Simply choose the "sim" config from the menu. -You can run AI against AI within one Sumatra instance. -After pressing the run button, you can use the "Ref" view in Sumatra to control the game. -You can also start the included autoRef from the "AutoRef" view. -Most configs can be found in the "config" view. +### Internal Simulator + +There is an internal simulator that can be used without any external dependencies. +Simply choose the "sim.xml" config from the moduli-menu. +It allows to run AI against AI within one Sumatra instance. + +### External Simulator + +The SSL-Simulation-Protocol is supported and was tested with [grSim](https://github.com/RoboCup-SSL/grSim) +and [ER-Force simulator](https://github.com/robotics-erlangen/framework#simulator-cli). -## Multiple Sumatra instances -If you want to run different AIs against each other, you can start a second instance of Sumatra and connect it to the first one. -On the second instance, you choose the "sim_remote" config. +To connect to an external simulator, choose one of the following moduli configs: + +- [simulation_protocol.xml](config/moduli/simulation_protocol.xml) + - for testing/development + - consumes ssl-vision messages from 224.5.23.2:10020 + - runs the ssl-game-controller internally and publishes messages on 224.5.23.1:11003 + - publishes vision tracking data on 224.5.23.2:11010 +- [simulation_match.xml](config/moduli/simulation_match.xml) + - for a virtual match + - consumes ssl-vision messages from 224.5.23.2:10006 + - listens for referee messages on 224.5.23.1:10003 + +You can change some of the configuration parameters in the respective XML files. +Further parameters can be changed either via CLI (`--help`) or in the Cfg view under "user". + +## Multiple Sumatra instances + +If you want to run different AIs against each other, you can start a second instance of Sumatra and connect it to the +first one. +On the second instance, you choose the "sim_remote" config. The configuration of this mode can be found under user -> sim. There, you can change the communication port and choose the team color that is controlled by the client. It is YELLOW by default. @@ -67,21 +86,16 @@ Make sure you disable the AIs that are not used by switching them to OFF in the The simulation can only be controlled from the server. The game-controller is also running on the server. You can use the autoRef on the server as well. The client only provides the AI including the skill system. -To simplify the setup, there is a docker-compose setup. It described [here](./modules/moduli-statistics-saver/Readme.md) -. +To simplify the setup, there is a docker-compose setup. It is +described [here](./modules/moduli-statistics-saver/Readme.md). + +## Further Documentation + +The documentation can be found in [doc](./doc). ## Known issues ### UI scaling -If the font size is too small (e.g. on high resolution screens), you can add following arguments to the command below. -16 is the font size and can be adapted. You can also choose other font types. - -```shell script -# Linux -export SUMATRA_OPTS="${SUMATRA_OPTS} -Dswing.plaf.metal.controlFont='sans-serif-16' -Dswing.plaf.metal.userFont='sans-serif-16'" -./run.sh -# Windows -set SUMATRA_OPTS="%SUMATRA_OPTS% -Dswing.plaf.metal.controlFont='sans-serif-16' -Dswing.plaf.metal.userFont='sans-serif-16'" -run.bat -``` +If the font size is too small (e.g. on high resolution screens), you can change the font size. +An example is given in [build.gradle](build.gradle). diff --git a/build.bat b/build.bat deleted file mode 100755 index 8a678a05..00000000 --- a/build.bat +++ /dev/null @@ -1,3 +0,0 @@ -ECHO OFF - -gradlew build diff --git a/build.gradle b/build.gradle index 1016d4f0..2446535d 100644 --- a/build.gradle +++ b/build.gradle @@ -69,6 +69,11 @@ dependencies { application { mainClass.set('edu.tigers.sumatra.Sumatra') + applicationDefaultJvmArgs = [ + // Change font (size): +// "-Dswing.plaf.metal.controlFont=sans-serif-16", +// "-Dswing.plaf.metal.userFont=sans-serif-16", + ] } jib { diff --git a/build.sh b/build.sh deleted file mode 100755 index 92b6c5a5..00000000 --- a/build.sh +++ /dev/null @@ -1,3 +0,0 @@ -#!/usr/bin/env bash - -./gradlew installDist diff --git a/run.bat b/run.bat deleted file mode 100755 index 41298497..00000000 --- a/run.bat +++ /dev/null @@ -1,11 +0,0 @@ -ECHO OFF - -set args=%* - -echo "Sumatra not installed, running with Gradle" -IF [%1] == [] ( - gradlew run -) ELSE ( - gradlew run --args="%args%" -) - diff --git a/run.sh b/run.sh deleted file mode 100755 index 1eb597b1..00000000 --- a/run.sh +++ /dev/null @@ -1,19 +0,0 @@ -#!/bin/bash - -# -# Copyright (c) 2009 - 2022, DHBW Mannheim - TIGERs Mannheim -# - -INSTALL_DIR=build/install/sumatra -ARGS="$@" - -if [[ -d "${INSTALL_DIR}" ]]; then - ${INSTALL_DIR}/bin/sumatra ${ARGS} -else - echo "Sumatra not installed, running with Gradle" - if [[ -n "${ARGS}" ]]; then - ./gradlew :run --args="${ARGS}" - else - ./gradlew :run - fi -fi