BabylonJS/Babylon.js · error · Error

Instanced arrays are required for MSDF text rendering.

Error message

Instanced arrays are required for MSDF text rendering.

What it means

MSDF text rendering draws glyphs with instanced quads for performance. CreateTextRendererAsync checks the engine for `instancedArrays` capability and sprite-instancing feature support, and throws when either is missing, since the renderer cannot function without instancing.

Source

Thrown at packages/dev/addons/src/msdfText/textRenderer.ts:426

    }

    /**
     * Creates a new TextRenderer instance asynchronously
     * @param font define the font asset to use
     * @param engine define the engine to use
     * @returns a promise that resolves to the created TextRenderer instance
     */
    public static async CreateTextRendererAsync(font: FontAsset, engine: AbstractEngine) {
        if (engine.isWebGPU) {
            const { RegisterEnginesWebGPUExtensionsEngineAlphaToCoverage } = await import("core/Engines/WebGPU/Extensions/engine.alphaToCoverage.pure");
            RegisterEnginesWebGPUExtensionsEngineAlphaToCoverage();
        } else {
            const { RegisterEnginesExtensionsEngineAlphaToCoverage } = await import("core/Engines/Extensions/engine.alphaToCoverage.pure");
            RegisterEnginesExtensionsEngineAlphaToCoverage();
        }

        if (!engine.getCaps().instancedArrays || !engine._features.supportSpriteInstancing) {
            throw new Error("Instanced arrays are required for MSDF text rendering.");
        }

        let shaderLanguage = ShaderLanguage.GLSL;
        let vertex: string;
        let fragment: string;
        if (engine.isWebGPU) {
            shaderLanguage = ShaderLanguage.WGSL;
            vertex = (await import("./shadersWGSL/msdf.vertex")).msdfVertexShaderWGSL.shader;
            fragment = (await import("./shadersWGSL/msdf.fragment")).msdfPixelShaderWGSL.shader;
        } else {
            vertex = (await import("./shaders/msdf.vertex")).msdfVertexShader.shader;
            fragment = (await import("./shaders/msdf.fragment")).msdfPixelShader.shader;
        }

        const textRenderer = new TextRenderer(engine, shaderLanguage, font);
        textRenderer._setShaders(vertex, fragment);

        return textRenderer;

View on GitHub (pinned to 0592b347b8)

Solutions

  1. Use a WebGL2 or WebGPU engine, both of which support instancing: `new BAB.Engine(canvas)` resolves WebGL2 where available.
  2. Feature-check before creating: `if (!engine.getCaps().instancedArrays) { /* fallback to normal text (GUI text block / DynamicTexture) */ }`.
  3. Test on the actual target device — if a specific browser/device lacks instancing, provide a non-instanced text fallback path.

Example fix

// before
const renderer = await TextRenderer.CreateTextRendererAsync(msdf, engine, scene); // throws on WebGL1
// after
if (engine.getCaps().instancedArrays && engine._features.supportSpriteInstancing) {
  const renderer = await TextRenderer.CreateTextRendererAsync(msdf, engine, scene);
} else {
  // fallback: DynamicTexture-based text
}
Defensive patterns

Strategy: validation

Validate before calling

function supportsMsdfText(engine: BABYLON.AbstractEngine): boolean {
  return !!engine.getCaps().instancedArrays && engine._features.supportSpriteInstancing;
}
if (!supportsMsdfText(engine)) { /* use fallback text rendering */ }

Type guard

const isInstancingCapable = (e: BABYLON.AbstractEngine): boolean =>
  e.isWebGPU || e.webGLVersion >= 2 || !!e.getCaps().instancedArrays;

Try / catch

try {
  textRenderer = await TextRenderer.CreateTextRendererAsync(msdf, engine, scene);
} catch (e) {
  if (String(e).includes("Instanced arrays are required")) {
    textRenderer = null; // fallback: DynamicTexture text
  } else throw e;
}

Prevention

When it happens

Trigger: Calling TextRenderer.CreateTextRendererAsync(...) on an engine whose caps lack instancedArrays (typically WebGL1 without the OES_element_index_uint/instanced_arrays extension or a software renderer) or where `engine._features.supportSpriteInstancing` is false.

Common situations: Running on old devices/browsers or headless/software GL (swiftshader) without instanced_arrays; using a legacy WebGL1 engine; embedded webviews with limited GPU support.

Related errors

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/b7c5905639c0b8e0. Report an issue: GitHub.