Extensibility API

This document is intended to provide a high-level overview of the different types of APIs that can be used to extend Inspector with additional features. It is not exhaustive, but it is representative and should help give a good sense of what is involved in extending Inspector.

Showing and Hiding Inspector

The ShowInspector function is used to show Inspector. It returns an InspectorToken that can be used to hide Inspector and check its visibility.

API	Description
`ShowInspector`	Attaches Inspector to the given Babylon scene and makes it visible. Pass options to further configure Inspector, including defining new static or dynamic extensions. Returns an `InspectorToken` that can be used to hide Inspector and check its current visibility.
`InspectorToken`	Returned by `ShowInspector`. Call `dispose()` to hide Inspector and tear down all its resources. The `isDisposed` property can be used to check whether Inspector is currently visible, and `onDisposed` can be observed to react to Inspector being hidden.

Options

ShowInspector accepts an optional InspectorOptions object as its second argument. The following options are available:

Option	Type	Default	Description
`layoutMode`	`"overlay"` \| `"inline"`	`"overlay"`	In overlay mode, Inspector floats on top of the canvas. In inline mode, Inspector replaces the canvas in the DOM, making the canvas the central content within the Inspector shell.
`autoResizeEngine`	`boolean`	`true`	When enabled, automatically resizes the Babylon engine when Inspector is shown or hidden.
`containerElement`	`HTMLElement`	(auto)	The DOM element to host Inspector. If not provided, Inspector automatically walks up the DOM tree from the engine's rendering canvas and uses the nearest suitable ancestor, falling back to `document.body`.
`themeMode`	`"system"` \| `"light"` \| `"dark"`	`"system"`	Sets the initial theme. When set to `"system"`, the theme automatically matches the user's OS-level preference and updates when it changes.
`showThemeSelector`	`boolean`	`true`	When enabled, a theme toggle button is displayed in the toolbar, allowing users to switch between light and dark themes.
`serviceDefinitions`	`ServiceDefinition[]`	`[]`	An array of static extension service definitions to load immediately when Inspector is shown.
`extensionFeeds`	`IExtensionFeed[]`	`[]`	An array of extension feeds that provide dynamic extensions users can install through the extensions dialog.
`leftPaneDefaultWidth`	`number`	(auto)	Default width in pixels for the left side pane.
`rightPaneDefaultWidth`	`number`	(auto)	Default width in pixels for the right side pane.
`leftPaneMinWidth`	`number`	(auto)	Minimum width in pixels for the left side pane.
`rightPaneMinWidth`	`number`	(auto)	Minimum width in pixels for the right side pane.
`leftPaneDefaultCollapsed`	`boolean`	`false`	Whether the left side pane starts collapsed.
`rightPaneDefaultCollapsed`	`boolean`	`false`	Whether the right side pane starts collapsed.

Inspector persists certain settings (such as theme preference and pane widths) to localStorage. These settings are scoped by an internal namespace to avoid conflicts with the host app (including other Babylon tools).

Core Services

There are several core services that provide the main extensibility points.

API	Description
`IShellService`	Allows adding new left/right side panes and toolbar items.
`ISceneExplorerService`	Allows adding new sections to Scene Explorer (which itself uses `IShellService` to add a side pane), or commands to existing entity types (e.g. Meshes, Textures, etc.) that are displayed in the tree view.
`IPropertiesService`	Allows adding content to sections of the properties pane (which itself uses `IShellService` to add a side pane). You can add whole new sections, or add entries to existing sections, and you can target the specific entity type (e.g. Meshes, Textures, etc.).
`IDebugService`	Allows adding content to sections of the debug pane (which itself uses `IShellService` to add a side pane).
`IStatsService`	Allows adding content to sections of the stats pane (which itself uses `IShellService` to add a side pane).
`ISettingsService`	Allows adding content to sections of the settings pane (which itself uses `IShellService` to add a side pane).
`IToolsService`	Allows adding content to sections of the tools pane (which itself uses `IShellService` to add a side pane).
`ISceneContext`	Provides access to the scene that Inspector is attached to.
`ISelectionService`	Provides access to the currently selected entity, and allows changing the currently selected entity. The selected entity is for example what is shown as selected in Scene Explorer, for the properties shown in the properties pane, etc.
`ISettingsStore`	Provides access to persisted Inspector settings with change notifications. Use the `useSetting` hook for convenient read/write/reset of settings within React components.
`IWatcherService`	Allows watching for changes to properties of entities (Meshes, Materials, Textures, etc.).

Custom Services (Extensions)

There are a number of types used when defining new features/services/extensions.

Type	Description
`IService`	This interface must be implemented by any service that can be consumed by other services (i.e., one that produces a service contract). A service that only consumes others and returns an `IDisposable` does not need to implement `IService`.
`ServiceDefinition`	This type is used to define a "service." It includes a friendly name for the service, specifies other services that this service consumes (depends on), service contracts that this service produces (including its own extensibility points), and the factory function that instantiates the service.
`BuiltInsExtensionFeed`	This class can be used to inject "dynamic" extensions when calling `ShowInspector` (extensions that the user optionally but explicitly installs through the extensions dialog).

React Components

There are a number of React components that can be used to simplify extension implementation and ensure UX consistency with the default Inspector features.

Component	Description
`BoundProperty`	This is a wrapper component that can be used with the components listed below but takes care of "binding" to a property of an entity (meaning it observes changes to that property in real time). Use this whenever you can for side panes like the properties pane, the debug pane, etc. Internally `BoundProperty` uses the `useProperty` hook described later.
`Property`	A lightweight wrapper similar to `BoundProperty` but without automatic data binding. It provides copy-to-clipboard support for properties but requires the caller to manage value and onChange handling directly. Use this when you need custom value/onChange handling.
`Vector3PropertyLine`, `SwitchPropertyLine`, etc.	Any component that is suffixed with `PropertyLine` is intended to be used in the properties pane, debug pane, etc., and can be wrapped in `BoundProperty`.
`ButtonLine`, `FileUploadLine`, etc.	Any component that is suffixed with just `Line` is intended to be used in the properties pane, debug pane, etc., but is used standalone (not wrapped in `BoundProperty`).
`Button`, `Switch`, `DropDown`, etc.	There are many other "primitive" components that can be used for building UI that is more custom than what is seen in the properties pane (and other similar panes).
`SidePaneContainer`	This is a container component that can be used for side panes and provides default standard layout. You should usually use this when adding a new side pane.

React Hooks

There are a number of React hooks that make it easy to re-use much of the behavior you might see in the core Inspector features.

Hook	Description
`useProperty`	Can be used to ensure the containing React component re-renders when a property of an object changes, even if it doesn't have a corresponding `Observable`. This hook is built on top of the `useInterceptObservable` and `useObservableState` hooks described later in this section.
`useVector3Property`, `useColor4Property`, etc.	These hooks target specific property types that have nested properties and internally use multiple `useProperty` hooks.
`useInterceptObservable`	"Intercepts" a property mutation or function call on an object, which is useful when the property/function does not have a corresponding `Observable` in the underlying Babylon API. The returned `Observable` can be used in conjunction with `useObservableState`. This hook is built on top of the instrumentation helpers described later.
`usePollingObservable`	This hook simply creates an `Observable` that fires at a polling rate, which can be used in conjunction with `useObservableState`. Use this sparingly as it causes work to happen even when nothing in the scene is changing.
`useObservableState`	Causes the containing React component to re-render and a value to be recomputed when any of the specified `Observable`s fire.
`useObservableCollection`	Pass in an `ObservableCollection` (described below under helpers) and it returns an array. The containing React component is re-rendered whenever an item is added/removed to/from the `ObservableCollection`.
`useResource`, `useAsyncResource`	These hooks help manage the lifetime of an `IDisposable` within a React component, ensuring the resource is disposed at the right time.
`useSetting`	A hook for managing reactive settings with read/write/reset capabilities. Returns a tuple of the current value, a setter function, and a reset function. The containing React component re-renders when the specified setting changes.
`useAngleConverters`	Consume `ISettingsService` in your own service and pass it to this hook to convert angles based on user's preferred angle unit (degrees or radians) as specified in the Inspector settings UI.

Helpers

There are a number of helpers that also make it easy to re-use much of the behavior you might see in the core Inspector features.

Helper	Description
`InterceptProperty`	This function enables lightweight transient "instrumentation" of a property of an object. You can provide callbacks for property mutation lifecycle points, such as after the property value changes. It returns an `IDisposable` that must be disposed to "uninstrument" the object and restore it to its original state.
`InterceptFunction`	This function enables lightweight transient "instrumentation" of a property of an object that is a function. You can provide callbacks for function invocation lifecycle points, such as after the function is called. It returns an `IDisposable` that must be disposed to "uninstrument" the function and restore it to its original state.
`ObservableCollection`	This class is a simple combination of an array and an `Observable`. The `Observable` fires whenever an item is added or removed.