Materials as assets and property type

[vincentfretin]

Fixes #5457

Description

Materials can now be defined once in <a-assets> and shared across any number of entities, instead of every entity creating its own THREE.Material:

<a-assets>
  <img id="wood-texture" src="wood.png">
  <a-material id="wood" src="#wood-texture" roughness="0.8"></a-material>
  <a-material id="red" shader="flat" color="red"></a-material>
</a-assets>

<!-- Both boxes share the exact same THREE.Material instance. -->
<a-box material="material: #wood"></a-box>
<a-box material="material: #wood"></a-box>

<a-material> asset element (src/core/a-material.js)

• Creates the material through the registered shader system (standard, flat, or any custom shader) during scene loading, including its textures; <a-assets> blocks scene rendering until the material and its textures are ready.
• Properties are individual HTML attributes combining the material component base schema and the selected shader's schema. Attribute names are matched case-insensitively against the schema (HTML lowercases attributes, e.g. normalmap → normalMap).
• Changing an attribute after creation updates the shared material live for every entity using it (shader cannot be changed after creation).
• Removing the element from the DOM disposes the material and its textures.

material property type (src/core/propertyTypes.js)

Resolves an ID selector to the underlying shared THREE.Material. Any component can accept a material in its schema (e.g. the hand-tracking-controls use case from the issue):

AFRAME.registerComponent('my-component', {
  schema: {highlightMaterial: {type: 'material'}}
});

It also accepts a THREE.Material instance directly, and inline definitions (below). Stringification round-trips to #id / material(...) for flushToDOM.

Material component integration (src/components/material.js)

• New material property: material="material: #wood". When set, the shared material is used as-is and all other material component properties are ignored (the asset fully defines the material).
• The component does not take ownership of shared materials: it never disposes/re-registers them, and remove()/material switching leaves them intact. Setting material back to empty returns the entity to its own component-managed material.
• Works with primitives: <a-box material="material: #wood">.

Inline material(...) definitions

For one-off materials, the property type also accepts an inline definition (the optional syntax proposed in the issue):

<a-entity hand-tracking-controls="hand: right; handMaterial: material(shader: flat; color: red)"></a-entity>
<a-box material="material: material(color: #8B4513; roughness: 0.9)"></a-box>

Each inline definition is backed by an <a-material> element automatically attached under the scene's <a-assets>; identical definition strings are cached and share a single THREE.Material instance.

To support semicolons inside the parentheses, styleParser no longer splits style strings inside parenthesized values — a generalization of the existing unclosed-url( special case for data URIs.

Commits

1. Move shared material helpers to utils/material — pure refactor: parseSide, parseBlending, disposeMaterial and base property assignment (updateBaseMaterial) extracted from the material component for reuse.
2. Add <a-material> asset element and material property type — the core feature, tests, docs, examples.
3. Fix primitive mapping collision with material material property — the new schema property collided with the material component name in auto-generated mesh primitive mappings, spamming a "mapping collision" warning per primitive.
4. Fix <a-material> texture loading when created before scene systems exist — on-demand creation by an early property parse (e.g. setAttribute at DOMContentLoaded) crashed on the missing material system; texture loading is now deferred until the system is available.
5. styleParser: don't split style strings inside parentheses.
6. Support inline material() definitions in the material property type.
7. Fix styleParser re-entrancy corrupting the pooled chunks array — found while testing the inspector: the component attrValueProxy setter synchronously parses the inline material(...) value, and that nested parse clobbered the pooled chunks array of the outer parse (leaking inner keys into attrValue, dropping outer properties).

Performance

Measured with examples/test/material-asset/perf.html (Chrome, Linux, 500-frame sample; ?shared=&n= to reproduce):

	shared <a-material>	per-entity materials
2000 boxes — load time	788–845 ms	1150 ms
8000 boxes — frame avg / p50	16.9 / 16.7 ms (60 fps)	25.0 / 24 ms (~40 fps)
8000 boxes — unique materials	2	8001
8000 boxes — settled JS heap	103 MB	326 MB

GL program count and GPU texture count are identical in both modes (three.js already deduplicates programs, and the texture source cache deduplicates uploads), so the wins are per-material CPU overhead in the render loop, loading time, and memory.

Tests

• tests/core/a-material.test.js (13 tests): creation from attributes, shader defaults, texture load blocking, instance sharing, live attribute updates, dispose ownership (entity switch/removal vs asset removal), early-creation regression, inline materials (cache sharing, single-property schema).
• tests/core/propertyTypes.test.js: material type parse/stringify incl. inline round-trip.
• tests/extras/primitives/primitives.test.js: no material/material-material primitive mapping.
• tests/utils/styleParser.test.js (new file): paren-aware splitting incl. data URIs and nested parens.

Full suite: 1200+ passing; the only failures are the 2 look-controls touch-drag tests that fail identically on master in this environment (canvas-size assertion, unrelated).

Docs & examples

• New docs/primitives/a-material.md; updates to docs/components/material.md, docs/core/component.md (property types table), docs/core/asset-management-system.md.
• examples/test/material-asset/index.html (demo: shared texture/PBR/transparent materials, inline materials) and examples/test/material-asset/perf.html (benchmark used for the numbers above).

🤖 Generated with Claude Code

[mrxz]

Nitpick: an <a-material>

I'd also drop the word "shared". While one of the primary benefits is material sharing, it's not inherently required. Nothing wrong with a user creating an <a-material> and only using it for a single object, for example.

[vincentfretin]

Fixed in 93d7c09: "an <a-material>" and dropped the "shared" wording.

[mrxz]

This description should probably no longer mention materials to avoid confusion.

[vincentfretin]

Done in 93d7c09, the <a-asset-item> line no longer mentions materials.

[mrxz]

Nitpick: I don't think "shared" needs to be highlighted here, as this applies to most assets. You can "share" the same audio, image tag as well. Something simple like "Materials and their textures" probably suffices.

[vincentfretin]

Done in 93d7c09, now reads "Materials and their textures".

[mrxz]

Instead of instantiating new empty arrays for nested calls, we could turn pooledChunks into an array of arrays. One entry for each level.

In fact, we could even consider limiting the amount of "nesting" we allow. Maybe even as low as 2 levels, and throwing an Error if this is exceeded. With the idea that under normal usage you wouldn't encounter this (or if you did, you probably wouldn't want it).

For the getKeyValueChunks method it could receive the chunks array to use and the styleParse function could pass it using pooledChunks[parseDepth] (as well as throw if we introduce an upper bound)

[vincentfretin]

Good idea, done in 6f786c5: pooledChunks is now an array of arrays indexed by parse depth, getKeyValueChunks receives the chunks array to use, and nesting is capped at two levels (outer style string + nested parse from a property assignment, e.g. an inline material value) — exceeding the cap throws. parseDepth is decremented in a finally so a throwing property setter cannot poison subsequent parses. Added a test for the cap and recovery.

[mrxz]

Minor point, but the material would now also be marked as needing an update if the attribute is changed to the same value, as attributeChangedCallback still fires in that case.

But looking at it more closely, I think we could move this logic into updateBaseMaterial and actually check if any of the relevant properties changed. That would also make the logic in material.js easier, as it now bases it on the oldData properties, whereas the material itself should be the source of truth.

[vincentfretin]

Good point, done in ef50899: updateBaseMaterial now compares against the material itself and only flags needsUpdate when alphaTest/side/vertexColors actually change. That removed the oldData diff from the material component (updateMaterial is now a one-liner) and the explicit flag in <a-material>'s attributeChangedCallback. Added a test that setting an attribute to its current value does not bump material.version while a real change does.

[vincentfretin]

Changes for the inspector: aframevr/aframe-inspector#859