FectarBlocks API

Version: 1.2.3
Date: 31-05-2022
Time: 15:01

Core module

Fectar Blocks core primitive types

Classes

Vector3

Representation of 3D vectors and points.

Static Properties

Name
Type
Read/Write
Description
back
Vector3
Read
Shorthand for writing Vector3(0, 0, -1).
down
Vector3
Read
Shorthand for writing Vector3(0, -1, 0).
forward
Vector3
Read
Shorthand for writing Vector3(0, 0, 1).
left
Vector3
Read
Shorthand for writing Vector3(-1, 0, 0).
one
Vector3
Read
Shorthand for writing Vector3(1, 1, 1).
right
Vector3
Read
Shorthand for writing Vector3(1, 0, 0).
up
Vector3
Read
Shorthand for writing Vector3(0, 1, 0).
zero
Vector3
Read
Shorthand for writing Vector3(0, 0, 0).

Properties

Name
Type
Read/Write
Description
magnitude
number
Read
Returns the length of this vector.
normalized
number
Read
Returns this vector with a magnitude of 1.
x
number
ReadWrite
X component. Axis points to the right.
y
number
ReadWrite
Y component. Axis points upwards
z
number
ReadWrite
Z component. Axis points away.

Constructors

Vector3 Vector3(number x, number y, number z)
Creates a new vector with given x, y, z components.
Parameter
Type
Description
x
number
y
number
z
number
Example
// Set a clicked spot to x,y,z-coordinates: (0, 0.5, 1).
function onClick(eventParams)
{
    eventParams.spot.position = new Vector3(0, 0.5, 1);
}

Static Methods

number Angle(Vector3 from, Vector3 to)
Returns the angle in degrees between the two vectors.
Parameter
Type
Description
from
Vector3
The vector from which the angular difference is measured.
to
Vector3
The vector to which the angular difference is measured.

Vector3 Cross(Vector3 lhs, Vector3 rhs)
Cross Product of two vectors.
Parameter
Type
Description
lhs
Vector3
Left hand side vector.
rhs
Vector3
Right hand side vector.

number Distance(Vector3 a, Vector3 b)
Returns the distance between a and b.
Parameter
Type
Description
a
Vector3
First position.
b
Vector3
Second position.

number Dot(Vector3 lhs, Vector3 rhs)
Dot Product of two vectors.
Parameter
Type
Description
lhs
Vector3
Left hand side vector.
rhs
Vector3
Right hand side vector.
Example
// Detect if spot 'mySpot' is behind the camera.
setInterval(()=> {
    var mySpot = Space.getSpot('mySpot');
    var offset = mySpot.position - Space.camera.position;

    if (Vector3.Dot(Space.camera.forward, offset) < 0)
        log('Object is behind me');
    else 
        log('Object is in front of me');
}, 1000);

Vector3 Lerp(Vector3 a, Vector3 b, number t)
Linearly interpolates between two points.
Parameter
Type
Description
a
Vector3
Start value, returned when t = 0.
b
Vector3
End value, returned when t = 1.
t
number
Value used to interpolate between a and b.

Quaternion

Representation of rotations. Beware this is a value type. If you want to set the rotation of the spot, you have to reassign the modified quaternion or use the rotationEuler property of the spot.

Static Properties

Name
Type
Read/Write
Description
identity
Quaternion
Read
The identity rotation.

Properties

Name
Type
Read/Write
Description
eulerAngles
Vector3
ReadWrite
Returns or sets the euler angle representation of the rotation.

Constructors

Quaternion Quaternion(number x, number y, number z, number w)
Constructs new Quaternion with given x,y,z,w components.
Parameter
Type
Description
x
number
y
number
z
number
w
number

Static Methods

Quaternion Euler(number x, number y, number z)
Returns a rotation that rotates z degrees around the z axis, x degrees around the x axis, and y degrees around the y axis; applied in that order.
Parameter
Type
Description
x
number
y
number
z
number

Quaternion Slerp(Quaternion a, Quaternion b, number t)
Spherically interpolates between quaternions a and b by ratio t. The parameter t is clamped to the range [0, 1].
Parameter
Type
Description
a
Quaternion
Start value, returned when t = 0.
b
Quaternion
End value, returned when t = 1.
t
number
Value used to interpolate between a and b.

Public Methods

Quaternion setLookRotation(Vector3 view, Vector3 up)
Creates a rotation with the specified forward and upwards directions.
Parameter
Type
Description
view
Vector3
The direction to look in.
up
Vector3
Optional up vector. The vector that defines in which direction up is. (Default Vector3.up).

Color

Representation of RGBA colors.

Properties

Name
Type
Read/Write
Description
a
number
ReadWrite
Alpha component.
b
number
ReadWrite
Blue component.
g
number
ReadWrite
Green component.
r
number
ReadWrite
Red component.

Constructors

Color Color(number r, number g, number b, number a)
Constructs a new Color with given r,g,b,a components.
Parameter
Type
Description
r
number
Red component.
g
number
Green component.
b
number
Blue component.
a
number
Alpha component.

Color Color(number r, number g, number b)
Constructs a new Color with given r,g,b components and sets a to 1.
Parameter
Type
Description
r
number
Red component.
g
number
Green component.
b
number
Blue component.

Debug module

All debug related functions and constants.

Public Methods

log(Object message)
Log any data to the debug log.
Parameter
Type
Description
message
Object
Object to write as string to the log.
Example
// Log the name of a clicked spot.
function onClick(eventParams)
{
    log(eventParams.spot.name);
}

Event module

All event related functions and constants.

Public Methods

onClick(Event params)
Implement this event handler to handle all click events.
Parameter
Type
Description
params
Event
event parameters
Example
// Implement an onClick event handler like this, to catch all clicks and taps.
// This example hides the spot that was clicked.
function onClick(eventParams)
{
    eventParams.spot.hide();
}


onCollision(CollisionEvent params) New
Implement this event handler in the global init() to handle all collision events.
Parameter
Type
Description
params
CollisionEvent
collision event parameters

Classes

Event

Event related functions and variables of the current event. You can use the globally declared Event instance to get information about the event triggered or implement a custom event handler to get an instance to this object as a parameter.

Properties

Name
Type
Read/Write
Description
spot
Spot
N/A
Spot object (null if not part of the event context).

CollisionEvent

Inherits from: Event
CollisionEvents are triggered when objects with physics enabled, collide. You can use the globally declared Event instance to get information about the event triggered or implement a custom event handler to get an instance to this object as a parameter.

Properties

Name
Type
Read/Write
Description
otherSpot
Spot
N/A
Other spot which spot collided with.

Physics module New

Let's get physical

Classes

Floor (static)

Object representing a floor used for collisions

Static Properties

Name
Type
Read/Write
Description
isEnabled
boolean
ReadWrite
Floor collider is enabled (default true). Set to false if you want to use your own floor collider.

Physics (static)

Physics related functions and variables

Static Properties

Name
Type
Read/Write
Description
floor
Floor
N/A
Invisible floor object used for collisions

SpotPhysics

Spot specific physics related functions and variables

Properties

Name
Type
Read/Write
Description
enabled
boolean
ReadWrite
Enable physics for a spot.
useGravity
boolean
ReadWrite
Controls whether gravity affects this spot.

Space module

Everything space related

Classes

Camera

An object representing a camera.

Properties

Name
Type
Read/Write
Description
forward
Vector3
Read
The forward vector of the camera. (Readonly)
position
Vector3
Read
Representation of 3D vectors and points. (Readonly)
rotation
Quaternion
Read
A Quaternion that stores the rotation of the Transform in world space. (Readonly)
rotationEuler
Vector3
Read
The rotation as Euler angles in degrees. (Readonly)

Spot

An object representing a spot.

Properties

Name
Type
Read/Write
Description
id
string
Read
Identifier (GUID) of the spot.
isAlwaysFacingCamera
boolean
ReadWrite
Get this value to determine if camera facing is active. When set to true, FacingCameraStart(false) will be used to let this spot always face the camera.
isPausing
boolean
ReadWrite
When this value is true, the spot will show no movement (except video, rotation of objects facing camera). [Unavailable during a network session]
isVisible
boolean
ReadWrite
When this value is true, the spot is visible.
name
string
Read
Name of the spot.
physics
SpotPhysics
N/A
Reference to a SpotPhysics object (see Physics Module). Enables control over all physics related parameters.
position
Vector3
ReadWrite
Get position in world space (relative to space origin) coordinates. Set to move the spot to its new location.
Example
// Set position of a spot named 'mySpot' to (0,0,0) when clicked.
function onClick(eventParams)
{
    let clickedSpot = eventParams.spot;
    if (clickedSpot.name == 'mySpot')
        clickedSpot.position = Vector3.zero;
}
rotation
Quaternion
ReadWrite
Get or set the rotation using a quaternion.
rotationEuler
Vector3
ReadWrite
Get or set the rotation using euler angles in degrees.
scale
Vector3
ReadWrite
Get or set the scale.
type
string
Read
Returns name of the type of the spot.

Public Methods

facingCameraStart(boolean allAxis)
Spot will always be facing the camera.
Parameter
Type
Description
allAxis
boolean
When true it will rotate over all axis (X,Y,Z). When left empty or to false (default) it will only rotate over Y-axis (billboarding).
Example
// Make any clicked spot always turn towards the camera when clicked.
function onClick(eventParams)
{
    eventParams.spot.facingCameraStart();
}

facingCameraStop()
Spot will stop facing the camera. It will be left at its current position. Use Spot.Reset() to return it to its initial position.

hide()
Hide a spot.

moveTo(Vector3 targetPos, number duration, Function onComplete)
Move a spot from its current position to a target position.
Parameter
Type
Description
targetPos
Vector3
Target position
duration
number
Duration in seconds
onComplete
Function
Optional parameter. OnComplete function called on movement completion.
Example
// Move spot mySpot to the position of a spot myTarget within 2 seconds. Hide mySpot when target is reached. 
function onClick(eventParams)
{
    let clickedSpot = eventParams.spot;
    if (clickedSpot.name == 'mySpot')
        clickedSpot.moveTo(Space.getSpot('myTarget').position, 2, function(){ 
            clickedSpot.hide(); 
        });
}


pause()
Pause a spot. All movement will stop (except video, rotation of objects facing camera). [Unavailable during a network session]

reset()
Resets position, rotation and scale to their initial values.

resume()
Resume a paused spot. Movement will continue from its current position (except video, rotation of objects facing camera). [Unavailable during a network session]

rotateTo(Vector3 eulerRot, number duration, Function onComplete) New
Rotate a spot from its current rotation to the nearest absolute target rotation (uses quaternion internally).
Parameter
Type
Description
eulerRot
Vector3
Rotation in euler angles.
duration
number
Duration in seconds.
onComplete
Function
Optional parameter. OnComplete function called on rotation completion.

show()
Show a spot.

stop()
Stops all automated movement (except video, rotation of objects facing camera). [Unavailable during a network session]

stopMove() New
Stops all automated movement started with moveTo. [Unavailable during a network session]

stopRotate() New
Stops all automated rotation started with rotateTo. [Unavailable during a network session]

Text3D

Inherits from: Spot
An object representing a 3D Text spot.

Properties

Name
Type
Read/Write
Description
color
Color
ReadWrite
Color of the text.
text
string
ReadWrite
Text to show.

VideoBasedSpot New

Inherits from: Spot
An object representing a video based spot.

Properties

Name
Type
Read/Write
Description
video New
SpotVideo
N/A
Reference to a SpotVideo object (see Video Module). Enables control over all video related parameters.

Video New

Inherits from: VideoBasedSpot
An object representing a video spot.

HoloPresenter New

Inherits from: VideoBasedSpot
An object representing a holo presenter spot.

Space (static)

Space related functions and variables

Static Properties

Name
Type
Read/Write
Description
camera
Camera
N/A
Main camera.
isPausing
boolean
ReadWrite
When this value is true, all spots will show no movement.
spotIds
ArrayOfString
Read
All spot ids.
spotNames
ArrayOfString
Read
All spot names.
spots
ArrayOfSpot
Read
All spot instances.
Example
// Go through all spots in the space and place them next to eachother.
for (let i = 0; i < Space.spots.length; i++)
    Space.spots[i].position = new Vector3(i, 0, 0);    

Static Methods

Spot getSpot(string spotName)
Get a spot object by name. Returns first spot matching the given name.
Parameter
Type
Description
spotName
string
Name of the spot
Example
// Get the spot named 'mySpot' and write the position to the log.
log(Space.getSpot('mySpot').position);

Spot getSpotById(string uuid)
Get a spot object by its identifier. Returns first spot matching the given uuid.
Parameter
Type
Description
uuid
string
Guid of the spot

boolean hide(string spotName)
Hide a spot. Returns true if spot was found and deactivated.
Parameter
Type
Description
spotName
string
Name of the spot

pause()
Pause all spots. All movement will stop.

reset()
Resets the space to its initial state.

resume()
Resume all paused spots. Movement will continue from its current position.

boolean show(string spotName)
Show a spot. Returns true if spot was found and activated.
Parameter
Type
Description
spotName
string
Name of the spot

Time module

All time related functions and constants.

Public Methods

bigint setTimeout(Function onTimeout, number delay)
The setTimeout() method sets a timer which executes a function or specified piece of code once the timer expires. Returns a handle to use with clearTimeout.
Parameter
Type
Description
onTimeout
Function
Function to call or code to execute.
delay
number
Interval in milliseconds.

clearTimeout(number timeoutHandle)
The clearTimeout() method clears a timer set with the setTimeout() method.
Parameter
Type
Description
timeoutHandle
number
The ID value returned by setTimeout() is used as the parameter for the clearTimeout() method.

bigint setInterval(Function onInterval, number delay)
The setInterval() method repeatedly calls a function or executes a code snippet, with a fixed time delay between each call. Returns a handle to use with clearInterval.
Parameter
Type
Description
onInterval
Function
Function to call or code to execute.
delay
number
Interval in milliseconds.
Example

Example 1:

// Create a log entry every 5 seconds setInterval(() => log('Another 5 seconds have passed.'), 5000);

Example 2:

// Rotate three spots to create a realtime analog clock let hands = ['hourHand', 'minutesHand', 'secondsHand']; // Get spot instances based on the names in the hands array let hourSpot = Space.getSpot(hands[0]); let minuteSpot = Space.getSpot(hands[1]); let secondSpot = Space.getSpot(hands[2]); // Set interval to update the clock every 1000 milliseconds (1 second) setInterval(() => { // Get the current time let now = new Date(); let seconds = now.getSeconds(); let minutes = now.getMinutes(); let hours = now.getHours() + (minutes / 60); // Get the rotations based on the time let rotationHours = Quaternion.Euler(0, 0, hours / 12 * 360); let rotationMinutes = Quaternion.Euler(0, 0, minutes / 60 * 360); let rotationSeconds = Quaternion.Euler(0, 0, seconds / 60 * 360); // Rotate around Z hourSpot.rotation = rotationHours; minuteSpot.rotation = rotationMinutes; secondSpot.rotation = rotationSeconds; // Position the spots hourSpot.position = rotationHours * Vector3.up; minuteSpot.position = rotationMinutes * Vector3.up; secondSpot.position = rotationSeconds * Vector3.up; }, 1000);

clearInterval(number intervalHandle)
The clearInterval() method clears a timer set with the setInterval() method.
Parameter
Type
Description
intervalHandle
number
The ID value returned by setInterval() is used as the parameter for the clearInterval() method.
Example
// Hide and show 'mySpot' every 500 milliseconds for a total of 3 seconds. 
let mySpot = Space.getSpot('mySpot');
// Toggle visibility every 500 ms and store a handle to the interval in myInterval.
let myInterval = setInterval(() => mySpot.isVisible = !mySpot.isVisible, 500);
// Clear the interval after 3 seconds have passed.
setTimeout(() => {
    clearInterval(myInterval);
    // Make sure the spot is visible at the end of this blinking sequence.
    mySpot.isVisible = true;
}, 3000);

Classes

Time (static)

Time related class with functions and constants.

Static Properties

Name
Type
Read/Write
Description
deltaTime
number
Read
The interval in seconds from the last frame to the current one.
time
number
Read
The time in seconds since the start of the application.

Utility module

All utility related functions and constants.

Classes

Util (static)

Utility related class with functions and constants.

Static Methods

Color hexToColor(string hexColor)
Converts hexadecimal string to color object. Returns black color with alpha 0 when parse fails.
Parameter
Type
Description
hexColor
string
Hexadecimal color (ex. #FF0000 is red)

Video module New

Video killed the radio star

Classes

SpotVideo New

Spot specific video related functions and variables

Properties

Name
Type
Read/Write
Description
isLooping New
boolean
ReadWrite
Returns true when video is played in a loop. Set true to let video repeat itself indefinitely.
isPausing New
boolean
ReadWrite
Returns true when video is paused. Set true to pause or false to resume.
length New
number
Read
Duration of the video in seconds.
pauseOnClick New
boolean
ReadWrite
Pause video on click. (default: true)
time New
number
ReadWrite
Absolute playback time in seconds. Set to jump to time.
timeProgress New
number
ReadWrite
Relative playback time. Value is from 0 to 1 where 1 is the end of the video. Set to jump to time.

Public Methods

Pause() New
Pauses the video.

Resume() New
Resumes playback of the video.

Rewind() New
Resets the playhead to the beginning of the video.

Migration

Old Version New Version
NrModuleScript NrModuleScript
<= v0.2.2aglobalspotId => v0.2.3aEventEvent.spot.name
<= v0.2.2aDebugString test(Number) => v0.2.3anonenone

Version

Version number contains a major, minor and patch number.
Major number will be incremented when there are incompatible API changes.
Minor number will be incremented on each release of the APP, but only if there were any changes to the API. All changes will be backwards compatible.
Patch number will be incremented with each set of bug fixes and internal releases.
The letter suffix will specify if it's:
a - alpha version, for internal use only
b - beta version, for test purposes only, allowed for external beta testers
f - final version, tested and not subject to any breaking changes