Introduction
The racing system allows races between non-NPC avatars (herein called agents to distinguish them from NPCs), NPCs and/or vehicles. It comprises a single starting gate, any number of waypoints (one of which serves as a finish gate) and any number of scoreboards.
Only one racing system should exist in a region at one time; there is no mechanism to prevent cross-talk between multiple systems.
The system utilises sensors, collisions or a combination of both to detect agents, NPCs and vehicles. It is possible to have different detection methods (and sensor ranges) between different components of a race.
Usage
To start the race, the entrants should congregate on or near the start gate (depending on detection type) until all their names have appeared on the scoreboard. When ready, the "start" sign (see below) can be clicked for the race to commence - there is a countdown before the race, with the traffic lights showing a red-to-green cycle.
Contestants should visit each of the waypoints in turn before arriving at the finish line (although the finish gate may be the only waypoint). On arrival at the finish gate, the names of each entrant is displayed together with the time in seconds they took to complete the race. When all entrants have arrived at the finish gate, the race is reset and after a pause, the next race may commence.
If a contestant moves significantly (>1m) during the countdown, the counting is reset.
If a contestant is in a vehicle (in a race that includes vehicles) and stands up during the countdown, they are disqualified. Likewise, if a contestant is standing and sits down, they are disqualified.
If a contestant leaves the region or logs out, they are removed from the race.
If all contestants are removed from a race, the race finishes with no winners.
If a contestant fails to complete the course but doesn't leave the region or log out (for example, they become stuck), the race will finish without them after a timeout (specified by the TimeOut configuration parameter).
Construction
For collision detection to work, the start gate and waypoint scripts need to be in either the root prim of a linkset, or in the prim that receives the collisions. In the former case, child prims that receive collisions should have llPassCollisions(TRUE) set.
If is possible to have several prims in a linkset containing waypoint scripts, in effect providing a series of linked waypoints. It is also theoretically possible to include the scoreboards and the start script in this manner - scoreboards are almost certain to work, but the start gate should be tested in this setup.
The scoreboard script needs to be in the board prim itself (on account of the lack of linked prim-drawing capabilities in OpenSim), which should have square face(s) visible to display the information (if the face(s) are not square, the text will be distorted in appearance).
The start gate may have the following named prims (* = mandatory):
start*: a sign which may be clicked to start the race
red*, amber*, green*: traffic light prims
reset: a special prim that the owner may click to reset the system in the event of failure
The start gate prim should contain a sound file which will be played during the countdown phase.
The names of waypoint prims/objects are significant. The sequence of the waypoints is determined by the sort order of the names of the waypoints, and the last (highest-named) is the finish line. The names of other objects are not significant.
Design
The start gate acts as a controlling server, with the waypoint and scoreboard objects as peripheral items. The waypoints send messages to the start gate when a contestant is detected, and the server sends messages to the scoreboard with the data that needs to be displayed. The centralised model was chosen to minimise the possibility of handshaking failure.
Communications
The system makes use of osMessageObject() where possible in order to reduce the dependence on listeners. The waypoint and scoreboard scripts output regular signals on a hidden chat channel to identify themselves. When first loaded or reset, the start gate listens for a period (specified by ListenTime in the configuration) and records the UUIDs of waypoints and scoreboards that send out signals during that time. Then the listener is shut down and the start gate is ready for the first race.
It would be possible to change the script so that the start gate continues listening so that it will detect waypoints/scoreboards added to the scene later. Perhaps this should be considered. -- J
Types of object-to-object message
On chat channel -8300371400, picked up by the start gate:
"+" is sent periodically by waypoints
"S" is sent periodically by scoreboards
Using osMessageObject():
Waypoints receive messages from start gate of the format "@<s1>,<s2>,<s3> , where <s1>, <s2> and <s3> are the "Allow" booleans (see Configuration)
Waypoints also receive the message "c" to indicate that they should clear their cache of known detected objects/avatars at the start of a race
Scoreboards receive the following commands: "DC" to clear screen; "DR" to reset the displayed data; "DH" to set the display title; "DL<x>,<s>" to display string <s> on line <x> of the display body text (there are 10 lines).
Messages about the setup, progress and outcome of the race are sent to all avatars in the region via llRegionSayTo(). This means that there is no need for an audience to be especially close to any object to be kept informed.
Configuration
The start gate and waypoint objects may be configured via notecards in the scripted prims' contents. Notecards are of INI-file layout ("x = y" on each line) and may contain comments beginning with "//".
Start gates and waypoints have the following parameters:
SensorRange The radius of search of the sensor, or 0 to turn the sensor off
UseCollisions (True/False) Use collisions
In addition, start gates have these parameters:
AllowAgents (True/False) Non-NPC avatars can take part in the race
AllowNPCs (True/False) NPC avatars can take part in the race
AllowVehicles (True/False) Vehicles can take part in the race
TimeOut Period (seconds) before race resets when abandoned
ListenTime Period (seconds) during boot that start gate listens for peripheral objects
Note that that the Allow* parameters are passed from the start gate to the other gates automatically, since the values must be consistent.