Registering Side Effects

What Are Side Effects?

In the context of tree-shaking, a side effect is any code that runs automatically when a file is imported, changing global state. Babylon.js has several categories:

When using pure imports, these side effects do not run automatically. You turn them on by calling the corresponding RegisterXxx() function.

Finding Registration Functions

All registration functions follow the naming pattern Register plus the PascalCase file name:

Type Register in your IDE and autocomplete will list available registration functions. The names map directly to the Babylon.js module paths you already know.

Categories of Registration

Material and Serialization Registration

Serialized content needs class and parser registration so Babylon.js can recreate objects by class name:

import { RegisterStandardMaterial, RegisterPBRMaterial, RegisterImageProcessingConfiguration, RegisterTexture, RegisterFresnelParameters } from "@babylonjs/core/pure";

RegisterStandardMaterial();
RegisterPBRMaterial();
RegisterImageProcessingConfiguration(); // Also registers ColorCurves automatically
RegisterTexture();
RegisterFresnelParameters();

Register these when loading .babylon files, snippets, or other serialized content that may contain those types.

Scene Component Registration

Some features add methods to existing classes such as Scene, Engine, Mesh, or Camera:

// Physics
import { RegisterJoinedPhysicsEngineComponent } from "@babylonjs/core/pure";
import "@babylonjs/core/Physics/joinedPhysicsEngineComponent.types";

RegisterJoinedPhysicsEngineComponent();
// Now scene.enablePhysics(), scene.getPhysicsEngine(), etc. are available

After registration, methods such as scene.enablePhysics() are available at runtime. The .types import makes TypeScript aware of the same methods.

Other common scene component registrations include:

import { RegisterRay, RegisterDepthRendererSceneComponent, RegisterBoundingBoxRenderer } from "@babylonjs/core/pure";

RegisterRay();
RegisterDepthRendererSceneComponent();
RegisterBoundingBoxRenderer();

Engine Extension Registration

Engine extensions add capabilities like texture loading, alpha blending, multi-render targets, and uniform buffers. Three tiered helpers let you register groups of extensions at once:

import { RegisterCoreEngineExtensions, RegisterStandardEngineExtensions, RegisterFullEngineExtensions } from "@babylonjs/core/pure";

RegisterCoreEngineExtensions(); // Minimum: DOM, render passes, GPU states, stencil
RegisterStandardEngineExtensions(); // Most apps: Core + textures, file loading, alpha, render targets, uniform buffers
RegisterFullEngineExtensions(); // Everything: Standard + cube/raw/dynamic textures, multi-render, multiview, queries, compute, video, debugging

For most applications, RegisterStandardEngineExtensions() is the right choice. All tiers are safe to call multiple times or in combination. Calling a higher tier after a lower one just adds the missing pieces.

You can also register individual extensions if you need fine-grained control:

import { RegisterEnginesExtensionsEngineMultiRender, RegisterEngineTransformFeedback } from "@babylonjs/core/pure";

RegisterEnginesExtensionsEngineMultiRender();
RegisterEngineTransformFeedback();

Node Editor Block Registration

Node Material, Node Geometry, Node Particle, Flow Graph, and Node Render Graph systems need block registration for deserialization and editor workflows.

Register all blocks for a system:

import { RegisterAllNodeMaterialBlocks } from "@babylonjs/core/pure";

RegisterAllNodeMaterialBlocks();

Or register only selected categories:

import { RegisterNodeMaterialPBRBlocks, RegisterNodeMaterialMathBlocks, RegisterNodeMaterialVertexBlocks } from "@babylonjs/core/pure";

RegisterNodeMaterialPBRBlocks();
RegisterNodeMaterialMathBlocks();
RegisterNodeMaterialVertexBlocks();

Bulk registrations include:

XR Feature Registration

import { RegisterWebXRDefaultExperience, RegisterWebXRHandTracking, RegisterWebXRAnchorSystem, RegisterWebXRHitTest } from "@babylonjs/core/pure";

RegisterWebXRDefaultExperience();
RegisterWebXRHandTracking();
RegisterWebXRAnchorSystem();
RegisterWebXRHitTest();

Automatic Dependencies

Some registration functions automatically register the features they depend on. For example:

• RegisterImageProcessingConfiguration() automatically calls RegisterColorCurves().
• RegisterStandardMaterial() registers the class and its parser.

You do not need to manually register dependencies that are already handled this way. If you are unsure, calling a registration function multiple times is harmless.

The CheckMissingImports Diagnostic

If you're unsure which registrations your app needs, use the diagnostic utility:

import { CheckMissingImports } from "@babylonjs/core/Misc/checkMissingImports";

// Call after all your imports but before scene logic
const missing = CheckMissingImports();

This scans all known placeholders (stubs) and reports which features haven't been registered:

[Babylon.js] The following side-effect modules have not been imported:
  - Ray
  - ImageProcessingConfiguration
  - Texture
Note: These are only required if your application uses the corresponding features.
If you do use them, import the modules or their parent packages to avoid runtime errors.
See: https://doc.babylonjs.com/setup/treeshaking

Important: CheckMissingImports reports ALL unregistered stubs, even ones your app may never hit. Not every reported module needs to be imported — only the ones your code actually uses.

This utility is intended for development only. It imports several core modules to test their stubs, so don't include it in production builds.

Runtime Stub Warning Diagnostics

CheckMissingImports() reports all known unregistered stubs, including features your app may never use. If you want to debug only the missing side-effect registrations that are actually called at runtime, enable one-time stub warnings:

import { SetMissingSideEffectWarningsEnabled } from "@babylonjs/core/Misc/devTools";

SetMissingSideEffectWarningsEnabled(true);

Missing side-effect stubs are quiet by default because Babylon internals may probe optional augmented APIs. When warnings are enabled, each missing Class.method logs at most once. For code that intentionally probes optional APIs, suppress warnings around the synchronous probe:

import { SuppressMissingSideEffectWarnings } from "@babylonjs/core/Misc/devTools";

SuppressMissingSideEffectWarnings(() => {
  scene.getPhysicsEngine?.();
});

Keep runtime stub warnings as a development diagnostic unless your application intentionally wants this logging in production.

Safe to Call Multiple Times

All registration functions are safe to call more than once. Only the first call actually does anything:

RegisterStandardMaterial();
RegisterStandardMaterial(); // No-op, already registered
RegisterStandardMaterial(); // No-op

This means:

• You can safely call registration functions from multiple modules.
• Libraries can register what they need without worrying about duplicate calls.
• The order of registration usually does not matter, except for dependencies that must exist before use.

Migration from Existing Side-Effect Imports

To migrate an existing side-effect import:

// Before:
import "@babylonjs/core/Physics/joinedPhysicsEngineComponent";

// After:
import { RegisterJoinedPhysicsEngineComponent } from "@babylonjs/core/pure";
RegisterJoinedPhysicsEngineComponent();

The mapping is straightforward:

1. Take the side-effect import path.
2. Add .pure before the extension.
3. Import the matching RegisterXxx function from @babylonjs/core/pure, where Xxx is the PascalCase filename.
4. Call it before using the feature.
5. Add the .types import when the feature augments TypeScript types.

Further reading

Tree-Shaking with Pure Imports

Use the Babylon.js pure barrel to keep a single import surface while preserving tree-shaking.

Using Pure Imports

Import Babylon.js through pure paths and the pure barrel without losing tree-shaking.

Troubleshooting Pure Imports

Diagnose common runtime and TypeScript issues when using Babylon.js pure imports.