README.md

three musketeers

"All for one. One for all."

This module serves as an intuitive tool to introspect, debug and test any THREE.js application.

GitHub — Documentation — Examples — Demo

Demo

Usage

Download the minified library and include it in your HTML, or install and import it as a npm module.

$ npm i three-musketeers

The code below creates a scene, a camera, and a geometric cube, and it adds the cube to the scene. It then creates a WebGL renderer for the scene and camera, and it adds that viewport to the document.body element. Finally, it animates the cube within the scene for the camera.

Lastly, we simply pass the necessary resources to the musketeers instance and attach it to our window via the alias $$$ for experimentation:

// sample application
import * as THREE from 'three';
import musketeers from 'three-musketeers';

init();

function init() {
  const { innerWidth, innerHeight } = window;
  const scene = new THREE.Scene();

  const renderer = new THREE.WebGLRenderer({ antialias: true });
  renderer.setSize(innerWidth, innerHeight);
  document.body.appendChild(renderer.domElement);

  const camera = new THREE.PerspectiveCamera(70, innerWidth / innerHeight, 0.01, 10);
  camera.position.z = 1;
  scene.add(camera);

  const mesh = new THREE.Mesh(
    new THREE.BoxGeometry(0.2, 0.2, 0.2),
    new THREE.MeshBasicMaterial({ color: 0xFF0000 })
  );
  // assign a unique name to our mesh to be able to query it later
  mesh.name = 'CUBE_1';
  scene.add(mesh);

  renderer.render(scene, camera);

  // attach $$$ to the window for browser debugging
  window.$$$ = musketeers({ renderer, scene, camera });
}

Now, you can inspect the scene through the window object:

// javascript console in the browser

$$$
.debug() // enable visual debug mode
.isValid(); // true

$$$
.find('Cube_1') // the unique identifier we assigned to our mesh
.exists(); // true

$$$
.findAll((node) => node.geometry.type === 'BoxGeometry') // returns an array of items of this type

$$$
.find('Cube_1')
.click(); // locates the item in the 3D scene and clicks the item

window.addEventListener('click', (event) => {
  // find all intersected items on 'click'
  const intersectedItems = $$$.pickFromEvent(event);
  console.log(intersectedItems); // useful for debugging
});

Check out the documentation for more details. You can also check out the example testing a 3D application with selenium.

# running and testing the example 3d application

$ npm run selenium
$ npm run start
$ npm run test:e2e

Contribute

I welcome contributors. Please contribute if you have ideas to improve this library. Please use GitHub's pull request and issues features. You can also help implement upcoming features from the TODO page. Feel free to reach out if you'd like more context or info for implementation details.

Here are a few scripts to help you get started:

NPM Commands	Description
start	Runs the examples for development
test	Runs unit tests for the module
build	Builds the module
docs	Updates the documentation
components	Updates the component entry points
selenium	Runs selenium
test:e2e	Runs e2e automated testing for the examples as an example

Other Resources

Three.js Questions — Three.js Forum — Three.js Gitter — Three.js Slack