{"id":47842309,"url":"https://github.com/srobo/competition-simulator","last_synced_at":"2026-04-03T21:01:11.461Z","repository":{"id":46118741,"uuid":"260002173","full_name":"srobo/competition-simulator","owner":"srobo","description":"A simulator for Student Robotics Virtual Competitions","archived":false,"fork":false,"pushed_at":"2024-02-04T13:55:56.000Z","size":5063,"stargazers_count":7,"open_issues_count":28,"forks_count":2,"subscribers_count":22,"default_branch":"main","last_synced_at":"2024-02-04T15:10:39.949Z","etag":null,"topics":["simulator","webots"],"latest_commit_sha":null,"homepage":"https://studentrobotics.org/docs/simulator/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/srobo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-04-29T17:58:50.000Z","updated_at":"2024-01-09T08:34:52.000Z","dependencies_parsed_at":"2023-09-26T23:24:57.698Z","dependency_job_id":"4e158b41-338c-4929-857f-6b338f62ae22","html_url":"https://github.com/srobo/competition-simulator","commit_stats":null,"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"purl":"pkg:github/srobo/competition-simulator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srobo%2Fcompetition-simulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srobo%2Fcompetition-simulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srobo%2Fcompetition-simulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srobo%2Fcompetition-simulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/srobo","download_url":"https://codeload.github.com/srobo/competition-simulator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srobo%2Fcompetition-simulator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31377084,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["simulator","webots"],"created_at":"2026-04-03T21:01:04.116Z","updated_at":"2026-04-03T21:01:11.455Z","avatar_url":"https://github.com/srobo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# competition-simulator\n\n[![Github Actions](https://github.com/srobo/competition-simulator/workflows/Simulator%20tests/badge.svg)](https://github.com/srobo/competition-simulator/actions?query=workflow%3A%22Simulator+tests%22)\n[![Github Actions](https://github.com/srobo/competition-simulator/workflows/Simulator%20match/badge.svg)](https://github.com/srobo/competition-simulator/actions?query=workflow%3A%22Simulator+match%22)\n\nA simulator to be used for the Student Robotics Virtual Competition\n\n## Installation instructions\n\nTake a look at [the docs](https://studentrobotics.org/docs/simulator/#installation).\n\n## Overview\n\nWithin the IDE, there are a few different panels:\n\n- In the centre of your screen is the 3D simulated view of the arena\n- On the left is a tree hierarchy of all elements in this \"world\"\n- At the bottom is your console\n- At the top are your general controls which include the time controls. Press the centre play button to run the simulation at normal speed.\n\n**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.\n\nOn 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:\n\n``` plain\n.\n├── competition-simulator\n│   ├── controllers\n│   │   ├── example_controller\n│   │   └── sr_controller\n│   ├── ...\n│   └── worlds\n└── robot.py\n```\n\n## Development\n\nIn addition to the basic setup for running the simulator, if you are intending\nto work on our wrapper API, our controllers or other helper scripts then you\nshould also install the linting requirements:\n\n``` shell\npip install -r script/linting/requirements.txt\npip install -r script/typing/requirements.txt\n```\n\nYou can then run all linting/type checking/tests in one go using `script/check`.\n\n### Running Webots\n\nWhile the default location that our controllers look for `robot.py` files is the\ndirectory above the repo, that is not particularly convenient for development.\nInstead you may wish to run Webots having set the `ARENA_ROOT` environment\nvariable to a suitable location. This is also how `run-comp-match` configures\nthe arena to use when it runs matches.\n\nFor example, you may find it convenient to have a `robots` directory within the\nrepo and then have a number of code and arena directories within that:\n\n```\nrobots\n├── arena  # A development arena with a single (symlinked) robot\n│   └── robot.py -\u003e ../ultrasounds/robot.py\n├── brakes-arena  # A competition style arena with two robots\n│   ├── zone-0\n│   │   └── robot.py\n│   └── zone-1\n│       └── robot.py\n├── dancer  # Some robot code for a robot which dances\n│   └── robot.py\n├── single-arena  # A competition style arena with a single (symlinked) robot\n│   └── zone-0 -\u003e ../dancer/\n└── ultrasounds  # Some robot code for testing ultrasound sensors\n    └── robot.py\n```\n\nGiven a setup like the above, running Webots such that it picks up on one of the\narena directories is possible through setting the `ARENA_ROOT` to an absolute\npath when launching the webots process:\n\n```\n$ ARENA_ROOT=$PWD/robots/brakes-arena webots --mode=pause worlds/Arena.wbt\n```\n\nThis will launch Webots using our world file, with the simulation paused and the\ncontrollers (when started) will use the robots within `brakes-arena`.\n\nNote: `webots` has a number of useful command line flags which are quite useful.\nWe won't document them here, though you are encouraged to run `webots --help` to\nexplore them yourself.\n\n### Competition Mode\n\nIn Competition Mode the simulation behaves slightly differently:\n- the simulation exits after the game completes\n- an animation recording is made of the simulation\n- a video recording is made of the simulation\n\nIf a match is being run, then the log of score-impacting events is also output\ninto the match file.\n\nCompetition mode is enabled when a `robot_mode.txt` marker file is found in the\narena directory and that file contains only the text `comp`:\n\n``` bash\necho comp \u003e robot_mode.txt\n```\n\nThe match file is a separate `match.json` file, also in the arena directory.\nThis file conforms to the [Proton](https://github.com/PeterJCLaw/proton) spec\nand is used to enable integration with [SRComp][srcomp]. Primarily this file\ncaptures score-relevant data for SRComp, however it also supports some other\nkeys which are useful in development. See the `MatchData` structure for details.\n\nDuring an actual competition, matches will be run using the `run-comp-match`\nscript, which is documented below. Note however that it consumes robot code from\na Zip archive rather than a directory. Suitable archives contain a `robot.py` at\ntheir root and thus can be created (for some team `ABC`) using:\n\n```\nzip ABC.zip robot.py\n```\n\n[srcomp]: https://github.com/PeterJCLaw/srcomp/wiki\n\n## Doing a release\n\n0. Merge all the desired changes into `main` and push\n1. Let CI run, ensure it passes\n2. Create an annotated tag:\n\n   ``` console\n   git tag srYYYY.N --annotate\n   ```\n\n   N is a 1-based number for the revision of the rules. `0` is reserved for a\n   release before the start of the competition year, if there is one. `1` should\n   ideally be the initial release containing the game for the given year.\n   Greater numbers correspond to revisions during the year.\n\n   The tag annotation message should contain a summary of the changes in the\n   revision, typically this can be similar to the revision log within the\n   document itself. See the previous tags for the common format, for example\n   `git show sr2024.0` or `git show sr2023.5`.\n\n3. Push the tag: `git push --tags`\n4. Wait for CI to create the GitHub release, build a zip archive and upload it to the release\n5. Update the [docs](https://github.com/srobo/docs) to point to the new archive\n6. Announce the update to teams via Discord and [email](https://github.com/srobo/team-emails)\n\n## Running competition matches\n\nIn order to run competition matches you'll need to:\n\n1. Install the third party libraries the teams are depending on, into the same\n   Python environment as will be running their code:\n\n    ``` bash\n    pip install -r libraries.txt\n    ```\n\n   Note: you can change the version of Python which Webots uses from the UI --\n   go to \"Tools\" \u003e \"Preferences\" \u003e \"General\" \u003e \"Python command\".\n\n   We are using Python 3.8, though it shouldn't matter whether it's a system\n   install or a virtual environment.\n\n2. Launch webots and configure it for recordings:\n\n    - close the robot-camera overlays which appear on top of the main view\n\n    - in \"Tools\" \u003e \"Preferences\" \u003e \"OpenGL\" set:\n\n        - Ambient Occlusion to Disabled,\n        - Texture Quality to High,\n        - Disable shadows to false, and\n        - Disable anti-aliasing to false\n\n   Then close webots.\n\n3. Run the match:\n\n    ```bash\n    competition-simulator/script/run-comp-match \u003cdirectory containing team code\u003e \u003cmatch number\u003e \u003cZone 0 TLA\u003e \u003cZone 1 TLA\u003e\n    ```\n\n    Note: use a dash instead of a TLA if a robot is not present.\n\n    This will orchestrate everything to run the match, including running webots\n    and collecting together the logs and recordings. The logs \u0026 recordings will\n    be within the directory which contains the team code, as follows:\n    - The teams' logs will be in a directory named for their TLA\n    - The match file (suitable for SRComp) will be within a `matches` directory\n    - The recordings will be within a `recordings` directory\n\n    Note: you may see an error like the following regarding the video creation:\n    ``` plain\n    [libx264 @ 0x562cf1ba9840] Error: 2pass curve failed to converge\n    [libx264 @ 0x562cf1ba9840] target: 20250.00 kbit/s, expected: 3339.51 kbit/s, avg QP: 0.0252\n    [libx264 @ 0x562cf1ba9840] try reducing target bitrate\n    ```\n    This warns that we have requested a higher bit-rate from the video than is\n    possible given the images the simulation generates. It does not appear to\n    create any issues with the rendered videos, though you are encouraged to\n    check that your setup is recording the videos correctly.\n\nIf `webots` is not available on `PATH` (such as on Windows by default) you can\npass the full path to the webots executable using the `WEBOTS_EXECUTABLE`\nenvironment variable.\n\n## Collecting up logs for the Discord bot\n\nThe `zip-comp-logs` command allows logs to be collated into a zip with certain combinations of match animations.\nTo create the zip file used by the discord bot to distribute the logs use the command:\n\n```bash\n./script/zip-comp-logs \u003carchive-folder\u003e \u003coutput-folder\u003e --with-combined--animations all [--suffix=\u003czip-name-suffix\u003e ]\n```\nOnce 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).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrobo%2Fcompetition-simulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsrobo%2Fcompetition-simulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrobo%2Fcompetition-simulator/lists"}