Introducing three-query-selector: CSS-like Selector Syntax for Three.js

Showcase
, , , ,
1

Hello Three.js community!

I’m excited to introduce a new library I’ve been working on: three-query-selector. This library provides a powerful and flexible way to query and select objects in your Three.js scenes using an intuitive, CSS-like selector syntax.

Features:

  • CSS-like selector syntax for Three.js objects
  • Support for querying by object type, name, and UUID
  • Filtering system for custom queries
  • Ability to select direct children or all descendants
  • Caching mechanism for improved performance on repeated queries
  • Lightweight and easy to integrate into existing Three.js projects

Installation:

npm install three-query-selector
# or
yarn add three-query-selector
# or
pnpm add three-query-selector
# or
bun add three-query-selector

Usage:

First, import the QuerySelector class:

import { QuerySelector } from "three-query-selector";

Then, create an instance of QuerySelector with your Three.js scene or object array:

const scene = new THREE.Scene();
// ... add objects to your scene
const engine = new QuerySelector([scene]);

Now you can use the engine to query objects:

// Find all Mesh objects
const allMeshes = engine.get("Mesh");

// Find objects by name
const namedObject = engine.get("[name='MySpecialObject']");

// Find direct children
const directChildren = engine.get("Scene > Group");

// Find descendants
const allLights = engine.get("Scene Light");

// Complex queries
const specificMesh = engine.get("Group[name='MyGroup'] > Mesh");

Advanced Filtering:

The library features a new filtering system for more advanced queries. You can now define custom filters for attributes, improving the flexibility of your queries.

Example Usage of Filters:

// Add a custom filter for objects with a specific property
engine.filters.add(
  "customAttribute",
  (object, value) => object.userData.customAttribute === value
);

// Query using the custom filter
const filteredObjects = engine.get("[customAttribute='someValue']");

Query Syntax:

  • TypeName: Selects objects by their Three.js type (e.g., ‘Mesh’, ‘Light’, ‘Group’)
  • [name='ObjectName']: Selects objects by their name
  • [uuid='ObjectUUID']: Selects objects by their UUID
  • [attribute='value']: Selects objects by custom attributes
  • >: Selects direct children
  • Space: Selects all descendants

Examples:

// Find all Mesh objects that are direct children of a Group named 'MyGroup'
const meshes = engine.get("Group[name='MyGroup'] > Mesh");

// Find all Light objects anywhere in the scene
const lights = engine.get("Scene Light");

// Find a specific object by UUID
const specific = engine.get("[uuid='1234-5678-90ab-cdef']");

// Use custom filters to find objects with a specific userData attribute
engine.filters.add(
  "customAttribute",
  (object, value) => object.userData.customAttribute === value
);
const customFilteredObjects = engine.get("[customAttribute='someValue']");

Contributing:

Contributions are welcome! Please feel free to submit a Pull Request.

License:

This project is licensed under the MIT License.

I hope you find three-query-selector useful for your projects. I’m looking forward to your feedback and contributions!

2 Likes
2

Excellent.

How does it compare with @agargaro’s Three.ez, which also supports query selection of Three.js objects?

2 Likes