Difference between revisions of "World Scripting Reference"

Revision as of 11:11, 11 October 2016

This page is part of the Infrastructure Guide. Here we'll describe the various objects you'll work with from in the server JavaScript scripting environment, as well as provide step by step instructions to help you create your first server script, and examples of working scripts you can use on your server.

Creating A Server Script

TODO: make a tutorial explaining how to make, upload, and debug a server script

Script Examples

TODO: make a table of script examples with the link in the first column, and a quick description in the second. The links can go to pages with the full source

System Global Objects

These objects are created by the core, and are always available to server scripts. An instance of each can be accessed at the global scope. For example, a script can access DOM.Self to get a reference to the DOMScript node on which the script is running.

DOM (C# class: DOMGlobals)

• C# class DOMFunctions

Properties

DOMObject Self {get;}

Gets a reference to the DOMScript node which loaded the calling script.

DOMController Controller {get;}

Gets a reference to the DOMController node which represents the avatar in the persona document in which the calling script is running. If the calling script is running in a scene document, this property will be null.

DOMObject Document {get;}

Gets a reference to the DOMDocument under which this script is running. Same as DOM.Self.Document

Methods

DOMObject FindNode(int objectID)

Attempts to find a DOMObject by its ID in the same document in which the calling script is running.

DOMObject FindNodeInParticipants(int objectID)

Attempts to find a DOMObject by its ID in the entire participants container document (All persona documents).

DOMObject GetNodeByID(int objectID)

An alias for FindNode

DOMObject[] GetNodesByName(string name)

Finds DOMObjects with the given name inside the document in which the calling script is running.

Instance (C# class: InstanceExtended)

• C# class InstanceExtended

Properties

DOMDocument Document {get;}

Gets a reference to the DOMDocument at the root of the instance

DOMDocument Participants {get;}

Gets a reference to the DOMDocument that contains all participants

DOMDocument Scene {get;}

Gets a reference to the DOMDocument that contains the scene

string Title {get;}

Returns the title of the instance

string SceneTitle {get;}

Returns the title of the scene

bool DesignMode {get;}

Returns true of the instance is running in design mode

ViewInfo View {get;}

Returns the main view for the instance

Events

OnDisposed()

Fired when the instance shuts down

OnEnter(Participant user)

Fires when a new participant enters the room

OnLeave(bool user)

Fires when a participant leaves the room

OnLoad(bool restarting)

Fires for your script when the instance starts or you are reloaded

OnChildAdded(DOMObject obj)

Fires when a new node is added to the instance

Methods

ViewInfo AddView(string identifier)

Creates a new shared view (document) to which you can attach participants, and add nodes like in the scene document

ViewInfo FindView(string identifier)

Searches for a named shared view

Participant[] GetParticipants()

Returns an array of participants in the instance

System (C# class: SystemFunctions)

• C# class SystemFunctions

Methods

void Debug(string message)

An alias for Log.WriteDebug

void ServerLog(string message)

Writes a debug message to the server log system (as opposed to the script debug system)

Instance GetInstance()

Gets a reference to the Instance object representing the current “room” or instance in which the calling script is running.

int CreateTimer(function callback, int dueTime, int period)

Creates a timer which will fire once in dueTime milliseconds and then every period milliseconds. When the timer fires, it will call the specified JavaScript callback function. An integer handle to the timer is returned.

bool RemoveTimer(int timerID)

Removes a timer given a timer handle from CreateTimer.

bool BroadcastMessage(int channel, string message, DOMObject source)

Sends a JSScriptEVentMessage packet to all connected clients in the room. Client side UI script can process and respond to this message.

void ListenOnChannel(int channel, function callback)

Begins listening on a given script channel number and defines a JavaScript callback to call when a message arrives from another script.

void BroadcastOnChannel(int channel, string message, DOMObject source)

Sends a message on a given channel to all listening scripts. The message an source will be passed to the listening scripts’ callback function registered with ListenOnChannel. These messages are not delivered to connected clients.

DOMController FindController(DOMObject target)

If the target object is in a persona document, this method will return the document’s first DOMController.

DOMController FindParentController(DOMObject target)

Searches up the DOM tree from target looking for the first DOMController.

Participant FindParticipant(DOMObject target)

If the target object is in a persona document, this method will return the document’s first DOMController.

void CreateWebRequest(string requestType, string contentType, string url, function callback, string postData)

Requests data from the web at the given url. requestType should be GET or POST. If POST, the postData should contain the data to post. contentType is optional and can be null or empty. The callback will be called with two parameters: the response string data, and an integer http status code (200 = success).

Physics

• C# class PhysicsFunctions

Methods

void CastSphere(Vector3 origin, Vector3 direction, float radius, float maxdistance)

Ask patrick

void FireProjectile(DOMTransform projectile, Vector3 origin, Vector3 direction, float speed, float maxdistance, bool usegravity)

Ask patrick

void PathTo(Vector3 position, float speed)

Ask patrick

Log

• C# class DebugLog

Methods

void WriteVerbose(string message)

void WriteDebug(string message)

void WriteInfo(string message)

void WriteWarning(string message)

void WriteError(string message)

void WriteFatal(string message)

These methods write script debug messages to connected clients with LayerOne permissions

Chat

• C# class ChatChannelExtended.ChatFunctions

Methods

ChatChannel GetLocalChannel()

Gets a reference to the general chat channel for the current instance.

ChatChannel CreateChannel(string displayName)

Creates a new named chat channel for use by the calling script.

Component Global Objects

These object templates are created by components, and are always available to server scripts as long as the associated component is installed. As with system global objects, an instance of each is created with the same name as the template and can be accessed at the global scope.

Rays

• C# class JSGlobalRays

Methods

bool Transfer(Participant source, Participant target, float amount)

Transfers Rays currency between the two accounts represented by the source and target DOMObjects which must each belong to persona documents.

bool Collect(Participant source, float amount)

Takes the specified amount of Rays currency from the account represented by the source DOMObject which must belong to persona document.

bool Payout(Participant target, float amount)

Gives the specified amount of Rays currency to the account represented by the target DOMObject which must belong to persona document.

float GetBalance(Participant target)

Gets the balance in Rays of the account represented by the target DOMObject which must belong to persona document.

Adult

• C# class JSGlobalAdult

Methods

EngagementControl CreateEngagement(DOMObject target, string startingState, bool autoDispose)

Begins an adult system engagement (shared animation state), using target as the focus or parent object of the engagement and beginning in the state specified by startingState. When autoDispose is true, the engagement will clean itself up when the number of participants falls below critical numbers (usually when the last participant leaves, but in some cases, like hugging, when any one person leaves).

EngagementControl GetEngagement(DOMObject target)

Tries to find an engagement control involving the DOMObject specified by target.

Cloud

• C# class JSGlobalCloud

Methods

void SetApplication(string applicationID)

Associates this script with an application (scope of data storage). A single call to this function is required before most other GameCloud functions will work. Simply pass a Guid as a string.

void SetData(string key, string value)

Sets the value of an application-scoped data item. This is basic global application string data storage.

bool DataExists(string key)

Checks if an application scoped data item exists (is set).

string GetData(string key)

Gets the value of an application scoped data item.

void DeleteData(string key)

Deletes the specified application scoped data item.

InteractionMapping RegisterInteraction(string selector, string abilityIdentifier, string groupIdentifier = null)

Wraps up the ViewInfo’s AddInteractionMapping and AddAbility methods into a single call. The abilityIdentifier is the name of a GameCloud registered ability (created in the admin). The groupIdentifier is the optional name of a GameCloud registered entity group used to filter who gets the interaction, and the selector is a CSS-Style selector which identifies nodes which are eligible targets of the interaction.

void SaveData()

Checkpoints your app data. Just in case.

CloudCurrency GetCurrency(string identifier, bool accountScoped)

Gets or creates a currency for use in your javascript applications. The returned object can be used to transact in this currency, and get balance of accounts.

HAM

• C# class JSGlobalHAM (hosted by CreatureManager)

Methods

bool IsAvailable()

Returns true if the creature manager is installed.

bool SetAttachment(string attachmentName, DOMObject target, int attachID)

Obsolete

bool HasAttachment(strin attachmentName, DOMObject target)

Obsolete

bool ClearAttachment(string attachmentName, DOMObject target)

Obsolete

Avatar

• C# class JavascriptAvatar

Methods

bool PlayAnimation(DOMObject target, string actionID, bool looping)

Triggers a HAM action item on the specified player, given its actionID as a Guid

bool StopAnimation(DOMObject target, string actionID)

Stops a HAM action from playing on the specified player given its actionID as a Guid

Bot

• C# class JavascriptBot

Methods

bool IsAvailable()

bool PlayAnimation(DOMObject target, string animationName, bool looping)

Same as above, but for bots in a room rather than player avatars

bool StopAnimation(DOMObject target, string animationName)

Same as above, but for bots in a room rather than player avatars

Layer One Objects

These are JavaScript wrappers for # objects that can be passed down into JavaScript as return value of a function call or as the parameter to an event or callback method.

ConfirmationHandle

• C# class ConfirmationHandleExtended

Properties

Guid ID {get;}

string Title {get;}

string Description {get;}

string[] Buttons {get;}

The list of button labels (eg: yes, no)

int DefaultButton {get;}

The zero-based index into Buttons which will be the default button

bool IsCompleted {get;}

True if this confirmation request was cancelled or completed

bool Success {get;}

True if the user completed the confirmation request

int ButtonChoice {get;}

The zero-based index into Buttons which was chosen by the user

int ReplyTimeout {get;}

The time to wait for the users' reply in milliseconds. -1 to wait indefinitely.

int TimeRemaining {get;}

The time remaining of ReplyTimeout. This property will be -1 if ReplyTimeout is -1, and 0 if the time has expired.

Events

Cancelled()

Fires when the confirmation request has been cancelled (usually because the user logs off or navigates)

Completed()

Fires when the confirmation request completes with success or failure

Methods

void Cancel()

Cancels the confirmation request

void Complete(int buttonChoice)

Simulates the completion of the confirmation request with a specified button choice.

CloudCurrency

• C# class CloudCurrencyExtended

Properties

Guid ID {get;}

string Identifier {get;}

Methods

bool Transfer(Participant source, Participant target, float amount)

Same as Rays.Transfer except in this cloud currency

bool Collect(Participant source, float amount)

Same as Rays.Collect except in this cloud currency

bool Payout(Participant target, float amount)

Same as Rays.Payout except in this cloud currency

float GetBalance(Participant target)

Same as Rays.GetBalance except in this cloud currency

Participant

• C# class ParticipantExtended

Events

OnEntitiesChanged(Participant part)

Fires when a the participant’s connection’s entity list changes (i.e. the user joins or leaves a dynamic or entity group).

OnAreaPermissionsChanged(Participant part)

Fires when the permission set for this user changes due to changes in permission on the current instance, or any of it’s parent world or area group hierarchy, or due to entity set changes.

OnSceneReady(Participant part)

Fires when the connected client informs the server that it has loaded all reasources, lowered it’s loading screen, and is ready to show the scene.

OnTypingStarted(Participant part)

Fires when the connected client informs the server that the user has begun typing.

OnTypingStopped(Participant part)

Fires when the connected client informs the server that the user has stopped typing.

OnTargetChanged(DOMObject newTarget, DOMObject oldTarget)

Fires when the connected client changed it’s targeted DOMObject.

OnVirtualRealityStarted(Participant part)

Fires when the connected client informs the server that the user has turned on their VR headset.

OnVirtualRealityStopped(Participant part)

Fires when the connected client informs the server that the user has turned on their VR headset.

OnDisposed()

Fires as the participant is cleaned up.

Properties

string Name {get;}

Gets the participant’s persona’s name.

DOMController Controller {get;}

Gets the root DOMController object that represents the participant’s avatar in the room. This will almost always be the only direct DOMController child of the participant document.

string AccountID {get;}

Gets the account ID of the participant as a GUID in string format

string PersonaID {get;}

Gets the persona ID of the participant as a GUID in string format

string SessionID {get;}

Gets the session ID of the participant as a GUID in string format

AbilitySet Abilities {get;}

Gets the ability set for this participant which can be used to create ability groups and abilities and modify their state

Properties (from CreatureManager)

string CreatureType {get;}

Gets the creature type ID as a GUID in string format

bool IsMale {get;}

Returns true if the participant’s creature type is male

Methods

bool InEntity(string id)

Checks if this participant’s connection identity is in the requested entity (account, persona, entitygroup, dynamicgroup, etc)

bool HasAreaPermission(string id)

Checks if this participant’s connection identity has the requested permission in the current area

void ResetPosition()

Resets the user’s world position to their specified DOMStartPoint or the default DOMStartPoint or origin

bool SendUIScript(ResourceValue packageResource, string args)

Pushes the requested UI package to the connected client

bool NavigateTo(string vwwUrl, bool designMode = false)

Attempts to navigate the participant to another destination scene by vwwUrl and optionally in design mode

Methods (from GameCloud)

void SetData(string key, string value)

Sets the value of a persona scoped data item.

bool DataExists(string key)

Checks if a persona scoped data item exists (is set).

string GetData(string key)

Gets the value of a persona scoped data item.

void DeleteData(string key)

Deletes the specified persona scoped data item.

void SetAccountData(string key, string value)

Sets the value of an account scoped data item.

bool AccountDataExists(string key)

Checks if an account scoped data item exists (is set).

string GetAccountData(string key)

Gets the value of an account scoped data item.

void DeleteAccountData(string key)

Deletes the specified account scoped data item.

void GiveObject(string id)

Creates an ObjectTemplate of the ObjectType specified by the Guid in the id parameter and puts it in the participant’s persona’s inventory. Essentially, gives a person a thing, like clothing, or an object for scene editing.

void GiveUniqueObject(string id)

Creates an ObjectTemplate of the ObjectType specified by the Guid in the id parameter and puts it in the participant’s persona’s inventory if one doesn't exist already. Essentially, gives a person a thing, like clothing, or an object for scene editing.

ConfirmationHandle Inform(string title, string description, string buttonText = "core.confirmbutton.ok", int timeout = -1 )

Initiates a new Confirmation Request meant to inform the user of something.

ConfirmationHandle Confirm(string title, string description, function yesCallback, function noCallback = null, string[] buttons = null, int timeout = -1 , function cancelCallback = null)

Initiates a new Confirmation Request meant to confirm something with the user. The participant’s connection will be sent a packet asking them to confirm the activity described by title and description, by pressing one of the described buttons. The confirmation will be automatically cancelled if the user disconnects or navigates. You can provide functions that will be called back when the user presses yes no or cancel.

ConfirmationHandle ConfirmationRequest(string title, string description, string buttons, int defaultButton, int timeout)

Initiates a new Confirmation Request meant to confirm something with the user. The participant’s connection will be sent a packet asking them to confirm the activity described by title and description, by pressing one of the described buttons. The confirmation will be automatically cancelled if the user disconnects or navigates. Buttons are specified as a comma separated list.

bool JoinGroup(string groupIdentifier, bool accountLevel)

Joins the participant to an EntityGroup which has been registered to your application via the admin GameCloud configuration tool

bool LeaveGroup(string groupIdentifier, bool accountLevel)

Removes the participant from an EntityGroup which has been registered to your application via the admin GameCloud configuration tool

bool CheckGroup(string groupIdentifier)

Tests whether the participant is in the EntityGroup which has been registered to your application via the admin GameCloud configuration tool

InteractionMapping RegisterInteraction(string selector, string abilityIdentifier)

Registers an ability (created earlier in a call to Instance.View.AddAbility) as an interaction that only this participant will see.

bool SetOverlayItem(string path, string objectTypeId)

Sets the specified object type as a GameCloud clothing slot overlay in the slot specified by path on this participant.

bool SetOverlayBlank(string path)

Sets a 'blank' or clothing remove request as a GameCloud clothing slot overlay in the slot specified by path on this participant.

bool ClearOverlayItem(string path)

Clears any GameCloud clothing slot overlay in the slot specified by path on this participant.

bool ClearOverlay()

Clears all GameCloud clothing slot overlays on this participant.

Methods (from HumanAvatarManager)

bool EnableAbilityGroup(string identifier)

Enables a group of abilities for the player. (eg, turning on dance moves when you enter the dance floor)

bool DisableAbilityGroup(string identifier)

Disables a group of abilities for the player. (eg, turning off dance moves when you leave the dance floor)

AbilitySet

• C# class AbilitySetExtended

Events

OnDisposed()

Fired when the ability set is destroyed.

OnAbilityFired(Ability ability, Participant participant)

Fires when the user fires an ability (usually by pressing a button on their quickbar).

Methods

Ability Find(Guid id)

Finds an Ability or AbilityGroup by ID.

AbilityGroup CreateGroup(string identifier, ResourceValue iconResource = null)

Creates a new ability group with an optional iconResource.

AbilityGroup

• C# class AbilityGroupExtended, Inherits Ability

Events

OnDisposed()

Fired when the AbilityGroup is destroyed.

Methods

AbilityGroup CreateGroup(string identifier, ResourceValue iconResource = null)

Creates a child ability group under this one.

Ability CreateAbility(string identifier, float cooldown = 0, ResourceValue iconResource = null)

Creates a new ability with an optional cooldown and icon resource.

void Remove()

Removes the ability.

Ability

• C# class AbilityExtended

Events

OnDisposed()

Fired when the Ability is destroyed.

Properties

bool ScriptCreated {get;}

True if the Ability or AbilityGroup was created by javascript.

string Identifier {get;}

The translatable identifier of the ability

string Description {get;}

The description of the ability (not currently used)

bool Enabled {get; set;}

True if the ability is currently enabled. Note that setting an ability to enabled will make the change locally, but may not take effect if the ability is denied, or any of it’s parents are disabled or denied.

bool Denied {get; set;}

True if the ability or any of it’s parents are denied. Setting this value may have no effect until parents are un-denied (allowed).

bool Active {get; set;}

Marks an ability as active (in use). This is meant mainly for display purposes.

float Cooldown {get;}

True if the ability or any of it’s parents are denied. Setting this value may have no effect until parents are un-denied (allowed).

float CooldownProgress {get;}

A number between 0 and 1 representing the percentage of cooldown time elapsed since the ability was last set Active.

Methods

void Reset()

Attempts to reset the ability (Enabled, not Denied, not Active)

void Remove()

Removes the ability.

ChatChannel

• C# class ChatChannelExtended

Events

OnDisposed()

Fired when the channel is destroyed.

OnJoin(Participant participant)

Fired when a new participant enters the channel.

OnLeave(Participant participant)

Fired when a participant leaves the channel.

OnMessage(Participant participant, ChatMessageEventArgs message)

Fired when a message is sent in the channel.

Methods

bool Join(Participant participant)

Add a participant to the channel.

bool Leave(Participant participant)

Remove a participant from the channel.

void Close()

Closes (Disposes) a channel.

void Broadcast(string message, int messageStyle = 253)

Sends a message to all participants of a channel. By default, the message style is 253 (System)

void SendMessageTo(Participant participant, string message, int messageStyle)

Sends a message to a single participant of a channel. By default, the message style is 253 (System)

Participant[] GetParticipants()

Gets the participants of the channel

ChatMessageEventArgs

• C# class ChatMessageEventArgsExtended

Properties

string Message {get; set;}

The text of the message.

Participant Source {get;}

The participant representing the sender of the message. Or null if it’s a system message.

ViewInfo

• C# class ViewExtended

Events

OnEnter(Participant who)

Fired when a participant in an engagement uses one of their abilities

OnInteraction(Participant who, DOMObject target, Guid abilityID, object value)

Fired when a participant executes an interaction.

OnLeave(Participant who)

Fired when a participant in an engagement uses one of their abilities

Properties

long ViewID {get;}

The unique ID of the view

Methods

InteractionMapping AddInteraction(string selector, Guid abilityID, Guid entityID = null)

Add a participant to the shared view.

ViewAbility AddAbility (string identifier, string initialMetadata, float? cooldown = null, Guid? entityID = null)

Creates a new view-local ability which will be automatically delivered to participants when they join the view. This ability is mean to be used by AddInteraction.

bool Join(Participant participant)

Add a participant to the shared view.

bool Leave(Participant participant)

Remove a participant from the shared view.

bool Release()

Destroys the shared view.

InteractionMapping

• C# class InteractionMappingExtended

Events

OnInteraction(Participant who, DOMObject target, Guid abilityID, object value)

Fired when a participant executes an interaction.

Properties

string Selector {get;}

The CSS-style selector string used to select possible target objects for an this interaction

Guid AbilityID {get;}

The ID of the ability bound to this mapping as an interaction

Guid EntityID {get;}

The optional ID of an entity to which a participant must belong to get this interaction

Methods

bool Release()

Destroys the interaction mapping

ViewAbility

• C# class ViewAbilityExtended

Properties

Guid AbilityID {get;}

The ID of the ability bound to this mapping as an interaction

Guid EntityID {get;}

The optional ID of an entity to which a participant must belong to get this interaction

string Identifier {get;}

The identifier of the ability (used for language translation)

float Cooldown {get;}

The cooldown timer for the ability. 0 if there is none.

string InitialMetadata {get;}

The initial metadata attached to the participant’s ability when it’s created.

Methods

bool Release()

Destroys the view ability

EngagementControl

• C# class EngagementControlExtended

Events

AbilityFired(Participant who, string identifier)

Fired when a participant in an engagement uses one of their abilities

StateChanged(string identifier)

Fired when the state of the angagement changes, and passes in the new state identifier

PlayerAdded(int who)

Fired when a new player is added to an engagement. ‘who’ is the ID of the controller of the new player, which may be a participant or a bot.

PlayerRemoved(int who)

Fired when a new player is added to an engagement. ‘who’ is the ID of the controller of the new player, which may be a participant or a bot.

OnDisposed()

Fired when this engagement control is shutting down

Properties

bool IsValid {get;}

Ask dirk

Methods

void Close()

Disposes this engagement control.

bool IsPlayerEngaged(DOMObject who)

Tests if the player represented by the DOMObject is in this engagement.

bool AddPlayer(DOMObject who)

Adds a player represented by the DOMObject to this engagement.

bool RemovePlayer(DOMObject who, bool restoreAnimator)

Removes a player represented by the DOMObject from this engagement.

void SetOptions(Vector3 position, Vector3 rotation)

Ask dirk. Looks like it sets the offset and rotation of the players from center of the target object of the engagement.

Layer One Objects (DOM)

As above, these are wrappers for C# objects that can be returned from function calls or passed to events. These are all wrappers for DOMObject derived classes implemented by DOMObjectExtended and it's derived classes.

DOMObject

• C# class DOMObjectExtended

Events

OnDisposed()

Fires when a DOMObject is being destroyed, usually because it’s being removed from the DOM.

OnSelect(Participant who, DOMObject source)

Fires when a user selects an object in world. Who is the Participant doing the selecting.

OnDeselect(Participant who, DOMObject source)

Fires when a user deselects an object in world. Who is Participant doing the deselecting.

OnTarget(Participant who, DOMObject source)

Fires when a user targets an object in world. Who is the Participant doing the targeting.

OnUnTarget(Participant who, DOMObject source)

Fires when a user un-targets an object in world. Who is the Participant doing the un-targeting.

Properties

string Class {get; set;} // via attribution

A space separated list of class names which are used by CSS-style selectors to match this node

DOMDocument Document {get;}

Gets a reference to the DOMDocument in which this DOMObject resides.

string DocumentTitle {get;}

A shortcut equivilant to DOMObject.Document.Title.

bool Enabled {get; set;} // via attribution

Indicates whether the client should carry out the effects of this object or it’s children. A disabled node tree should have no effect on the scene

long ID {get;} // via attribution

The unique ID of the object in it’s current DOM tree

bool IsTemporary {get;} // via attribution

An object marked as temporary will not be saved when the DOM is serialized for storage. Objects created by scripts are marked as temprary by default

bool IsTransient {get;} // via attribution

An object marked as transient be sent to connected clients but will not be saved in the DOM.

bool IsTypeRoot {get;} // via attribution

True if this node is the root node of an instantiated object type.

DOMProperties LocalProperties {get;}

Gets a DOMProperties object representing the properties of this object which are NOT send over the network.

string Title {get; set;} // via attribution

The title of the DOM node. Visible in curiosity.

string Type {get;}

A string version of this object’s type’s name, for derived objects, this will return the name of the derived object, so DOMRenderable.Type returns “DOMRenderable”

DOMObject Parent {get;}

Gets a reference to the DOMObject directly parenting this one.

DOMProperties Properties {get;}

Gets a DOMProperties object representing the properties of this object visible to all viewers of the DOM. Changes to these properties ARE sent over the network.

int ProtectionFlags {get;} // via attribution

A bitfield specifying what sorts of operations are not allowed on this object. 1 = Delete, 2 = Move, 4 = Add (child), 8 = Remove (child), 16 = Change (properties)

bool Visible {get;} // via attribution

An object marked as not visible will not be delivered to connected clients or will be removed if it already has been. Usefull for hiding a tree from clients until it’s ready to be displayed.

Methods

void AddClass(string className)

Adds a class name to the space separated list of class names found on the Class property of this DOMObject.

DOMObject Clone(DOMObject newParent)

Clones this object and places it as a direct child of the specified parent object

DOMTransform CreateCurve(string title = null, bool visible = true)

Creates a new DOMCurve object, optionally initially invisible, as a direct child of this object.

DOMTransform CreateCurveFromJson(string json)

Creates a new DOMCurve object from the JSON Curve Definition, as a direct child of this object.

DOMTransform CreateEmptyNode(bool visible = false)

Creates a simple DOMTransform object, optionally initially invisible, as a direct child of this object.

DOMObject CreateHookpoint(string title, bool visible = false)

Creates a simple DOMHookpoint object, optionally initially invisible, as a direct child of this object.

DOMLight CreateLight(int color, float intensity, int shadowtype, float shadowstrength, Vector3 position, Vector3 rotation)

Creates a DOMLight object as a direct child of this object with the specified properties already set.

DOMObject CreateNode(string templateID, bool visible = false)

Creates an instance of the specified ObjectTemplate given its GUID templateID, optionally initially invisible, as a direct child of this object.

DOMObject CreateTitleNode(string title, int index, bool visible = false)

Creates a simple DOMTitle object, optionally initially invisible, as a direct child of this object.

bool DeleteNode()

Removes this node from the DOM.

DOMObject[] GetChildren()

Gets all direct children.

DOMController FindController()

Returns the first child DOMController object found in the document in which this object is a member, as long as that document is a persona document (essentially finds the root of an avatar starting from some other object in the avatar’s document). Not so good for finding bot controllers.

DOMObject FindNode(string name)

Find the first child node (recursive, deep search) with the specified name;

DOMObject[] FindNodes(string name)

Finds child nodes (recursive, deep search) with the specified name;

DOMController FindParentController()

Searches up the tree for the first DOMController. Better for finding bot controllers.

object GetAttributeValue(string attributeName)

Looks for an attribute with the given name and returns its value. Attributes are like special properties placed on the DOM nodes and properties when they appear in an ObjectType definition. An ObjectType is a container for a small snippet of DOM which can be re-used at runtime to create instances of that same layout and inject it into a running document. Attributes placed on these object or properties can later be accessed on any instance of these objects or properties. Think of these like metadata “about” an object or property, rather than data describing the object instance itself.

bool HasAttribute(string attributeName)

Checks to see if a given attribute exists on this object.

bool HasClass(string className)

Tests if the specified class name is found in the space separated list of class names found on the Class property of this DOMObject.

void ListenOnChannel(int channelID, function callback)

Starts listening for messages sent to this object from other scripts, or from client UI scripts. Callback will be called with (int channelID, string message, DOMObject source, DOMObject dest) describing the message. This is similar to System.ListenOnChannel but listens only for messages sent directly to this object.

bool MatchesSelector(string selector)

Parses the specified CSS-style selector string and then tests itself (the current node) for a match.

DOMObject[] QuerySelectorAll(string selector)

Parses the specified CSS-style selector string and then queries the DOM from this node down, looking for objects that match. Returns an array of found objects.

DOMObject QuerySelector(string selector)

Parses the specified CSS-style selector string and then queries the DOM from this node down, looking for objects that match. Returns the first found object.

void RemoveClass(string className)

Removes a class name from the space separated list of class names found on the Class property of this DOMObject.

bool SendMessage(int channel, string message, DOMObject source)

Sends a message on the specified script communication channel given another object as the source. Someone else having previously used ListenOnChannel could receive this message to their callback function.

void ToggleClass(string className)

Toggles a class name in the space separated list of class names found on the Class property of this DOMObject.

DOMTransform

• C# class DOMTransformExtended, Inherits DOMObject

Properties

string AttachToBone {get; set;} // via attribution

When this transform is under a renderable with a skeleton, it’s transform is further modified by the current animated position of a bone in the renderable’s skeleton as well as the transform of the parent renderable itself

bool IsClickable {get; set;} // via attribution

Allows an object to receive client click events.

bool IsSelectable {get; set;} // via attribution

Allows an object to be selected.

bool IsTargetable {get; set;} // via attribution

Allows an object to be the users target.

string ToolTip {get; set;} // via attribution

Specifies a tool tip to display when the user hovers their pointer over this object.

string ToolTipTitle {get; set;} // via attribution

For large-style tool tips, allows for a title displayed over the tool main tip text

ResourceUri ToolTipIcon {get; set;} // via attribution

For large-style tool tips, allows for an icon displayed beside the main tip text

DOMTransform TransformParent {get; set;}

Gets a reference to this object’s DOMTransform parent, if it has been set to something other than normal node hierarchy.

int TransformParentID {get; set;} // via attribution

The ID of the node of the specified TransformParent

float X {get; set;} // via attribution

Gets or sets the X component of the transform’s position

float Y {get; set;} // via attribution

Gets or sets the Y component of the transform’s position

float Z {get; set;} // via attribution

Gets or sets the Z component of the transform’s position

float RX {get; set;} // via attribution

Gets or sets the X component of the transform’s rotation

float RY {get; set;} // via attribution

Gets or sets the Y component of the transform’s rotation

float RZ {get; set;} // via attribution

Gets or sets the Z component of the transform’s rotation

float SX {get; set;} // via attribution

Gets or sets the X component of the transform’s scale

float SY {get; set;} // via attribution

Gets or sets the Y component of the transform’s scale

float SZ {get; set;} // via attribution

Gets or sets the Z component of the transform’s scale

Events

OnClick(Participant who, DOMObject source)

Fires when a user clicks an object in world. Who is the Participant doing the clicking.

OnRightClick(Participant who, DOMObject source)

Fires when a user right-clicks an object in world. Who is the Participant doing the right-clicking.

Methods

bool MoveTo(float x, float y, float z, float speed)

Moves this object smoothly, and linearly to the specified x,y,z location over time specified by speed. This is accomplished using a child DOMInterpolation node.

bool MoveToWithCallback(float x, float y, float z, float speed, function callback)

Same as above, but requests a callback when the operation completes.

DOMPhysics PhysicsSpawn(float radius, bool stack)

Creates a DOMPhysics node as a direct child of this node requesting the Spawn operation and given the specified parameters. The returned DOMPhysics node can be used to start / stop the operation and monitor for its completion.

DOMPhysics PhysicsPathTo(float targetX, float targetY, float targetZ, float speed)

Creates a DOMPhysics node as a direct child of this node requesting the PathTo operation and given the specified parameters. The returned DOMPhysics node can be used to start / stop the operation and monitor for its completion.

DOMPhysics PhysicsPathToVector(Vector3 target, float speed)

Creates a DOMPhysics node as a direct child of this node requesting the PathToVector operation and given the specified parameters. The returned DOMPhysics node can be used to start / stop the operation and monitor for its completion.

DOMPhysics PhysicsFollow(DOMTransform target, float minDistance, float, maxDistance)

Creates a DOMPhysics node as a direct child of this node requesting the Follow operation and given the specified parameters. The returned DOMPhysics node can be used to start / stop the operation and monitor for its completion.

DOMPhysics PhysicsProjectile(float directionX, float directionY, float directionZ, float speed, bool gravity, float maxDistance)

Creates a DOMPhysics node as a direct child of this node requesting the Projectile operation and given the specified parameters. The returned DOMPhysics node can be used to start / stop the operation and monitor for its completion.

DOMPhysics PhysicsProjectileVector(Vector3 direction, float speed, bool gravity, float maxDistance)

Creates a DOMPhysics node as a direct child of this node requesting the ProjectileVector operation and given the specified parameters. The returned DOMPhysics node can be used to start / stop the operation and monitor for its completion.

void ResetTransformParent(bool restoreLastPosition)

Resets this object’s transform parent reference to null so that it behaves normaly, transforming relative to the next DOMTransform up the hierarchy.

void SetPosition(float x, float y, float z)

Sets the position (transform) of this object from its next parent DOMTransform or from world origin (0,0,0).

void SetRotation(float x, float y, float z)

Sets the rotation of this object relative to its next parent DOMTransform or from (0,0,0)

void SetScale(float x, float y, float z)

Sets the scale of this object relative to its next parent DOMTransform or from (1,1,1)

void SetTransformParent(DOMTransform target, Vector3 position, Vector3 rotation, Vector3 scale)

Sets this objects transform parent reference to the specified DOMTransform preventing it from transforming relative to the next DOMTransform up the hierarchy, but rather, the specified object instead. Sets the position, rotation, and scale to new values along with the transform parent change as a single atomic operation.

DOMRenderable

• C# class DOMRenderableExtended, Inherits DOMTransform

Properties

string AnimationName {get; set;} // via attribution

The name of an animation to play

bool CamPassable {get; set;} // via attribution

Specifies that this object allow the camera to pass through it

bool CastShadows {get; set;} // via attribution

Specifies that this object should cast shadows onto surrounding geometry

int InteractionDistance {get; set;} // via attribution

The distance in worldspace units beyond which the user should not be able to interact with the object (see tool tips, respond to clicks, etc)

bool LightProbes {get; set;} // via attribution

Specifies that this object should use light probe information in it’s lighting calculations

bool PhysicsEnabled {get; set;} // via attribution

Specifies that physics is enabled for this object

bool ReceiveShadows {get; set;} // via attribution

Specifies that this object should receive shadows from surrounding geometry

Methods

void SetClickable(bool clickable)

Apparently sets property #Clickable

void EnablePhysics(bool enabled)

Apparently sets property #Physics

DOMController

• C# class DOMControllerExtended, Inherits DOMRenderable

Properties

DOMAnimationController AnimationController {get; set;}

Returns the DOMAnimationController that this controller should use for animation. If none is specified an immediate child DOMAnimationController will be used instead.

int AnimationControllerID {get; set;} // via attribution

The ID of the node of the specified AnimationController override.

DOMController ActiveController {get; set;}

Returns the DOMController that this controller should use to overide control. If none is specified this DOMController controls itself.

int ActiveControllerID {get; set;} // via attribution

The ID of the node of the specified ActiveController override.

int BlendshapeTypeNodeID {get; set;} // via attribution

No idea what this does.

int Direction {get;} // via attribution

The direction the avatar is pointing in degrees.

bool IsParticipant {get;}

Returns true if this object is in a persona document.

DOMTransform : LookAt {get; set;}

Returns the DOMTransform object that this controller should try to “look at” if any

int LookAtID {get; set;} // via attribution

The ID of the node of the specified LookAt target

string LookAtBone {get; set;} // via attribution

Gets or sets the name of the bone in the LookAt target to fine-tune the looking.

Participant Participant {get;}

Returns the Participant object associated with the persona document in which this controller resides.

int ParticipantID {get;} // via attribution

When in a multiplayer engagement, specifies the participant (slot) ID (OMG… why is this here and why is it named so ambiguously close to Participant which has a really different meaning!)

bool PositionLocked {get;} // via attribution

Specifies whether the controller is allowed to move.

int Running {get;} // via attribution

Indicates the controller’s running speed.

float Speed {get;} // via attribution

The speed the avatar is moving in units per second.

Methods

void LockPosition(bool locked)

Position locks this object so it can’t move or be controlled to move. Useful for playing animations where locked position is necessary.

bool SetAnimationInt(string name, int value)

Sets the specified name and integer value of a property on the first child animation controller. This is super cheesy and should be replaced.

bool StartAnimation(string layerName, string animKey, bool looping, int timeOffset)

Creates a DOMAnimation node and puts it on the specified DOMAnimationLayer. This function is in the wrong place. Should be on DOMController

bool StartLookAt(DOMTransform target, string boneName)

Sets the LookAt and BoneName properties in a single update

bool StopAnimation(string layerName, string animKey)

Stops an animation from playing.

bool StopAnimationLayer(string layerName)

Stops all animations on the specified animation layer from playing.

bool StopLookAt()

Clears the LookAt and BoneName properties in a single update

DOMAnimation

• C# class DOMAnimationExtended, Inherits DOMObject

DOMScript

• C# class DOMScriptExtended, Inherits DOMObject

Methods

void ReloadScript()

Causes the script associated with this node to reload.

DOMPhysics

• C# class DOMPhysicsExtended, Inherits DOMObject

Events

OnComplete()

Fires when the physics host says the physics operation represented by this object has been completed.

Methods

void Start()

Asks the physics host to start carrying out the physics operation represented by this object.

void Stop()

Asks the physics host to stop carrying out the physics operation represented by this object.

DOMCurve

• C# class DOMCurveExtended, Inherits DOMObject

This DOM object represents an animation of the DOM. A Curve is made up of Keyframes with Values. A Player plays the curve and it's properties reflect the values at any given moment along the curve, and can project those values onto other objects in the DOM via it's Selector. You can create a new DOMCurve via the CreateCurve and CreateCurveFromJson methods of DOMObject.

Methods

DOMCurveKeyframe CreateKeyframe(float time, string title = null)

Creates a new keyframe at the specified time on this curve

DOMCurvePlayer CreatePlayer(string title = null)

Creates a new player on this curve

string ToJson()

Creates a stringified JSON object in the JSON Curve Definition format from this curve.

DOMCurveKeyframe

• C# class DOMCurveKeyframeExtended, Inherits DOMObject

Properties

float Time {get; set} // via attribution

The time that this keyframe occurs on the curve

Events

OnPlayerCrossed(DOMCurvePlayer player)

Fires when this keyframe is crossed by a player

Methods

DOMObject CreateValue(string name)

Creates a new DOMCurveValue node with the specified name, you must set a property on it with an appropriate value

DOMObject CreateColorValue(string name, Color32 value)

Creates a new DOMCurveValue node with the specified name, and Color32 value

DOMObject CreatePointValue(string name, Point3D value)

Creates a new DOMCurveValue node with the specified name, and Point3D value

DOMObject CreateFloatValue(string name, float value)

Creates a new DOMCurveValue node with the specified name, and float value

DOMObject CreateResourceValue(string name, ResourceValue value)

Creates a new DOMCurveValue node with the specified name, and ResourceValue value

DOMObject CreateStringValue(string name, string value)

Creates a new DOMCurveValue node with the specified name, and string value

DOMObject CreateIntValue(string name, int value)

Creates a new DOMCurveValue node with the specified name, and int value

DOMObject CreateBoolValue(string name, bool value)

Creates a new DOMCurveValue node with the specified name, and bool value

DOMCurvePlayer

• C# class DOMCurvePlayerExtended, Inherits DOMObject

Properties

float Time {get; set} // via attribution

Gets or sets the current time index of this player. Generally you'll only read this value, not set it.

DOMCurveOperation Operation {get; set} // via attribution

Set to one of the following enum values, this property specifies the operational mode of the player:

• Stop (0) : The player freezes and it's values do not change, it stops projecting it's values onto DOM Nodes matching it's selector
• Run (1) : The player begins counting time and each "tick" it assumes new property values by "playing" the curve. As it moves between keyframes, value nodes are used to generate lerped values for the properties assumed by the player. The player then projects these values onto other nodes in the DOM via it's Selector
• Step (2) : As with Run above, except as the player passes keyframes it consumes it's "StepCount" and eventually stops
• JumpToKeyframe (3) : The player freezes, sets it's time index to that of the keyframe specified by the ID in the JumpToKeyframeID property, and projects it's values once onto the DOM nodes matching it's Selector
• Reset (4) : The player freezes, sets it's time index to 0, and stops projecting it's values onto DOM Nodes matching it's selector

long JumpToKeyframeID {get; set} // via attribution

The ID of the keyframe node under this curve to which the player should jump if it's Operation property is set to JumpToKeyframe

bool Loop {get; set} // via attribution

If set to true the player loops around from the last keyframe's Time to 0.0 when it reaches the end (or from 0.0 to the last keyframes's time when it reaches the beginning when running in reverse)

bool Reverse {get; set} // via attribution

If set to true the player runs backward

string Selector {get; set} // via attribution

The CSS-style selector used to identify nodes in the DOM that should be affected by this player

int StepCount {get; set} // via attribution

The number of steps the player should run for if it's Operation property is set to Step

Events

OnKeyframeCrossed(DOMCurveKeyframe keyframe)

Fires when this player crosses a keyframe

Methods

void Run()

Starts the player running by setting the Operation property to "Run"

void Stop()

Stops the player from running by setting the Operation property to "Stop"

void Reset()

Stops the player from running and resets it to time index 0.0 by setting the Operation property to "Reset"

void Step(int count = 1)

Increments the step count by count and sets the Operation property to "Step". The player will run until it consumes count' steps

void JumpToKeyframe(DOMCurveKeyframe keyframe)

Sets the time index of the player to that of the specified keyframe, fires the crossed events for the keyframe and player, and stops.

DOMVolume

• C# class DOMVolumeExtended, Inherits DOMTransform

Events

OnEnter(Participant who, DOMObject source)

Fires when a user enters an DOMVolume in world. Who is the Participant doing the entering.

OnLeave(Participant who, DOMObject source)

Fires when a user leaves an DOMVolume in world. Who is the Participant doing the entering.

DOMProperties

• C# class DOMPropertiesExtended

Methods

object GetAttributeValue(string propertyName, string attributeName)

Gets the value of an attribute placed on the specified property. Attributes are like special properties placed on the DOM nodes and properties when they appear in an ObjectType definition. An ObjectType is a container for a small snippet of DOM which can be re-used at runtime to create instances of that same layout and inject it into a running document. Attributes placed on these object or properties can later be accessed on any instance of these objects or properties. Think of these like metadata “about” an object or property, rather than data describing the object instance itself.

bool HasAttribute(string propertyName, string attributeName)

Checks if the specified property has the specified attribute defined.

string[] WithAttribute(string attributeName)

Gets the name of all properties with the given attribute defined.

bool SetInt32(string propertyName, int value, bool silent = false, bool persist = false)

bool SetInt64(string propertyName, int value, bool silent = false, bool persist = false)

bool SetInt64(string propertyName, int value, bool silent = false, bool persist = false)

bool SetSingle(string propertyName, float  value, bool silent = false, bool persist = false)

bool SetGuid(string propertyName, string value, bool silent = false, bool persist = false)

bool SetString(string propertyName, string value, bool silent = false, bool persist = false)

bool SetBoolean(string propertyName, bool value, bool silent = false, bool persist = false)

bool SetInt32Array(string propertyName, string JSONValue, bool silent = false, bool persist = false)

bool SetStringArray(string propertyName, string JSONValue, bool silent = false, bool persist = false)

bool SetColor(string propertyName, int value, bool silent = false, bool persist = false)

bool SetPoint3D(string propertyName, Vector3 value, bool silent = false, bool persist = false)

All of these functions set the value of a property in a type-safe manner.

void RemoveProperty(string propertyName)

Removes the specified property.

ProtoValue GetProperty(string propertyName)

int GetInt32(string propertyName)

float GetSingle(string propertyName)

string GetGuid(string propertyName)

bool GetBoolean(string propertyName)

string GetString(string propertyName)

Color32 GetColor(string propertyName)

Point3D GetPoint3D(string propertyName)

All of these functions get the value of a property in a type-safe manner.

void AddWatcher(string propertyName, function callback)

Begins watching for changes to a property, specifying a callback to be invoked when the property changes.

void RemoveWatcher(string propertyName)

Stops watching for changes to the specified property.