Global

Methods

$$$ - debug(debugopt) → {self}

Source:

Enabled debug mode across all methods, which displays cursor positions throughout actions.

Example
$$$.debug(); // turns on global debug mode
$$$.debug(false); // turns off global debug mode
Parameters:
Name Type Attributes Default Description
debug boolean <optional>
true

A mouse event that is used for trigger a click action.

Returns:

Chainable api by returning the instance.

Type
self

$$$ - isValid() → {boolean}

Source:

Returns whether the instance is valid with all required resources to be functional.

Example
import musketeers from 'three-musketeers';

const $$$ = musketeers();
$$$.isValid(); // returns false

$$$.setResource({
  camera,
  renderer,
  scene
});
$$$.isValid(); // returns true
Returns:
  • Whether the instance is valid.
Type
boolean

$$$ - find(name, rootopt) → {node}

Source:

Find the first node with the given validator. By default, the first argument accepts a string that is used to find the first node with the matching name value. For more advanced queries, you can provide a function to validate any property to find the desired node.

The second argument is an option argument where you can specify the parent node to search down the all children nodes. By default, it will search from the top of the THREE.js scene across all nodes.

Example
// returns the first node with the `name` being `Cube_1`
$$$.find('Cube_1');

// returns the first node with the `name` being `Cube_1`
$$$.find(node => node.name === 'Cube_1');

// returns the first node with geometry type being 'PlaneBufferGeometry'
$$$.find(node => node.geometry.type === 'PlaneBufferGeometry');
Parameters:
Name Type Attributes Default Description
name string | function

Either a string or function that is used to find the matching node.

root object <optional>
scene

The parent node to traverse the scene. By default, it's the scene.

Returns:
  • Chainable api by returning node.
Type
node

$$$ - findAll(name, rootopt) → {Array.<node>}

Source:

Find all nodes with the given validator. By default, the first argument accepts a string that is used to find the first node with the matching name value. For more advanced queries, you can provide a function to validate any property to find the desired node.

The second argument is an option argument where you can specify the parent node to search down the all children nodes. By default, it will search from the top of the THREE.js scene across all nodes.

Example
// returns an array of nodes with the `name` being `Cube_1`
$$$.findAll('Cube_1');

// returns an array of nodes with the `name` containing the word `Cube`
$$$.findAll(node => ~node.name.indexOf('Cube'));

// returns an array of nodes with geometry type being 'PlaneBufferGeometry'
$$$.findAll(node => node.geometry.type === 'PlaneBufferGeometry');
Parameters:
Name Type Attributes Default Description
name string | function

Either a string or function that is used to find the matching node.

root object <optional>
scene

The parent node to traverse the scene. By default, it's the scene.

Returns:
  • An array of matching nodes.
Type
Array.<node>

$$$ - getResource(resourceName) → {node|false}

Source:

Returns the matching resource given the resource name. The returned resource is a node with attached node methods.

You can also leverage the constants from the instance for valid string values.

Example
// returns the `camera` resource
$$$.getResource('camera');

// constants are useful to ensure the strings match
const C = $$$.constants;
// returns the `renderer` resource
$$$.getResource(C.RENDERER);

// returns false for invalid resources
$$$.getResource('INVALID');
Parameters:
Name Type Description
resourceName string

The name of for the resource.

Returns:
  • An array of matching nodes.
Type
node | false

$$$ - moveMouse(event, debugopt) → {self}

Source:

Move the mouse to the coordinates provided by an event's clientX and clientY coordinates. Additionally, debug can be enabled to see the cursor position of of the click action.

Example
const event = { clientX: 500, clientY: 500 }; // sample event
$$$.moveMouse(event); // updates the mouse positions provided in the event
$$$.moveMouse(event, true); // enable cursor visual with `debug` set to `true`
Parameters:
Name Type Attributes Default Description
event object

A mouse event that is used for move to the mouse

Properties
Name Type Description
clientX object

The screen space x-coordinate.

clientY object

The screen space y-coordinate.

debug boolean <optional>
false

Allows to turn on the visuals for the click action.

Returns:
  • Chainable api by returning the instance.
Type
self

$$$ - off(event, callbackopt) → {self}

Source:

Removes the callback's associated with the WebGL canvas element. If no callback is provided, all callback associated with the event are removed.

Example
function clickCallback() {
  console.log('CLICKED');
}

$$$
.on('click', clickCallback)
.trigger('click') // logs 'CLICKED'
.off('click', clickCallback)
.trigger('click'); // no log

$$$
.on('click', clickCallback)
.trigger('click') // logs 'CLICKED'
.off('click') // all callbacks associated with `click` are removed
Parameters:
Name Type Attributes Description
event object

The event to remove the provided callback.

callback function <optional>

The specific callback to remove from the event.

Returns:
  • Chainable api by returning the instance.
Type
self

$$$ - on(event, callbackopt) → {self}

Source:

Attaches the callback's associated with the WebGL canvas element to the event.

Example
function clickCallback() {
  console.log('CLICKED');
}

$$$
.on('click', clickCallback)
.trigger('click') // logs 'CLICKED'
Parameters:
Name Type Attributes Description
event object

The event for the callback.

callback function <optional>

The specific callback to attach to the event.

Returns:
  • Chainable api by returning the instance.
Type
self

$$$ - pickFromEvent(event, debugopt, recursiveopt) → {Array.<object>}

Source:

Given an event, return all intersected items from the given clientX and clientY coordinates. By default, it returns all intersected points, but you can turn off recursive mode to return only the first intersected item.

Example
const event = { clientX: 500, clientY: 500 }; // sample event

$$$.pickFromEvent(event); // returns an array of intersected points

// a useful debugging tool of using events and picking to grab intersected items
$$$.on('mousemove', (event) => {
  console.log($$$.pickFromEvent(event)); // logs all intersected items on `mousemove`
});
Parameters:
Name Type Attributes Default Description
event object

A mouse event that is used for move to the mouse

Properties
Name Type Description
clientX object

The screen space x-coordinate.

clientY object

The screen space y-coordinate.

debug boolean <optional>
false

Allows to turn on the visuals for the click action.

recursive boolean <optional>
true

Whether to intersect all intersected items.

Returns:
  • An array of intersected items.
Type
Array.<object>

$$$ - setResource(key, valueopt) → {self}

Source:

Sets the resource to be consumed throughout tool. You can either set resources one-by-one which can be useful to add them throughout your application at various times or as a collection.

You can also leverage the constants from the instance for valid string values.

Example
// can leverage constants
const C = $$$.constants;

$$$.setResource(C.C, camera); // camera being a THREE.js camera instance
$$$.setResource('renderer', renderer); // camera being a THREE.js renderer instance
$$$.setResource('scene', scene); // camera being a THREE.js scene instance

// or you can set all at once
$$$.setResource({
  camera,
  renderer,
  scene
});
Parameters:
Name Type Attributes Description
key string | object

The resource name or an object containing the resource key and values.

Properties
Name Type Attributes Description
camera camera <optional>

THREE.js camera instance. If not provided, the one attached to the scene will automatically be used.

renderer renderer

THREE.js renderer instance.

scene scene

THREE.js scene instance.

value object <optional>

The resource value or it's optional if first argument is an object.

Returns:
  • Chainable api by returning the instance.
Type
self

node - exists() → {boolean}

Source:

Given a node, check whether it exists in the scene by checking whether it has a uuid.

Example
$$$
.find('INVALID') // find an element with the name `INVALID`
.exists(); // returns `false` as this node doesn't exist

 $$$
.find('Cube_1')
.exists(); // returns `true` as this node exists in the scene.
Returns:
  • Returns whether the node exists in the scene
Type
boolean

node - find(name) → {node}

Source:

Find the first node with the given validator. By default, the first argument accepts a string that is used to find the first node with the matching name value. For more advanced queries, you can provide a function to validate any property to find the desired node.

Example
// returns the first child node under `Cube_1` with the `name` being `Child_Cube_1`
$$$
.find('Cube_1')
.find('Child_Cube_1');

// returns the first child node under `Cube_1` with the `name` being `Child_Cube_2`
$$$
.find(node => node.name === 'Cube_1')
.find('Child_Cube_2');
Parameters:
Name Type Description
name string | function

Either a string or function that is used to find the matching node.

Returns:
  • Chainable api by returning node.
Type
node

node - findAll(name) → {Array.<node>}

Source:

Find all nodes with the given validator. By default, the first argument accepts a string that is used to find the first node with the matching name value. For more advanced queries, you can provide a function to validate any property to find the desired node.

Example
// returns an array of child nodes under `Cube_1` with the `name` being `Cube_1`
$$$
.find('Cube_1')
.findAll('Cube_1');

// returns an array of child nodes under `Cube_1` with the `name` containing the word `Cube`
$$$
.find('Cube_1')
.findAll(node => ~node.name.indexOf('Cube'));
Parameters:
Name Type Description
name string | function

Either a string or function that is used to find the matching node.

Returns:
  • An array of matching nodes.
Type
Array.<node>

node - hasChildren() → {boolean}

Source:

Given a node, check whether it has any child nodes in the scene.

Example
$$$
.find('Cubes') // find an element with the name `Cubes`
.hasChildren(); // returns `true` as this node contains many cubes
Returns:
  • Returns whether the node has any children.
Type
boolean

node - off(event, callbackopt) → {self}

Source:

Removes the callback's associated with the given node. If no callback is provided, all callback associated with the event are removed.

Example
function clickCallback() {
  console.log('CLICKED');
}

$$$
.find('Cube_1')
.on('click', clickCallback)
.trigger('click') // logs 'CLICKED'
.off('click', clickCallback)
.trigger('click'); // no log

$$$
.find('Cube_1')
.on('click', clickCallback)
.trigger('click') // logs 'CLICKED'
.off('click') // all callbacks associated with `click` are removed
Parameters:
Name Type Attributes Description
event object

The event to remove the provided callback.

callback function <optional>

The specific callback to remove from the event.

Returns:
  • Chainable api by returning the node.
Type
self

node - on(event, callbackopt) → {self}

Source:

Attaches the callback's associated with the given node.

Example
function clickCallback() {
  console.log('CLICKED');
}

$$$
.find('Cube_1')
.on('click', clickCallback)
.click() // `click` the node and also logs 'CLICKED'
Parameters:
Name Type Attributes Description
event object

The event for the callback.

callback function <optional>

The specific callback to attach to the event.

Returns:
  • Chainable api by returning the node.
Type
self

node - trigger(event) → {self}

Source:

Given an node, trigger the associated event in order for the appropriate callbacks to be invoked.

Example
function clickCallback() {
  console.log('RANDOM EVENT');
}

$$$
.find('Cube_1')
.on('sampleEvent', clickCallback)
.trigger('sampleEvent') // logs 'RANDOM EVENT'
Parameters:
Name Type Description
event object

The event for the callback.

Returns:
  • Chainable api by returning the node.
Type
self