https://github.com/srobo/competition-simulator
A simulator for Student Robotics Virtual Competitions
https://github.com/srobo/competition-simulator
simulator webots
Last synced: 3 months ago
JSON representation
A simulator for Student Robotics Virtual Competitions
- Host: GitHub
- URL: https://github.com/srobo/competition-simulator
- Owner: srobo
- License: mit
- Created: 2020-04-29T17:58:50.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2024-02-04T13:55:56.000Z (over 2 years ago)
- Last Synced: 2024-02-04T15:10:39.949Z (over 2 years ago)
- Topics: simulator, webots
- Language: Python
- Homepage: https://studentrobotics.org/docs/simulator/
- Size: 4.83 MB
- Stars: 7
- Watchers: 22
- Forks: 2
- Open Issues: 28
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# competition-simulator
[](https://github.com/srobo/competition-simulator/actions?query=workflow%3A%22Simulator+tests%22)
[](https://github.com/srobo/competition-simulator/actions?query=workflow%3A%22Simulator+match%22)
A simulator to be used for the Student Robotics Virtual Competition
## Installation instructions
Take a look at [the docs](https://studentrobotics.org/docs/simulator/#installation).
## Overview
Within the IDE, there are a few different panels:
- In the centre of your screen is the 3D simulated view of the arena
- On the left is a tree hierarchy of all elements in this "world"
- At the bottom is your console
- At the top are your general controls which include the time controls. Press the centre play button to run the simulation at normal speed.
**Important:** Changes to the world must happen with the simulation paused at 0:00. If e.g. you move an object at a different time, rewinding back to the start will delete your changes.
On first run, the robot will execute an example program. On first run, this will be copied to the directory `competition-simulator` is stored in to make updating easier:
``` plain
.
├── competition-simulator
│ ├── controllers
│ │ ├── example_controller
│ │ └── sr_controller
│ ├── ...
│ └── worlds
└── robot.py
```
## Development
In addition to the basic setup for running the simulator, if you are intending
to work on our wrapper API, our controllers or other helper scripts then you
should also install the linting requirements:
``` shell
pip install -r script/linting/requirements.txt
pip install -r script/typing/requirements.txt
```
You can then run all linting/type checking/tests in one go using `script/check`.
### Running Webots
While the default location that our controllers look for `robot.py` files is the
directory above the repo, that is not particularly convenient for development.
Instead you may wish to run Webots having set the `ARENA_ROOT` environment
variable to a suitable location. This is also how `run-comp-match` configures
the arena to use when it runs matches.
For example, you may find it convenient to have a `robots` directory within the
repo and then have a number of code and arena directories within that:
```
robots
├── arena # A development arena with a single (symlinked) robot
│ └── robot.py -> ../ultrasounds/robot.py
├── brakes-arena # A competition style arena with two robots
│ ├── zone-0
│ │ └── robot.py
│ └── zone-1
│ └── robot.py
├── dancer # Some robot code for a robot which dances
│ └── robot.py
├── single-arena # A competition style arena with a single (symlinked) robot
│ └── zone-0 -> ../dancer/
└── ultrasounds # Some robot code for testing ultrasound sensors
└── robot.py
```
Given a setup like the above, running Webots such that it picks up on one of the
arena directories is possible through setting the `ARENA_ROOT` to an absolute
path when launching the webots process:
```
$ ARENA_ROOT=$PWD/robots/brakes-arena webots --mode=pause worlds/Arena.wbt
```
This will launch Webots using our world file, with the simulation paused and the
controllers (when started) will use the robots within `brakes-arena`.
Note: `webots` has a number of useful command line flags which are quite useful.
We won't document them here, though you are encouraged to run `webots --help` to
explore them yourself.
### Competition Mode
In Competition Mode the simulation behaves slightly differently:
- the simulation exits after the game completes
- an animation recording is made of the simulation
- a video recording is made of the simulation
If a match is being run, then the log of score-impacting events is also output
into the match file.
Competition mode is enabled when a `robot_mode.txt` marker file is found in the
arena directory and that file contains only the text `comp`:
``` bash
echo comp > robot_mode.txt
```
The match file is a separate `match.json` file, also in the arena directory.
This file conforms to the [Proton](https://github.com/PeterJCLaw/proton) spec
and is used to enable integration with [SRComp][srcomp]. Primarily this file
captures score-relevant data for SRComp, however it also supports some other
keys which are useful in development. See the `MatchData` structure for details.
During an actual competition, matches will be run using the `run-comp-match`
script, which is documented below. Note however that it consumes robot code from
a Zip archive rather than a directory. Suitable archives contain a `robot.py` at
their root and thus can be created (for some team `ABC`) using:
```
zip ABC.zip robot.py
```
[srcomp]: https://github.com/PeterJCLaw/srcomp/wiki
## Doing a release
0. Merge all the desired changes into `main` and push
1. Let CI run, ensure it passes
2. Create an annotated tag:
``` console
git tag srYYYY.N --annotate
```
N is a 1-based number for the revision of the rules. `0` is reserved for a
release before the start of the competition year, if there is one. `1` should
ideally be the initial release containing the game for the given year.
Greater numbers correspond to revisions during the year.
The tag annotation message should contain a summary of the changes in the
revision, typically this can be similar to the revision log within the
document itself. See the previous tags for the common format, for example
`git show sr2024.0` or `git show sr2023.5`.
3. Push the tag: `git push --tags`
4. Wait for CI to create the GitHub release, build a zip archive and upload it to the release
5. Update the [docs](https://github.com/srobo/docs) to point to the new archive
6. Announce the update to teams via Discord and [email](https://github.com/srobo/team-emails)
## Running competition matches
In order to run competition matches you'll need to:
1. Install the third party libraries the teams are depending on, into the same
Python environment as will be running their code:
``` bash
pip install -r libraries.txt
```
Note: you can change the version of Python which Webots uses from the UI --
go to "Tools" > "Preferences" > "General" > "Python command".
We are using Python 3.8, though it shouldn't matter whether it's a system
install or a virtual environment.
2. Launch webots and configure it for recordings:
- close the robot-camera overlays which appear on top of the main view
- in "Tools" > "Preferences" > "OpenGL" set:
- Ambient Occlusion to Disabled,
- Texture Quality to High,
- Disable shadows to false, and
- Disable anti-aliasing to false
Then close webots.
3. Run the match:
```bash
competition-simulator/script/run-comp-match
```
Note: use a dash instead of a TLA if a robot is not present.
This will orchestrate everything to run the match, including running webots
and collecting together the logs and recordings. The logs & recordings will
be within the directory which contains the team code, as follows:
- The teams' logs will be in a directory named for their TLA
- The match file (suitable for SRComp) will be within a `matches` directory
- The recordings will be within a `recordings` directory
Note: you may see an error like the following regarding the video creation:
``` plain
[libx264 @ 0x562cf1ba9840] Error: 2pass curve failed to converge
[libx264 @ 0x562cf1ba9840] target: 20250.00 kbit/s, expected: 3339.51 kbit/s, avg QP: 0.0252
[libx264 @ 0x562cf1ba9840] try reducing target bitrate
```
This warns that we have requested a higher bit-rate from the video than is
possible given the images the simulation generates. It does not appear to
create any issues with the rendered videos, though you are encouraged to
check that your setup is recording the videos correctly.
If `webots` is not available on `PATH` (such as on Windows by default) you can
pass the full path to the webots executable using the `WEBOTS_EXECUTABLE`
environment variable.
## Collecting up logs for the Discord bot
The `zip-comp-logs` command allows logs to be collated into a zip with certain combinations of match animations.
To create the zip file used by the discord bot to distribute the logs use the command:
```bash
./script/zip-comp-logs --with-combined--animations all [--suffix= ]
```
Once the the zip files have been generated the zip file beginning "combined" can be used with the [discord bot](https://github.com/WillB97/discord-logs-uploader).