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

Tue Apr 21 02:20:02 PDT 2026

Color fields work exactly like all other fields and have been extensively tested. It is always important to use the field objects with SF* or MF* when assigning values. For example: material.emissiveColor = new SFColor(r, g, b). 

In ECMAScript within the Script node, you don’t need to set the X3D namespace for a class, but you do need to do so outside of it—that is, in external JavaScript files. So, in the example above, it becomes material.emissiveColor = new X3D.SFColor(r,g,b). As Len already mentioned, this is to avoid polluting the global namespace.

I’ve created a simple example that show the use of the SFColor values, click the Box:

Script node solution:
https://create3000.github.io/x_ite/playground/?url=https://create3000.github.io/Library/Tests/Components/Core/Colors.x3d

External Script HTML Page
https://create3000.github.io/Library/Tests/Components/Core/Colors.html

## Answers to Questions

1. If there is an assignment to a field, this will automatically trigger an update of the node and the whole scene will be redrawn.

You can use material.emissiveColor or because emissiveColor is an inputOutput field material.set_emissive color, I would prefer the shorter version.

2. This is done automatically, everything that needs to be updated, will automatically be updated..

3. You include the x_ite.js in you HTML and there will be only one global variable X3D exposed by X_ITE to the global namespace. All classes you need are then accessible through this X3D object. So you will do: new X3D.SFColor ().

https://create3000.github.io/x_ite/reference/ecmascript-object-and-function-definitions/#x3d-object

## 

My assumption is the scripting elements were maybe used incorrectly somehow. Is material of class Material, and is really a SFColor used? Were there typos? Is the material assigned to a visible object?

You can do material.toVRMLString() to debug a node, you can do color.toString() to debug a value or field. You can even do scene.toVRMLString() to debug a whole scene.

But without a test file that does not work I cannot say more.

Best regards,
Holger

—
Holger Seelig
holger.seelig at yahoo.de

> Am 21.04.2026 um 03:19 schrieb Len Bullard via x3d-public <x3d-public at web3d.org>:
> 
> 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
> 
> _______________________________________________
> x3d-public mailing list
> x3d-public at web3d.org
> http://web3d.org/mailman/listinfo/x3d-public_web3d.org

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20260421/8cfa69b3/attachment-0001.html>