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

[John Carlson]

Use the Script.url field to specify external JS scripts using “internal”
namespaces—no extra “X3D.” in front of classes and field classes.

I don’t know if MF fields are JavaScript arrays or X3D.MF…

John

On Mon, Apr 20, 2026 at 8:19 PM <cbullard at hiwaay.net> wrote:

> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20260420/2d4d41c5/attachment-0001.html>