Scripting API

AudioAPI Reference

The Audio API provides methods to control sound logic.

Methods

deleteSound(url)

Delete the sound at the given URL completely.

Parameters

pauseSound(url)

Pause the sound at the given URL.

Parameters

playSound(url, loop, volume)

Play the sound at the given URL.

Parameters

stopSound(url)

Stop the sound at the given URL.

Parameters

ClientAPI Reference

Methods

getUserNameForConnectionID(id)

Talk more about that.

Arguments:

id (String)
String unique to each user.

Returns:

name (String)
The user’s name.

getConnectionIDForUserName(name)

Discuss the various ins and outs.

Arguments:

name (String)
The user’s name.

Returns:

id (String)
String unique to each user.

getAvatarForUserName(name)

What’s in a name?

Arguments:

name (String)
The user’s name.

Returns:

avatar (node)
The user’s 3D avatar.

focus(cid, nodeID)

Focus.

Arguments:

cid (String)
The client’s unique identification string.

nodeID (String)
The node’s unique identification string.

Returns:

(Nothing)

getCameraIDForClient(id)

Give me that thingamajig, so I can take a picture.

Arguments:

id (String)
The client’s unique identification string.

Returns:

cameraID (String)
The camera’s unique identification string.

getCameraForClient(id)

Now that we’ve got the camera, we are out of here!

Arguments:

id (String)
The client’s unique identification string.

Returns:

camera (node)
The first person camera for the user.

CommsAPI Reference

The communications properties and methods are used to chat, call, etc.

Methods

PM(from_client_id, to_client_id)

Yeah, I don’t know what that is. Private Messaging??

Arguments:

from_client_id (String)
Sending client’s identification string.

to_client_id (String)
Receiving client’s identification string.

Returns:

(Nothing)

Chat()

Opens a chat window.

Arguments:

(None)

Returns:

(Nothing)

VideoCall(from_client_id, to_client_id)

Establishes video call between two users.

Arguments:

from_client_id (String)
Sending client’s identification string.

to_client_id (String)
Receiving client’s identification string.

Returns:

(Nothing)

VoiceCall(from_client_id, to_client_id)

Establishes voice call between two users.

Arguments:

from_client_id (String)
Sending client’s identification string.

to_client_id (String)
Receiving client’s identification string.

Returns:

(Nothing)

Face Reference

In a FaceIntersect, the face is an object representing the polygon of the mesh that was intersected.

See FaceIntersect.

FaceIntersect Reference

An object representing the intersection of a ray or sphere cast with a simulation object.

See the traceAPI’s rayCast(origin, direction, options) and sphereCast(origin, radius, options) methods, which return FaceIntersect objects.

MATH Reference

A global MATH object provides commonly used vector manipulation functions.

Methods

crossVec3(a, b)

Returns the cross product between vector a and vector b.

Parameters

Return

Array[3] - the cross product.

distanceVec3(a, b)

Returns the distance between vector a and vector b.

1
2
3
4
5
6

    var distance = MATH.distanceVec3(position1, position2);

    if (distance < safe_distance)
    { 
        // ...
    }

Parameters

Return

Number - the distance between the two given vectors.

dotVec3(a)

Returns the dot product between vector a and vector b.

Parameters

Return

Array[3] - the resulting dot product.

lengthVec3(a)

Returns the length of vector a.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

    var attackRange = 300;
    var target = this.Scene.findNodeByID(this.aiTargetID);
    var targetPos;
    if (target)
    {
        targetPos = target.transformAPI.getWorldPosition();
        targetPos = this.transformAPI.globalToLocal(targetPos);
        if (MATH.lengthVec3(targetPos) < attackRange)
        {
            if (targetPos[0] < 0)
                this.doTurn('right')
            else
                this.doTurn('left');
        }
        else
        {
            this.aiActiveState = 'attack';
        }
    }

Parameters

Return

Number - the length of the vector.

subVec3(a, b)

Returns the result of subtracting vector a from vector b.

1

var direction = MATH.subVec3(position1, position2);

Return

Array[3] - the result of subtracting vector a from vector b.

toUnitVec3(a)

Returns a unitized version of the input vector a.

1

var norm_direction = MATH.toUnitVec3(direction);

Return

Array[3] - a unitized version of the input vector a.

PhysicsAPI Reference

The Physics API provides methods to apply forces, torques, and velocities to objects.

Methods

addForceAtCenter(x, y, z)

Applies a force at the center of mass of the object.

Parameters

addForceImpulse(x, y, z)

Applies a given acceleration represented by x, y, z (in world coordinates) to the object regardless of its mass.

Parameters

addForceOffset(x, y, z, x1, y1, z1)

Applies a force x, y, z at the position offset x1, y1, z1 from the object’s center of mass in world coordinates.

Parameters

addTorque(x, y, z)

Apply a rotational force whose direction is represented by x, y, z to the center of mass of the object.

Parameters

addTorqueImpulse(x, y, z)

Applies a given angular acceleration represented by x, y, z (in world coordinates) to the object regardless of its mass.

Parameters

getAngularVelocity()

Returns the vector x, y, z representing the rate of rotation in world coordinates.

Return

Array[3] - the rate of rotation in world coordinates.

getLinearVelocity()

Returns the vector x, y, z representing the rate of change of the object’s position in world coordinates.

Returns:

Array[3] - the rate of change of the object’s position in world coordinates.

setAngularVelocity(x, y, z)

Immediately set the object’s rate of rotation to the vector x, y, z in world coordinates.

Parameters

setLinearVelocity(x, y, z)

Immediately set the object’s rate of change in position to the vector x, y, z in world coordinates.

Parameters

wake()

Make an object wake up from its sleeping state.

Scene Reference

The Scene provides properties and methods accessible to all simulation objects.

Properties

SimTime

Returns the number of ticks that have been processed.

traceAPI

Returns the Scene’s traceAPI endpoint.

Methods

findNode(displayName)

Search the Scene for the provided simulation object displayName

Arguments:

displayName: the DisplayName of the simulation object to be found

Returns:

foundObject (object)

The simulation object matching the provided displayName or null if no matching object is found.

findNodeByID

Search the Scene for the provided simulation object ID.

Arguments:

ID: the ID of the simulation object to be found

Returns:

foundObject (object)

The simulation object matching the provided ID or null if no matching object is found.

Simulation Object Reference

Each Simulation Object provides properties and methods to manipulate the simulation object.

Properties

Any property that the object has defined will be availble. In addition, some standard properties are provided.

audioAPI

Read-only. AudioAPI - The simulation object’s AudioAPI endpoint.

children

Read-only. Array - An Array of child objects.

1
2
3
4

for (i = 0; i < this.children.length; i++)
{
    console.log(this.children[i].DisplayName);
}

children_by_name

Read-only. Object - An Object containing child objects.

1

var sphere2 = this.Scene.children_by_name["sphere1"].children_by_name["sphere2"];

client

Read-only. String - The socket identifier (GUID) of the person who sent the message that is being processed. On tick() it is null. A button’s onClick() this.client is the person who clicked the button.

1
2
3
4
5
6
7
8
9

function verifyCamera()
{
    if (!this.controllingCamera)
        return true;
    var cam = this.Scene.clientAPI.getCameraForClient(this.client);

    if (!cam || cam.id != this.controllingCamera) return false;
    return true;
}

See also the clientAPI. The clientAPI can be used to resolve the name of a client’s user.

DisplayName

String - The name of the object that appears in the Properties panel in the Editor.

EditorData

Object - A JSON object that defines which properties should be exposed through the Property Editor and which user interface controls should be provided.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
    "aiTargetID": {
        "displayname": "Target Object",
        "property": "aiTargetID",
        "type": "nodeid"
    },
    "fuel": {
        "displayname": "Fuel",
        "max": 1000,
        "min": 1,
        "property": "fuel",
        "type": "slider"
    },
    "hostile": {
        "displayname": "Hostile",
        "property": "hostile",
        "type": "check"
    }
}

moniker

Read-only. String - The client’s socket identifier (GUID).

See also the client property of a simulation object.

physicsAPI

Read-only. PhysicsAPI - The simulation object’s PhysicsAPI endpoint.

time

Read-only. Number - The current simulation time stamp. Duration since the server started the simulation.

transformAPI

Read-only. TransformAPI - The simulation object’s TransformAPI endpoint.

Methods

Any method that the object has defined will be available. In addition, some standard methods are provided.

bind(eventName, value)

Binds an event to a function definition.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

function ready()
{
    this.Scene.unbind("keyDown", this._kd);
    this.Scene.unbind("keyUp", this._ku);

    var self = this;

    this._kd = function(e, d)
    {
        self._keyDown(e, d)
    };

    this._ku = function(e, d)
    {
        self._keyUp(e, d)
    };

    this.Scene.bind("keyDown", this._kd);
    this.Scene.bind("keyUp", this._ku);
}

Parameters

broadcast(signal, data, range)

Calls the signal method passing the data array to any objects within the given range.

1
2
3

var leader_projection = this.transformAPI.localToGlobal(-150, 0, 0);

this.broadcast("facLeaderInput", [leader_projection], 500);

Parameters

random()

Return, preserving replicated computation, a random number between 0 (inclusive) and 1 (exclusive). Similar to JavaScript’s Math.random(), but is safe for replicated computation.

Return

Number - The generated random number between 0 and 1.

traceAPI Reference

Methods

rayCast(origin, direction, options)

Casts a ray from an origin in a given direction, sorting all the intersections with simulation objects, and returning the nearest intersection. All parameters are world space.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

        var offset = this.transformAPI.localToGlobalRotation(0, 0, 1);
        var center = this.transformAPI.getPosition();
        var hit = this.Scene.traceAPI.rayCast(center, offset,
        {
            ignore: [findviewnode(this.id)]
        });
        if (hit && hit.distance < 2)
        {
            this.explode();
            return;
        }

Parameters

options

Return

FaceIntersect - the nearest intersection of the ray cast.

sphereCast(origin, radius, options)

Used to find all polygons with an invisible sphere defined by radius, returning an array of all intersections. All parameters are world space.

Parameters

options

Return

FaceIntersect[] - an Array of intersections.

TransformAPI Reference

The TransformAPI provides methods to access and change an object’s position and rotation. The TransformAPI also provides methods to translate vectors between coordinate systems.

Methods

getPosition()

Return an object’s position relative to its parent.

Return

Array[3] - object position [x, y, z] relative to its parent.

getRotation()

Returns an object’s rotation relative to its parent (in Euler XYZ format).

Return

Array[3] - angles (in degrees) of rotation [x, y, z] relative to its parent.

getScale()

Return an object’s scale relative to its parent.

Return

Array[3] - object scale [x, y, z] relative to its parent.

getWorldPosition()

Return an object’s global position relative to the Scene.

Return

Array[3] - object’s global position [x, y, z] relative to the Scene.

globalRotationToLocalRotation(x, y, z)

Converts a global rotation to a local rotation.

Parameters

Return

Array[3] - containing local x, y and z values of local rotation.

globalToLocal(x, y, z)

Moves a point from global space to local space.

Parameters

Return

Array[3] - a point [x, y, z] in local space.

globalToLocalRotation(x, y, z)

Converts a global direction vector into the local coordinate system.

Parameters

Return

Array[3] - A direction vector [x, y, z] in the local coordinate system.

localToGlobal(x, y, z)

Moves a point from local space to global space.

Parameters

Return

Array[3] - a point [x, y, z] in global space.

localToGlobalRotation(x, y, z)

Converts a local direction vector into the global coordinate system.

Parameters

Return

Array[3] - A direction vector [x, y, z] in the global coordinate system.

lookAt(t, clamp, axis, up, fromOffset)

Set the rotation of the object to align the axis parameter (‘X’, ‘Y’, ‘-Y’, ‘Z’) to point at the t position (Array[3]). The up value (‘X’, ‘Y’, or ‘Z’) defines the rotation around the lookAt vector. clamp (‘X’, ‘Y’, or ‘Z’) can be used to force rotation on only one axis (defaults to null). fromOffset (Array[3]) is a position added to the object’s current position (defaults to null).

Parameters

move(x, y, z, coordinateSystem)

Moves an object by a given amount in meters.

Parameters

rotate(x, y, z, coordinateSystem)

Rotates the object by given amount (angles in degrees)

Parameters

rotateX(angle, coordinateSystem)

Rotates the object by the given angle (in degrees) around the (local or global) X axis.

Parameters

rotateY(angle, coordinateSystem)

Rotates the object by the given angle (in degrees) around the (local or global) Y axis.

Parameters

rotateZ(angle, coordinateSystem)

Rotates the object by the given angle (in degrees) around the (local or global) Y axis.

Parameters

rotateAroundAxis(angle, axis, coordinateSystem)

Rotates object around given axis by the given angle.

Parameters

setPosition(x, y, z)

Set an object’s position relative to its parent.

Parameters

setRotation(x, y, z)

Set an object’s rotation by the given angles (in degrees) (in Euler XYZ order) relative to its parent.

Parameters

setScale(x, y, z)

Set an object’s scale relative to its parent.

Parameters