Async SceneGraph
The move to Async SceneGraph changes how the core of Threekit operates, including improvements for custom code simplicity, speed, and accessing nested configurations.
Implementation will need to update code for both compatibility and to take advantage of new features. Details are included below:
Required Changes
Snapshot
For the client API, the snapshot
function has been deprecated, since it is now an asynchronous operation.
Convert any usage of player.snapshot()
to await player.snapshotAsync()
Initial Configuration Propagation
Currently, during the initial asset evaluation, the top level attributes may not be propagated down. For example, if we have an Item
with a Material
attribute that has been set, and the Model
that the item points to also has a Material
attribute, but with a default value. During initial load, the model will appear with the attribute set to its default value. Only when the attribute is switched on the Item will it propagate down to the model.
With the new changes, however, the attribute hierarchy is properly reflected on load. Since the top level attribute is unset, that will be propagated down to the underlying model, and the initial load will show up with a blank Material
. To resolve this, proper defaults need to be set.
- Undefined behavior is being closed down.
- There are no implied defaults in assets anymore. Everything is set explicitly from Products if they are matching attributes.
Ensure that defaults are properly set upon initialization
Async Configuration Scripts
Currently, if you attempt to attach a configurator script to an action that is itself async, the evaluation will attempt to resolve the script before the asset is fully loaded. However, this is done in an undetermined manner, and as a result there have been rendering issues.
With the new changes, any async script must return a promise. This promise will be used during evaluation, so it is known with certainty when the script has fully executed. There is a timeout during script execution (currently 20 seconds) so evaluation will not halt completely if the script times out.
- This will break async custom scripts if they do not return promises.
- Please return promises from async custom scripts.
If a configurator script runs in an async fashion, return a promise that resolves when the script has been fully evaluated. If the script is not itself asynchronous, nothing else needs to be done
Simplify Scripting
The changes will simplify what is required to script a complex asset.
setConfiguration is async
Currently, if a configuration is changed, there is no way to know when the change has been applied. With the new changes, you can simply await
for the results of the change:
Resolving an asset
Currently, if an asset reference is set, it is difficult to know when the assets have been loaded and evaluated, in order to do further scripting. This is now as simple as waiting for the evaluation to resolve.