Services

Services are singletons that provide reusable functionality (loading, materials, camera, selection, etc.) and live for the viewer lifetime. Plugins consume them through the ServiceRegistry.

Usage

import type { IService, ServiceContext, ServiceStatus } from "@optellix/xviewr-sdk";

const loader = viewer.getService("loader");
if (loader) {
  // call loader-specific methods
}

Custom services follow the same contract as built-ins.

class MyService implements IService {
  readonly name = "my-service";
  readonly version = "1.0.0";
  readonly dependencies = ["material"];

  private status: ServiceStatus = ServiceStatus.Uninitialized;

  async init(ctx: ServiceContext): Promise<void> {
    this.status = ServiceStatus.Ready;
  }

  async destroy(): Promise<void> {
    this.status = ServiceStatus.Destroyed;
  }

  getStatus(): ServiceStatus {
    return this.status;
  }
}

viewer.registerService(new MyService());
await viewer.serviceRegistry.initialize("my-service");

IService

Member	Type	Description
name	string	Unique service identifier. Used for lookup.
version	string	Semver.
dependencies	string[]	Names of services that must initialize first.
init(context)	Promise<void>	Initialize internal state. Called once.
destroy()	Promise<void>	Release all resources.
getStatus()	ServiceStatus	Current lifecycle state.

ServiceContext

Passed to init.

Field	Type	Description
viewer	IViewer	The viewer.
eventBus	IEventBus	Shared event bus.
configManager	IConfigManager	Config access.
logger	ILogger | undefined	Optional logger.

ServiceStatus

enum ServiceStatus {
  Uninitialized = "uninitialized",
  Initializing = "initializing",
  Ready = "ready",
  Error = "error",
  Destroyed = "destroyed",
}

ILogger

interface ILogger {
  debug(message: string, ...args: any[]): void;
  info(message: string, ...args: any[]): void;
  warn(message: string, ...args: any[]): void;
  error(message: string, ...args: any[]): void;
}

IServiceRegistry

Accessible as viewer.serviceRegistry.

Method	Returns	Description
register(service)	void	Register a service instance.
registerService(name, factory)	Promise<void>	Register and construct lazily from an async factory.
unregister(name)	boolean	Remove a registered service.
get<T>(name)	T | null	Look up a service. Returns null if missing.
has(name)	boolean	Existence check.
getStatus(name)	ServiceStatus	Current status.
list()	ServiceInfo[]	All registered services with dependency info.
initialize(name)	Promise<void>	Initialize a service (resolves dependencies first).
initializeAll()	Promise<void>	Initialize every registered service in dependency order.
destroy(name)	Promise<void>	Destroy a single service.
destroyAll()	Promise<void>	Destroy every service. Called from viewer.dispose().

ServiceInfo

interface ServiceInfo {
  name: string;
  version: string;
  status: ServiceStatus;
  dependencies: string[];
  dependents: string[];
}

Service lifecycle events

Emitted on the event bus: service:registered, service:initializing, service:initialized, service:destroyed, service:error.

Notes

• getService and registerService on ViewerCore are wrappers around the registry.
• Built-in services (camera, loader, material, rendering, environment, grid, lod, selection, measurement, etc.) are registered automatically. A subset is initialized eagerly during ready(). The rest initialize on demand when looked up via initialize.