[x3d-public] X_ITE External SAI — Request for Clarification and Documentation

[cbullard at hiwaay.net]

All,

We are developing MCCF (Multi-Channel Coherence Field), an open-source
simulation system that uses X3D 4.0 as its spatial visualization layer.
Repository: https://github.com/artistinprocess/mccf

We have been working through X_ITE 11.6.6 external SAI behavior and have
reached a point where we need clarification before proceeding further.
John Carlson has been helpful and we are grateful. This post summarizes
our findings and asks for precise documentation or correction.

---

## What We Have Confirmed Working

Through systematic testing, the following external SAI patterns produce
correct visual results in X_ITE 11.6.6 (Firefox and Edge, Windows 11):

```javascript
// Scalar fields — requires X3D. typed constructor
node.intensity    = new X3D.SFFloat(0.9);     // ✓ visual update 
confirmed
node.transparency = new X3D.SFFloat(0.3);     // ✓ visual update 
confirmed

// Vector fields — requires X3D. typed constructor
node.translation  = new X3D.SFVec3f(x, y, z); // ✓ visual update 
confirmed

// String fields — plain array works
node.string = ["text"];                        // ✓ visual update 
confirmed
```

John Carlson confirmed the `X3D.` namespace prefix requirement for 
external
SAI. This diverges from the W3C SAI specification which defines global
constructors (`new SFColor(r,g,b)` etc.) but is consistent with X_ITE's
approach of namespacing its types to avoid global namespace pollution.

---

## What Does Not Work

The following assignments are accepted without error, the internal 
object
state updates (confirmed via console inspection of Symbol-keyed 
properties
including `X_ITE.Color3.r/g/b`), but **no visual update occurs**:

```javascript
// Color fields — value stored internally but no visual redraw
mat.emissiveColor = new X3D.SFColor(r, g, b);   // ✗ no visual update
mat.diffuseColor  = new X3D.SFColor(r, g, b);   // ✗ no visual update
mat.set_emissiveColor = new X3D.SFColor(r, g, b); // ✗ no visual update

// Light color — same behavior
light.color = [r, g, b];                         // ✗ no visual update
light.color = new X3D.SFColor(r, g, b);         // ✗ no visual update

// Light intensity — value stored, no visual update
light.intensity = new X3D.SFFloat(0.9);         // ✗ darkens scene 
instead
```

Console inspection confirms the color values ARE stored in the X_ITE
internal object (`Symbol("X_ITE.Color3.r"): 0.588` etc.) but the
renderer does not update. Our hypothesis is that external SAI color
assignments do not propagate the dirty flag to the parent Shape or
Appearance node, so the render loop does not know to redraw.

---

## Our Questions

**1. Is there a documented external SAI pattern for color field updates
that triggers a visual redraw in X_ITE?**

We have tried `emissiveColor`, `set_emissiveColor`, plain arrays, and
`X3D.SFColor`. All store the value without visual effect. Is there a
correct approach we are missing, or is this a known limitation?

**2. Does X_ITE require the parent Appearance or Shape node to be marked
dirty for Material property changes to render?**

If so, is there a documented way to trigger that from external SAI — for
example, a touch() method, a scene refresh call, or a property on the
Appearance node that forces a render pass?

**3. Is the `X3D.` prefix requirement for typed constructors documented
anywhere in X_ITE's documentation or source?**

We found it through testing and John's guidance, but we cannot find it 
in
X_ITE's GitHub or the Web3D documentation. A canonical reference would
help other developers and would help us understand what other type
differences exist between spec SAI and X_ITE external SAI.

---

## The Script Node Workaround — and Why It Does Not Scale

We are aware that internal X3D Script nodes can update Material color
properties and trigger correct visual updates. We have tested this 
approach
and it works.

However, for our use case — a narrative simulation system that generates
multiple X3D scenes programmatically with different geometry and 
character
configurations — the Script Node approach introduces a significant
maintenance burden:

- Every generated scene must include the same Script Node boilerplate
- The Script Node must be aware of all Material DEF names in that scene
- As scenes become more complex (H-Anim humanoids, richer environments)
   the Script Node grows proportionally
- Programmatic scene generation (we use Python/Flask with the x3d PyPI
   package) must maintain the Script Node in sync with scene content

We are not opposed to the Script Node pattern if it is the correct
architectural approach. But before committing to it across our entire
scene generation pipeline we want to confirm there is no cleaner path
through external SAI that we have missed.

---

## Summary

We have an open-source system that is working well in most respects.
The field simulation, HotHouse dynamics, constitutional arc, and avatar
positioning all work correctly via external SAI. The one remaining gap
is Material color updates driven by simulation state.

We are pausing development of the color update path until we have
clarification. We would rather wait for the right answer than build on
an undocumented workaround.

Any guidance — including confirmation that external SAI color updates
simply do not work in the current X_ITE version and are on the roadmap —
would be valuable.

Full technical documentation of our findings is in `X3D_KNOWN_ISSUES.md`
in the repository: https://github.com/artistinprocess/mccf

Thank you for your time and for maintaining X_ITE and the X3DJSONLD 
tools.

Len Bullard
with Claude (Anthropic)
https://github.com/artistinprocess/mccf