Things-Scene

A high-performance 2D/3D scene graph library for building interactive visual editors. It combines the HTML5 Canvas and Three.js to enable facility visualization, data-driven animations, and real-time monitoring dashboards from a single component model.

Features

• High-performance Canvas-based 2D rendering
• Three.js-based 3D rendering (WebGL)
• Component-based architecture
• Gizmo editing system (Move / Rotate / Scale)
• Material3D preset system (metal, glass, plastic, wood, ceramic, rubber)
• Seamless 2D ↔ 3D property binding
• GLTF/GLB model loading with per-node control
• ESM and UMD builds
• TypeScript strict mode

Installation

npm install @hatiolab/things-scene

Usage

ESM (recommended)

import { Scene, Component } from '@hatiolab/things-scene'

// create and render a scene

UMD

<script src="node_modules/@hatiolab/things-scene/things-scene-min.js"></script>
<script>
  const { Scene, Component } = window['things-scene']
</script>

3D Features (v10)

Enabling 3D mode

Set threed: true on the model-layer to enable 3D mode. A single component model renders to both 2D and 3D, with live mode switching.

Material3D API

Control 3D materials through a component's material3d property:

component.set('material3d', {
  preset: 'glass',      // default, metal, glass, plastic, wood, ceramic, rubber
  metalness: 0.5,       // 0–1
  roughness: 0.3,       // 0–1
  opacity: 0.3,         // 0–1 (preset default or explicit)
  envMapIntensity: 1.5, // 0–3
  side: 'double',       // double, front, back
  castShadow: true,
  receiveShadow: false,
})

3D component types

Sphere, Cube, Cylinder, Banner, Camera, Wall, GLTFObject, Light, Sprite.

GLTF models

component.set('src', '/models/building.glb')
component.set('nodes', {
  Wall: { color: '#ff0000', opacity: 0.5 },
  Door: { visible: false },
})

Builds

| Format | File | Target | | ------ | --------------------- | -------------------------- | | ESM | things-scene.mjs | Modern browsers | | UMD | things-scene-min.js | Any environment | | Node | things-scene-transfer.mjs | Headless / SSR simulation |

npm run build       # types + rollup (production)
npm test            # 2460+ tests (mocha)
npm run type-check  # tsc --noEmit

Development

See DEVELOPMENT.md for the development setup.

Migrating v9 → v10

Breaking changes

• strict: true — custom components must satisfy strictPropertyInitialization, etc.
• Hardened evaluator sandbox — window / document / globalThis access is blocked (scene, setTimeout, Math, and similar remain available).
• innerHTML → textContent, with safe HTML rendering via DOMPurify.
• The state getter is now a Proxy (behavior-compatible: get / has / ownKeys / spread all supported).
• bounds return values are Object.freezed — copy with a spread before mutating.

See CHANGELOG.md for the full list.

License

This project is distributed under a proprietary license. License terms: http://things-scene.hatiolab.com/EULA/