THREE.Interactive

Fast and simple interaction manager for THREE.js for enabling pointer, mouse and touch events on 3D objects.

Note: When using ReactJS I can highly recommend react-three-fiber, which has built-in interaction support. For pure THREE.js projects, this little library can be very useful though.

ESM only. Currently no CJS version is built.

How it works:

Interactive Objects (THREE.Object3D) are added to the InteractionManager, which fires instances of InteractiveEvent.
Differenciates between mouseover/mouseout (closest objects) and mouseenter/mouseleave (all objects) events.
Intersections are sorted by distance to the camera and the events are dispatched in that order (closest first). If InteractiveEvent.stopPropagation() is called, the event won't fire again on other objects.

Alternative to three.interaction.

Collaborations and improvements are welcome.

Examples

Simple: Basic example
Auto Add: Auto-add example, still beta
Depth: Overlapping objects example
glTF: Hover/click gltf objects example

Usage

yarn add three.interactive

npm install three.interactive

Include script:

import { InteractionManager } from 'three.interactive';

Create an InteractionManager instance

const interactionManager = new InteractionManager(
  renderer,
  camera,
  renderer.domElement
);

Add object to InteractionManager

interactionManager.add(cube);

Add event listener to object

cube.addEventListener('click', (event) => {});

Call InteractionManager.update() on each render

interactionManager.update();

Simple example

import * as THREE from 'three';
import { InteractionManager } from 'three.interactive';

const container = document.createElement('div');
container.setAttribute('id', 'container');
document.body.appendChild(container);

const renderer = new THREE.WebGLRenderer();
renderer.setPixelRatio(window.devicePixelRatio);
renderer.setSize(window.innerWidth, window.innerHeight);
container.appendChild(renderer.domElement);

const scene = new THREE.Scene();

const camera = new THREE.PerspectiveCamera(
  45,
  window.innerWidth / window.innerHeight,
  0.1,
  1000
);
camera.position.set(0.0, 0.0, 10.0);

const interactionManager = new InteractionManager(
  renderer,
  camera,
  renderer.domElement
);

const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshBasicMaterial();

const cube = new THREE.Mesh(geometry, material);
cube.addEventListener('mouseover', (event) => {
  event.target.material.color.set(0xff0000);
  document.body.style.cursor = 'pointer';
});
cube.addEventListener('mouseout', (event) => {
  event.target.material.color.set(0xffffff);
  document.body.style.cursor = 'default';
});
cube.addEventListener('mousedown', (event) => {
  event.target.scale.set(1.1, 1.1, 1.1);
});
cube.addEventListener('mouseup', (event) => {
  event.target.scale.set(1.1, 1.1, 1.1);
  if (event.wasIntersectedOnMouseDown) {
    // Object was intersected when mouse down fired, so this is essentially a click event
  } else {
    // Object was not intersected when mouse down fired
  }
});
cube.addEventListener('click', (event) => {
  event.target.scale.set(1.0, 1.0, 1.0);
});
scene.add(cube);
interactionManager.add(cube);

const animate = (time) => {
  requestAnimationFrame(animate);

  interactionManager.update();

  renderer.render(scene, camera);
};

animate();

API

InteractionManager class

new InteractionManager(renderer, camera, renderer.domElement [, { autoAdd: false, scene, bindEventsOnBodyElement: true } ])

Constructor of InteractionManager instance; if the autoAdd option (still beta) is used, there is no need for adding objects to InteractionManager manually and calling interactionManager.update(); In this mode, the scene needs to be provided in the options.

Members:

Member	Type	Default	Description
`treatTouchEventsAsMouseEvents`	boolean	true	Whether touch events should fire as mouse events

Methods:

Method	Description
`add(object, childNames = [])`	Add object(s), optionally select only children of `object` by their names
`remove(object, childNames = [])`	Remove object(s), optionally select only children of `object` by their names
`update()`	Update InteractionManager on each render
`dispose()`	Dispose InteractionManager

InteractionManagerOptions class

new InteractionManagerOptions({ autoAdd: false, scene, bindEventsOnBodyElement: true })

Constructor of InteractionManagerOptions instance

InteractiveEvent class

Members:

Member	Type	Default	Description
`cancelBubble`	boolean	false	Whether events should continue to bubble
`coords`	THREE.Vector2		Mouse/touch coords
`distance`	Number		Distance of intersected point from camera
`intersected`	boolean		Whether object is still intersected
`wasIntersected`	boolean		Whether object was intersected during the last event or last render
`wasIntersectedOnMouseDown`	boolean		Whether object was intersected during mousedown event
`originalEvent`	Event object		Original event, if available (MouseEvent, TouchEvent or PointerEvent)
`target`	THREE.Object3D		Target object
`type`	string		event type: 'click', 'mouseover', 'mouseout', 'mouseenter', 'mouseleave', 'mousedown', 'mousemove', 'mouseup', 'touchstart', 'touchmove', 'touchend', 'pointerdown', 'pointerup', 'pointermove'

Methods:

Method	Description
`stopPropagation`	Stop bubbling of event (cancelBubble), e.g. when only the object closest to the camera is supposed to fire an event

Editing source

In order to edit the source code, run:

yarn start

And open http://127.0.0.1:8000/ in your browers.

The files in the build folder will automatically be rebuilt when the files in the src folder are modified.

License

MIT licensed

Created by Markus Lerner & contributors

markuslerner/THREE.Interactive