Allow async loading of aframe library and interoperation with ES module libraries #5419

chrisirhc · 2023-12-21T03:44:37Z

Description:
This allows interop with ES module libraries such as webxr.
ES modules are a part of the Web Component spec but it's a bit surprising that aframe doesn't play well with other Web Components that rely on ES modules.

It allows aframe to be loaded as a module or deferred on page load.
Currently, aframe needs to be loaded synchronously. Adding async or defer or type="module" can cause aframe library to fail in many different ways such as:

a-scene is registered and connectedCallback hook does not find the camera component as it hasn't been registered
a-entity's connectedCallback hook unable to find that a-scene is initialized

These proposed changes allow the following code snippet to run:
Note that new LookingGlassWebXRPolyfill() needs to run before importing aframe in order to polyfill/override webxr for looking glass capabilities.

    <script type="module">
      import { LookingGlassWebXRPolyfill } from "@lookingglass/webxr"
      new LookingGlassWebXRPolyfill()
      window.AFRAME_ASYNC = true;
      await import("aframe")
      // add any components
      await import("https://quadjr.github.io/aframe-gaussian-splatting/index.js")
      window.AFRAME.ready();
    </script>

Example of this working is at https://chrisirhc.github.io/looking-glass-viewer-experiments/aframe.html .

Changes proposed:

Delay running doConnectedCallback until ready is called if window.AFRAME_ASYNC is set to a truthy value
Reorder the initialization in index.js so that default components and system are registered before connectedCallback is called.

This is a strawman implementation. I'm not sure how to name these API surfaces and open to suggestions.

Alternatives considered

Change the order or delay order in which the customElements are registered.
- Not that this doesn't work well because a-scene element creates a-entity elements during its connectedCallback lifecycle hook, so if a-entity isn't already registered, then

dmarcos · 2023-12-21T15:04:23Z

src/core/a-entity.js

@@ -11,6 +11,17 @@ var MULTIPLE_COMPONENT_DELIMITER = '__';
 var OBJECT3D_COMPONENTS = ['position', 'rotation', 'scale', 'visible'];
 var ONCE = {once: true};

+var _resolveReadyPromise;


Can name just resolveReadyPromise. We don't use ampersand

dmarcos · 2023-12-21T15:19:15Z

Thanks so much!

@vincentfretin @diarmidmackenzie what do you think? Sorry for the ping. Have the feeling you know more about this than me :)

At first glance it feels weird tying the logic to the Entity load when async is supposed to be at library level. But maybe. Not sure yet.

src/core/scene/a-scene.js

vincentfretin · 2023-12-21T16:10:09Z

The changes looks ok. I don't really have better.
Do we need a similar fix in src/core/scene/a-scene.js to delay executing of this.initSystems() if you imported a module that registered a system?

I guess this PR fixes this old issue #4038

dmarcos · 2023-12-21T16:29:32Z

Just curious how a complete example would look like?

await import("aframe") I imagine 'aframe' has to defined somehow previously.

I'm still getting familiar with ES6 modules.

Would be nice to see one full basic example: https://glitch.com/~aframe

vincentfretin · 2023-12-21T17:10:00Z

You need to define the importmap. In his linked example, this is defined:

    <script type="importmap">
      {
          "imports": {
              "@lookingglass/webxr": "./lib/webxr.module.js",
              "aframe": "./lib/aframe-master.js"
          }
      }
    </script>

You can replace the path by a jsdelivr url.

dmarcos · 2023-12-22T00:13:53Z

Wouldn't be better to tie the promise to A-Frame loading as a whole vs when the first entity connects? For example here: https://github.com/aframevr/aframe/blob/master/src/index.js#L95

chrisirhc · 2023-12-22T08:05:14Z

Just curious how a complete example would look like?

await import("aframe") I imagine 'aframe' has to defined somehow previously.

You could use the importmaps or, more typically, It'd look like the full JS url:

await import("https://aframe.io/releases/1.5.0/aframe.min.js")

The import() and await statements are to ensure the side effects of the modules are run in the order in the code. See
reference .

Wouldn't be better to tie the promise to A-Frame loading as a whole vs when the first entity connects? For example here: https://github.com/aframevr/aframe/blob/master/src/index.js#L95

Ah, the change I'm proposing is to run the entity connectedCallback after A-Frame loading has completed.
The setTimeout achieves this since it waits until all the synchronous loading/execution has completed.

That said, the problem it works around is that the connectedCallback expect that the A-Frame loaded has completed, but these connectedCallback are being run during registerElement because the DOM is already available during the async loading.

Typically, the steps look like:

Load script synchronously via <script src=https://aframe.io/releases/1.5.0/aframe.min.js></script> in the head. This includes running customElement.register but just registers the element and doesn't call the callbacks.
Parse the DOM including the body that contains <a-scene> and other elements. During the parse, constructor and callbacks (connectedCallback) are called for each element as they're encountered.

However, in the async/module flow, the steps look like:

Parse the DOM, including the body that contains <a-scene> and other elements. Does not call custom element constuctors because the module hasn't loaded yet.
Then while loading + executing the aframe script:
As it encounters the line customElement.register('a-scene', …) code, it runs the constructors and connectedCallback.
Continues to execute the rest of the aframe code.

The problem is that in Step 3, not all of the aframe code has executed. So things like the camera weren't registered. This is only a problem because the connectedCallback was called during parsing/execution of the aframe script.
It's not a problem if all of the aframe script has already executed.

Hope this provides an explanation of what's going on.
This is what I gather was happening as I was working through this issue.

mrxz · 2023-12-22T08:11:20Z

There is already logic in place to defer the initialization till the document.readyState is complete. I feel it would be cleaner to generalize this logic instead of adding additional flows. Instead of listening for the readystatechange it could listen to a dedicated event, which by default would still be based on the ready state.

As for the magic AFRAME_ASYNC variable, I don't really like it as it's easily something someone can forget or get wrong. Perhaps it's possible for A-Frame to detect it's being loaded asynchronously and automatically switch to expecting a ready signal from the user?
Ideally there would then be a warning logged to the console if this signal isn't given, but not sure if there is a logical moment to detect this apart from a timeout. Likewise an error if the ready signal is given more than once, or if components/systems are registered after the signal has been given.

Example of this working is at https://chrisirhc.github.io/looking-glass-viewer-experiments/aframe.html .

This example doesn't work in Firefox for me, but does on Chrome. Didn't dive into the cause, but it seems there is some difference in execution order between the two.

As an aside, the way I generally workaround the issue is by placing the scene in a template and adding it to the DOM after loading and registering all dependencies:

<html>
    <head>
        <script type="importmap">
            (...)
        </script>
        <script type="module">
            await import("aframe");

            // Load dependencies

            const sceneTemplate = document.getElementById('scene');
            document.body.appendChild(sceneTemplate.content)
        </script>
    </head>
    <body>
        <template id="scene">
            <a-scene>
                <a-box id="box" color="red" position="0 1.6 -2"></a-box>
            </a-scene>
        </template>
    </body>
</html>

chrisirhc · 2023-12-22T08:11:59Z

src/core/a-entity.js

+var _resolveReadyPromise;
+var isReady = false;
+var isReadyPromise = new Promise(function (resolve) {
+  _resolveReadyPromise = resolve;
+});
+
+function ready () {
+  isReady = true;
+  _resolveReadyPromise();
+}


Looking at this again, it might make more sense for this "ready" logic to live in its own file/module that just governs whether the entire aframe library is ready. I can tidy this up.

This initial PR was only to gather and understand if there's interest/appetite for such a change.

sounds good. thanks. In an ideal world we would have a single build that can be loaded via modules (export, import) or script tag. As far as I know that's not possible, right?

dmarcos · 2023-12-22T15:19:33Z

As an aside, the way I generally workaround the issue is by placing the scene in a template and adding it to the DOM after loading and registering all dependencies:

Nice workaround. Hopefully we can find a way for A-Frame to work seamlessly with both modules and script tags. I would like to also avoid two separate builds (aframe.js, aframe.module.js) but not sure if possible. Biggest downside of ES6 modules is that how it seems to split JS space in two: pre and post modules. Also I think there's still valuable simplicity on loading JS with just a <script> tag and no additional incantations.

arpu · 2023-12-22T18:52:05Z

not sure where the problem is at the moment what still works is
https://glitch.com/edit/#!/ink-zealous-pudding

arpu · 2023-12-22T19:10:23Z

i think a good example is model-viewer https://modelviewer.dev/

dmarcos · 2023-12-27T17:04:12Z

Let me know if you need help or any questions to move this along. Thanks!

vincentfretin · 2023-12-27T18:32:13Z

@arpu In your glitch example you don't async load any new component, so of course you don't have any issue.
I didn't understand the reference to modelviewer, this is a module js yes, just a single web component. For aframe the issue is component on a web component, the component is not yet loaded when the web component is initialized.

@chrisirhc on my comment #5419 (comment) need to test to async load a system.

arpu · 2023-12-28T13:40:00Z

Thanks @vincentfretin you are right not trying to load second componet, and now i see the problem
for the modelviewer refrence was more for @dmarcos to see how easy it is today with es module and script tag

chrisirhc · 2023-12-28T14:46:26Z

@chrisirhc on my comment #5419 (comment) need to test to async load a system.

Hi, do you mind sharing an example on how I can do this?

vincentfretin · 2023-12-29T14:47:24Z

You can try loading the uvscroll.js as a module, that includes a uv-scroll system and uv-scroll component, see c-frame/sponsorship#15

dmarcos · 2024-01-13T00:01:37Z

There are some pending changes here

vincentfretin · 2024-01-13T16:48:29Z

I created a glitch with the same example as @chrisirhc and the uv-scroll system/component, it's working properly as far as I can tell.
https://glitch.com/edit/#!/vfretin-async-aframe

dmarcos · 2024-02-01T06:37:43Z

@chrisirhc There are few pending changes from the review (e.g underscore on name variables). Do you want to finish it up? Thanks so much!

chrisirhc · 2024-03-26T23:45:00Z

Hi there, apologies for the radio silence.
I likely won't be able to get to this any time soon.

I was stuck on a blurness issue ( mkkellogg/GaussianSplats3D#65 (comment) ) after finding out that aframe using a pretty old/forked version of ThreeJS so I've had to look elsewhere despite hacking this fix together.

I might not get back to this in the near future. Feel free to close this out.

dmarcos · 2024-03-27T00:37:39Z

@chrisirhc FYI A-Frame master is on latest THREE r162. Can use builds linked in commits https://github.com/aframevr/aframe/commits/master/

vincentfretin · 2024-03-27T10:02:38Z

Also you can close this PR now that #5481 is merged.

chrisirhc · 2024-03-27T12:21:52Z

Got it! Thanks @mrxz for getting the change to the finish line!
I'll be able to test things out with the main branch now, with the above suggestions. 👍

hack to fix async loading

67c1c39

chrisirhc mentioned this pull request Dec 21, 2023

Make A-Frame ES Modules Compliant to Enable Tree Shaking #4242

Open

dmarcos reviewed Dec 21, 2023

View reviewed changes

src/core/scene/a-scene.js Outdated Show resolved Hide resolved

remove unnecessary change

fcdc59f

chrisirhc commented Dec 22, 2023

View reviewed changes

vincentfretin mentioned this pull request Jan 12, 2024

svelte aframe TypeError: Cannot read properties of undefined (reading 'constructor') #5428

Closed

mrxz mentioned this pull request Feb 17, 2024

Get rid of build step #5363

Open

mrxz mentioned this pull request Feb 28, 2024

Defer initialization until end of aframe script or manual ready signal #5481

Merged

chrisirhc closed this Mar 27, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Allow async loading of aframe library and interoperation with ES module libraries #5419

Allow async loading of aframe library and interoperation with ES module libraries #5419

chrisirhc commented Dec 21, 2023 •

edited

Loading

dmarcos Dec 21, 2023

dmarcos commented Dec 21, 2023 •

edited

Loading

vincentfretin commented Dec 21, 2023

dmarcos commented Dec 21, 2023 •

edited

Loading

vincentfretin commented Dec 21, 2023

dmarcos commented Dec 22, 2023

chrisirhc commented Dec 22, 2023 •

edited

Loading

mrxz commented Dec 22, 2023

chrisirhc Dec 22, 2023 •

edited

Loading

dmarcos Dec 22, 2023

dmarcos commented Dec 22, 2023 •

edited

Loading

arpu commented Dec 22, 2023

arpu commented Dec 22, 2023

dmarcos commented Dec 27, 2023

vincentfretin commented Dec 27, 2023

arpu commented Dec 28, 2023

chrisirhc commented Dec 28, 2023

vincentfretin commented Dec 29, 2023

dmarcos commented Jan 13, 2024

vincentfretin commented Jan 13, 2024

dmarcos commented Feb 1, 2024

chrisirhc commented Mar 26, 2024

dmarcos commented Mar 27, 2024

vincentfretin commented Mar 27, 2024

chrisirhc commented Mar 27, 2024 •

edited

Loading

Allow async loading of aframe library and interoperation with ES module libraries #5419

Allow async loading of aframe library and interoperation with ES module libraries #5419

Conversation

chrisirhc commented Dec 21, 2023 • edited Loading

dmarcos Dec 21, 2023

Choose a reason for hiding this comment

dmarcos commented Dec 21, 2023 • edited Loading

vincentfretin commented Dec 21, 2023

dmarcos commented Dec 21, 2023 • edited Loading

vincentfretin commented Dec 21, 2023

dmarcos commented Dec 22, 2023

chrisirhc commented Dec 22, 2023 • edited Loading

mrxz commented Dec 22, 2023

chrisirhc Dec 22, 2023 • edited Loading

Choose a reason for hiding this comment

dmarcos Dec 22, 2023

Choose a reason for hiding this comment

dmarcos commented Dec 22, 2023 • edited Loading

arpu commented Dec 22, 2023

arpu commented Dec 22, 2023

dmarcos commented Dec 27, 2023

vincentfretin commented Dec 27, 2023

arpu commented Dec 28, 2023

chrisirhc commented Dec 28, 2023

vincentfretin commented Dec 29, 2023

dmarcos commented Jan 13, 2024

vincentfretin commented Jan 13, 2024

dmarcos commented Feb 1, 2024

chrisirhc commented Mar 26, 2024

dmarcos commented Mar 27, 2024

vincentfretin commented Mar 27, 2024

chrisirhc commented Mar 27, 2024 • edited Loading

chrisirhc commented Dec 21, 2023 •

edited

Loading

dmarcos commented Dec 21, 2023 •

edited

Loading

dmarcos commented Dec 21, 2023 •

edited

Loading

chrisirhc commented Dec 22, 2023 •

edited

Loading

chrisirhc Dec 22, 2023 •

edited

Loading

dmarcos commented Dec 22, 2023 •

edited

Loading

chrisirhc commented Mar 27, 2024 •

edited

Loading