Player API
-
DarkLight
Modules
- Camera
This module is for manipulating the camera.
- Configurator
This module is used to interact with the active configurator.
- Player
This is the root player api object, from which all other modules are accessed.
- Scene
This module is a high level scene graph manipulation and query library.
- Either id, name, or regex's can be used for node names.
- All
get
functions return the value, or undefined if no match is found - All
find
functions return anid
or a Path - All
filter
functions return an array ofid
or Path
- Selection
This module is used to interact with the current scene selection set, which is the set of currently selected nodes in the active scene.
- Tools
This module is for interacting with tools, which are responsible for updating the scene based on keyboard, mouse, and touch interfaces.
The default set of tools installed will handle scene navigation (orbit, pan, zoom).
Functions
- InitManipulator(player) ⇒
Object
- UpdateManipulator(player) ⇒
void
- HoverManipulator(player, [obj], [intersection]) ⇒
boolean
- ToolEventHandler(ev) ⇒
void
Typedefs
- QueryObject :
object
- Color :
object
- SelectionSetStyle :
object
- WidgetResult :
object
- Manipulator :
object
- EventControllerMouseEvent :
object
- ToolEventHandlers :
object
- Tool :
object
Camera
This module is for manipulating the camera.
Camera~orbit(dx, dy)
Orbit the active camera.
Kind: inner method of Camera
Param | Type |
---|---|
dx | number |
dy | number |
Example
player.camera.orbit(1, 0);
Camera~pan(dx, dy)
Pan the active camera.
Kind: inner method of Camera
Param | Type |
---|---|
dx | number |
dy | number |
Example
player.camera.pan(1, 0);
Camera~zoom(delta)
Zoom the active camera.
Kind: inner method of Camera
Param | Type |
---|---|
delta | number |
Example
player.camera.zoom(1);
Camera~frameBoundingSphere([assetIds], [direction], [options])
frame the active camera.
Kind: inner method of Camera
Param | Type |
---|---|
[assetIds] | Array.<String> |
[direction] | Vector3 |
[options] | any |
Example
player.cameraController.frameBoundingSphere();
Camera~getPosition([target])
get the active camera's position
Kind: inner method of Camera
Param | Type |
---|---|
[target] | Vector3 |
Example
console.log(player.cameraController.getPosition(tmpVector3));
Camera~setPosition([position])
set the active camera's position
Kind: inner method of Camera
Param | Type |
---|---|
[position] | Vector3 |
Example
player.cameraController.setPosition(new Vector3(0, 0, 10));
Camera~getQuaternion([target])
get the active camera's quaternion
Kind: inner method of Camera
Param | Type |
---|---|
[target] | Quaternion |
Example
console.log(player.cameraController.getQuaternion(tmpQuaternion));
Camera~setQuaternion([quaternion])
set the active camera's quaternion
Kind: inner method of Camera
Param | Type |
---|---|
[quaternion] | Quaternion |
Example
player.cameraController.setQuaternion(new Quaternion().setFromAxisAngle(new Vector3(0,1,0), Math.PI));
Configurator
This module is used to interact with the active configurator.
- Configurator
- ~getAttributes() ⇒
object.<string, any>
- ~getMetadata() ⇒
object.<string, any>
- ~getConfiguration() ⇒
object.<string, any>
- ~setConfiguration(conf) ⇒
object.<string, any>
- ~prefetchAttributes(attributes) ⇒
Promise.<void>
- ~getAttributes() ⇒
Configurator~getAttributes() ⇒ object.<string, any>
Returns all enabled attributes.
Kind: inner method of Configurator
Configurator~getMetadata() ⇒ object.<string, any>
Returns all metadata.
Kind: inner method of Configurator
Configurator~getConfiguration() ⇒ object.<string, any>
Retrieves the active configuration with the form { [attributeName]: value }
.
Kind: inner method of Configurator
Configurator~setConfiguration(conf) ⇒ object.<string, any>
Sets the active configuration.
Kind: inner method of Configurator
Param | Type |
---|---|
conf | object.<string, any> |
Example
const configurator = await player.getConfigurator();
configurator.setConfiguration({ Color: 'Blue' });
Configurator~prefetchAttributes(attributes) ⇒ Promise.<void>
Prefetches all images for attributes specified to improve loading performance (only applies to 2D player).
Kind: inner method of Configurator
Param | Type |
---|---|
attributes | Array.<string> |
Example
const configurator = await player.getConfigurator();
await configurator.prefetchAttributes(['Rotation'])
Player
This is the root player api object, from which all other modules are accessed.
Scene
This module is a high level scene graph manipulation and query library.
- Either id, name, or regex's can be used for node names.
- All
get
functions return the value, or undefined if no match is found - All
find
functions return anid
or a Path - All
filter
functions return an array ofid
or Path
Scene~find(query)
Finds first matching node. (See {@tutorial sdk-SceneGraph})
Kind: inner method of Scene
Param | Type | Description |
---|---|---|
query | QueryObject |
The query object to filter on. |
Example
// Return the node uuid
scene.find({ name: 'Box' }); -> ['uuid']
// Return the path to the transform operator
scene.find({ name: 'Box', plug: 'Transform', property: 'translation' }); -> ['uuid','plugs','Transform',0]
// Match the first node that starts with Box
scene.find({ name: 'Box*' });
Scene~fetch(id)
Fetch an asset, to make it available for querying sceneGraph data.
Kind: inner method of Scene
Param | Type | Description |
---|---|---|
id | String |
Asset id to fetch |
Scene~alignNode(nodeId, alignNodeId)
Move nodeId
to align with alignNodeId
, optionally using anchorNodeId
to do the alignment.
Kind: inner method of Scene
Param | Type | Description |
---|---|---|
nodeId | String |
The node that will be aligned. |
alignNodeId | String |
The node |
options.anchorNodeId | String |
Optionally, the child of |
options.withRotation | boolean |
Default is false. When set to true, both position and rotation of |
Example
// Move the sword to place the sword handle in the hand
scene.alignNode(swordId, handId, { anchorNodeId: swordHandleId, withRotation: true });
"PHASES"
There are three events that are triggered in turn as the scene loads: PRELOADED, LOADED, and RENDERED.
Kind: event emitted by Scene
Read only: true
Properties
Name | Description |
---|---|
PHASES.PRELOADED | Emitted when the scene and all assets necessary to render the scene have been loaded. Occurs before the 'loaded' event, and is an opportunity to modify the scene before it becomes visible. A change here might trigger more loading. |
PHASES.LOADED | Emitted when the scene and all assets necessary to render the scene have been loaded. |
PHASES.RENDERED | Emitted when the scene is ready for display. |
Selection
This module is used to interact with the current scene selection set, which is the set of currently selected nodes in the active scene.
- Selection
- ~includes ⇒
boolean
- ~toggle(query) ⇒
void
- ~add(query) ⇒
void
- ~remove(query) ⇒
void
- ~clear() ⇒
void
- ~set(query) ⇒
void
- ~getStyle() ⇒
SelectionSetStyle
- ~setStyle(selectionSetStyle) ⇒
void
- ~includes ⇒
Selection~includes ⇒ boolean
Checks if the selection set includes node(s).
Kind: inner property of Selection
Param | Type |
---|---|
query | QueryObject | string | Array.<string> |
Selection~toggle(query) ⇒ void
Toggles node(s) to the selection set.
Kind: inner method of Selection
Param | Type |
---|---|
query | QueryObject | string | Array.<string> |
Example
selectionSet.add({ name: 'Box' });
Selection~add(query) ⇒ void
Adds node(s) to the selection set.
Kind: inner method of Selection
Param | Type |
---|---|
query | QueryObject | string |
Example
selectionSet.add({ name: 'Box' });
Selection~remove(query) ⇒ void
Removes node(s) from the selection set.
Kind: inner method of Selection
Param | Type | Description |
---|---|---|
query | QueryObject | string | Array.<string> |
query object or nodeId or array of nodeIds |
Example
selectionSet.remove({ name: 'Box' });
Selection~clear() ⇒ void
Removes all node(s) from the selection set.
Kind: inner method of Selection
Selection~set(query) ⇒ void
Set the node(s) of the selection set.
Kind: inner method of Selection
Param | Type |
---|---|
query | QueryObject | string |
Selection~getStyle() ⇒ SelectionSetStyle
Returns the style object for the selection set.
Kind: inner method of Selection
Selection~setStyle(selectionSetStyle) ⇒ void
Sets the selection set styling properties.
Kind: inner method of Selection
Param | Type |
---|---|
selectionSetStyle | SelectionSetStyle |
Example
selectionSet.setStyle({ outlineColor: '#00ff00', outlineThinkness: 5, color: '#ff0000', opacity: 0.5 });
Tools
This module is for interacting with tools, which are responsible for updating the scene based on keyboard, mouse, and touch interfaces.
The default set of tools installed will handle scene navigation (orbit, pan, zoom).
- Tools
- ~addTool(tool) ⇒
void
- ~addTools(tools) ⇒
void
- ~setTool(key, attrs) ⇒
void
- ~setTools(tools) ⇒
void
- ~removeTool(toolName)
- ~removeTools(toolNames)
- ~setPrimary(toolName)
- ~getPrimaryTool() ⇒
string
- ~addTool(tool) ⇒
Tools~addTool(tool) ⇒ void
Adds a tool to the player.
Kind: inner method of Tools
Param | Type |
---|---|
tool | string | Tool |
Example
player.addTool('orbit')
Tools~addTools(tools) ⇒ void
Adds an array of tools to the player.
Kind: inner method of Tools
Param | Type |
---|---|
tools | array.<(string|Tool)> |
Example
player.addTools(['pan', 'orbit', 'zoom'])
Tools~setTool(key, attrs) ⇒ void
Updates an existing tool.
Kind: inner method of Tools
Param | Type |
---|---|
key | string |
attrs | Tool |
Example
player.setTool('orbit', { enabled: false })
Tools~setTools(tools) ⇒ void
Updates existing tools.
Kind: inner method of Tools
Param | Type |
---|---|
tools | object.<string, Tool> |
Example
player.setTools({ 'orbit', { enabled: false }, 'pan': { enabled: true } })
Tools~removeTool(toolName)
Removes a tool from the player.
Kind: inner method of Tools
Param | Type |
---|---|
toolName | string |
Example
player.removeTool('orbit')
Tools~removeTools(toolNames)
Removes an array of tools from the player.
Kind: inner method of Tools
Param | Type |
---|---|
toolNames | array.<string> |
Example
player.removeTools(['pan', 'orbit', 'zoom'])
Tools~setPrimary(toolName)
Sets a tool as Primary tool.
Kind: inner method of Tools
Param | Type |
---|---|
toolName | string |
Example
player.setPrimary('zoom')
Tools~getPrimaryTool() ⇒ string
Gets the current primary tool.
Kind: inner method of Tools
Returns: string
-
primaryToolName
Example
player.getPrimaryTool()
InitManipulator(player) ⇒ Object
Kind: global function
Param | Type |
---|---|
player | Player |
UpdateManipulator(player) ⇒ void
Kind: global function
Param | Type |
---|---|
player | Player |
HoverManipulator(player, [obj], [intersection]) ⇒ boolean
Kind: global function
Param | Type |
---|---|
player | Player |
[obj] | THREE.Object3D |
[intersection] | any |
ToolEventHandler(ev) ⇒ void
Kind: global function
Param | Type |
---|---|
ev | EventControllerMouseEvent |
QueryObject : object
Kind: global typedef
Properties
Name | Type |
---|---|
[all] | boolean |
[id] | string |
[name] | string | RegExp |
[type] | string | Array.<string> |
[names] | Array.<RegExp> |
[properties] | any |
[property] | string |
[child] | string |
[parent] | boolean |
[includeParent] | boolean |
[from] | QueryObject | string |
[hasPlug] | string |
[operator] | any |
[operatorIndex] | number |
[evalNode] | boolean |
[evalPlug] | string |
[plug] | string |
[shallow] | boolean |
[skipModels] | boolean |
[configurator] | boolean |
[attributeIndex] | number |
[attributes] | any |
[attribute] | string |
[tags] | Array.<RegExp> |
[hierarchical] | boolean |
Color : object
Kind: global typedef
Properties
Name | Type |
---|---|
r | number |
g | number |
b | number |
SelectionSetStyle : object
Kind: global typedef
Properties
Name | Type |
---|---|
[outlineColor] | Color |
[outlineThickness] | number |
[color] | Color |
[opacity] | number |
WidgetResult : object
Kind: global typedef
Properties
Name | Type |
---|---|
[widget] | THREE.Object3D |
Manipulator : object
Kind: global typedef
Properties
Name | Type |
---|---|
init | InitManipulator |
update | UpdateManipulator |
[hover] | HoverManipulator |
EventControllerMouseEvent : object
Kind: global typedef
Properties
Name | Type |
---|---|
[_t] | Date |
isTouch; | boolean |
rect; | ClientRect |
clientX; | number |
clientY; | number |
deltaX; | number |
deltaY; | number |
originalEvent; | MouseEvent |
which; | number |
altKey; | boolean |
ctrlKey; | boolean |
metaKey; | boolean |
shiftKey; | boolean |
ToolEventHandlers : object
Kind: global typedef
Properties
Name | Type |
---|---|
[click] | ToolEventHandler |
[dblclick] | ToolEventHandler |
[mousedown] | ToolEventHandler |
[mouseup] | ToolEventHandler |
[hover] | ToolEventHandler |
[drag] | ToolEventHandler |
[scroll] | ToolEventHandler |
[pinch] | ToolEventHandler |
[swipe] | ToolEventHandler |
[keydown] | ToolEventHandler |
[keyup] | ToolEventHandler |
[keyheld] | ToolEventHandler |
[dragenter] | ToolEventHandler |
[dragover] | ToolEventHandler |
[dragleave] | ToolEventHandler |
Tool : object
Kind: global typedef
Properties
Name | Type |
---|---|
label | string |
key | string |
active | boolean |
enabled | boolean |
options | object |
[activate] | function |
[deactivate] | function |
[modifiers] | object.<string, array.<array.<(number|string)>>> |
[manipulator] | Manipulator |
handlers | ToolEventHandlers |