v2.0.0

We have been carefully following semantic versioning rules to avoid breaking changes for our diverse user base, but this has caused parts of our API to become less beginner-friendly as our newer best-practices have not become defaults. The time has come to reset with a v2.0 release!

The API simplifications have also allowed us to clean up our code base, easing maintenance and reducing the likelihood of future bugs.

To be clear, we still want to make updating to v2.0 easy for our users, so we're changing features that are little-used or will improve the experience on most sites. The changes to defaults can be overridden by specifying attribute values. Regeneration of poster images is strongly recommended. See discussion in #3460.

✋Breaking Changes

Updated Defaults

• Minimum radius is doubled to match the enable-pan default, with default field-of-view narrowed to 30 degrees (12 degree default minimum). This gives the default framing a "longer lens" with reduced perspective warp: #3668
• Default enable-pan to true, replacing the enable-pan attribute with disable-pan. Also added disable-tap attribute: #3713
• Switch touch-action default from pan-y to none: #3712
• Switch default environment-image to neutral, renaming the current default as legacy: #3676
• Enable USDZ autogeneration by default, by switching the ar-modes default to webxr scene-viewer quick-look: #3802

API Simplification

• Remove the 'bounds' attribute, making the behavior equivalent to bounds="tight": #3683
• Remove the deprecated scene-graph-ready event: #3700
• Remove the progress-mask; equivalent to setting its part to display: none;. This will keep the poster from appearing lightened during loading: #3692
• Remove the "interaction" option from the reveal attribute. Use "manual" and dismissPoster() instead to achieve this behavior: #3688
• Remove the interaction-policy attribute, allowing only the default "always-allow" behavior: #3686
• Remove the "when-focused" option from the interaction-prompt attribute: #3687
• Remove the interaction-prompt-style attribute, allowing only the default "wiggle" behavior: #3685
• Remove --poster-color, making the poster always have a transparent background: #3701
• Remove the seamless-poster attribute, making the behavior as though this option is always enabled. Note this in combination with the previous bullet means there is no longer a transition fade between poster and model, so seamless posters as generated by toBlob({idealAspect: true}) or our editor are strongly recommended: #3704
• Remove the Image.setURI method from our materials API. Use the createTexture method instead: #3710
• Update exportScene options to match three.js r143. Specifically, remove embedImages (always true now) and forcePowerOfTwoTextures. Add forceIndices: #3711
• Remove preload event, as there is no longer any distinction from the load event: #3799

TypeScript Updates

• Switch our package.json module to point to lib instead of dist. For JS users, main will still point to our bundle in dist, but this change will send TS users to our lib so they can build and tree-shake it themselves, which is best practice. Also, our lib already contains all our *.d.ts files: #3718
• Add types pointers to package.json as well as a fallback model-viewer.d.ts bundled types file, thanks @subhankar-trisetra! #3774, #3791

Features

🆕 Added External Renderer API to drive e.g. cloud-based or path-tracing renderers: #3482
🆕 Added Material API documentation: #3493
🆕 Added keyboard controls for pan, thanks @clochardM33! #3702
🆕 Added inputSensitivity property: #3719
🆕 Added getBoundingBoxCenter: #3734

Bugfixes

• Move the Exit AR button to the safe zone, thanks @yuta-hayashi! #3464
• Fix fractional pixel sizes causing some blurring, thanks @bcairns! #3555
• Fix positionAndNormalFromPoint() hitting the floor plane: #3599
• Fix skybox shown in AR when switching src: #3606
• Fix docs page build failure, thanks @demarijm! #3696
• Ensure the 'load' event fires after the pixels are properly rendered: #3702
• Make JS camera changes cancel interaction prompts and add "automatic" to camera-change event: #3717
• Improve WebXR wall-placement UX: #3736
• Fix error event detail: #3742
• Fix reveal changes causing rendering breakage: #3745
• Ensure dynamic render scaling always returns to full-res when the model stops moving: #3752
• Ensure exportScene is including scale/orientation changes: #3772
• Fix iOS AR feature detection for WebViews and iOS16, thanks @milesgreen! #3784
• Fix bounds calculation for quantized models: #3768

Other notable changes

• Updated to Three.js r144
• Dynamic render scaling is now less aggressive, targeting 15-20 fps before down-sampling
• Various loading performance improvements