Skip to content
vgai Learn

Share a material with a .mat.json

quick start Beginner ⏱ 4 min vgai 0.1.0

Prerequisites: Installed vgai and run the editor

What you'll learn

  • Author a shared material as a .mat.json asset
  • Reference it from multiple entities with materialRef
  • Know materialRef and inline material are mutually exclusive

What you'll build: Three shapes sharing one polished-gold material via materialRef.

Walkthrough — Share a material with a .mat.json · generated by site/media/lessons/learn-scenefeats.lesson.ts (4 steps)

Instead of copying material settings onto every entity, define a material once in a .mat.json file and point entities at it with materialRef. Change the file and every referencing entity updates. This scene has three shapes — box, sphere, cylinder — all wearing one polished-gold material.

Steps

Section titled “Steps”

  1. Open the scene. The scene is already open — if you followed the link above, the shared-material scene is loaded and rendering (in the local dev editor: VGAI_PROJECT=examples/learn-matfiles npm run dev): three shapes, identical gold finish.

    Three gold shapes
    Box, sphere, cylinder — one shared material.

  2. Select the GoldBox. A cube using the shared gold material (not an inline copy).

    GoldBox selected
    The cube references the shared material.

  3. Select the GoldSphere. Same gold material — reused, not duplicated.

    GoldSphere selected
    The sphere reuses the same material file.

  4. Select the GoldCylinder. All three entities materialRef the one .mat.json.

    GoldCylinder selected
    One material asset, three entities.
// polished-gold.mat.json (the shared asset)
{ "version": 1, "name": "Polished Gold",
  "material": { "type": "standard", "color": "#ffcc33", "metalness": 1.0, "roughness": 0.3 } }


// each entity references it (no inline `material`):
"materialRef": "materials/polished-gold.mat.json"

Recap

New functionality

  • Authored a shared material as a .mat.json
  • Referenced it from three entities with materialRef

New concepts & skills

  • A .mat.json is { version, name, material } — a reusable material asset
  • materialRef points an entity at it; one source, many objects
  • materialRef and inline material are mutually exclusive (load-time error)

Next lesson → Materials (manual)

On Your Own!

Extend what you built:

  • Edit polished-gold.mat.json (e.g. roughness) and reload — all three update
  • Add a fourth shape that materialRefs the same file
  • Make a second .mat.json and point one shape at it

See also

Section titled “See also”