ViewerCore

Main entry class for the XViewer SDK. Owns the Three.js scene, camera, renderer, and the plugin/service/event/config subsystems.

Usage

import { ViewerCore } from "@optellix/xviewr-sdk";

const viewer = new ViewerCore(container, {
  viewer: {
    camera: { type: "perspective", fov: 75, position: { x: 5, y: 5, z: 5 } },
    licensing: { key: "YOUR_LICENSE_KEY" },
  },
  rendering: { antialias: true },
  plugins: [],
});

await viewer.ready();

const loader = viewer.getService("loader");
await viewer.loadPlugin(new MyPlugin());

// later
await viewer.dispose();

ready() resolves once the license is validated, built-in services are initialized, core plugins are loaded, and the config-driven plugins are loaded. Most runtime APIs throw LicenseError if called before ready() resolves.

Constructor

new ViewerCore(container: HTMLElement, config: XViewerConfig)

The viewer attaches its renderer.domElement to container during initialization and listens for window resize events.

Public properties

Property	Type	Description
scene	THREE.Scene	Root Three.js scene.
camera	THREE.Camera	Active camera (perspective or orthographic).
renderer	THREE.WebGLRenderer	WebGL renderer. Local clipping is enabled.
root	THREE.Object3D	Group inside scene for loaded content.
container	HTMLElement	Host element passed to the constructor.
pluginManager	IPluginManager	See plugins.md.
eventBus	IEventBus	See event-bus.md.
serviceRegistry	IServiceRegistry	See services.md.
configManager	IConfigManager	See config-manager.md.

Public methods

Method	Returns	Description
ready(timeoutMs?: number)	Promise<void>	Resolves when initialization completes. Default timeout is 10000 ms. Pass 0 to disable.
loadPlugin(plugin: IPlugin)	Promise<void>	Register and load a plugin.
unloadPlugin(name: string)	Promise<void>	Unload a previously loaded plugin.
getService<T extends IService>(name: string)	T | null	Look up a service by name.
registerService(service: IService)	void	Register an additional service.
getServiceContext()	{ viewer, eventBus, configManager }	Context object useful when wiring custom services.
render()	void	Render a single frame. Called by the internal animation loop.
resize(width, height)	void	Resize renderer and update camera projection. Emits viewer:resize.
addFrameCallback(cb)	string	Register a callback invoked every frame. Returns an id for removal.
removeFrameCallback(id)	boolean	Remove a frame callback.
addPostRenderCallback(cb)	string	Register a callback invoked after each render.
removePostRenderCallback(id)	boolean	Remove a post-render callback.
getSceneMetrics()	SceneMetrics	Counts of objects, meshes, vertices, and triangles under root.
updateConfig(config: Partial<XViewerConfig>)	void	Merge new values into the config.
dispose()	Promise<void>	Tear down plugins, services, renderer, and DOM.
destroy()	Promise<void>	Alias for dispose().

SceneMetrics

interface SceneMetrics {
  objectCount: number;
  meshCount: number;
  visibleMeshCount: number;
  vertexCount: number;
  triangleCount: number;
  visibleTriangleCount: number;
}

Lifecycle events

Emitted on eventBus during the viewer lifetime:

• viewer:initializing { viewer }
• viewer:ready { viewer }
• viewer:resize { width, height }
• viewer:disposing { viewer }
• viewer:disposed { viewer }
• viewer:error { error }

Notes

• The constructor starts initialization synchronously. Always await ready() before calling loadPlugin, getService, registerService, or updateConfig.
• dispose() is idempotent.
• Window resize handling is installed automatically and removed on dispose.