#ossl

The OSSL Heartbeat System: Problem: There is often the need for object scripts to act at regular time intervals in order to provide periodic action to provide stimulus for agents and other object scripts.  However, the timer facility provided by LSL/OSSL has proven to be an inefficient solution to this problem. This has led to a scenario wherein creating content which requires timer-based periodic action is discouraged, thereby preventing the easy development of immersive interactive simulations.   Observations:

Simulations which exclusively react to explicit user interaction feel less immersive than ones in which actions occur proactively.

Many object scripts using the timer event don't need a precise timer, rather they need a simple and reliable system for repeated script triggering.

Many game systems implement repeated script action with a periodic world heartbeat event.

A heartbeat system can be derived from the simulation frame system, and provide a low-overhead solution to periodic script stimulus.

Solution: Economize the time-keeping functionality to provide a scalable system for proactive action.  Rather than requiring scripts to request a repeating timer event, the simulator emits a periodic "heartbeat" event.  If a script has subscribed to this heartbeat event, they will recieve the event via a dataserver event.  The heartrate can be configured in two ways by the simulator. It can be derived via a set frame increment (once every x simulator frames). Alternatively, a target heart rate can be set, and the simulator will dynamically adjust the frame increment to attempt to match the target.  The OSSL API provides facilities for determining the current and target heartrates.   Proposed API Definition: key osHeartbeatListen()     Sets up a listener for the region's heartbeat.  When the heartbeat is emmited, the script will recieve a dataserver event with a key matching the returned key. The returned message will be the current heartbeat count. void osHeartbeatUnlisten()     Unsuscribes the script from the region's heartbeat. float osGetHeartbeatInterval()     Returns a float of the average interval in seconds between heartbeats.  This allows a script to dynamically adjust its behavior to match the simulator's heartbeart. float osGetTargetInterval()     Returns the target heartbeat interval for the region (in seconds).  If there is no target (i.e. there's a static frame increment), the returned value will be zero. Additional Notes:

The proposed API has been kept intentionally short and as stateless as possible.  There is a temptation to add more commands, but until these prove to be useful the API should remain small.

In order to facilitate the target heartrate and frame increment functions, there will need to be additions to the config files.  Allowing these values to be settable via script seems inadvisable at this stage.

An added benefit of a heartbeat system is that it can facilitate synchronized object behavior without relying on time-sensitive message passing or knowledge of all participating objects.  This is behavior which would be more difficult to implement using existing LSL/OSSL commands.