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

Mon Apr 20 20:04:17 PDT 2026

For X_ITE:

So HTML <script> (outside the scene) means use prefix “X3D.” Even if src=
is used to pull in JavaScript code.

And X3D <Script> (inside the scene) means don’t use a prefix.  Even if url=
is used to pull in JavaScript code.

So you can share with external JavaScript files, but don’t mix and match
your in scene and out of scene references and code.

Sorry, my brain wasn’t working well enough before.

You always use src= in X3DOM, and the prefix is often “x3dom.”  That’s
X3DOM’s namespace.

For out of scene X_ITE, you might be able to create aliases,  like:

const SFFloat = X3D.SFFloat;

Good luck!

John

On Mon, Apr 20, 2026 at 9:42 PM John Carlson <yottzumm at gmail.com> wrote:

> 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/d450f095/attachment.html>