Add native Draco and meshopt codec plugins

[bkaradzic-microsoft]

Adds native C++ implementations of the Draco and meshopt mesh decoders as two
new optional plugins, NativeDraco and NativeMeshopt.

Today Babylon Native runs these codecs through the same WASM modules the web
uses. That pulls a WASM runtime into a native app purely to decompress meshes,
costs a module instantiation per session, and copies buffers across the JS/WASM
boundary. These plugins let the native host do the work directly.

What's here

Plugin	Exposes	Replaces
NativeDraco	_native.DracoCodec.Decode(data, attributeIds?)	draco_decoder_gltf.wasm
NativeDraco	_native.DracoCodec.Version	—
NativeMeshopt	_native.MeshoptCodec.Decode(source, count, stride, mode, filter?)	meshopt_decoder.wasm
NativeMeshopt	_native.MeshoptCodec.Version	—

Each codec is a single object rather than a set of free functions, so the
JavaScript side needs one feature probe per codec instead of one per entry
point, and so the object can publish the codec version compiled into the
binary. Version matters because meshoptimizer records its codec version in the
first header byte and a decoder refuses streams newer than it understands; a
bare function name gives a caller no way to find that out except by failing.

DracoCodec.Decode supports both call shapes the Babylon loaders use: the glTF
path, where the caller passes the EXT/KHR_draco_mesh_compression map of
Babylon vertex-buffer kind to Draco unique id, and the standalone .drc path,
where no map is supplied and the plugin probes the standard named attributes.
Attribute data is de-interleaved and tightly packed per point, mirroring
emscripten's GetAttributeDataArrayForAllPoints that the WASM decoder relies
on, so the returned buffers are drop-in equivalents.

Dependencies

Two new FetchContent dependencies, both pinned to release tags:

• google/draco @ 1.5.7
• zeux/meshoptimizer @ v0.22

Both are declared EXCLUDE_FROM_ALL and built with tests, install, executables
and JS glue disabled. draco adds its include directories as PRIVATE, so
Dependencies/CMakeLists.txt re-exports them as PUBLIC on the combined
target; the target is named draco under MSVC and draco_static elsewhere and
both spellings are handled.

draco is additionally built with DRACO_GLTF_BITSTREAM=ON, which compiles only
mesh compression, normal encoding and the standard edgebreaker. That is the
same subset draco_decoder_gltf.wasm is built with, and that module is what
Babylon.js's default configuration loads, so this costs no capability the
JavaScript path has. It drops point cloud compression, the predictive
edgebreaker and pre-glTF backwards compatibility; point cloud streams return a
Draco error instead of decoding, matching Babylon.js.

Footprint, and why both plugins default to OFF

Both options default to OFF. Nothing routes to these entry points until the
Babylon.js side lands, so until then no consumer should be paying for them.
Measured on Playground, Win32 x64, RelWithDebInfo, same tree, only the two
options changed:

configuration	Playground.exe	delta
both OFF (default)	11,100,672 B	baseline
NativeMeshopt only	11,132,928 B	+31.5 KB
both ON	11,734,528 B	+619 KB (+5.7%)

meshoptimizer is nearly free; draco is +587 KB.

Draco started at +1.64 MB. Two things brought it down, both of which track
Babylon.js more closely rather than less:

• No encoder. Babylon.js does not bundle one either — DracoDecoder loads
  draco_decoder_gltf.wasm and DracoEncoder fetches a separate
  draco_encoder.wasm on demand. Linking the encoder here would cost every
  binary ~1.2 MB to serve an authoring path Babylon Native does not exercise.
• DRACO_GLTF_BITSTREAM, as described above.

Together that is a 65% reduction in draco's contribution, which is close enough
to what a minidraco fork would buy that staying on the upstream bitstream looks
like the better trade.

Trust boundary

Worth stating plainly, because it cuts both ways:

• On V8 and JavaScriptCore, this moves decoding of untrusted mesh data
  out of the WASM sandbox and into the host process.
• On QuickJS and Hermes there is no WebAssembly at all, so this is
  net-new capability rather than a relocation of existing capability.
• It removes a runtime fetch of executable code from a CDN, since no .wasm
  ships in this tree.

That is the reason the input-validation and malformed/truncated-input tests
below exist, and why the codecs validate every caller-supplied extent rather
than trusting the calling loader.

Scope

The change is additive. Nothing existing is modified except the CMake
wiring that registers the new plugins, four lines in
Embedding/Source/Runtime.cpp that initialize them, the UnitTests wiring for
the new coverage, and the three CI workflows that enable the plugins for the
jobs which run UnitTests. No existing plugin, engine path, or test
configuration is touched, and Apps/Playground/Scripts/config.json is
deliberately left alone.

On validation

These entry points are not reachable from the currently pinned babylonjs
npm package (9.15.0), so the plugins are inert until the corresponding
Babylon.js side lands and the loaders start feature-detecting them. The
validation suite therefore cannot exercise this code, but Apps/UnitTests
can, and now does.

Both plugins are linked and initialized in Apps/UnitTests behind their
options, and tests.javaScript.all.ts carries a describe block for each — 16
cases covering decoding and malformed, truncated and out-of-range input for
every entry point. The blocks report as skipped when the build did not opt
in, rather than passing vacuously; CI enables both options for the Linux, macOS
and Win32 jobs that run UnitTests, including the sanitizer configurations.

Neither codec's positive test is self-referential. Since neither plugin exposes
an encoder, both fixtures come from the reference JavaScript encoders, which
pins these decoders to the upstream bitstreams rather than to themselves:

• Draco — two fixtures from draco3dgltf 1.5.7, the same package
  Babylon.js takes its decoder from. One is a two-triangle mesh; the other is a
  63-vertex sphere carrying POSITION, NORMAL and TEX_COORD, which covers
  multi-attribute decoding and a non-degenerate edgebreaker traversal — the
  parts DRACO_GLTF_BITSTREAM actually restricts.
• meshopt — a stream from the reference meshoptimizer 0.22.0 encoder,
  with the test asserting the native decoder reproduces the original bytes
  exactly.

The sphere fixture is worth a note. It decodes to 62 vertices and 91
triangles, not the 63 and 96 that were encoded: Draco merges points whose
attributes all match and drops the degenerate triangles at the poles. Rather
than adjust the expected numbers to whatever this decoder produced, they were
taken from the reference draco3dgltf decoder run over the same buffer, which
reports 62 points and 91 faces. This decoder reproduces that exactly.

meshoptimizer's vertex codec is versioned in the first header byte. Encoders
from 0.23.0 onward emit format version 1 (0xa1), which a v0.22 decoder
correctly rejects with -1, so the encoder used to produce the fixture was
version-matched deliberately. That version is now also pinned at compile time
with a static_assert, because bgfx vendors its own copy of meshoptimizer and
the dependency guard skips our FetchContent when a target of that name
already exists — a mismatch there would surface as silent data corruption
rather than a build break.

• No regression. Full validation suite on this branch:
  ran=295 passed=295 failed=0 missingRef=0 skipped=420, identical to the
  upstream master baseline. (Indices 53–57 are excluded from the run: they
  crash in RendererContextD3D11::submit on pristine master too.)
• Unit tests. JavaScript.All — 42 passing, 0 failing.

Note for the Babylon.js side

dracoEncoder.ts on the Babylon.js side feature-detects _native.encodeDracoMesh.
With no native encoder that probe is simply false and it falls back exactly as
it does today, so nothing breaks — but the paired Babylon.js change should drop
that hunk rather than ship a probe that can never succeed. If the capability is
wanted, the encoder can come back behind an off-by-default option.

[Copilot]

Pull request overview

Adds two new native codec plugins (NativeDraco, NativeMeshopt) to replace the current WASM-based Draco/meshopt mesh decoding path in Babylon Native, wiring them into the Embedding runtime and build system via new FetchContent dependencies.

Changes:

• Introduces C++ N-API implementations for _native.decodeDracoMesh, _native.encodeDracoMesh, and _native.decodeMeshopt.
• Adds CMake targets for the new plugins and wires them into Embedding initialization.
• Adds draco and meshoptimizer as FetchContent dependencies and configures their builds for use as libraries.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
Plugins/NativeMeshopt/Source/NativeMeshopt.cpp	Implements native meshopt decode entry point exposed to JS.
Plugins/NativeMeshopt/Include/Babylon/Plugins/NativeMeshopt.h	Declares NativeMeshopt initialization API.
Plugins/NativeMeshopt/CMakeLists.txt	Builds/link-wires the NativeMeshopt plugin.
Plugins/NativeDraco/Source/NativeDraco.cpp	Implements native Draco decode + encode entry points exposed to JS.
Plugins/NativeDraco/Include/Babylon/Plugins/NativeDraco.h	Declares NativeDraco initialization API.
Plugins/NativeDraco/CMakeLists.txt	Builds/link-wires the NativeDraco plugin.
Plugins/CMakeLists.txt	Registers the new plugin subdirectories in the plugin build.
Embedding/Source/Runtime.cpp	Initializes the new plugins during runtime setup.
Embedding/CMakeLists.txt	Links the new plugins into the Embedding target.
Dependencies/CMakeLists.txt	Fetches/configures draco + meshoptimizer dependency targets.
CMakeLists.txt	Declares new FetchContent sources for draco and meshoptimizer.

[bkaradzic-microsoft]

Pushed 5d89056 addressing all five review comments plus the macOS/iOS build break.

Build break (macOS / iOS)

NativeDraco.cpp used long for vertex and face counts. That's 32-bit on MSVC but 64-bit on the Apple toolchains, so narrowing it to draco's uint32_t index types tripped -Werror,-Wshorten-64-to-32 at three sites. All three now use uint32_t directly. Windows/Linux/Android were green precisely because long is 32-bit there — worth noting for anyone reviewing similar code.

Plugin gating

You're right, and it mattered more than just convention. Both plugins now have BABYLON_NATIVE_PLUGIN_NATIVEDRACO / BABYLON_NATIVE_PLUGIN_NATIVEMESHOPT options (default ON), wired through all four of the usual places — root CMakeLists.txt, Plugins/CMakeLists.txt, Embedding/CMakeLists.txt (option + compile definition + link), and the #if guards in Runtime.cpp.

I also gated the FetchContent blocks in Dependencies/CMakeLists.txt on the same options, since otherwise turning a plugin off would still pay for its dependency. Verified end to end: configuring with both OFF fetches neither draco nor meshoptimizer (no _deps entries for them) and Embedding still compiles.

Input validation

All four findings were real. Fixed and each one verified to now raise a JS exception rather than misbehave:

Input	Before	Now
Draco attribute size: 0	division by zero	attribute 'size' must be in [1, 127], got 0
Draco attribute size: -3	negative component count	same range error
attribute length not divisible by size	silent truncation	data length (4) is not a multiple of its component count (3)
index 99 with 3 vertices	out-of-bounds read in the corner table builder	index 99 is out of range for 3 vertices
index count 4	silently truncated to 1 face	index count (4) is not a multiple of 3
Float32Array indices	reinterpreted as Uint16Array	indices must be a Uint16Array or a Uint32Array
meshopt stride: 0	zero-size allocation	stride must be in [1, 256], got 0
meshopt count: -1	wrapped to a huge size_t	count must not be negative, got -1
meshopt stride: 512	past the codec limit	stride must be in [1, 256], got 512
meshopt ATTRIBUTES stride 6	not a multiple of 4	explicit error
meshopt TRIANGLES stride 12	must be 2 or 4	explicit error
unknown mode	—	unchanged, still rejected

Worth calling out for the meshopt ones: meshoptimizer validates count/stride with assert(), which compiles out under NDEBUG, so these were undefined behavior in release builds rather than a caught error. The decoded size is now also bounded to 2 GB so count4 * stride can't wrap.

Range guards compare through uint64_t so they stay well-defined on 32-bit ABIs instead of turning into tautological comparisons.

Unindexed meshes now also require a vertex count that's a multiple of 3 rather than silently dropping the remainder.

Verification

• 12/12 malformed inputs rejected with a clear message, 0 missed.
• Draco encode -> decode round trip unchanged (both the attributeIds and named-probe paths).
• meshopt decode still a byte-exact match.
• Validation suite: ran=300 passed=300 failed=0 missingRef=0 skipped=420, same as the upstream baseline.

[bkaradzic-microsoft]

CI is green across all 34 checks.

The four macOS/iOS jobs that were failing (MacOS, MacOS_QuickJS, MacOS_Xcode26, MacOS_Sanitizers, iOS_Xcode26, iOS_Installation, MacOS_Installation) all pass with the long -> uint32_t narrowing fix.

One note for the record: Win32_x64_D3D11 failed on the first run of this commit with a pixel diff on OpenPBR Analytic Lights Anisotropy — a test unrelated to this PR. It was a flake, and it passed on re-run. Evidence, in case it recurs for someone else:

• The CI diff was 37.9% of pixels with the first mismatch reading (51, 51, 76) against an expected (1, 1, 1) — i.e. the frame rendered background where geometry should have been, rather than a subtly wrong shade.
• Running the same test locally on this exact commit gives 0.524% (limit 2.5%), a comfortable pass.
• The test pulls playground #GRQHVV#61 plus GUI assets and fonts from the snippet server, which the runner already calls out as a likely async asset-load timing flake.
• The identical plugin code passed Win32_x64_D3D11 on the previous push, and nothing in this PR is reachable from that test.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

Plugins/NativeMeshopt/Source/NativeMeshopt.cpp:84

• The decoded-size guard can be bypassed for very large countIn values because count4 (a size_t) is narrowed to int64_t in the check. If count4 > INT64_MAX, the cast becomes negative and the limit check can fail, potentially leading to a huge allocation (or wrap/DoS). Avoid narrowing casts and validate the rounded count4 using unsigned arithmetic before allocating.

            const size_t count = static_cast<size_t>(countIn);
            const size_t stride = static_cast<size_t>(strideIn);

            // Round count up to a multiple of 4 (the reference decoder over-allocates
            // and runs the vertex filter over count4 elements).
            const size_t count4 = (count + 3) & ~static_cast<size_t>(3);

            // Guard the allocation size so a huge count cannot wrap size_t.
            constexpr int64_t maxDecodedBytes = 1LL << 31;
            if (static_cast<int64_t>(count4) * strideIn > maxDecodedBytes)
            {

Plugins/CMakeLists.txt:25

• This block’s indentation is inconsistent with the surrounding plugin if()/endif() sections (and currently makes it look like NativeInput is nested under NativeEngine). Align the if/endif indentation to match the rest of the file for readability/maintenance.

if(BABYLON_NATIVE_PLUGIN_NATIVEENGINE)
    add_subdirectory(NativeEngine)
    endif()

    if(BABYLON_NATIVE_PLUGIN_NATIVEINPUT)

[bkaradzic-microsoft]

Good catch — fixed in d784a88.

draco declares the combined library plus ~25 internal object libraries (draco_core, draco_mesh, draco_compression_*, draco_points_*, ...). I had only set FOLDER on draco / draco_static, so the other 25 landed at the top level of the solution, sitting right next to the Babylon Native projects.

Rather than hand-listing them — which would go stale the next time draco reorganizes its build — I added a small group_directory_targets helper that walks a directory's BUILDSYSTEM_TARGETS plus nested SUBDIRECTORIES and assigns the folder to every non-INTERFACE target. It's applied to both draco and meshoptimizer.

Verified against the regenerated solution:

Folder	Targets
Dependencies/draco	26
Dependencies/meshoptimizer	1
Plugins (NativeDraco, NativeMeshopt)	2

and no target anywhere in the solution is left ungrouped — which wasn't true before this PR either, so this cleans up the tree slightly beyond just the draco additions.

[bghgary]

[Reviewed by Copilot on behalf of @bghgary]

Two comments inline. The code itself looks careful; both points are about what the change implies rather than what it does.

[bghgary]

[Reviewed by Copilot on behalf of @bghgary]

LGTM. A few asks inline.

[bghgary]

[Reviewed by Copilot on behalf of @bghgary]

LGTM.