High Fidelity API Reference

Tools Used: JavaScript, JSDoc, GitHub Pages, Markdown, HTML, CSS

---

Script

• Properties • Methods • Signals • Type Definitions • Method Details • Signal Details •

The Script API provides facilities for working with scripts.

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts • Server Entity Scripts • Assignment Client Scripts

---

Properties

Name	Type	Summary
context	string	The context that the script is running in: "client": An Interface or avatar script. "entity_client": A client entity script. "entity_server": A server entity script. "agent": An assignment client script. Read-only.

---

Methods

Name	Return Value	Summary
addEventHandler	None	Adds a function to the list of functions called when an entity event occurs on a particular entity.
callEntityScriptMethod	None	Calls a method in an entity script.
clearInterval	None	Stops an interval timer set by setInterval.
clearTimeout	None	Stops a timeout timer set by setTimeout.
getContext	string	Gets the context that the script is running in: Interface/avatar, client entity, server entity, or assignment client.
isAgentScript	boolean	Checks whether the script is running as an assignment client script.
isClientScript	boolean	Checks whether the script is running as an Interface or avatar script.
isDebugMode	boolean	Checks whether the application was compiled as a debug build.
isEntityClientScript	boolean	Checks whether the script is running as a client entity script.
isEntityScriptRunning	boolean	Checks whether an entity has an entity script running.
isEntityServerScript	boolean	Checks whether the script is running as a server entity script.
print	None	Prints a message to the program log and emits Script.printedMessage. Alternatively, you can use print or one of the console API methods.
removeEventHandler	None	Removes a function from the list of functions called when an entity event occurs on a particular entity.
require	object | array	Provides access to methods or objects provided in an external JavaScript or JSON file.
setInterval	object	Calls a function repeatedly, at a set interval.
setTimeout	object	Calls a function once, after a delay.
stop	None	Stops and unloads the current script. Warning: If an assignment client script, the script gets restarted after stopping.

---

Signals

Name	Summary
doneRunning	Triggered when the script has stopped.
entityScriptPreloadFinished	Triggered when the script starts for the user. See also, Entities.preload. Supported Script Types: Client Entity Scripts • Server Entity Scripts
errorMessage	Triggered when the script generates an error, console.error or console.exception is called, or console.assert is called and fails.
infoMessage	Triggered when the script generates an information message or console.info is called.
printedMessage	Triggered when the script prints a message to the program log via print, Script.print, console.log, console.debug, console.group, console.groupEnd, console.time, or console.timeEnd.
runningStateChanged	Triggered when the running state of the script changes, e.g., from running to stopping.
scriptEnding	Triggered when the script is stopping.
unhandledException	Triggered when a script generates an unhandled exception.
update	Triggered frequently at a system-determined interval.
warningMessage	Triggered when the script generates a warning or console.warn is called.

---

Type Definitions

EntityEvent EntityEvent Type: string

The name of an entity event. When the entity event occurs, any function that hasbeen registered for that event via Script.addEventHandler is called with parameters per the entity event. Properties Event Name Entity Event "enterEntity" Entities.enterEntity "leaveEntity" Entities.leaveEntity "clickDownOnEntity" Entities.clickDownOnEntity "clickReleaseOnEntity" Entities.clickReleaseOnEntity "collisionWithEntity" Entities.collisionWithEntity

---

Method Details

addEventHandler (static) addEventHandler( entityID, eventName, handler )

Adds a function to the list of functions called when an entity event occurs on a particular entity. Parameters Name Type Description entityID Uuid The ID of the entity. eventName Script.EntityEvent The name of the entity event. handler function The function to call when the entity event occurs on the entity. It can be either the name of a function or an in-line definition. Example: Report when a mouse press occurs on a particular entity var entityID = Entities.addEntity({ type: "Box", position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })), dimensions: { x: 0.5, y: 0.5, z: 0.5 }, lifetime: 300 // Delete after 5 minutes. }); function reportMousePress(entityID, event) { print("Mouse pressed on entity: " + JSON.stringify(event)); } Script.addEventHandler(entityID, "mousePressOnEntity", reportMousePress);

callEntityScriptMethod (static) callEntityScriptMethod( entityID, methodName, parametersopt, remoteCallerIDopt )
Calls a method in an entity script. Parameters Name Type Attributes Default Value Description entityID Uuid The ID of the entity running the entity script. methodName string The name of the method to call. parameters Array.<string> <optional> [] The parameters to call the specified method with. remoteCallerID Uuid <optional> Uuid.NULL An ID that identifies the caller.

clearInterval (static) clearInterval( timer )

Stops an interval timer set by setInterval. Parameters Name Type Description timer object The interval timer to stop. Example: Stop an interval timer // Print a message every second. var timer = Script.setInterval(function () { print("Interval timer fired"); }, 1000); // Stop the timer after 10 seconds. Script.setTimeout(function () { print("Stop interval timer"); Script.clearInterval(timer); }, 10000);

clearTimeout (static) clearTimeout( timer )
Stops a timeout timer set by setTimeout. Parameters Name Type Description timer object The timeout timer to stop. Example: Stop a timeout timer // Print a message after two seconds. var timer = Script.setTimeout(function () { print("Timer fired"); }, 2000); // Uncomment the following line to stop the timer from firing. //Script.clearTimeout(timer);

getContext (static) getContext( ) → { string } Returns: The context that the script is running in: "client": An Interface or avatar script. "entity_client": A client entity script. "entity_server": A server entity script. "agent": An assignment client script.
Gets the context that the script is running in: Interface/avatar, client entity, server entity, or assignment client.

isAgentScript (static) isAgentScript( ) → { boolean } Returns: true if the script is running as an assignment client script, false if it isn't.
Checks whether the script is running as an assignment client script.

isClientScript (static) isClientScript( ) → { boolean } Returns: true if the script is running as an Interface or avatar script, false if it isn't.
Checks whether the script is running as an Interface or avatar script.

isDebugMode (static) isDebugMode( ) → { boolean } Returns: true if the application was compiled as a debug build, false if it was compiled as a release build.
Checks whether the application was compiled as a debug build.

isEntityClientScript (static) isEntityClientScript( ) → { boolean } Returns: true if the script is running as a client entity script, false if it isn't.
Checks whether the script is running as a client entity script.

isEntityScriptRunning (static) isEntityScriptRunning( entityID ) → { boolean } Returns: true if the entity has an entity script running, false if it doesn't.
Checks whether an entity has an entity script running. Parameters Name Type Description entityID Uuid The ID of the entity.

isEntityServerScript (static) isEntityServerScript( ) → { boolean } Returns: true if the script is running as a server entity script, false if it isn't.
Checks whether the script is running as a server entity script.

print (static) print( message )
Prints a message to the program log and emits Script.printedMessage. Alternatively, you can use print or one of the console API methods. Parameters Name Type Description message string The message to print.

removeEventHandler (static) removeEventHandler( entityID, eventName, handler )
Removes a function from the list of functions called when an entity event occurs on a particular entity. Parameters Name Type Description entityID Uuid The ID of the entity. eventName Script.EntityEvent The name of the entity event. handler function The name of the function to no longer call when the entity event occurs on the entity.

require (static) require( module ) → { object | array } Returns: The value assigned to module.exports in the JavaScript file, or the value defined in the JSON file.
Provides access to methods or objects provided in an external JavaScript or JSON file. Parameters Name Type Description module string The module to use. May be a JavaScript file, a JSON file, or the name of a system module such as "appUi" (i.e., the "appUi.js" system module JavaScript file).

setInterval (static) setInterval( function, interval ) → { object } Returns: A handle to the interval timer. This can be used in Script.clearInterval.
Calls a function repeatedly, at a set interval. Parameters Name Type Description function function The function to call. This can be either the name of a function or an in-line definition. interval number The interval at which to call the function, in ms. Example: Print a message every second Script.setInterval(function () { print("Interval timer fired"); }, 1000);

setTimeout (static) setTimeout( function, timeout ) → { object } Returns: A handle to the timeout timer. This can be used in Script.clearTimeout.
Calls a function once, after a delay. Parameters Name Type Description function function The function to call. This can be either the name of a function or an in-line definition. timeout number The delay after which to call the function, in ms. Example: Print a message once, after a second Script.setTimeout(function () { print("Timeout timer fired"); }, 1000);

stop (static) stop( marshalopt )

Stops and unloads the current script. Warning: If an assignment client script, the script gets restarted after stopping. Parameters Name Type Attributes Default Value Description marshal boolean <optional> false Marshal. Deprecated: This parameter is deprecated and will be removed. Example: Stop a script after 5s Script.setInterval(function () { print("Hello"); }, 1000); Script.setTimeout(function () { Script.stop(true); }, 5000);

---

Signal Details

doneRunning doneRunning( ) Returns: Signal
Triggered when the script has stopped.

entityScriptPreloadFinished entityScriptPreloadFinished( entityID ) Returns: Signal

Triggered when the script starts for the user. See also, Entities.preload. Supported Script Types: Client Entity Scripts • Server Entity Scripts Parameters Name Type Description entityID Uuid The ID of the entity that the script is running in. Example: Get the ID of the entity that a client entity script is running in var entityScript = function () { this.entityID = Uuid.NULL; }; Script.entityScriptPreloadFinished.connect(function (entityID) { this.entityID = entityID; print("Entity ID: " + this.entityID); }); var entityID = Entities.addEntity({ type: "Box", position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })), dimensions: { x: 0.5, y: 0.5, z: 0.5 }, color: { red: 255, green: 0, blue: 0 }, script: "(" + entityScript + ")", // Could host the script on a Web server instead. lifetime: 300 // Delete after 5 minutes. });

errorMessage errorMessage( message, scriptName ) Returns: Signal
Triggered when the script generates an error, console.error or console.exception is called, or console.assert is called and fails. Parameters Name Type Description message string The error message. scriptName string The name of the script that generated the error message.

infoMessahe infoMessage( message, scriptName ) Returns: Signal
Triggered when the script generates an information message or console.info is called. Parameters Name Type Description message string The information message. scriptName string The name of the script that generated the information message.

printedMessage printedMessage( message, scriptName ) Returns: Signal
Triggered when the script prints a message to the program log via print, Script.print, console.log, console.debug, console.group, console.groupEnd, console.time, or console.timeEnd. Parameters Name Type Description message string The message. scriptName string The name of the script that generated the message.

runningStateChanged runningStateChanged( ) Returns: Signal
Triggered when the running state of the script changes, e.g., from running to stopping.

scriptEnding scriptEnding( ) Returns: Signal
Triggered when the script is stopping. Example: Report when a script is stopping print("Script started"); Script.scriptEnding.connect(function () { print("Script ending"); }); Script.setTimeout(function () { print("Stopping script"); Script.stop(); }, 1000);

unhandledException unhandledException( exception ) Returns: Signal
Triggered when a script generates an unhandled exception. Parameters Name Type Description exception object The details of the exception. Example: Report the details of an unhandled exception Script.unhandledException.connect(function (exception) { print("Unhandled exception: " + JSON.stringify(exception)); }); var properties = JSON.parse("{ x: 1"); // Invalid JSON string.

update update( deltaTime ) Returns: Signal
Triggered frequently at a system-determined interval. Parameters Name Type Description deltaTime number The time since the last update, in s. Example: Report script update intervals Script.update.connect(function (deltaTime) { print("Update: " + deltaTime); });

warningMessage warningMessage( message, scriptName ) Returns: Signal
Triggered when the script generates a warning or console.warn is called. Parameters Name Type Description message string The warning message. scriptName string The name of the script that generated the warning message.