The NeL pipeline uses glTF 2.0 as a lossless intermediate between authoring tools and the runtime asset formats (.skel, .shape, .anim, …). Standard glTF properties (translation, rotation, scale, matrix) get lossily transformed by import/export layers — assimp, in particular, combines per-node TRS into a single aiNode::mTransformation on read and requires the consumer to Decompose() it back, introducing precision loss on near-identity rotations and non-uniform scales.

To make the intermediate byte-lossless where it matters, tools that generate glTF for the NeL runtime write duplicate values in extras, and NeL's assimp-based readers prefer the extras when present, falling back to standard glTF properties otherwise. This preserves interop — Blender, three.js, and every other glTF consumer sees the standard fields and works correctly — while our roundtrip through the pipeline stays bit-exact.

The extras are scoped: per-node (aiNode::mMetaData after assimp import), per-mesh, etc. Extras on other structures are not currently used; if a future asset class needs them (e.g. per-primitive material flags), add a new section here and note the type mapping.

The extras represent the source truth as the writer saw it, not a suggestion. A reader that respects the extras must not renormalise, quantise, or re-decompose the values behind them — that's the whole point. If a reader wants to normalise (e.g., a runtime that requires unit quaternions), it should either normalise the standard rotation field or normalise a copy, keeping the extras semantics unchanged for downstream tools.

Aimed at aiNode. Assimp's glTF loader surfaces JSON extras as aiMetadata entries keyed by the JSON property name. Type mapping (assimp 5.x observed):

Written by pipeline_max_export_skel --gltf …; read by mesh_utils's exportSkels() when the source is a glTF file. If any of the T/R/S triples is incomplete, the reader falls back to decomposing mTransformation — so an artist-authored glTF without our extras still works.

Rationale for individual scalar keys instead of nel_translation: [x, y, z]: assimp's glTF-to-metadata mapping for JSON arrays has varied across versions. Scalar numbers map cleanly to typed aiMetadataEntry in every 5.x release; arrays are inconsistent. Ten extra keys per node is a small cost compared to a fragile array roundtrip.

Rationale for decimal-forced encoding: assimp's JSON parser picks the smallest integer type when the token has no . or e, so "nel_lodDisableDistance": 0 came through as AI_UINT64. The writer post-processes %.9g output and appends .0 if neither . nor e[E] appears, guaranteeing AI_DOUBLE.

Rationale for %.9g not %.17g: the source values are float32. 9 decimal digits are sufficient to round-trip float32 exactly through a double parser and back; 17 digits (needed for double bit-exactness) would just add noise-looking trailing digits with no information gain.

What about the standard translation/rotation/scale fields? The writer emits both. The standard fields make the glTF viewable in Blender, three.js, glTF-Validator etc. — where slight precision loss doesn't matter. The extras make our internal roundtrip bit-exact.

Standard glTF has no concept of either — they're NeL-runtime-specific and would be silently lost by a round-trip through a stock glTF pipeline. Preserving them in extras is what makes the mesh_export roundtrip carry a full skeleton.

Consumer code should read extras and prefer them over the standard fields when both are present and the extras form a complete set:

float tx, ty, tz, rx, ry, rz, rw, sx, sy, sz;
bool haveTrans = getNelFloat(node, "nel_tx", tx) & getNelFloat(node, "nel_ty", ty) & getNelFloat(node, "nel_tz", tz);
bool haveRot   = getNelFloat(node, "nel_rx", rx) & /* ...ry, rz, rw */;
bool haveScl   = /* nel_sx, sy, sz */;
if (haveTrans && haveRot && haveScl) {
    // use nel_* extras verbatim
} else {
    // fall back to assimp's Decompose(mTransformation)
}

All-or-nothing per triple: if a writer emits only two of three translation components, the reader treats the whole triple as missing rather than mixing extras with decomposed values. Cleaner failure mode, avoids partial-noise cases.

mesh_export exposes a --no-nel-extras flag that makes the reader ignore every nel_* per-node key and reconstruct transforms via Decompose(mTransformation) even when the extras are present. This is the same code path an artist-authored glTF without our extras hits, so with the flag we can:

• confirm the fallback is functionally correct (semantic content preserved end-to-end),
• measure the fallback's byte-accuracy floor against our extras-based path,
• catch regressions in the fallback that would otherwise be hidden by the extras always winning.

On the 9-file non-biped skeleton corpus, A vs B parity is:

The residual delta with the flag on is float noise in InvBindPos rotation cells from Decompose's row-magnitude renormalisation of the 3×3 — same class of noise Max's own arithmetic produces in the reference outputs (T3-epsilon per pipeline_max_design §9). Semantic correctness — bone hierarchy, names, in-engine animation appearance — is unaffected.

Use this flag in CI as a regression gate on the fallback path: it must always produce a valid .skel, and the byte-parity against the extras-based .skel should stay ≥90% on the corpus.

The current writer is nel/tools/3d/pipeline_max_export_skel/main.cpp::writeGltf(). The current reader is nel/tools/3d/mesh_utils/assimp_skel.cpp::walkSkelNode(). Both track this spec; a change to either without updating the other is a bug.

When adding a new extras key:

1. Update this page (add a row in the appropriate table).
2. Update both writer and reader in the same commit if both sides need to change.
3. Add a compile-time or CI check that reader knows about all keys writer emits (nice-to-have, not currently enforced).

Under consideration but not implemented:

• Mesh/shape extras for nel_material_flags, nel_lightmap_group, etc. Would move NeL-specific material data out of scene_meta sidecar files and into the glTF itself.
• Animation extras for nel_track_default, nel_loop_mode etc.
• Scene extras for nel_scene_version, nel_tag_time — for the tag-file roundtrip protocol from build_gamedata.
• Deprecation path if the standard glTF KHR_* extensions ever cover our needs (e.g., a glTF extension for non-uniform bone scale semantics). Extras are cheap to add and remove; extensions are conservative.

See also: Pipeline Max Design for the .max-side context, and mesh_utils/scene_meta.h for the JSON sidecar format currently used for non-transform NeL flags.