SceneObjectScript

SceneObjectScript Class

Extend SceneObjectScript to create a script that can be used on content that is natively in the scene. This is the primary script type in Sansar.

Syntax

[Sansar.Script.Interface]
public abstract class SceneObjectScript : Sansar.Script.ScriptBase

Remarks

Override Sansar.Script.ScriptBase.Init() for script initialization, primarily event subscriptions.

Use SceneObjectScript.ObjectPrivate to access the Object the script is on.

Use SceneObjectScript.ScenePrivate to access the Scene the object is in.

C# Example
/* This content is licensed under the terms of the Creative Commons Attribution 4.0 International License.
 * When using this content, you must:
 * •    Acknowledge that the content is from the Sansar Knowledge Base.
 * •    Include our copyright notice: "© 2017 Linden Research, Inc."
 * •    Indicate that the content is licensed under the Creative Commons Attribution-Share Alike 4.0 International License.
 * •    Include the URL for, or link to, the license summary at https://creativecommons.org/licenses/by-sa/4.0/deed.hi (and, if possible, to the complete license terms at https://creativecommons.org/licenses/by-sa/4.0/legalcode.
 * For example:
 * "This work uses content from the Sansar Knowledge Base. © 2017 Linden Research, Inc. Licensed under the Creative Commons Attribution 4.0 International License (license summary available at https://creativecommons.org/licenses/by/4.0/ and complete license terms available at https://creativecommons.org/licenses/by/4.0/legalcode)."
 */

/* Start a coroutine to wait for collision events.
 * Which types of collisions are handled may be set on the properties panel for
 * the object when editing the scene.
 */
using Sansar.Simulation;
using System;

// To get full access to the Object API a script must extend from ObjectScript
public class ObjectScriptExample : SceneObjectScript
{
    // Components can be set in the editor if the correct component types are added to the object
    public RigidBodyComponent RigidBody = null;
    public bool TrackAgentHits = true;
    public bool TrackObjectHits = true;

    // while ChatEvents.MessageAllUsers doesn't work
    private void MessageAllUsers(string message)
    {
        foreach (var agentpublic in ScenePrivate.GetAgents())
        {
            // Use a Try to catch the race condition of someone leaving while sending them the message.
            try
            {
                agentpublic.SendChat(message);
            }
            catch (Exception) { }
        }
    }

    public ObjectScriptExample()
    {
        // Script initialization order:
        //    Constructor (this method)
        //    Set base class members (ObjectScript's ExperienceInfo, SceneInfo, and ObjectPrivate)
        //    Set public fields that were configured at edit time (RigidBody, TrackAgentHist, TrackObjectHits)
        //    Init()
    }

    // Override Init to set up event handlers and start coroutines.
    public override void Init()
    {
        // When unhandled exceptions occur, they may be caught with this event handler.
        // Certain exceptions may not be recoverable at all and may cause the script to
        // immediately be removed.
        Script.UnhandledException += UnhandledException;

        // If the object had its components set in the editor they should now have the member initialized
        // The component can also be found dynamically
        if (RigidBody == null)
        {
            if(!ObjectPrivate.TryGetFirstComponent(out RigidBody))
            {
                // Since object scripts are initialized when the scene loads, no one will actually see this message.
                MessageAllUsers("There is no RigidBodyComponent attached to this object.");
                return;
            }
        }

        // Convert the supplied bools to the correct CollisionEventType to track
        CollisionEventType trackedEvents = 0;
        if (TrackAgentHits)
        {
            trackedEvents |= CollisionEventType.cCharacterContact;
        }
        if (TrackObjectHits)
        {
            trackedEvents |= CollisionEventType.cRigidBodyContact;
        }

        // StartCoroutine will queue CheckForCollisions to run
        // Arguments after the coroutine method are passed as arguments to the method.
        StartCoroutine(CheckForCollisions, trackedEvents);
    }

    private void CheckForCollisions(CollisionEventType trackedEvents)
    {
        while (true)
        {
            // This will block the coroutine until a collision happens
            CollisionData data = (CollisionData)WaitFor(RigidBody.Subscribe, trackedEvents, Sansar.Script.ComponentId.Invalid);
            if(data.EventType == CollisionEventType.cCharacterContact)
            {
                MessageAllUsers("I hit an avatar!");
            }
            else
            {
                MessageAllUsers("I hit an object!");
            }
        }
    }
    
    private void UnhandledException(object sender, Exception e)
    {
        // Depending on the script scheduling policy, the exception may or may not be recoverable.
        // An unrecoverable exception that can be handled will only be given a short time to run
        // so the handler method needs to be kept small.
        // Any exception thrown from this method will terminate the script regardless of the value
        // of UnhandledExceptionRecoverable
        if (!Script.UnhandledExceptionRecoverable)
        {
            MessageAllUsers("Unrecoverable exception happened, the script will now be removed.");
        }
        else
        {
            MessageAllUsers("This script will be allowed to continue.");
        }
    }
}

Requirements

Namespace: Sansar.Simulation
Assembly: Sansar.Simulation (in Sansar.Simulation.dll)
Assembly Versions: 1.1.0.0

Members

See Also: Inherited members from Sansar.Script.ScriptBase.

Protected Constructors

  This constructor is called before any properties have been set. Override Sansar.Script.ScriptBase.Init() to initialize the script after properties have been set.

Public Properties

  Log Sansar.Script.Log . Gets the script console. (Inherited from Sansar.Script.ScriptBase.)
  Memory Sansar.Script.Memory . Memory information for the pool this script is in. (Inherited from Sansar.Script.ScriptBase.)
  ObjectPrivate ObjectPrivate . The ObjectPrivate this script is attached to if it is attached to an object.
  ScenePrivate ScenePrivate . The Scene API for the Scene this script is a part of if the script is attached to scene content.
  Script Sansar.Script.ScriptHandle . Script handle to this script. (Inherited from Sansar.Script.ScriptBase.)

Public Methods

abstract
Init ()
Init() is called after all interfaces have been initialized. (Inherited from Sansar.Script.ScriptBase.)

Protected Methods

  StartCoroutine (Action)
Starts a coroutine on the current script. (Inherited from Sansar.Script.ScriptBase.)
  StartCoroutine<T> (Action<T>T)
Starts a coroutine on the current script. (Inherited from Sansar.Script.ScriptBase.)
  StartCoroutine<T,T1> (Action<T, T1>TT1)
Starts a coroutine on the current script. (Inherited from Sansar.Script.ScriptBase.)
  StartCoroutine<T,T1,T2> (Action<T, T1, T2>TT1T2)
Starts a coroutine on the current script. (Inherited from Sansar.Script.ScriptBase.)
  StartCoroutine<T,T1,T2,T3> (Action<T, T1, T2, T3>TT1T2T3)
Starts a coroutine on the current script. (Inherited from Sansar.Script.ScriptBase.)
  Terminate (string)
Terminates this script immediately. (Inherited from Sansar.Script.ScriptBase.)
  Wait (TimeSpan)
Delays execution of the current coroutine for the specified time. (Inherited from Sansar.Script.ScriptBase.)
  WaitFor (Action<Action<Sansar.Script.EventData>,System.Boolean>) : Sansar.Script.EventData
Use in a coroutine to pause the script until an event happens. (Inherited from Sansar.Script.ScriptBase.)
  WaitFor<ARG1> (Action<ARG1, Action<Sansar.Script.EventData>,System.Boolean>ARG1) : Sansar.Script.EventData
Use in a coroutine to pause the script until an event happens. (Inherited from Sansar.Script.ScriptBase.)
  WaitFor<T1> (Func<T1, Action<Sansar.Script.OperationCompleteEvent>,System.UInt64>T1) : Sansar.Script.OperationCompleteEvent
Use in a coroutine to pause the script until an event happens. (Inherited from Sansar.Script.ScriptBase.)
  WaitFor<ARG1,ARG2> (Action<ARG1, ARG2, Action<Sansar.Script.EventData>,System.Boolean>ARG1ARG2) : Sansar.Script.EventData
Use in a coroutine to pause the script until an event happens. (Inherited from Sansar.Script.ScriptBase.)
  WaitFor<T1,T2> (Func<T1, T2, Action<Sansar.Script.OperationCompleteEvent>,System.UInt64>T1T2) : Sansar.Script.OperationCompleteEvent
Use in a coroutine to pause the script until an event happens. (Inherited from Sansar.Script.ScriptBase.)
  WaitFor<ARG1,ARG2,ARG3> (Action<ARG1, ARG2, ARG3, Action<Sansar.Script.EventData>,System.Boolean>ARG1ARG2ARG3) : Sansar.Script.EventData
Use in a coroutine to pause the script until an event happens. (Inherited from Sansar.Script.ScriptBase.)
  WaitFor<T1,T2,T3> (Func<T1, T2, T3, Action<Sansar.Script.OperationCompleteEvent>,System.UInt64>T1T2T3) : Sansar.Script.OperationCompleteEvent
Use in a coroutine to pause the script until an event happens. (Inherited from Sansar.Script.ScriptBase.)
  WaitFor<ARG1,ARG2,ARG3,ARG4> (Action<ARG1, ARG2, ARG3, ARG4, Action<Sansar.Script.EventData>,System.Boolean>ARG1ARG2ARG3ARG4) : Sansar.Script.EventData
Use in a coroutine to pause the script until an event happens. (Inherited from Sansar.Script.ScriptBase.)
  WaitFor<T1,T2,T3,T4> (Func<T1, T2, T3, T4, Action<Sansar.Script.OperationCompleteEvent>,System.UInt64>T1T2T3T4) : Sansar.Script.OperationCompleteEvent
Use in a coroutine to pause the script until an event happens. (Inherited from Sansar.Script.ScriptBase.)
  WaitFor<ARG1,ARG2,ARG3,ARG4,ARG5> (Action<ARG1, ARG2, ARG3, ARG4, ARG5, Action<Sansar.Script.EventData>,System.Boolean>ARG1ARG2ARG3ARG4ARG5) : Sansar.Script.EventData
Use in a coroutine to pause the script until an event happens. (Inherited from Sansar.Script.ScriptBase.)

Member Details

SceneObjectScript Constructor

This constructor is called before any properties have been set. Override Sansar.Script.ScriptBase.Init() to initialize the script after properties have been set.

Syntax

[Sansar.Script.Interface]
protected SceneObjectScript ()

Remarks

 

Requirements

Namespace: Sansar.Simulation
Assembly: Sansar.Simulation (in Sansar.Simulation.dll)
Assembly Versions: 1.1.0.0

ObjectPrivate Property

The ObjectPrivate this script is attached to if it is attached to an object.

Syntax

[get: Sansar.Script.Interface]
public ObjectPrivate ObjectPrivate { protected get; set; }

Value

The scene object this script is attached to if it is attached to an object, null otherwise.

Remarks

For AgentScripts this is the Agent's ObjectPrivate of their avatar.

Requirements

Namespace: Sansar.Simulation
Assembly: Sansar.Simulation (in Sansar.Simulation.dll)
Assembly Versions: 1.1.0.0

ScenePrivate Property

The Scene API for the Scene this script is a part of if the script is attached to scene content.

Syntax

[get: Sansar.Script.Interface]
public ScenePrivate ScenePrivate { protected get; set; }

Value

The Scene API for this scene if this script was attached to scene content, null otherwise.

Remarks

This value will be set before Init is called.

Requirements

Namespace: Sansar.Simulation
Assembly: Sansar.Simulation (in Sansar.Simulation.dll)
Assembly Versions: 1.1.0.0


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

0 Comments

Article is closed for comments.