Skip to content

API - Objects

Allows manipulation of objects in the 3D environment.

When extending BasePlugin, these functions can be accessed via this.objects.*

When extending BaseComponent, these functions can be accessed via this.plugin.objects.*

Properties

When 3D objects are created in the world, you can assign properties to them to define how they look and behave.

Below is a list of the available object properties

Field Type Editable Description
id string Identifier for the object. Automatically set when an object is created
dateModified number UNIX timestamp in milliseconds of the last time an object was updated. Automatically set when an object is created or modified
dimension string Identifier of the server to which this object belongs. Automatically set when an object is created
type string Type of an object. Once the type has been set, it cannot be changed. Available options are:
  • 'model' : 3D model
  • 'image' : Image
  • 'text' : 2D text
  • 'plane' : 2D square
  • 'triangle' : 2D triangle
  • 'circle' : 2D circle
  • 'cylinder' : 3D cylinder
  • 'torus' : 3D torus
  • 'tube' : 3D tube
  • 'cube' : 3D cube
  • 'sphere' : 3D sphere
  • 'group' : Used to group multiple items together
  • 'zone' : Audio zone
parent string Identifier of another object that is the parent of this object. All parent transformations will be applied to this object as well
x number The X position in 3D space
height number The Y position (height) in 3D space
y number The Z position (depth) in 3D space
collide boolean true to allow object to collide with the user and prevent the user from walking through it, false otherwise
alpha_test number Pixel intensities above this value will be rendered and pixel intensities below this value will not be rendered. Default is 0, meaning all pixels will be rendered
depth_write string Can be either 'on' or 'off'. When 'on', the rendering of this object has an effect on the depth buffer. Default is 'on'
hidden boolean true to not render the object, false otherwise
disabled boolean true to not load the object, false otherwise
render_order number Minimum value is 0. Low values indicate higher rendering priority, whereas high values indicate lower rendering priority
rotation_x number Rotation, in radians, along the X axis
rotation_y number Rotation, in radians, along the Y (height) axis
rotation_z number Rotation, in radians, along the Z (depth) axis
rotation_speed number Number of radians to rotate per second around the Y axis
rotate_with_camera boolean true to rotate this object so that it always looks at the camera, false otherwise. Default is false
rotate_with_camera_axes_x boolean true to rotate this object along the X axis when rotate_with_camera is enabled, false otherwise. Default is false
rotate_with_camera_axes_y boolean true to rotate this object along the Y (height) axis when rotate_with_camera is enabled, false otherwise. Default is true
rotate_with_camera_axes_z boolean true to rotate this object along the Z (depth) axis when rotate_with_camera is enabled, false otherwise. Default is false
quatX number Quaternion rotation along the X axis. Automatically set when rotation changes
quatY number Quaternion rotation along the Y axis. Automatically set when rotation changes
quatZ number Quaternion rotation along the Z axis. Automatically set when rotation changes
quatW number Quaternion rotation along the W axis. Automatically set when rotation changes
scale number Uniform scale to apply along all axes
scale_x number Scale to apply along the X axis
scale_y number Scale to apply along the Y (height) axis
scale_z number Scale to apply along the Z (depth) axis
world_center_x number World X co-ordinate of the object
world_center_y number World Y (height) co-ordinate of the object
world_center_z number World Z (depth) co-ordinate of the object
world_bounds_x number Bounding box X value
world_bounds_y number Bounding box Y (height) value
world_bounds_z number Bounding box Z (depth) value
shading string Determines the shading model to use. Available options are: '', 'standard', 'basic', 'phong', 'lambert', or 'custom'. See custom shader for additional properties when using 'custom' shading
server_tick_enabled boolean true to run the component's onServerTick() function every 30 seconds, false otherwise. Automatically set when adding and removing components
targetable boolean true to allow object to be clicked, false otherwise. Default is true
temporary boolean true to indicate that this is a temporary object, false otherwise. Default is false. Temporary objects can be created by anyone, even guest users, but they will be removed from the space a minute or so after that user leaves
temporary_owner_id string Identifier of the owner of the temporary object, when temporary is enabled
temporary_keepalive number UNIX timestamp in milliseconds since the last time this object was kept alive. Automatically updated every few minutes

Shape

When an object has a type of 'plane', 'circle', 'cylinder', 'triangle', 'torus', 'cube', 'sphere' or 'tube', the following additional properties are available and editable

Field Type Description Example
url string URL of the image to display on the shape ''
color string CSS color value to use if there is no url specified. Default is '#FFFFFF' '#0074CC'
transparent boolean true to allow light to pass through the object so that objects behind can be seen, false otherwise. Default is false true
opacity number Minimum is 0 and maximum is 1. Determines how transparent the object is if transparent is enabled, where 0 indicates that the object will not be visible and 1 indicates that the object will be visible 0.68
doublesided boolean true to allow the object to be viewable from all directions, false otherwise. Default is false true

Image

When an object has a type === 'image', the following additional properties are available and editable

Field Type Description Example
image_repeat_x number Number of times to repeat the image along the X axis 3
image_repeat_y number Number of times to repeat the image along the Y axis 2

Model

A model is a 3D object that has been added into a space.

When an object has a type === 'model', the following additional properties are available and editable

Field Type Description Example
url string URL of the .glb model to display ''
animation_rules object[] List of animation rules. Defaults to playing the first animation in the .glb file if empty []
use_original_scale boolean true to use original model size, false otherwise. Default is true true
do_not_clone boolean true to load multiple objects with the same URL independently of one another, false to only load multiple objects with the same URL once. Setting this value to false helps with performance, but causes issues when changing material properties or animations. Default is false false

Custom Shader

You can apply a custom shader to a model or shape with these properties.

Field Type Description Example
shading string Set to 'custom' to use a custom shader 'custom'
vertex_shader string Vertex shader written in GLSL See here
fragment_shader string Fragment shader written in GLSL See here
fragment_shader_shadertoy boolean true if the fragment shader is in ShaderToy image format, false otherwise. Default is false false

Zones

Zones allow you to specify different audio settings based on the position of the user. Used mainly to setup private conversation squares.

Zone properties are cumulative when nested, meaning if you have a zone within a zone, the smaller inside zone will have its settings default to the values provided in the bigger zone.

When an object has a type === 'zone', the following additional properties are available and editable

Field Type Description Example
zone_audio_attenuation number Defines how quickly sound falls away. A value of 0.0001 means sound is fully loud at all distances, while 0.9999 means only those directly near a user could hear them. Default is 0.5 0.81
zone_audio_disable_inbound boolean true to prevent audio from outside entering this zone, false otherwise. Default is false true
zone_audio_disable_outbound boolean true to prevent audio from inside exiting this zone, false otherwise. Default is false false

Group

A group is an invisible container item with type === 'group'. It can be used to group multiple items and apply transformations to them all at once.

Functions

create(props) : string

Creates a local object and returns the ID of that created object.

Field Type Description Example
props properties Properties to use when creating the object { type: 'plane', scale_x: 16 / 9 }

update(id, props, localOnly)

Updates properties on an object.

Field Type Description Example
id string Identifier used to find the object that should be updated '042ed071-649c-4601-9a30-669a59c9e1ee'
props properties Properties to update { color: '#0074CC' }
localOnly boolean true to only update the object for the user calling this method, false to update for all users in the space. Default is false false

remove(id)

Deletes an object.

Field Type Description Example
id string Identifier used to find the object that should be deleted '042ed071-649c-4601-9a30-669a59c9e1ee'

get(id) : object

Returns the properties for an object.

Field Type Description Example
id string Identifier used to find the object properties '042ed071-649c-4601-9a30-669a59c9e1ee'

fetchInRadius(centerX, centerY, radius) : object[]

Returns the properties for each object found within the circle formed by the center co-ordinates and radius.

Field Type Description Example
centerX number Center x co-ordinate 2.1
centerY number Center y co-ordinate 3.8
radius number Radius around the center point in which objects should be fetched 5

registerComponent(Class, options)

Register a component class. Class must be a subclass of BaseComponent.

Properties available for the options parameter

Field Type Description Example
id string Identifier for the component 'my-component'
name string Name of the component 'My Component'
description string A short description of this component 'Some short description'
settings object[] Settings that the user is able to modify. See below for all available properties for each setting object inside this array [{ id: 'hi', name: 'Text', help: 'Enter your favourite quote', type: 'text' }]

Properties available for the settings property

Field Type Description Examples
id string Identifier for the setting 'my-component-settings'
name string Name of the setting 'Score Increase'
help string Additional information about the setting 'How many points to add to score'
readonly boolean true to not allow editing of the setting, false otherwise false
type string Determines the type of input to show. Available options are:
  • 'text' : Shows a one-line text input
  • 'textarea' : Shows a multi-line text input
  • 'number' : Shows an input that only accepts numbers
  • 'select' : Shows a dropdown of items that can be chosen
  • 'checkbox' : Shows a checkbox that can either be enabled or disabled
  • 'button' : Shows a button that triggers onAction(id) when clicked
  • 'color' : Shows a color picker that returns a hexadecimal value
  • 'slider' : Shows a slider to select a value between a minimum and maximum
  • 'label' : Shows a text label
  • 'section' : Shows a big text label, used mainly to group inputs into sections
'number'
default number Default number to use when type === 'number' 5.2
value any Value to display in the input field. Must be a number when type === 'number' or type === 'slider', a boolean when type === 'checkbox' and a string otherwise 'Some value'
values string[] Array of possible values to select from when type === 'select' ['Facebook', 'Amazon', 'Apple', 'Netflix', 'Google']
percent boolean true to show values as a percent, false otherwise. Only applies when type === 'slider' false
min number Minimum number the value can be, when type === 'slider' -2
max number Maximum number the value can be, when type === 'slider' 19
precision number How many numbers to show after the decimal point, when type === 'slider' 1
fill boolean true to fill up the slider when changing the value, false otherwise. Only applies when type === 'slider' true
showValue boolean true to show the current value, false otherwise. Only applies when type === 'slider' false
Back to top