@needle-tools/engine/CHANGELOG.md

Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in

# Changelog
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.1.0-alpha.1] - 2024-01-09
- Add: Support for loading KTX2 textures as `environment-image` and `background-image` (e.g. `<needle-engine background-image="my-skybox.ktx2">`)
- Fix: Issue where raycasting was not using acceleration structures and instead falling back to slow raycasting. This release greatly improves raycasting performance

## [4.1.0-alpha] - 2024-01-08
- Add: Screenshot support for AR:   
  To use you need to request the `camera-access` XR feature when starting a new XR session.   
  For that you can *either* simply add the *WebARCameraBackground* component to your scene   
  or add the feature in the `NeedleXRSession.onSessionRequestStart` event hook. 

## [4.0.4-alpha] - 2024-01-02
- Fix: Detecting OBJ files starting with `mtllib` or content-type header `model/obj`
- Fix: Issue where `screenshot()` method with custom camera and postprocessing didn't work
- Update gltf-progressive package to load higher texture LODs by default

## [4.0.3-alpha] - 2024-12-20
- Add: OBJLoader now automatically loads mtl files
- Add: OBJLoader materials are now fixed like FBX materials 

## [4.0.2-alpha] - 2024-12-12
- Add: Support for custom scripts on WebXR custom hands
- Fix: OrbitControls should not listen to window.body for key events

## [4.0.1-alpha] - 2024-12-11
- Fix: Objects spawned with `syncedInstantiate` should automatically be removed when disconnecting from the networking room
- Fix: Issue where objects rendered with instancing enabled were not visible in screenshots

## [4.0.0-alpha] - 2024-12-09
- Add: Builds can now be compressed on Needle Cloud instead of locally. Set the `NEEDLE_CLOUD_TOKEN` environment variable to your Cloud access token to enable this. This allows running compression in CI build pipelines, for example in a Github Action. Needle Cloud access tokens can be obtained on https://cloud.needle.tools/team.
- Add: `DropListener` now optionally supports networking when `allowNetworking` is on. Dropped files will be network-synced if the file size does not exceed a certain size (50 MB for projects on paid plans; 5 MB for projects free plans).
- Fix: Previously, when changing a `@syncField` property, only the last changed property was synchronized to the server. This is now fixed. Note that this is a **breaking change**: previously networked server state with the `@syncField` attribute in Needle Engine 3.x projects will not be loaded in Needle Engine 4.0.
- Change: `EventList` now takes a generic type code hints when using `myEventList.addEventListener(...)` e.g. `new EventList<string>()` 
- Change: The default networking server is now located at `networking.needle.tools`
- Change: The `DropListener` API has changed
- Change: OrbitControls `useKeys` is now false by default since the underlying three.js OrbitControls incorrectly capture ALL keyboard events on the page.
- Change: Loading speed improvements and improved Lighthouse score
- Change: md5 hashing results are now S3-compatible

## [3.51.1] - 2024-12-09
- Fix: DragControls snap to surface setting should use world normal
- Fix: Needle Menu missing focus-visible for overflow menu button
- Fix: Needle Menu :focus-visible on menu elements barely being visible
- Fix: edge case where we still showed the QR code when only the WebXR component is on and we're on mobile
- Fix: detect URL content format using "Content-Type" header as well
- Fix: double quotes in USDZ displayName need to be escaped
- Fix: don't fetch when we already know fetch won't work due to cross-origin isolation
- Change: for QuickLook, use "View in AR" instead of "Download for AR" even for cases where we're not sure if the device actually supports QuickLook – rel="ar" is not reliable
- Change: disable Needle logo being clickable during loading because users click it accidentally and then they're lost
- Docs: add @group Component to components since TypeDoc doesn't do inheritance as expected

## [3.51.0] - 2024-11-28
- Add: API docs for networking methods
- Add: USDZ export automatically creates "hold" animations now to prevent animation snapping
- Add: USDZ export now supports ShadowCatcher component and materials
- Add: USDZ export now contains more meta-info about exported animations
- Add: Log warnings on USDZ export for overlapping animation roots so hierarchy can be manually adjusted
- Add: Use ?debugusdzbehaviours to log more information and Behaviour Graphs during USDZ export. A graph in mermaid format will be logged into the console, which can be pasted into https://massive-mermaid.glitch.me or other viewers. 
- Fix: USDZ animation rounding error edge cases for long-running animations (>20.000 frames)
- Fix: USDZ export only adds physics extension now if required to work around QuickLook issue (FB15925487) for animated objects with physics components
- Fix: USDZ exporter adds rest poses properly again
- Fix: Developer console is now more robust against network errors, e.g. offline PWA usage
- Fix: Canvas parent element size now matches the canvas size

## [3.50.0-beta] - 2024-10-28
- Add: PWA plugin now works with gzip compression
- Add: Asynchronous overload for `screenshot2` method that returns a `Promise<Blob>`
- Add: USDZExporter supports `animator.minMaxOffsetNormalized` and `animation.minMaxOffsetNormalized` for QuickLook now
- Add: USDZExporter vertex color export. Use unlit white materials with only vertex colors to export as `displayColor` without a material. This is supported on iOS 18+ and visionOS 2+.
- Fix: automatically instanced/batched meshes are not exported twice in USDZ anymore.
- Change: "Open in QuickLook" is now "View in AR" to be more consistent
- Change: Deprecate device utilities outside the `DeviceUtilities` namespace, use the methods directly from the namespace instead (e.g. `DeviceUtilities.isSafari()`)
- Change: legacy `Object3D.transform` wrapper that returns itself

## [3.49.0-beta] - 2024-10-21
- Add: More jsdoc code API documentation
- Add: `OrbitControls` can now lerp to a target field of view
- Add: Timeline animation tracks now can have 0..1 weights
- Add: `getBoundingBox` can now optionally respect a layer mask for determining which objects to include
- Fix: Regression with animations not playing on instantiated objects
- Fix: `DeleteBox` uses `getBoundingBox` now instead of a custom implementation
- Fix: `Duplicatable` now correctly checks for its target object already being deleted
- Fix: vite plugins use vite 5.x API (and are still compatible with 4.x)
- Fix: MX Ink support for QuestOS v71+
- Fix: Some logs where incorrectly not behind debug flags
- Fix: Don't export cameras in USDZ when requesting QuickLook-compatible assets
- Fix: Exclude childs of `ContactShadows` and `GroundProjectedEnv` from USDZ export
- Fix: Custom hand models should not automatically become occluders in Passthrough XR
- Fix: Avoid potential exception in `GameObject.getAllComponents(...)`
- Fix: Prevent exception in `DragControls` when dragged object or controller disappear mid-drag
- Fix: Improve `EventList` usage from pure JS
- Fix: Regression in `OrbitControls.autoFit` that resulted in a wrong fit in some cases
- Fix: Improve order of batch validation for automatic instancing when some meshes have different attributes
- Change: Needle Menu styles are more consistent now
- Change: Change casing on `isiPad()`, deprecate `isIPad()`

## [3.48.3] - 2024-09-30
- Add: `NeedleXRSession.start("ar")` support which will start `immersive-ar` on supported devices or export an interactive USDZ on iOS devices
- Add: nextjs alias plugin
- Fix: Voip on iOS with connected bluetooth device should select the bluetooth device  

## [3.48.1] - 2024-09-24
- Add: `<needle-engine>` attributes for `background-color`, `background-blurriness` and `background-image`
- Fix: Loading of OBJ files exported from ZBrush
- Fix: Loading of FBX files with empty vertex color attributes
- Fix: Unregister mixer in Animation component 
- Fix: Needle Menu CSS improvements when using custom html elements inside the menu
- Fix: Needle Menu top positioning now takes CSS safe area into account
- Fix: Balloon message styles adjusted
- Fix: ContactShadows auto fit calculation
- Change: Exit AR button style aligned with Needle Menu

## [3.48.0] - 2024-09-19
- Add: Logitech MX Ink controller support
- Add: Quest menu button now shows Needle Menu in immersive-ar and immersive-vr
- Fix: Improved USDZ code generation regarding transformations/matrices
- Fix: USDZ multi-channel attribute export
- Fix: Minor jsdoc comment error
- Fix: Postprocessing Volume `removeEffect` does now also remove effects from assigned `sharedProfile`
- Internal: Warn if Rigidbody physics object could not be created due to a missing collider

## [3.47.8] - 2024-09-10
- Fix: LookAt orientation fixed when both `copyRotation` and `keepUp` are active
  - If you have both options enabled and rely on the previous behaviour, toggle `invertForward` to get the same result as before. 
- Fix: USDZExporter correctly applying `arScale` again
- Fix: Issue with Needle Menu buttons preventing AR or VR to start in certain cases/devices 
- Fix: BatchedMesh/Instancing error after adding/removing many instances and growing the batched mesh buffers where internal state was not properly reset causing an error
- Change: Make Needle Menu text not selectable
- Change:`NeedleXRSession.start("immersive-ar")` now exports to USDZ when called on iOS (experimental) 
- Change: Needle Menu foldout is now closed when entering XR
- Change: Remove `Quit XR` button for screen based AR experiences (in favor of the X icon at the top right corner)
- Change: Needle Menu foldout button has now an larger click area to avoid accidental clicks on the Needle logo
- Change: LookAt `copyTargetRotation` is now disabled automatically during VR/passthrough AR session

## [3.47.7] - 2024-09-04
- Fix: Support loading FBX files in ASCII format
- Fix: Support loading OBJ files starting with `# Alias OBJ`
- Change: Needle Menu buttons height adjusted for mobile

## [3.47.6] - 2024-09-02
- Fix: USDZ animation interpolation. We're now using timesamples for `translation`, `orientation` and `scale` separately. This fixes an issue with animation optimization (optimization removing redundant keyframes) to just 2 keyframes where matrix timesamples would produce unexpected interpolations
- Change: inline mesh bvh worker

## [3.47.6-beta] - 2024-09-02
- Add: `Mathf.random()` can now also accept an array to randomly select an element
- Add: AudioSource `pitch` property
- Add: SpriteRenderer `addSprite` method
- Add: SpriteRenderer `texture` setter to change the texture of the currently rendered sprite
- Fix: SpriteRenderer `sprite` setter
- Fix: OrbitControls double click to focus should not focus if the click was already used (e.g. by a button)
- Fix: XR `screenshot()` support
- Fix: DragControls now work with physical objects again e.g. Rigidbodies that react to gravity

## [3.47.5-beta.1] - 2024-08-28
- Add: `screenshot` option to output a texture
- Fix: `screenshot` method when using a camera with a RenderTexture assigned
- Fix: `ObjectUtils.createPrimitive` option linting
- Change: Addressables `instantiate` method now returns Object3D type

## [3.47.5-beta] - 2024-08-27
- Fix: Shader warmup when loading glTF file containing *only* materials (no scenes)
- Fix: OrbitControls `autoTarget` option causing `setLookTargetPosition` to be overriden during the first frame 
- Fix: Compressed RenderTexture not being updated on objects in the scene
- Fix: Physics mesh BVH generation on worker caused raycasts during processing to not work until the BVH was ready 

## [3.47.4-beta.3] - 2024-08-26
- Fix: three.js changing environment texture while in XR 
- Fix: three.js OrbitControls zoom damping
- Fix: GroundProjectedEnv error when setting `height` as part of init properties as part of `addComponent(..., { height: 4 })`
- Fix: OrbitControls `minZoom` and `maxZoom` should be applied during update
- Change: Camera `backgroundBlurriness` and `backgroundIntensity` should be undefined by default

## [3.47.4-beta.1] - 2024-08-24
- Add: Support loading of glTF files in `<needle-engine src="...">` that don't contain any objects/scenes but just materials. These glTF files will be rendered with a shaderball
- Fix: Regression in ParticleSystem trail rendering where `mode` was not set correctly
- Change: OrbitControls `fitCamera` can now also take a single object as a first parameter

## [3.47.4-beta] - 2024-08-17
- Add: OrbitControls `fitCamera` method overload which can directly take an options parameter. E.g. it can be invoked with `fitCamera({ immediate: false })`
- Fix: Lifecycle hooks like `onStart` and `onInitialized` are now properly called again for new subscribers
- Fix: Regression in raycasting with multi-material objects
- Fix: `<needle-engine>` canvas highlighting with touch on iOS
- Change: The WebGL context is now automatically restored when lost

## [3.47.3-beta.2] - 2024-08-14
- Fix: Issue where automatic camera change stopped working
- Fix: `screenshot` should update the camera aspect ratio before rendering 
- Fix: Physics raycasts do now run basic geometry validation 

## [3.47.3-beta] - 2024-08-13
- Add: Improved ParticleSystem MinMaxCurve and MinMaxGradient types with utility methods (`constant`, `betweenTwoColors` / `setConstant`, `setMinMaxConstant`, `setCurve`) 
- Add: preliminary support for MX Ink pens
- Add: NeedleXRController `pinchPosition` getter for hand tracking
- Add: SceneSwitcher add `sceneLoaded` Eventlist
- Add: DragControls static `CurrentlySelected` getter to access all currently active DragControls components
- Fix: Gizmo label offset
- Fix: XRControllerFollow on VisionOS with hand tracking
- Fix: Vision OS depth buffer workaround (FB14720123)
- Fix: emulate grip space for hands that don't have grip space
- Fix: `screenshot2` should use passed in camera
- Fix: nextjs plugin fix for error caused by mesh bvh worker integration
- Fix: `input.mouseDoubleClick` getter
- Fix: EventList invocation with custom arguments (e.g. `myEvent.invoke("test")`)

## [3.47.2-beta.3] - 2024-08-08
- Fix: Properly resolve EventList calls when using `instantiate` to the new instances
- Fix: WebXR simulator hand gesture calculation
- Fix: WebXR desktop preview with postprocessing enabled
- Fix: WebXR input `click` detection 

## [3.47.2-beta.2] - 2024-08-06
- Add: Type definitions for Object3D Needle Engine extension methods like `addComponent` or `worldPosition`
- Add: ObjectUtils `createText`
- Add: static `BoxCollider.add` method
- Add: Experimental util method `PlayerSync.setupFrom` to easily setup networked player representations 
- Add: ContactShadows `minSize` property
- Fix: ShadowCatcher should set `receiveShadow` to true
- Fix: Animation `play` should restart the animation if it's at the end
- Fix: ContactShadows should ignore Line materials
- Fix: SyncedRoom component is easier to setup from code
- Change: Physics collider center x should not be flipped. Instead the exporters need to ensure the correct space  

## [3.47.1-beta] - 2024-08-05
- Add: Voip microphone button option to allow users to mute and unmute themselves
- Add: More jsdoc documentation
- Fix: Improved audio and voicechat streams when using the Voip component to more reliably play audio and connect to all users in the room
- Fix: Prevent browsers translation of HTML icons
- Fix: Issue with Application audio playback permissions check
- Fix: SpriteRenderer setting `renderOrder` must be rounded to an integer

## [3.47.0-beta.3] - 2024-08-01
- Add: NeedleXRController `emitPointerDown`, `emitPointerUp` and `emitPointerMove` properties to control if the controller should emit pointer events to the Needle Engine Input System
- Add: NeedleXRController `pointerMoveDistanceThreshold` and `pointerMoveAngleThreshold` for changing when controller `pointermove` events are emitted. These values can be set to 0 to emit events every frame or larger values to reduce the number of events emitted.
- Add: Support to disable SpatialGrabRaycaster by setting the static property `SpatialGrabRaycaster.allow = false`
- Fix: Vite issue where mesh bvh worker was not found in local dev server
- Fix: Mesh BVH should not raycast on meshes that don't have a position attribute
- Change: EventSystem now respects used events. This means if you subscribe to `pointerdown/pointermove/pointerup` with the queue set to a negative value and call `event.use()` or `event.preventDefault()` the EventSystem will ignore the event.

## [3.47.0-beta] - 2024-07-31
- Add: accelerated raycasting using three-mesh-bvh. All calls to `physics.raycast()` now use a spatial grid solution under the hood to improve raycasting performance. (This can be disabled in the raycasting options by setting `useAcceleratedRaycast: false`)
- Add: `physics.engine.raycast` methods now have an option to ignore the `ignoreRaycastLayer` on the Object3D (the three.js layer 2 is used to exclude objects from raycasting. This means setting `layers.set(2)` is equivalent to "Do not raycast on this object")
- Minor UI performance improvements

## [3.46.1-beta.4] - 2024-07-30
- Add: SpriteRenderer `toneMapped` option
- Fix: minor iOS color fix in Needle Menu CSS
- Change: SyncedRoom auto-generated room name is now numbers only by default

## [3.46.1-beta.3] - 2024-07-29
- Fix: Voip should stop audio sending and receiving when user disconnects from a networked room
- Fix: WebXR avatar head being offset when user is not centered in rig space

## [3.46.1-beta.2] - 2024-07-29
- Fix: WebXR teleport and rotation now takes user position in rig space into account. This means when teleporting the user is now placed at the expected ray target point and when rotating the user is rotated around himself as expected (and the position stays the same)
- Fix: Animation component `fadeDuration` didn't fade out previously playing animations but instead stop immediately

## [3.46.1-beta.1] - 2024-07-29
- WebXR performance improvements
- Add: Needle Menu foldout submenu for smaller screen sizes. The compact Needle Menu does now have a submenu which can be opened by clicking the 3 dots button at the right side. This improves the menu layout for smaller screen sizes.
- Fix: ContactShadows performance improvements
- Fix: Gizmo label performance improvements

## [3.46.1-beta] - 2024-07-26
- Add: `isMacOS` utility method
- Improve WebXR controller and hand raycasting and line rendering. Hide rays while the primary pointer i active.
- Improve DragControls performance
- Fix: Animation `play` should resume paused animations instead of restarting
- Fix: PWA plugin now automatically disables gzip compression. Improved error message if there's missing configuration
- Fix: SyncedRoom `joinRoom` button not creating a new room if the room url parameter was present but empty
- Change: Better error message for circular imports causing scripts to not work 
- Change: On OSX and MacOS use power-preference `default` for improved performance ([webkit issue](https://bugs.webkit.org/show_bug.cgi?id=276959))

## [3.46.0-beta.5] - 2024-07-23
- Add: WebXR teleport using right hand pinch
- Add: WebXR `Quit XR` button
- Add: SceneSwitcher `useSceneBackground` option to apply background skybox from loaded scene (if it has any)
- Add: SceneSwitcher option to add Needle menu buttons
- Add: `Gizmos.DrawCircle`
- Fix: issue where `depth-sensing` would cause camera near and far planes to have invalid values causing the scene to not render properly anymore when exiting AR
- Fix: DropListener should not prevent propagation. Otherwise e.g. RemoteSkybox and DropListener would not work together
- Fix: DropListener `placeOnHit` should not raycast on just dropped object
- Fix: issue where onPointerEnter is only invoked once if onPointerExit isnt declared
- Fix: WebXRController hits rendering on UI elements
- Fix: WebXRController rays are always visible when enabled but with a low opacity if no object was hit
- Change: WebXR `autoPlace` does now only place on flat surfaces with a small time threshold
- Change: DragControls `SnapToSurface` now uses `DynamicViewAngle` if no object was hit
- Change: Needle Menu active and focus button CSS

## [3.46.0-beta.1] - 2024-07-23
- Add: MeshTracking (WebXRPlaneTracking) is by default now generating occluder meshes for detected planes and meshes
- Fix: Animation `playOnAwake` regression
- Fix: ContactShadows ignoring GroundProjectedEnv sphere, gizmos and depth only objects (e.g. occluder spheres from mesh tracking)
- Fix: Ensure Sprites when exporting to USDZ 
- Change: Settings on WebARSessionRoot are now all moved to the WebXR component
- Update three.js dependency to 0.162.6

## [3.46.0-beta] - 2024-07-22
- WebXR performance improvements for immersive-ar sessions as well as controller and hand tracking
- Add: GroundProjection can now blend with the AR environment using the `blending` property
- Change: WebXR controller hits now only use object bounds

## [3.45.2-beta.5] - 2024-07-22
- Add: AudioSource properties for `time`, `time01` (normalized time), `duration`
- Add: Animation properties for `time` and method for `pause()`
- Add: WebXRPlaneTracking `occluder` property to automatically generate occluder meshes for detected meshes
- Change: Hide GroundProjection in immersive-ar
- Update three.js dependency to 0.162.5

## [3.45.2-beta.4] - 2024-07-19
- Fix: DragControls `Snap To Surface` when starting to drag
- Change: Minimal increase of close distance for SpatialGrab in WebXR

## [3.45.2-beta.3] - 2024-07-18
- Add: Support for immersive-ar `unbounded` session for unlimited passthrough experiences (enabled by default).   
  This is currently an experimental feature in the Quest browser. To enable it go to `chrome://flags` and check `WebXR experiments`, then restart the Browser. The next time you start an immersive-ar session on quest the WebXR experience will run without guardian boundaries.
- Add: NEPointerEvent `isSpatial` getter to easily determine if an input event was generated by a spatial device
- Fix: Raycast handle null or empty objects in targets array

## [3.45.2-beta.1] - 2024-07-17
- Add: Object `static:true` does now disable `matrixAutoUpdate` 
- Fix: Animation component `play()` issue where previous animations were not always stopped/faded out
- Fix: SceneSwitcher regression causing scenes to not be unloaded
- Change: pointer events are now captured and continue to work when they hover over other HTML elements (if started in the 3D scene)

## [3.45.1-beta.7] - 2024-07-16
- Add: vite plugin that ensures that the npm folder exists
- Fix: Issue where completely empty scene without explicit XR rig caused invalid placement/rendering in VR
- Change: Disable touch-action on `<needle-engine>` element

## [3.45.1-beta.5] - 2024-07-16
- Update gltf-progressive to version 1.2.5

## [3.45.1-beta.3] - 2024-07-15
- Add: GroundProjection blurriness set from `scene.backgroundBlurriness`
- Fix: `getTempVector` and `getTempQuaternion` set to 0,0,0 by default to return consistent values when called without parameters

## [3.45.1-beta.1] - 2024-07-13
- Add: GroundProjection `autoFit` option
- Fix: OrbitControls re-applying autoFit again when enabled/disabled
- Fix: `getBoundingBox` should ignore gizmos

## [3.45.1-beta] - 2024-07-12
- Add: Camera `backgroundRotation` property
- Add: GroundProjection environment rotation using `scene.backgroundRotation`
- Fix: XRControllerModel `createHandModels` not working when `createControllerModels` was disabled
- Change: WebXR avatar does now hide local hand models when XRControllerModel models or hands are enabled

## [3.45.0-beta.1] - 2024-07-11
- Add: The WebXR component now uses a static avatar from the CDN if none is assigned

## [3.45.0-beta] - 2024-07-11
- Add: XRControllerFollow does now reset the object to the original pose after XR
- Fix: XRControllerFollow does now take original object scale into account
- Fix: OrbitControls autoFit now takes GroundProjection scale into account for the camera far plane 
- Change: ContactShadows do now apply scale and transform to a child object so it does not modify the transform anymore of the object it was added to
- Change: GroundProjectionEnv default height to 3
- change: Increase GroundProjectionEnv resolution to 128 for smoother edges
- Change: ChangeMaterialOnClick does now change mouse cursor on hover

## [3.44.6] - 2024-07-10
- Add: The default XR rig is now automatically placed to view the scene if no explicit XRRig component is found in the scene 
- Add: XRControllerMovement does now allow teleportation on the current rig ground plane (if no object is hit when trying to teleport)
- Fix: XRController ray rendering should respect rig scale if the ray doesnt hit any object in the scene
- Fix: rare issue in input calculating world position from screenspace input
- Change: Voip component `autoConnect` default changed to true

## [3.44.5] - 2024-07-10
- Add: `window[Needle].NeedleXRSession`
- Change: WebARSessionRoot reticle without depth test for better use with depth sensing
- Change: VR default movement speed increased slightly from 1 to 1.5
- Change: VR default hit visualization adjusted to improve raycasting.

## [3.44.4] - 2024-07-09
- Fix: SceneSwitcher can now activate and deactivate objects in the scene
- Fix: `XRControllerFollow` takes rig scale into account
- Change: WebXR controllers do not raycast the scene for hit visualization anymore by default. To use add `XRControllerMovement` and enable `showHits`

## [3.44.3] - 2024-07-05
- Add: TonemappingEffect `exposure` setting to control tonemapping exposure
- Fix: Animator transition for negative timescale

## [3.44.1] - 2024-07-05
- Add: `instantiate` can now be invoked to clone objects without components
- Fix: OrbitControls `autoTarget` and `autoFit` at the start of a scene
- Fix: KTX2Loader being created both by needle engine and gltf-progressive resulting in a warning
- Change: DragControls `SnapToSurface` is more snappy
- Change: DragControls `SnapToSurface` drag start behaviour improved

## [3.44.0] - 2024-07-04
- Add: `syncInstantiate(object, { deleteOnDisconnect:boolean })` and `IModel { deleteOnDisconnect:boolean }` option to delete a networked instance in the networking storage when a user disconnects. This requires the networking server to use `@needle-tools/networking@2.x` (instead of `@needle-tools/needle-tiny-networking-ws`)
- Fix: Improve `PlayerSync` networking, use `deleteOnDisconnect` 
- Fix: Update draco decoader to 1.5.7
- Fix: SharpeningEffect effect order
- Fix: SharpeningEffect alpha handling
- Fix: WebXR MeshTracking plane and mesh normals
- Fix: ChangeMaterialOnClick resolving of assigned material in certain cases
- Fix: Duplicatable + DragControls not properly networking on first duplication in cases where multiple DragControls components are nested 

## [3.44.0-beta.2] - 2024-07-02
- Add: Expose `AnimationUtils`
- Fix: Dont apply reflection probes to unlit materials
- Fix: FBX loading can now handle multimaterial objects
- Fix: WebXR networked Avatar head position
- Fix: Needle Menu layout update is now enforced immediately when options change
- Fix: Initialize Postprocessing effects parameter when created from code

## [3.44.0-beta.1] - 2024-07-01
- Add: support to use file extension for determining which loader to use to save initial header fetch 
- Add: Tuned AGX tonemapping
- Fix: Sharpening effect causing color overflow
- Fix: `screenshot()` breaking transparent rendering

## [3.43.0-beta.1] - 2024-06-29
- Add: `environment-image` magic names now use a lower-resolution version of the HDR/EXR image if the texture is just used for lighting
- Fix: Toggle Volume component `enable` should add and remove the effects
- Fix: Remove leftover log in `<needle-button>` 

## [3.43.0-beta] - 2024-06-28
- Add: Postprocessing Sharpening effect
- Add: PostprocessingManager `addEffect` and `removeEffect` API 
- Fix: Error in spatial menu caused by slots
- Fix: Export of WebXRButtonFactory type

## [3.42.0-beta] - 2024-06-27
- Add: `<needle-menu>` slot support
- Add: `<needle-button>` with support for `ar`, `vr` and `quicklook`. For example: `<needle-button ar>` creates a Needle VR button
- Change: default tonemapping is now tuned AGX

## [3.41.2-beta.3] - 2024-06-27
- Add: support to use file extension for determining which loader to use to save initial header fetch 
- Fix: Patched neutral tonemapping [issue](https://github.com/google/model-viewer/issues/4825)

## [3.41.2-beta] - 2024-06-25
- Add: DropListener can now take `dropArea` object to define a section of the scene that would accept the dropped file.
- Add: DropListener support to fit a mesh into a defined volume (e.g. 1x1x1)
- Add: SyncedRoom option to create a share button for the view only room URL
- Fix: DragControls `SnapToSurface` option when dragged object is not a mesh / the mesh is in the child hierarchy

## [3.41.1-alpha.1] - 2024-06-24
- Add: `<needle-engine tone-mapping>` attribute. Possible values are `none`, `linear`, `neutral` or `agx`.
- Change: Camera fitting near and far planes are now tighter to reduce z-fighting in some cases

## [3.41.0-alpha.5] - 2024-06-22
- Add: `<needle-engine>` web component attributes `environment-image` and `skybox-image` can now be set to presets values: "studio", "blurred-skybox", "quicklook" or "quicklook-ar" 
- Fix: ContactShadows should capture objects on all layers
- Fix: Issue in LOD gizmo debug rendering 
- Change: Use smaller icons font

## [3.41.0-alpha.4] - 2024-06-19
- Add: AnimationRegistry, accessible via `this.context.animations`
- Add: static AnimationUtils class
- Add: `TestSceneUtils.createComparisonScene` for quickly spinning up test scenes
- Add: Menu `appendChild` can now create a button from a structured json object 
- Add: New `exportAsGLTF` function
- Add: `<needle-engine contactshadows>` attribute
- Add: Lifecycle hooks like `onStart` or `onUpdate` can now be configured to only run once using the options argument. For example: `onBeforeRender(ctx => { ... },  { once: true })`
- Fix: Postprocessing where Tonemapping was not being applied in some cases
- Fix: `screenshot` method does now support Reflection Probe lighting
- Fix: Lightmapped objects with MultiMaterial objects spamming warnings
- Change: Improve Postprocessing Bloom
- Change: Improve FBX loading
- Change: ContactShadows `autoFit` increases shadow area by factor 1 (previously 0.5)
- Change: Bump three to 0.162.4 adding GLTFExporter plugin hooks and animation retargeting using `userData { name }`
- Change: Bump postprocessing to ^6.35.5
- Change: Bump gltf-progressive dependency

## [3.40.0-alpha.5] - 2024-06-14
- Add: start support for detecting and loading FBX files
- Fix: Camera fitting bounding box calculation where `instanceof Mesh` fails
- Fix: OrbitControls background click only accept primary clicks
- Fix: Issue on Quest due to change in `isMobile` check
- Internal: Deserialization of components can now resolve object if the requested type is an Object3D

## [3.40.0-alpha.2] - 2024-06-12
- Add: Experimental support to load `.fbx` files via `<needle-engine src>`
- Change: Production build command changed - vite plugin now runs when `vite build` is invoked with `--production` - e.g. `vite build -- --production`. The legacy npm build script is automatically updated when the plugin runs for the first time.

## [3.40.0-alpha.1] - 2024-06-10
- Fix: issue where `<needle-engine autoplay>` would not play animations
- Change: "IsMobile" check because window.orientation is deprecated
- Change: USDZ move direct/indirect interaction logic to tapTrigger and add options (by default, both are allowed)

## [3.40.0-alpha] - 2024-06-06
- Update gltf-progressive dependency for smarter LOD texture loading

## [3.39.0-alpha.4] - 2024-06-04
- Add: `WebARSessionRoot.onPlaced` event hook
- Fix: InputField click should open keyboard on Android and iOS
- Fix: ContactShadow and ShadowCatcher meshes should not be raycastable
- Change: OrbitControls `fitCamera` use options object, add "centerCamera" option

## [3.39.0-alpha.3] - 2024-06-04
- Fix: Mesh particle LODs not being loaded
- Fix: UI Image/Raw Image texture LODs not being updated

## [3.39.0-alpha.2] - 2024-06-03
- Fix: vite build pipeline plugin 

## [3.39.0-alpha] - 2024-06-03
- Fix: Issue where OrbitControls setTarget not working as expected sometimes due to first frame matrices not being updated yet
- Fix: Gizmos sometimes rendering for 2 frames instead of just 1
- Change: WebXRImageTracking now applies some smoothing based on jitter amount
- Change: Bump gltf-build-pipeline package to 2.1

## [3.38.0-alpha.3] - 2024-05-30
- Fix: needle menu CSS blur in safari
- Fix: USDZ - move Animation component animations into correct sequence depending on whether it should loop or not
- Fix: QuickLook button being created by WebXR despite `usdzExporter.allowCreateQuicklookButton` explicitly being off

## [3.38.0-alpha.2] - 2024-05-29
- Fix: Issue in vite plugin for Node 16 where fetch wasn't supported yet 
- Fix: AudioListener should remove itself when disabled

## [3.38.0-alpha.1] - 2024-05-29
- Add: OrbitControls `clickBackgroundToFitScene` property that can be used to allow autofitting when users click on the background. By default it is set to 2 clicks
- Add: Vite plugin option to open browser with network ip address when the server starts by setting `needlePlugins(command, config, { openBrowser: true })` in vite.config.js
- Fix: USDZ image tracking orientation corrects for node world matrix now, resulting in proper placement relative to the image
- Fix: WebARSessionRoot matrix and invertForward were not correctly applied for USDZ export
- Change: WebXR Image Tracking orientation was rotated by 180°. Now it's consistent between iOS USDZ and Android WebXR. If you're using image tracking, you might have to rotate your content 180° to adjust to the new orientation.

## [3.37.16-alpha] - 2024-05-28
- Add: `Gizmos.DrawWireMesh` 
- Fix: use lowpoly raycast mesh again when available
- Fix: USDZ - issue where image tracking orientation was inconsistent between Android and iOS
- Change: USDZ - better logs when unsupported animation tracks are used during export (e.g. .activeSelf or material animations).
- Change: USDZ - show balloon warning when exporting unsupported track types

## [3.37.15-alpha] - 2024-05-27
- Add: ScreenCapture `deviceFilter` and `deviceName` properties that simplify camera selection
- Fix: Avatar hands being visible in screenbased AR
- Fix: USDZ workaround for Apple bug FB13808839 - skeletal mesh rest poses must be decomposable in RealityKit
- Fix: Issue where Lightmap LOD textures did not load
- Fix: Issue where Custom Shader LOD textures did not load
- Change: `Powered by Needle` tag can be hidden with indie license

## [3.37.14-alpha] - 2024-05-24
- Fix: Issue where deactivated SpriteRenderer would not be included in USDZ
- Fix: Minor `@serializable` warning in SpriteRenderer 
- Fix: SpriteRenderer progressive textures
- Change: bump `gltf-progressive` package which includes a vanilla three.js example and fixes issue where texture settings were not re-applied correctly after having loaded the texture LOD (e.g. filter)

## [3.37.13-alpha] - 2024-05-23
- Add: WebXRImageTracking `hideWhenTrackingIsLost` option to configure if objects should stay visible or hide when tracking is lost
- Add: WebARSessionRoot `autoPlace` option to allow automatically placing the scene content on the first XR hit 
- Fix: WebXR component `createQRCode` options now respects Needle Menu QR code option
- Change: QR code now warns when being used for scanning a `localhost` address

## [3.37.12-alpha.5] - 2024-05-19
- Fix: Bump `gltf-progressive` package to support updating LODs when using postprocessing effects

## [3.37.12-alpha.4] - 2024-05-18
- Fix: AR placement being prevented by other scripts that caused the event being `used`

## [3.37.12-alpha.1] - 2024-05-17
- Fix: USDZ rel arrays must contain no duplicate entries
- Change: Renderer now manually calls reset for stats at the very end of a frame

## [3.37.12-alpha] - 2024-05-17
- Add: `onClear` (invoked e.g. when `<needle-engine src>` changes) and `onDestroy` hooks (invoked when the needle engine context is disposed)

## [3.37.11-alpha] - 2024-05-15
- Add: USDZ API now supports playing back audio from custom behavior scripts. Usage from inside `createBehaviours`:
  ```ts
  const audioClip = ext.addAudioClip(clipUrl);
  const behavior = new BehaviorModel("playAudio",
      TriggerBuilder.tapTrigger(this.gameObject),  
      ActionBuilder.playAudioAction(playbackTarget, audioClip, "play", volume, auralMode),
  );
  ```
- Add: USDZ API now supports registering animations from custom behavior scripts (experimental)
better lighting response
- Add: animator state speed support in USDZ
- Fix: USDZ export had multiple identical textures for the same cloned image
- Fix: USDZ sprites had wrong lighting because of QuickLook bug with non-specified normals, now emitting (0,0,1) and not (0,0,0) as fallback normals
- Fix: HideOnStart should not hide objects in USDZ that were manually enabled in the scene before
- Fix: issue with texture tiling being 0 in any direction leading to invalid USDZ files
- Fix: Contact Shadows now have consistent blur independent of scene scale
- Fix: Regression with audio not playing at start of USDZ scene
- Fix: Contact Shadows now properly correct for different scene aspect ratios 
- Fix: SceneSwitcher `scenes` array not immediately when creating from code 
- Fix: `onStart` hook not being called for all `<needle-engine>` elements
- Fix: Script registration to correct context when loading multiple `<needle-engine>` components on one page
- Fix: Renderer allow changing the ReflectionProbe anchor at runtime
- Change: USDZ now exports disabled objects as well, sets their visibility to false (for regular USD) and hides them on start (for QuickLook)

## [3.37.10-alpha.7] - 2024-05-14
- Add: `context.menu.setVisible` method for hiding the Needle Menu from code
- Add: `screenshot2` method that takes an options object for easier configuration and transparent screenshots support.
- Fix: Issue with OrbitControls `zoomToCursor` enabled in cases where the loaded glTF didn't contain any camera
- Change: Allow hiding the needle menu for local development 

## [3.37.10-alpha.6] - 2024-05-13
- Add: OrbitControls `zoomSpeed` and `zoomToCursor` properties
- Fix: Reflection probes with lightmaps causing memory leak
- Fix: Contact Shadows now have consistent blur
- Fix: Contact Shadows auto fit box is now correctly setup to include the whole scene
- Fix: Balloon Messages overflowing for very long words
- Change: `clearOverlayMessages` has been renamed to `clearBalloonMessages`

## [3.37.10-alpha.4] - 2024-05-09
- Fix: parents scaled to 0 could lead to `NaN` values appearing out of `lookAt()` calls (three.js issue)
- Fix: off-by-one error in determining which animation clips need to play in exclusive mode in USDZ
- Fix: use the same play action for `PlayAudioOnClick` and on scene start, and prevent scene start audio to play when a click action is also used

## [3.37.10-alpha.3] - 2024-05-08
- Fix: lightmaps with progressive meshes

## [3.37.10-alpha.2] - 2024-05-07
- Add: expose `clearOverlayMessages` method
- Fix: SyncedTransform should not set kinematic if `overridePhysics` is false
- Fix: CustomShader Screenspace support for shaders exported from Unity 2022
- Change: enable preload on audio sources dynamically created by PlayAudioOnClick
- Change: improve URL name parsing for loading screen for blob URLs

## [3.37.10-alpha.1] - 2024-05-06
- Add: static `ContactShadows.auto` 
- Add: ContactShadows `autoFit` option to automatically fit the contact shadows at startup and `fitShadows()` method for applying autofit manually
- Change: Improve PWA logging and rename Vite `pwaOptions` to `pwa` in needlePlugin
- Change: Improve loading screen rendering

## [3.37.9-alpha] - 2024-05-03
- Add: `INeedleGLTFExtensionPlugin.onLoaded` hook providing access to the loaded glTF when registering custom extensions
- Add: PWA ability to specify updateInterval (number in ms or undefined) for auto-updating apps while running
- Fix: WebXRImageTracking now restores tracked objects to their previous state after exit AR
- Fix: WebXRImageTracking extra check in session enabled features if image tracking is even enabled. Otherwise I did get tons of errors in mobile VR
- Fix: Input system now handles mouse wheel during pointer lock
- Fix: Simplify and improve PWA generation and passing workbox config to vite-pwa
- Fix: AnimatorController with multiple layers: don't select start state in another layer
- Fix: AnimatorController handle empty state to stay in last animated previous pose
- Bump gltf-progressive dependency for fixes regarding transparent materials as well as VRM materials
- Bump gltf-build-pipeline dependency to 1.5 alpha for VRM support

## [3.37.8-alpha.1] - 2024-05-02
- Fix: Camera should not set skybox from scene again automatically if there's a background skybox already
- Fix: Multi-material LOD meshes
- Change: Only set GLTFLoaders if none others are already set
- Change: vite userconfig expose "allowHotReload" in jsdoc types (third argument in `needlePlugins`)

## [3.37.8-alpha] - 2024-04-30
- Add: `@needle-tools/gltf-progressive` dependency that handles loading progressive meshes and textures.

## [3.37.7-beta.1] - 2024-04-29
- Fix: USDZ regression in writing timeSamples > 1000

## [3.37.7-beta] - 2024-04-29
- Fix: USDZ animation loops didnt work in some cases
- Fix: Properly apply and revert arScale on USDZ export
- Fix: Correctly apply WebXR arSceneScale on USDZ export even when no USDZExporter is present
- Fix: Hand models not being displayed on VisionPro – invalid data passed into registerExtensions leading to exception
- Fix: `time.timescale` set to 0 now fully pauses physics simulation
- Fix: `@syncField` now properly applies room state once on connection
- Fix: Timeline reset previously active animation actions then being disabled (e.g. when switching to another active timeline) 

## [3.37.6-beta] - 2024-04-26
- Fix: USDZExporter bug where geometry was getting duplicated on export when the same mesh was used multiple times
- Fix: USDZExporter duplicate export of scene start triggers
- Change: Improve USDZExporter animation export validation and improve handling of empty TransformData slots
- Change: Improve USDZ animation export allowing `RegisteredAnimationInfo` to also register a null clip for targeting the rest pose (e.g. empty state)
- Change: Improve USDZ time formatting
- Change: Invoke engine lifecycle hooks in the order in which they were registered (e.g. `onStart(ctx => ...)`)

## [3.37.6-alpha] - 2024-04-24
- Add: More API documentation
- Add: VideoPlayer can now play `m3u` livestream links
- Fix: WebARBackground now checks if camera-access is granted
- Change: Progressively loaded assets now postfix urls with the content hash of the assets if available to make sure the correct version is loaded and not a old version from cache
- Change: VideoPlayer setting `url` now immediately updates the videoplayback

## [3.37.5-alpha] - 2024-04-23
- Add: SceneSwitcher support for adding the `ISceneEventListener` on the sceneSwitcher gameObject
- Fix: OrbitControls should not update on user input when the camera is not currently active
- Change: OrbitControls middle click/double click does not change camera position anymore and just set the look target

## [3.37.4-alpha] - 2024-04-22
- Fix: Collider filtermask bug where it did previously override membership settings in certain cases
- Change: Menu now removes the buttons for very small sizes
- Change: `this.context.physics.engine.raycast` and `raycastWithNormal` api changed to take an options parameter instead of single values. It now also exposes rapier's `queryFilterFlags`, `filterGroups` and the `filterPredicate` options. It can now be called with e.g. `this.context.physics.engine.raycast(origin, direction, { maxDistance: 2 })`

## [3.37.3-alpha] - 2024-04-19
- Fix: Regression in progressive mesh for multi material objects / multiple primitives per mesh
- Change: Improve LOD level selection based on available mesh density per level
  Level of detail switching now finds a good match for screen and mesh density that results in more consistent on-screen triangle density. This change also improves LOD switching for low-poly meshes considerably.
- Change: ScreenCapture now respects if user is in `viewonly` networked room

## [3.37.2-alpha] - 2024-04-17
- Fix: Regression in USDZ export causing behaviours to stop working

## [3.37.1-alpha] - 2024-04-16
- Fix: Eventlist now handles EventListeners being added or removed during `EventList.invoke`
- Fix: Progressive LOD textures issue where compressed textures would not be loaded in some cases when using tiling
- Change: USDZExporter created by the WebXR component now enables `autoExportAnimation` and `autoExportAudioSources` by default

## [3.37.0-alpha] - 2024-04-15
- Add: USDZ physics export for VisionOS
- Add: Sprite `mesh` and `material` properties to simplify creating a new sprite object
- Fix: Loading files that don't have a `.glb` or `.gltf` extension but the correct mime type
- Fix: PostProcessing error when using tonemapping from vanilla threejs
- Change: Bump rapier dependency to ^0.12.0

## [3.36.6] - 2024-04-12
- Add: Needle Menu can now create QR button
- Change: Needle menu fullscreen button now switches the `needle-engine` element into fullscreen
- Change: LODs are now switched at a slightly larger distance

## [3.36.6-beta] - 2024-04-10
- Add: Expose `setAutoFitEnabled` method to remove objects from being included in camera fitting
- Change: Improve WebAR wall and ceiling placement

## [3.36.5-beta] - 2024-04-09
- Add: lifecycle hooks like `onUpdate(()=>{})` now return method to unsubscribe. For example you can now write it like this `const unsubscribe = onUpdate(()=>{ console.log("One Frame"); unsubscribe(); })` 
- Add: `onAfterRender` hook
- Add: RemoteSkybox can now handle locally dropped files
- Add: `ObjectUtils.createSprite` method
- Fix: `<needle-engine camera-controls="0">` does now not create OrbitControls anymore if the assigned glTF file doesn't contain a camera
- Fix: RemoteSkybox doesn't prevent drop events anymore if the dropped file can not be handled

## [3.36.4-beta] - 2024-04-05
- Add: More API documentation
- Add: `SceneSwitcher.addScene`
- Add: SceneSwitcher `scene-opened` event. Subscribe with `sceneSwitcher.addEventListener('scene-opened', args => {})`
- Fix: `OrbitControls.fitCamera` handle case where user passes in array with undefined entries

## [3.36.3-beta.1] - 2024-04-04
- Fix: Needle Menu not visible in AR overlay
- Fix: Contact Shadows should not render transparent objects
- Fix: API docs warnings (internal)

## [3.36.3-beta] - 2024-04-04
- Add: More API documentation for progressive loading, USDZExporter, getComponent methods etc
- Add: Needle Menu CSS for disabled buttons
- Add: Expose `onXRSessionStart` and `onXRSessionEnd` hooks
- Add: `isAndroidDevice` utility method
- Fix: Bounds calculation of SkinnedMeshRenderer with multi-material (multiple three skinned meshes in children)
- Fix: ContactShadows rendering for AR 
- Fix: WebAR touch transform does now ignore touches that start in top 10% of screen on android (e.g. when user is opening the menu by swiping down)
- Change: Needle Menu button height is clamped
- Change: Improve OrbitControls `fitCamera`
- Change: Needle asap now displays custom logo if assigned to `needle-engine` web component (requires PRO license)

## [3.36.2-beta] - 2024-04-03
- Add and improve API documentation
- Add: `onXRSessionEnd` method hook
- Fix: Regression introduced by 3.36.0 causing stencil rendering to not work anymore
- Change: Move QR button method into `ButtonsFactory`

## [3.36.0-beta] - 2024-04-02
- Add: support for Auto LOD generation and runtime switching based on mesh density
- Add: support for progressive mesh loading which can reduce the initial download size significantly
- Add: BatchedMesh support for instancing
- Add: `Renderer.setInstanced(myMesh, true)` call to enable instancing for any Mesh
- Change: raycasting will now use lowpoly LOD which can reduce intersection checks significantly for high-poly assets

## [3.35.1-beta.2] - 2024-04-02
- Add: Animator api for `getCurrentStateInfo()` and `currentAction` getter which returns the currently playing three action.
- Add: More documentation
- Add: `Mathf.randomVector3` method
- Internal: use `compileAsync` for prewarming newly loaded objects

## [3.35.0-beta.2] - 2024-03-25
- Add: Support for `transient-pointer` input sources for VisionOS
- Add: add metadata and intersections to `NEPointerEvent` type. Intersections are filled in from EventSystem. This information can be access via `this.input.addEventListener` or the input event callbacks
- Fix: `GameObject.destroy` should not dispose resources
-