Discussions

Scene

This module is a high level scene graph manipulation and query library.

If you would like to test these methods with the examples provided, please use the provided testing sandbox at the bottom of the page.

The Query Object

Each of these methods allows for a query object to be passed as a parameter. You can use an object with the following key:value pairs:

{
  from: 'String', // ID of the ____
  name: 'String', // Node you are querying for
  plug: 'String', // Plug you are querying for. Material, Translation, etc. 
  property: 'String', // Property the belongs to the queried plug. 
}

or you can use an array that defines the path to your query. 

[from, plugs, plugName, index, property]

Examples

{ 
  name: 'Cooler', 
  plug: 'Transform', 
  property: 'rotation', 
}

The Cooler -> Transform -> rotation object above will accomplish the same thing as the array below. You can find this path array using the find method.

['54f3a9f3-3ed1-4486-b5e7-9025fa0d9559', 'plugs', 'Transform', 0, 'rotation']

Using Regex

When querying a node by name, you may use a string or regular expression object. If you’re querying a node whose name has special characters, it’s recommended that you use a RegEx object for simplicity. Below are some examples of using a RegEx object to query nodes with various special characters in their names.

player.scene.get([player.scene.findNode({name: /Sphere\$/}), 'name']);
>> "Sphere$"
player.scene.get([player.scene.findNode({name: /Sphere\^/}), 'name']);
>> "Sphere^"
player.scene.get([player.scene.findNode({name: /Sphere\+/}), 'name']);
>> "Sphere+"
player.scene.get([player.scene.findNode({name: /Sphere\"/}), 'name']);
>> "Sphere\""

You can also use strings to query nodes by name, but these strings are not taken literally. Some of their special characters are replaced, and then the string is compiled into a RegEx in the form /^ReplacedString$/i. “ReplacedString" being the string that had some of its special characters replaced.

( and ) are escaped automatically, thus they are treated literally. You can’t do a ReGex “Group” via a string, you must use an actual RegEx object to achieve groups

* is converted to the regex (.*), thus behaving like a simple wildcard, the same as if you use * in a Google search

If the string starts or ends with a double-quote, ", it is removed. Thus, if you’re node name is something like "Ugly" Fabric, your string must be:
player.scene.get([player.scene.findNode({name: "\"\"Ugly\" Fabric"}), 'name'])

Here are the above examples implemented via strings:

// note, the name of the node ended with a space, not the "+" sign
player.scene.get([player.scene.findNode({name: "Sphere\\+ "}), 'name']);
>> "Sphere+ "

// first and last character are stripped if they are double-quotes, so I need to put 2
player.scene.get([player.scene.findNode({name: "Sphere\"\""}), 'name']);
>> "Sphere\""

player.scene.get([player.scene.findNode({name: "Sphere\\^"}), 'name']);
>> "Sphere^"

player.scene.get([player.scene.findNode({name: "Sphere\\$"}), 'name']);
>> "Sphere$"

Get All

getAll method will return object(s) of { nodeId: value } for all values that match the query.

Finds all nodes:

player.scene.getAll(null || QueryObject)

Examples

You query for and get all matching values for something as simple as the node's name:

player.scene.getAll({name: 'coolerMesh'})

{
   "a5628847-6af9-4bf8-a50a-de97a4388a31":{
      "id":"a5628847-6af9-4bf8-a50a-de97a4388a31",
      "name":"coolerMesh",
      "type":"PolyMesh",
      "plugs":{
         "PolyMesh":[],
         "Transform":[],
         "Properties":[],
         "Material":[]
      },
      "children":[],
      "parent":"f508e33a-d5b2-439d-ad8d-57ead4851a99",
      "sceneId":"88dd117b-3678-4aa5-870a-c82ae380f8a3",
      "_v":3
   }
}

You can provide additional parameters to your query:

player.scene.getAll({
  name: 'coolerMesh', 
  plug: 'Material', 
  property: 'defaultColor'
})

{
  "cf1a718a-5968-4b8a-bbf6-b5b660cc9cb5":
  {
    "r":0.6901960784313725,
    "g":0.6901960784313725,
    "b":0.6901960784313725
  }
}

Get

get method will return the value matching the query. An empty query will return the top level node.

player.scene.get(QueryObject)

Examples

player.scene.get({name: 'coolerMesh'})

{
   "id":"27f9ae9c-8f42-4ba9-9671-f87f926a9a07",
   "name":"coolerMesh",
   "type":"PolyMesh",
   "plugs":{
      "PolyMesh":[],
      "Transform":[],
      "Properties":[],
      "Material":[]
   },
   "children":[
      
   ],
   "parent":"9035187b-7dba-40a7-8830-d03dc3fde1f8",
   "sceneId":"6403ef24-5a4e-4043-9309-488607af8941",
   "_v":3
}

player.scene.get({
  name: 'coolerMesh', 
  plug: 'Material', 
  property: 'reference'
})

'ff335b7a-92fc-484d-a242-ff01e7c5391f'

Find

find method will locate the first matching query & return its path. An empty query will return the top-level node's ID.

player.scene.find(QueryObject)

Examples

player.scene.find({name: 'Cooler'})

['54f3a9f3-3ed1-4486-b5e7-9025fa0d9559']

player.scene.find({
  name: 'Cooler', 
  plug: 'Transform', 
  property: 'rotation'
})

['54f3a9f3-3ed1-4486-b5e7-9025fa0d9559', 'plugs', 'Transform', 0, 'rotation']

Find Node

findNode method will locate the first matching node & returns its ID. An empty query will return the top-level node's ID.

player.scene.findNode(QueryObject)

Examples

player.scene.find({type: 'PolyMesh'})

or

player.scene.find({name: 'coolerMesh'})

Although the queries are different, they will resolve to the same node because the coolerMesh is the first node with the type of PolyMesh:

['961841c9-6b92-4ea2-bdca-6cfc25ecc768']

Filter

filter method will return an array of all matching paths to a query. 

player.scene.filter(QueryObject)

Examples

player.scene.filter({
  type: 'PolyMesh', 
  plug: 'Transform', 
  property: 'rotation'
})

[
 ["391c3593-4c8e-4635-987f-a1a2394aecda","plugs","Transform",0,"rotation"],
 ["f823a979-4d67-446d-bb1f-177404c75e62","plugs","Transform",0,"rotation"],
 ["3e5081d3-4a60-42af-8797-aa7cff4cb7bb","plugs","Transform",0,"rotation"],
 ["558b6438-6ef5-45be-b676-314a48810248","plugs","Transform",0,"rotation"],
 ["d5abeac3-5fb7-4002-9927-32ce2bdf6094","plugs","Transform",0,"rotation"],
 ["0f58121c-d7ec-4ed4-949a-71b076184742","plugs","Transform",0,"rotation"],
 ["1f3a95cf-7ba5-46f2-9f0b-6ab305a36b7a","plugs","Transform",0,"rotation"],
 ["de5fcbe9-228b-4c69-9e7e-de440484d7d4","plugs","Transform",0,"rotation"],
 ["40e6255b-fd14-47da-929e-c6646d5923b6","plugs","Transform",0,"rotation"],
 ["4457cd9a-41ff-4708-994a-1c9a8ce3ab63","plugs","Transform",0,"rotation"]
]

Filter Nodes

filterNodes method returns an array of all node IDs that match the query.

player.scene.filterNodes(QueryObject)

Examples

player.scene.filterNodes({type: 'PolyMesh'})

["5ed10727-5dbc-429f-b0f1-b566157fa71a", "2cf1a3f8-8529-4bec-8d24-7978eac41520", ...]

Set

set method will set some value at the first query match. This method will accept two parameters: QueryObject and value. The value parameter must follow the format of the property being set (object, string, boolean, etc.).

player.scene.set(QueryObject, value)

Examples

player.scene.set(
  {
   name: "meterArrow_GEO", 
   plug: 'Transform', 
   property: 'rotation'
  }, 
  {x: 0,y: 50, z: 0}) // rotation property is an object with x, y, z values

{
    "path": [
        "45a82fe7-de94-413e-9639-fb9928a4706f",
        "plugs",
        "Transform",
        0,
        "rotation"
    ],
    "value": {
        "x": 0,
        "y": 50,
        "z": 0
    }
}

This particular example is subtle, zoom in on the meter to see it:

Set All

setAll method will set some value for each of the query matches.

player.scene.setAll(QueryObject, value)

Examples

scene.setAll(
  {
  from: editingAssetId, 
  plug: 'Transform', 
  property: 'translation'
  }, {x: 3, y: 4, z: 5})

[{…}, {…}, {…}, {…}, …]

Reparent

reparent method will set a new parent for all of the children in the array.

player.scene.reparent(parentId, childIds, index)
ParemeterTypeDescription
parentIdStringID of the new parent
childIdsArrayIDs of the children we're updating
indexIntegerOptional child index in the new parent

Examples

let parentId = '3352d9bb-9841-465a-a872-d3bf3c74b42a'; // ID of the new parent
let childIds = ['f4732ef7-4477-48d4-94fa-34e211e51c23']; // IDs of the children you are updating
let index; // Index of the optional child index in the new parent
player.scene.reparent(parentId, childIds, index) 

{
  parentId: "b35e489e-17b2-406e-b9eb-5d46bd21a737", 
  childIds: Array[1], 
  index: 0
}

Add Node

addNode method will add a node to the scene.

player.scene.addNode(Node)

Examples

player.scene.addNode(
  {
    name: "My Node",
    type: "PolyMesh"
  },"3352d9bb-9841-465a-a872-d3bf3c74b42a" // ID of the parent node for the new node
)

"32f1ea99-bfb9-4831-9f7f-46ad07c99a51"

Delete Node

deleteNode method will delete a node from a scene.

player.scene.deleteNode(NodeID)

Example

player.scene.deleteNode("52fa1c1b-2995-4980-b8f0-aa3158bc3c9c")

{
    "value": [
        "52fa1c1b-2995-4980-b8f0-aa3158bc3c9c"
    ],
    "type": "Node",
    "path": [
        "0b13c621-4ba7-42a0-8770-be44afdb4c79",
        "children"
    ]
}

Add Operator

addOperator will add an operator to a node.

player.scene.addOperator(nodeId, plugType, operatorType, operatorObject)
ParameterTypeDescription
nodeIdStringThe id of the node receiving the operator
plugTypeStringThe plug that is receiving the operator
operatorTypeStringThe type of operator being added
operatorObjectObjectThe details of the operator

Examples

let nodeId = "53f3ff02-8151-46ce-8831-d3e91285e024";
let plugType = "Material";
let operatorType = "Falloff";
let operatorObject = {color: {"r":0.5725490196078431,"g":0.09803921568627451,"b":0.09803921568627451}, strength: 1};

player.scene.addOperator(nodeId, plugType, operatorType, operatorObject)

Add Attribute

addAttribute method will add a configurator attribute.

player.scene.addAttribute(Attribute)

Examples

player.scene.addAttribute({
    type: "String", 
    name: "Attribute Name", 
    values: ['Hey there', 'other'], 
    defaultValue: 'Hey there'
  })

Fetch

fetch method will fetch an asset and make it available for querying sceneGraph data.

player.scene.fetch(AssetID)

Examples

player.scene.fetch(NodeId)

"a11fb954c6956a6e72a0c3bdbd2eb94bca94c5a7"

Align Node

alignNode method will move a provided nodeId to align with another.

player.scene.alignNode(nodeId, alignNodeId, options)
ParameterTypeDescription
nodeIdStringThe node that will be aligned.
alignNodeIdStringThe node nodeId will align with.
options.anchorNodeIdStringOptional - the child of nodeId that will be aligned with alignNodeId. If left undefined, nodeId itself will be aligned to alignNodeId.
options.withRotationBooleanDefault is false. When set to true, both position and rotation of alignNodeId and anchorNodeId will be same after alignment.

Examples

let nodeId = "d42068b1-8d2f-4c08-9935-68bb8de66bf6";
let alignNodeId = "143527fc-5f14-44de-ab35-48fa6099eb22";
let options = {anchorNodeId: "73988328-944f-4f8f-8fe9-5f65108a4950", withRotation: true};
player.scene.alignNode(nodeId, alignNodeId, options)

Merge Meshes

mergeMeshes method will merge the meshes specified by nodeIds, and creates a single mesh with the name specified by mergedName

player.scene.mergeMeshes(nodeIds, mergedName, options)
ParameterTypeDescription
nodeIdsArray || QueryObjectIds of the nodes to merge, or query that selects those meshes
mergedNameStringName of the resulting merged mesh
options.throwOnWarningsBooleanIf the command has warnings, throw an error. Defaults to true.

Scene Graph Sandbox

🚧

Warning

IDs returned from these calls will be different than what is in the examples. SceneGraph IDs are generated at loadtime and do not persist.