NITV Engine

NITV Engine is an ESM SDK for building Three.js based 3D scenes. It provides a higher-level runtime for scenes, cameras, controls, asset loading, post-processing, sky, water, reflection planes, tree objects, links, interaction workflows, and scene serialization.

Installation

npm install nitv-engine three

three is a peer dependency. Install it in the host application so the engine and the application share the same Three.js runtime.

Basic Usage

import { NITVEngine } from 'nitv-engine';
import * as THREE from 'three';

const container = document.querySelector('#viewport') as HTMLElement;
const engine = new NITVEngine(container);

engine.scene.add(new THREE.AxesHelper(2));
engine.start();

Runtime Assets

The package includes the runtime decoder assets used by the SDK:

• dist/sdk/decoders/draco/
• dist/sdk/decoders/ktx2/

These assets are required when loading Draco-compressed models or KTX2 textures. If your application serves package assets from a custom CDN or static path, point the corresponding Three.js loaders to those decoder directories.

dracoLoader.setDecoderPath('/path/to/decoders/draco/');
ktx2Loader.setTranscoderPath('/path/to/decoders/ktx2/');

Scene DataBox

SceneDataBox is a lightweight scene object index maintained by the engine. It helps applications query, list, and observe objects without repeatedly traversing the full Three.js scene graph.

const entries = engine.sceneDataBox.entries();
console.table(entries.map((entry) => ({
  id: entry.id,
  name: entry.name,
  type: entry.type,
  visible: entry.visible,
})));

const stopWatch = engine.sceneDataBox.onChanged((event) => {
  console.log('[SceneDataBox] added:', event.added);
  console.log('[SceneDataBox] removed:', event.removed);
  console.log('[SceneDataBox] updated:', event.updated);
});

stopWatch();

Loading, Cache, and Cancellation

Model and texture loading APIs accept an optional AbortSignal. Cached templates can be inspected or released without disposing the whole engine.

const controller = new AbortController();

const model = await engine.loadModel('/models/factory.glb', 'gltf', {
  signal: controller.signal,
});

console.table(engine.assetLoader.getCacheStats());
engine.assetLoader.disposeCachedModel('/models/factory.glb', 'gltf');
engine.assetLoader.clearTextureCache('hdr');

Scene Cache

Scene cache lets applications keep multiple imported scene instances in memory and switch between them quickly.

await engine.loadSceneCache('site-a', siteADocument);
await engine.loadSceneCache('site-b', siteBDocument);
await engine.activateSceneCache('site-a');

console.table(engine.getSceneCacheInfo());

Performance Stats

const stop = engine.onPerformanceStatsChanged((stats) => {
  console.log(stats.fps, stats.frameTimeMs);
});

engine.setLightPerformanceQuality('medium');
engine.resetPerformanceStats();

stop();

API Types

Type declarations are included at dist/nitv.d.ts and are exposed through the package exports field. Public exports are documented with JSDoc so editors can surface method, option, and property descriptions directly from the installed package.

import type { SceneDataBoxEntry } from 'nitv-engine';

Notes

• The package is ESM-only.
• Import Three.js directly from three; the SDK does not re-export THREE.
• Keep the SDK version and three version compatible with the peer dependency range.