Understanding the glTF extras Field for Custom Data

The extras field in glTF (GL Transmission Format) is a reserved property that allows developers to store custom, application-specific metadata directly within a 3D asset without violating the format's core specification. This article explains what the extras property is, where it can be applied within a glTF file, how it enables flexible data exchange between DCC (Digital Content Creation) tools and runtime engines, and the best practices for implementing it effectively.

What Is the extras Field?

In the glTF 2.0 specification, standard objects strictly define how 3D data—such as geometry, materials, animations, and scene hierarchies—should be structured and rendered. However, real-time applications often require additional information that falls outside standard visual rendering, such as gameplay mechanics, physics properties, or sound triggers.

To accommodate this, glTF specifies the extras property on virtually every core glTF object, including:

  • Nodes (transforms and scene graph elements)
  • Meshes and Primitives
  • Materials
  • Textures and Images
  • Animations and Animation Channels
  • Skins
  • Cameras
  • The root glTF asset object

Any valid JSON data type can be assigned to an extras field, including objects, arrays, strings, numbers, booleans, and null values.

How extras Provides Application-Specific Data

The primary function of extras is to act as a bridge between content creation tools (like Blender, Maya, or 3ds Max) and runtime environments (such as Three.js, Babylon.js, Unity, or Unreal Engine).

1. Preserving DCC Custom Properties

When artists define custom attributes in 3D modeling software, exporters can map those attributes directly into the extras field of the corresponding glTF element. For example, a custom property defined on an object in Blender can be automatically exported as:

{
  "nodes": [
    {
      "name": "TreasureChest",
      "mesh": 0,
      "translation": [0.0, 1.0, 0.0],
      "extras": {
        "isInteractable": true,
        "lootTier": "rare",
        "respawnTimeSeconds": 120,
        "collisionType": "box"
      }
    }
  ]
}

2. Runtime Retrieval and Logic

Because standard glTF loaders parse the extras object alongside the asset's structural data, runtime engines can inspect these fields during or after loading. In a WebGL application using Three.js, for example, the loaded node preserves this object under node.userData, allowing developers to read gameplay parameters or setup custom colliders dynamically:

loader.load('chest.gltf', (gltf) => {
  const chest = gltf.scene.getObjectByName('TreasureChest');
  if (chest.userData.isInteractable) {
    registerInteractionTrigger(chest, chest.userData.lootTier);
  }
});

3. Non-Destructive Extension

Unlike custom extensions (defined via extensions and extensionsUsed), the extras property does not require formal schema registration or extension handlers. Standard glTF parsers safely ignore extras data they do not recognize, ensuring the visual rendering of the model remains unaffected across different software pipelines.

Best Practices for Using extras

  • Use Namespacing: If multiple pipelines or plugins process the same file, use nested objects with dedicated vendor or application prefixes (e.g., "extras": { "myApp_physics": { ... } }) to prevent key collisions.
  • Keep Payloads Lightweight: Storing excessively large data sets (such as embedded binary streams or massive arrays) in extras inflates the JSON file size and slows down text parsing. Large binary structures should instead use glTF buffers and custom extensions.
  • Do Not Override Core Behavior: Avoid using extras to convey data that alters standard PBR rendering or transform hierarchies. Standard features or official glTF extensions should always handle graphics-critical behavior to maintain visual consistency.