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 |
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 |
||
root |
object |
<optional> |
scene
|
The parent node to traverse the scene. By |
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 |
||
root |
object |
<optional> |
scene
|
The parent node to traverse the scene. By |
Returns:
- An array of matching nodes.
- Type
- Array.<node>
$$$ - getResource(resourceName) → {node|false}
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}
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
|
|||||||||||
debug |
boolean |
<optional> |
false
|
Allows to turn on the visuals for the |
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 |
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 |
Returns:
- Chainable api by returning the instance.
- Type
- self
$$$ - pickFromEvent(event, debugopt, recursiveopt) → {Array.<object>}
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
|
|||||||||||
debug |
boolean |
<optional> |
false
|
Allows to turn on the visuals for the |
|||||||||
recursive |
boolean |
<optional> |
true
|
Whether to intersect all intersected items. |
Returns:
- An array of intersected items.
- Type
- Array.<object>
$$$ - setResource(key, valueopt) → {self}
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 Properties
|
|||||||||||||||||
value |
object |
<optional> |
The resource value or it's optional if first argument is an |
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 |
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 |
Returns:
- An array of matching nodes.
- Type
- Array.<node>
node - hasChildren() → {boolean}
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 |
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 |
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