@needle-tools/engine 4.8.8-next.e80f4d7 → 4.8.9

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this package will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [4.8.9] - 2025-09-05
+- Add: OrbitControls `fitCamera` has now additional options for `fitDirection`, `cameraOffset`, `relativeCameraOffset`, `targetOffset` and `relativeTargetOffset` giving more fine-grained control over the final camera view where necessary ([Stackblitz](<https://stackblitz.com/edit/needle-engine-fit-camera-options?file=src%2Fscripts%2FPanelsAndText.ts,index.html,src%2Fmain.ts>)).
+- Add: ContactShadows properties to `fitShadows` and static `ContactShadows.auto()` for more fine-grained control over which objects to fit the shadow to or to apply slight offsets to the shadow plane
+- Add: NestedGltf component `loaded` event property
+- Fix: OrbitControls should not override the camera FOV
+- Fix: Updating the `scene.background` when setting both <needle-engine> `background-color` and `background-image` or switching between one or the other
+- Fix: When setting `<needle-engine environment-image="url">` the assigned image should be respected by the engine and loaded glTF files (even if they bring their own skybox and environment images)
+- Fix: Issue with `<needle-engine autoplay>` animation speed and when using the AnimationUtils.autoplay feature where animations would play faster than expected
+- Fix: Minor fixes in Vite plugins
+- Change: ReflectionProbes are not applied on Objects that use lightmapping
 
 ## [4.8.8] - 2025-08-29
 - Fix: iOS AR image tracking bug where having multiple `WebXRImageTracking` components in the scene cause unexpected behaviour or invalid USDZ files 

package/README.md

@@ -1,73 +1,75 @@
 # Needle Engine 
 
-<!-- <img src="https://engine.needle.tools/docs/imgs/banner.webp" /> -->
-
-**[Needle Engine](https://needle.tools)** is a fast web engine for complex and simple 3D applications alike.   
-It is flexible, extensible and has built-in support for collaboration and XR! It is built around the **glTF standard** for 3D assets and is using three.js under the hood - so all your existing knowledge applies. 
-
-→ 📑 [Documentation](https://docs.needle.tools)  
-→ 💎 [Samples](https://samples.needle.tools)  
-→ 🏓 [Changelog](https://github.com/needle-tools/needle-engine-support/releases)
-
-## Features
-- Components System: Add your custom components with easy
-- WebXR support & iOS Quicklook support for interactive AR
-- Networking is built-in
-- Advanced PBR Rendering
-- Animate Anything
-- Animation Statemachines & Timeline Animations
-- Lightmaps
-- Physics
-- Postprocessing
-- Texture & Mesh LOD Generation
-- Progressive Texture and Mesh Loading  
-   *Higher resolution assets are loaded on demand*
-- Dynamic Content Loading & Multi-Scene support
-- Integrations for Unity or Blender
-- Commercial & Educational Licenses
-- [↪ more features](https://docs.needle.tools/features)
+**Needle Engine** is a web engine for high quality 3D applications with performance in mind.
 
+Built on three.js and the glTF standard, Needle Engine delivers flexible, extensible web experiences with built-in collaboration and XR support.
 
-<br />
+## Quick Links
+🏓 [Changelog](https://github.com/needle-tools/needle-engine-support/releases) • 📑 [Documentation](https://docs.needle.tools) • 🧠 [Sample Scenes](https://samples.needle.tools) • 💎 [Showcase](https://engine.needle.tools/samples/?overlay=showcase)
+
+## Key Features
+
+**🎮 Development Experience**
+- Component system with easy custom component creation
+- Unity and Blender integrations for familiar workflows
+- Multi-scene support with dynamic content loading
+
+**🌐 Web & XR Ready**
+- WebXR support for immersive experiences
+- iOS QuickLook support for interactive AR
+- Built-in networking and collaboration
 
+**⚡ Performance Optimized**
+- Progressive texture and mesh loading
+- Automatic LOD generation for textures and meshes
+- Advanced PBR rendering with lightmap support
 
+**🎬 Animation & Effects**
+- Animation state machines and timeline animations
+- Physics simulation
+- Post-processing effects
+- Animate anything with ease
+
+[→ See all features](https://docs.needle.tools/features)
 
 ## Editor Integrations
 
 **Powerful integrations for Unity and Blender** allow artists and developers to collaborate and manage web applications inside battle-tested 3d editors. Needle Engine integrations allow you to use editor features for exporting models, author materials, animate and sequence animations, bake lightmaps and more.   
 - 🎲 [Download Unity Integration](https://engine.needle.tools/downloads/unity)
 - 🐵 [Download Blender Integration](https://engine.needle.tools/downloads/blender)
-- 📜 [Code only](https://engine.needle.tools/docs/three/)
-
+- 📜 [Use with Code](https://engine.needle.tools/docs/three/)
 
 ## Getting Started
 
-Follow the [Getting Started Guide](https://docs.needle.tools/getting-started) to download and install Needle Engine or [try one of our samples](https://engine.needle.tools/samples) ⚡
+**Quick Start with npm:**
+```bash
+npm install @needle-tools/engine
+```
 
+**Or use our Editor Integrations:** Follow the [Getting Started Guide](https://docs.needle.tools/getting-started) to download and install Needle Engine with Unity or Blender.
 
-## Examples
+**Explore Examples:** [Try our interactive samples](https://engine.needle.tools/samples) to see what's possible ⚡
 
-### [Custom loading overlay & wait for LODs](https://lods-loading-overlay-z23hmxbz29h8vr.needle.run/) | [Code on Stackblitz](https://stackblitz.com/edit/needle-engine-wait-for-lods?file=README.md)
+---
 
-### [Animate Anything](https://khr-animation-pointer-zubcksz2dgy3k.needle.run/) | [Code on Stackblitz](<https://stackblitz.com/edit/needle-engine-animate-anything?file=src%2Fmain.ts>) |  [three.js Example](<https://threejs.org/examples/?q=gltf#webgl_loader_gltf_animation_pointer>)
-  [![](https://cdn.needle.tools/static/images/changelog/khr_animation_pointer-thumbnail.jpg?1)](https://responsive-layout-click-example-z23hmxbzuyk6y.needle.run/)
+*Available under commercial and educational licenses*
 
-### [Postprocessing Effects with custom Magnifier effect](https://antialiasing-and-postprocessing-zubcksz1o8daw.needle.run/) | [Code on Stackblitz](https://stackblitz.com/edit/needle-engine-postprocessing?file=README.md)  
-[![](https://cdn.needle.tools/static/images/changelog/magnifier-postprocessing-example-thumbnail.jpg)](https://antialiasing-and-postprocessing-zubcksz1o8daw.needle.run/)
-
-### [AR Restaurant Example](https://ar-restaurant-example-zubcks1t14le.needle.run/) | [Code on Github](https://github.com/needle-engine/ar-restaurant-example)
-
-### [Camera Focus DIV Example 1](https://responsive-layout-z23hmxb22no6t.needle.run/) | [Code on Stackblitz](<https://stackblitz.com/edit/needle-engine-camera-focus-rect?file=src%2Fsidebar.ts,index.html,src%2Fmain.ts>)  
-  [![](https://cdn.needle.tools/static/images/changelog/4.8.8-focus-thumbnail.jpg)](https://responsive-layout-z23hmxb22no6t.needle.run/)   
-
-### [Camera Focus DIV Example 2](https://responsive-layout-click-example-z23hmxbzuyk6y.needle.run/) | [Code on Stackblitz](<https://stackblitz.com/edit/needle-engine-camera-focus-rect-click-to-move?file=index.html,src%2Fmain.ts>)   
-  [![](https://cdn.needle.tools/static/images/changelog/4.8.8-focus-2-thumbnail.jpg?)](https://responsive-layout-click-example-z23hmxbzuyk6y.needle.run/)
-
-### [Motors & More Shop Example with React](https://reactshoppingcart-z23hmxbzcfkmf.needle.run/) | [Code on Stackblitz](https://stackblitz.com/edit/needle-react-shopping-cart-2)
+## Examples
 
+| Preview | Example | Description | Links |
+|---------|---------|-------------|-------|
+| [![](https://cdn.needle.tools/static/images/changelog/khr_animation_pointer-thumbnail.jpg?1)](https://khr-animation-pointer-zubcksz2dgy3k.needle.run/) | [Animate Anything](https://khr-animation-pointer-zubcksz2dgy3k.needle.run/) | Interactive animation system | [Code on Stackblitz](https://stackblitz.com/edit/needle-engine-animate-anything?file=src%2Fmain.ts) • [three.js Example](https://threejs.org/examples/?q=gltf#webgl_loader_gltf_animation_pointer) |
+| [![](https://cdn.needle.tools/static/images/changelog/magnifier-postprocessing-example-thumbnail.jpg)](https://antialiasing-and-postprocessing-zubcksz1o8daw.needle.run/) | [Postprocessing Effects](https://antialiasing-and-postprocessing-zubcksz1o8daw.needle.run/) | Custom magnifier effect with post-processing | [Code on Stackblitz](https://stackblitz.com/edit/needle-engine-postprocessing) |
+| [![](https://cdn.needle.tools/static/images/changelog/4.8.8-focus-thumbnail.jpg)](https://responsive-layout-z23hmxb22no6t.needle.run/) | [Camera Focus DIV 1](https://responsive-layout-z23hmxb22no6t.needle.run/) | Responsive layout with camera focus | [Code on Stackblitz](https://stackblitz.com/edit/needle-engine-camera-focus-rect?file=src%2Fsidebar.ts,index.html,src%2Fmain.ts) |
+| [![](https://cdn.needle.tools/static/images/changelog/4.8.8-focus-2-thumbnail.jpg)](https://responsive-layout-click-example-z23hmxbzuyk6y.needle.run/) | [Camera Focus DIV 2](https://responsive-layout-click-example-z23hmxbzuyk6y.needle.run/) | Click-to-move camera focus example | [Code on Stackblitz](https://stackblitz.com/edit/needle-engine-camera-focus-rect-click-to-move?file=index.html,src%2Fmain.ts) |
+| [![](https://cdn.needle.tools/static/images/changelog/fasthdr-thumbnail.jpg?1)](https://fasthdr-needle-engine-zubcks1li2iy.needle.run/) | [FastHDR Loading](https://fasthdr-needle-engine-zubcks1li2iy.needle.run/) | 10x faster than EXR, non-blocking, 95% less GPU memory | [Code on Stackblitz](https://stackblitz.com/edit/needle-fast-hdri-needle-engine) • [Learn more](https://cloud.needle.tools/hdris) |
+| | [AR Restaurant](https://ar-restaurant-example-zubcks1t14le.needle.run/) | Interactive AR restaurant experience | [Code on Github](https://github.com/needle-engine/ar-restaurant-example) |
+| | [Custom Loading Overlay](https://lods-loading-overlay-z23hmxbz29h8vr.needle.run/) | Wait for LODs with custom loading states | [Code on Stackblitz](https://stackblitz.com/edit/needle-engine-wait-for-lods) |
+| | [React Shopping Cart](https://reactshoppingcart-z23hmxbzcfkmf.needle.run/) | E-commerce integration with React | [Code on Stackblitz](https://stackblitz.com/edit/needle-react-shopping-cart-2) |
 
+<br/>
 
-👋 Find more examples on [samples.needle.tools](https://samples.needle.tools/), [docs.needle.tools](https://docs.needle.tools) and in the [Needle Engine Stackblitz Collection](https://stackblitz.com/@marwie/collections/needle-engine)
+👋 More examples on [samples.needle.tools](https://samples.needle.tools/), [docs.needle.tools](https://docs.needle.tools) and in the [Needle Engine Stackblitz Collection](https://stackblitz.com/@marwie/collections/needle-engine)
 
 <br />
 
@@ -77,5 +79,4 @@ Follow the [Getting Started Guide](https://docs.needle.tools/getting-started) to
 [Twitter](https://twitter.com/NeedleTools) • 
 [Discord](https://discord.needle.tools) • 
 [Forum](https://forum.needle.tools) • 
-[Youtube](https://www.youtube.com/@needle-tools)
-
+[Youtube](https://www.youtube.com/@needle-tools)

package/dist/{needle-engine.bundle-DfWoUjQM.js → needle-engine.bundle-BdgNRB4B.js}

@@ -1763,11 +1763,11 @@ fo('if(!globalThis["NEEDLE_ENGINE_VERSION"]) globalThis["NEEDLE_ENGINE_VERSION"]
 fo('if(!globalThis["NEEDLE_ENGINE_GENERATOR"]) globalThis["NEEDLE_ENGINE_GENERATOR"] = "unknown";');
 fo('if(!globalThis["NEEDLE_PROJECT_BUILD_TIME"]) globalThis["NEEDLE_PROJECT_BUILD_TIME"] = "unknown";');
 fo('if(!globalThis["NEEDLE_PUBLIC_KEY"]) globalThis["NEEDLE_PUBLIC_KEY"] = "unknown";');
-fo('globalThis["__NEEDLE_ENGINE_VERSION__"] = "4.8.8";');
+fo('globalThis["__NEEDLE_ENGINE_VERSION__"] = "4.8.9";');
 fo('globalThis["__NEEDLE_ENGINE_GENERATOR__"] = "undefined";');
-fo('globalThis["__NEEDLE_PROJECT_BUILD_TIME__"] = "Fri Sep 05 2025 10:35:01 GMT+0000 (Coordinated Universal Time)";');
+fo('globalThis["__NEEDLE_PROJECT_BUILD_TIME__"] = "Fri Sep 05 2025 14:43:18 GMT+0000 (Coordinated Universal Time)";');
 fo('globalThis["__NEEDLE_PUBLIC_KEY__"] = "' + NEEDLE_PUBLIC_KEY + '";');
-const En = "4.8.8", Cm = "undefined", Gb = "Fri Sep 05 2025 10:35:01 GMT+0000 (Coordinated Universal Time)";
+const En = "4.8.9", Cm = "undefined", Gb = "Fri Sep 05 2025 14:43:18 GMT+0000 (Coordinated Universal Time)";
 Hb && console.log(`Engine version: ${En} (generator: ${Cm})
 Project built at ${Gb}`);
 const bl = NEEDLE_PUBLIC_KEY, oo = "needle_isActiveInHierarchy", Br = "builtin_components", Mh = "needle_editor_guid";
@@ -16337,7 +16337,7 @@ class ye extends T {
       return;
     }
     let i;
-    if (Array.isArray(e) ? i = e : e && "type" in e ? i = e.children : e && typeof e == "object" && !(e instanceof M) && !Array.isArray(e) && (t = e, i = t.objects), i && !Array.isArray(i) && (i = i.children), (!Array.isArray(i) || i && i.length <= 0) && (i = this.context.scene.children), !Array.isArray(i) || i.length <= 0) {
+    if (Array.isArray(e) || e && "type" in e ? i = e : e && typeof e == "object" && !(e instanceof M) && !Array.isArray(e) && (t = e, i = t.objects), i && !Array.isArray(i) && (i = [i]), (!Array.isArray(i) || i && i.length <= 0) && (i = this.context.scene.children), !Array.isArray(i) || i.length <= 0) {
       console.warn("No objects to fit camera to...");
       return;
     }