Script API updates

Updated: February 1, 2018

Detailed summary

  • New Unsubscribe pattern for all event subscriptions
    • All Subscribe methods now return an object that implements IEventSubscription with an Unsubscribe() method and an Active property.
    • Timers have been updated to use this as well, named Timers are deprecated.
  • New "SimpleScript" base class to offer a quicker start for simple script writing
    • This class offers methods to be overriden for common subscriptions and takes care of the subscriptions for you.
    • All events are run in a co-routine to support Wait and WaitFor.
    • Attributes can be used to change the behavior of the subscriptions or to register new events.
    • See SimpleScriptExample.cs for a more complete example
A Simple Greeter Example
public class SimpleExample : SimpleScript
{
	// This event occurs when a user enters the scene
	protected override void OnAddUser(AgentPrivate agent)
	{
    		agent.SendChat($"Welcome to the {ScenePrivate.SceneInfo.ExperienceName} scene!");
	}
}
  • New Audio API calls for playing a stream.
    • Enum “StreamChannel” corresponds to streams set up in Scene Settings.
      • MediaChannel
      • AudioChannel1, AudioChannel2, AudioChannel3, AudioChannel4
    • Agent:
      • PlayStream(StreamChannel streamChannel)
      • PlayStreamAtPosition(StreamChannel streamChannel, float loudness)
      • PlayStreamOnComponent(StreamChannel streamChannel, AudioComponent* audioComponent, float loudness)
    • Scene:
      • PlayStream(StreamChannel streamChannel)
      • PlayStreamAtPosition(StreamChannel streamChannel, float loudness)
    • Component:
      • PlayStreamOnComponent(StreamChannel streamChannel, float loudness)
  • New Run argument in WaitFor will run code after the subscribe but before the wait to close some race conditions when using coroutines and cross script events.
Example
// It is possible for a script to respond to the "Message" event before the WaitFor, in which case the response could be lost.
PostScriptEvent("Message");
WaitFor(SubscribeToScriptEvent, "Response");

// Instead this is guaranteed to do PostScriptEvent after being set up to receive the response.
WaitFor(SubscribeToScriptEvent, "Response", () => { PostScriptEvent("Message") });
  • New limits on number of pending events on a script to prevent memory blowout
    • Use PendingEventCount to get number of pending events.
    • Events queued when there are already 256 pending events will be discarded
  • Coroutine operations (start/wait) always apply to active script to work better in cross script cases.
  • Removed "AllChannels" option for chat subscriptions. Scripts that were set to listen on all channels will now listen on the default 0 channel.
  • Fixed script stub dlls to not crash and created examples.csproj file for the example scripts, which is set up to use the stub dlls.
  • Fixed broken hyperlinks on script API help index.
  • More consistent behavior of user join/leave events in scripts.
  • Some optimizations to script memory tracking performance.

 

Documentation Updates

New Documentation

Updated Documentation

Was this article helpful?
1 out of 1 found this helpful
Have more questions? Submit a request

0 Comments

Article is closed for comments.