A-Frame ECS and Three.js Transform Authority: Which Should Be the Source of Truth During Animation?

Answer to the Core Question

For per‑frame animation in tick, mutating el.object3D directly is a documented, supported pattern, but it is *not* the single source of truth for the framework. The authoritative state for the entity’s transform remains the DOM attributes (or the component data that those attributes drive). Updating the Three.js matrix alone does not propagate changes back to the attribute system; other components that read el.getAttribute('position') will see stale values unless you manually sync them.

Why the Attribute System Remains the Source of Truth

• All A‑Frame components rely on the attribute lifecycle (setAttribute → update) to react to changes.
• Physics, collision, and third‑party extensions often query getAttribute for positioning.
• Direct object3D mutations bypass the component lifecycle, breaking those expectations.

Recommended Approach for Tick‑Based Animation

1. Update component data via setAttribute or the component’s data property. Example:

   tick: function (t, dt) {
     const pos = this.el.getAttribute('position');
     pos.x += 0.01 * dt;
     this.el.setAttribute('position', pos);
   }
   

2. Let A‑Frame convert the attribute change to a object3D matrix internally.
3. If you need to avoid the overhead of writing to the DOM every frame, consider batching updates or using a custom property that mirrors the attribute value, but still keep the DOM attribute in sync when other components may read it.

Using object3D Directly – When and How

• When you are certain no other component reads the attribute. For example, a lightweight visual effect that never interacts with physics.
• After mutating object3D, manually sync the attribute if needed:

  this.el.object3D.position.set(1,2,3);
  this.el.setAttribute('position', '1 2 3');
  

• Alternatively, cache the value in a custom property (e.g., el._cachedPosition) and expose a getter for other components to use. This avoids DOM writes but bypasses the normal lifecycle.

Version Consistency (A‑Frame 1.x)

All releases from 1.0.0 to 1.5.x maintain the same attribute‑to‑object3D sync logic. No version‑specific changes affect the decision; the framework still treats attributes as the source of truth.

How to Verify Sync in the Dev Console

1. Pick an entity:

   const el = document.querySelector('a-entity');

2. Directly mutate the Three.js matrix:

   el.object3D.position.set(5, 5, 5);

3. Read the attribute immediately:

   console.log(el.getAttribute('position')); // still old value

4. Sync the attribute:

   el.setAttribute('position', '5 5 5');

5. Now el.getAttribute('position') matches the matrix.

Diagnostic Question

If other components on the entity rely on getAttribute('position') for logic (e.g., physics or collision), you must keep the attribute in sync. If not, direct object3D mutation with manual sync when necessary is acceptable.