Building your own race-player

The process of (re-)playing a race is (deliberately) separate from the race server (although there’s a built-in race player, you can use your own if your prefer). This page describes how to go about creating your own. It probably should run in a browser (e.g., a JavaScript or WASM application), because that’s how your students are likely to be accessing it.

“Player” versus “runner”:
Remember the race player is the software you use to replay a race-file that has events and results that were generated by a race runner, which is a standalone application that calculates the outcome (events and results) of a race.

This page is incomplete, and is currently being written! (6-Dec-2023)

Summary: inputs/process/output

Inputs

There are effectively three inputs for the race player:

• race file
  The race file should contain the results (per buggy) and the events of the race (you can assume that the events describe a race that yields the results that are described within it). The race player is primarily concerned with displaying those events (presumably as an animation of the race as it progresses).

• racetrack background image URL
  This is a cosmetic depiction of the racetrack as a 2:1 (landscape) aspect ratio image (typically JPEG).

• racetrack path SVG path URL
  This describes the racetrack as an SVG path. If overlayed on the background image, the path describes the route followed by buggies driving along the racetrack. Racetrack paths must always be loops.

If you are also building your own race-runner then you can put anything you want in the race file for your customn race-player to consume. You need to keep the parts that the race-server uses intact (the buggies’ position for example is used when uploading results), but any new fields will be ignored. The server does not inspect anything in the events object.

Process

The race player should display the progress of a race — the built-in one uses animation applied to SVG elements to do this, and supports pausing, tracking (highlighting) individual buggies, speeding up (in case the race gets slow due to everyone running on punctured tyres, and so on).

Output

The race player doesn’t provide any output — only the display. The results don’t need to be displayed either, because those are already tabulated on the race server (although if you want to add a results display too… feel free).

Alternatives to a programmed race-player

The race-player is really just displaying, in animated form, a replay of the race. An extreme customisation of the race-runner could result in these replays being in other formats entirely, such as video — in which case you don’t need to implement a race-player like this at all. That’s a significant customisation to do, but is mentioned here so you can appreciate that the way the default race-player is implemented isn’t necessarily the only approach to take.