@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.7.1] - 2025-07-31
- Add: LODsManager parameter `skinnedMeshAutoUpdateBoundsInterval`
- Fix: Issue where model fetch with query parameters was constructing a wrong URL

## [4.7.0] - 2025-07-28
- Improved Postprocessing performance and stability - [Live Example](<https://antialiasing-and-postprocessing-zubcksz1o8daw.needle.run/>)
- Fix: Issue where Tonemapping would not be applied
- Change: Improve `<needle-engine background-image="<url>" />` support and deprecate the old `skybox-image` attribute

## [4.6.3] - 2025-07-25
- Update Vite alias plugin to make sure the same postprocessing module is used
- Improve postprocessing stability
- Fix: Postprocessing with transparent background

## [4.6.2] - 2025-07-23
- Postprocessing performance and stability improvements
- Add: Custom postprocessing effects can now use `PostProcessingEffectPriority` to ensure effects are correctly sorted (e.g. before DepthOfField)
- Fix: Postprocessing multisampling (MSAA) causing issues with performance
- Fix: `screenshot` correctly handling custom `devicePixelRatio`

## [4.6.1] - 2025-07-17
- Fix: Post-processing effects ordering and gamma correction handling
- Fix: Renderer and ReflectionProbe update behaviour where changing the scene environment texture would not affect certain objects anymore 
- Fix: ReflectionProbe should not be applied if the component is inactive (e.g. on a disabled Object3D)
- Fix: Internal resource dispose error when destroying objects with custom ShaderMaterials with certain uniform values

## [4.6.0] - 2025-07-14
- Add: Vite plugin to make remote assets local at build time. This currently supports google.font CSS and font assets as well as polyhaven HDRi/EXR textures.   
  To use enable `makeFilesLocal` in your `vite.config.js`:   
  ```js
  needlePlugins(command, needleConfig, {
    makeFilesLocal: true
  }),
  ```
- Change: AudioSource component `preload` option to `true` by default

## [4.5.8] - 2025-06-10
- Fix: QR code logo overlay now scales down for longer URLs and uses stronger error correction level

## [4.5.7] - 2025-06-10
- Fix: `instantiate({ visible: false })` should only set the root object's visible state

## [4.5.6] - 2025-05-21
- Add: `Cylinder` primitive to ObjectUtils
- Add: QR code now displays the URL that will open
- Fix: Issue where calling `NeedleXRSession.stop()` from within `update()` event caused an error

## [4.5.4] - 2025-05-21
- Add: DropListener now also allows custom file types
- Fix: File loading range request url did not handle relative URLs properly
- Fix: Vite built pipeline plugin

## [4.5.0] - 2025-05-21
- Add: `NeedleEngineModelLoader` namespace with methods to provide custom file loaders to load unsupported 3D model formats. For example to load STL files:
   ```ts
   import { NeedleEngineModelLoader } from "@needle-tools/engine";
   import { STLLoader } from "three/examples/jsm/loaders/STLLoader.js";

   // Register a callback for determining our custom loader mimetype
   NeedleEngineModelLoader.onDetermineModelMimetype(args => {
    // check if the mimetype is already provided by the server
    if (args.contentType === "model/stl") {
        return "model/stl";
    }
    // use URL extension if available
    if (args.url.endsWith(".stl")) {
        return "model/stl";
    }
    // check if first few bytes start with "solid"
    // this is a very naive check, but it works for most cases
    if(args.bytes[0] === 0x73 && args.bytes[1] === 0x74 && args.bytes[2] === 0x6c) {
        return "model/stl";
    }
    return null;
   });

   // Register a callback for creating our custom loader
   NeedleEngineModelLoader.onCreateCustomModelLoader(args => {
    if (args.mimetype === "model/stl") {
        const stlLoader = new STLLoader();
        return stlLoader;
    }
   });
   ```
- Add: Experimental attribute to autostart **AR**: `<needle-engine autostart="ar">`
- Add: Modify the QR code button URL via `ButtonsFactory.instance.qrButtonUrl = https://yourwebsite.de`
- Add: ContactShadows `manualUpdate` boolean. When enabled the ContactShadows component will not automatically re-render every frame. When enabled then set `needsUpdate=true` to manually schedule contact shadows re-render
- Change: Needle Engine loading view is now transparent by default. The `loading-background` attribute can be used to add custom styling like `<needle-engine loading-background="#000" />`. Alternatively the `<needle-engine>` web component or background can be styled.
- Removed: Web component attributes: `loading-background-color`, `loading-style`, `loading-text-color`
- Fix: Vite HMR (Hot Module Replacement) working nicely with browser breakpoints and debugging
- Fix: Debug stats (`?stats`) showing correct draw calls when using postprocessing
- Fix: `findObjectOfType` does now also search components on the root scene object

## [4.4.6] - 2025-05-05
- Change: Networking disconnect() should reset state + leaveRoom does now reset allowEditing to true
- Fix Vite prebundle engine with mesh bvh worker

## [4.4.5] - 2025-04-30
- Add: Support for easily adding an Animation component to the root object of a loaded glTF to automatically play animations.
- Add: `loadAsset` function
- Fix: OrbitControls issue where `fitCamera({immediate:true})` would not fit the camera immediately without lerping
- Fix: Vite fetch public key causing build to fail

## [4.4.3] - 2025-04-29
- Add: Support for `getKeyDown`, `getKeyPressed` and `getKeyUp` to pass in key name to check the state of keyboard input, e.g. `context.getKeyDown(<key>)`
- Add: License validation for webpack (nextjs) via access token or teamid. The `needleNext` plugin does now handle the license for passed in team or access tokens.   
  For example the `next.config.js` can be modified like so `... }, { modules: { webpack }, license: {team: "needle"} })` to pass in the name of a team (or a Needle Cloud access token).
- Change: License checks will now read the `NEEDLE_CLOUD_TOKEN` environment variable if no access token is provided.
- Fix: SyncedTransform `fastmode` lerp
- Fix: OrbitControls regression when calling `setCameraAndLookTarget` with a Camera object (or transform) where the forward direction (+Z) did not match the camera's look/render direction (-Z)

## [4.4.2] - 2025-04-24
- Fix: Vite license server timeout
- Fix: Vite `manualChunks` should not be declared if `rollupOutput.inlineDynamicImports` is set to true

## [4.4.0] - 2025-04-17
**Added**
- Add: The needle-engine web-component `contactshadows` attribute now allows you to specify a factor for controlling the darkness/lightness. E.g. `<needle-engine contactshadows="1">` will make the shadows appear darker vs. `<needle-engine contactshadows=".2">` will make the contact shadow appear lighter.
- Add: The needle-engine web-component does now support transparency for `background-color`. For example: `rgba(255, 255, 100, .5)` or `#ffdddd99` or `transparent` are valid values: `<needle-engine background-color="rgba(255, 255, 100, .5)" />`
- Add: `ObjectUtils.createPrimitive()` now supports scale as array   
    e.g. `ObjectUtils.createPrimitive("Cube", { scale: [1, .25, 1] } );`
- Add: Input `getGamepad(<index>)` function to query a connected gamepad. Example: `this.context.input.getGamepad()`
- Add: `lookAtScreenPoint()` function which allows 3D object to look at points in 2D screen coordinates (e.g. your mouse position).    
    **Example Component that makes the object look at the mouse**
    ```ts
    import { Behaviour, lookAtScreenPoint } from "@needle-tools/engine";

    export class LookAtMouse extends Behaviour {
      update() {
        lookAtScreenPoint(this.gameObject, this.context.input.mousePosition, this.context.mainCamera);
      }
    }
    ```
- Add: Default environment lighting. If you don't configure any environment-image needle engine will now create a default scene to light your objects. Previously the scene was just black when the loaded model didn't contain any lighting information.
- Add: SyncedTransform does now also sync scale changes
- Add: SyncedTransform `freeOwnership()` method
- Add: ReflectionProbe bounding box intersection check to automatically apply reflections to object's in a specific area (handled by the Renderer component)
- Add: `devicePixelRatio` option on Needle Context. This option controls the window.devicePixelRatio set on the renderer by Needle Engine (default `auto`). It can be set to `manual` to disable this behaviour or a custom number which will then be set on the renderer or composer.

**Fixed**
- Fix: Implicit camera did not automatically set to skybox when using `background-image`. E.g. `<needle-engine background-image="<url>"> 
- Fix: Tonemapping falsely set tonemappingEsposure to undefined causing a black screen
- Fix: `background-color` attribute was not always applied. E.g. `<needle-engine background-color="#ff3333">`
- Fix: `screenshot()` checks if XR is presenting
- Fix: Issue where MeshBVH worker import breaks for projects where the needle-engine vite plugins are not added to the plugins list
- Fix: SceneSwitcher regression with `Object3D` objects in scenes array
- Fix: SceneSwitcher preload was not using three.js FileLoader to re-use three's caching system
- Fix: GroundProjection regression where background blurriness was hardcoded
- Fix: RenderTexture regression where deserialization was not properly handled anymore
- Fix: OrbitControls regression where forward direction in `setCameraAndLookTarget` was inverted
- Fix: Physics bug where negative box collider scales were not correctly handled in all cases causing Rapier to break
- Fix: UI instantiate bug where three-mesh-ui `clone` method was not working and UI that was already in the scene could not be duplicated because of that.
- Fix: Vite license plugin not waiting for the CLI process to start
- Fix: Vite improve license checks in CI environments (e.g. when running via a Github Action).
- Fix: Vite plugins for running in CI environment
- Fix: Vite `manualChunks` are not defined when `preserveModules` is set to true

**Changed**
- Change: License check aborts now faster instead of retrying when connection is actively refused
- Change: OrbitControls `autoTarget` does now automatically update the look at target after panning and not when rotating the camera (previously the target would be updated after any input but this resultet in undesireable behaviour when rotating around objects)
- Change: When no background-color is defined by either the loaded scene or by a `background-color` attribute then the default scene background color respects the user's accessibility setting for `prefer-dark` or `prefer-light`. This means that the background color will be set to a default light or dark value.
- Change: Scene background color or image set on `<needle-engine>` are not overridden anymore by the camera component.
- Change: Hide Needle logo automatically when using Needle Engine with a license

## [4.4.0-beta.9] - 2025-04-07
- Add: `<needle-engine background-color="#ffdddd55">` does now support transparency. For example: `rgba(255, 255, 100, .5)` or `#ffdddd99` or `transparent` are valid values.
- Add: SyncedTransform `freeOwnership()` method
- Add: ReflectionProbe does now check boundingbox intersection
- Add: `devicePixelRatio` option on Needle Context. This option controls the window.devicePixelRatio set on the renderer by Needle Engine (default `auto`). It can be set to `manual` to disable this behaviour or a custom number which will then be set on the renderer or composer.
- Change: Scene background color or image set on `<needle-engine>` are not overridden anymore by the camera component.
- Change: Hide Needle logo automatically when using Needle Engine with a license
- Fix: Improve license checks in CI environments (e.g. when running via a Github Action).
- Fix: Vite plugins for running in CI environment
- Fix: Vite `manualChunks` are not defined when `preserveModules` is set to true
- Fix: `screenshot()` checks if XR is presenting
- Fix: Issue where MeshBVH worker import breaks for projects where the needle-engine vite plugins are not added to the plugins list
- Fix: Vite license plugin not waiting for the CLI process to start

## [4.4.0-beta] - 2025-03-28
- Add: `ObjectUtils.createPrimitive()` now supports scale as array   
    e.g. `ObjectUtils.createPrimitive("Cube", { scale: [1, .25, 1] } );`
- Add: Input `getGamepad(index?:number)` function to query a connected gamepad. Example: `this.context.input.getGamepad()`
- Add: `lookAtScreenPoint()` function which allows 3D object to look at points in 2D screen coordinates (e.g. your mouse position).    
    **Example Component that makes the object look at the mouse**
    ```ts
    import { Behaviour, lookAtScreenPoint } from "@needle-tools/engine";

    export class LookAtMouse extends Behaviour {
      update() {
        lookAtScreenPoint(this.gameObject, this.context.input.mousePosition, this.context.mainCamera);
      }
    }
    ```
- Add: SyncedTransform does now also sync scale changes
- Add: Default environment lighting. If you don't configure any environment-image needle engine will now create a default scene to light your objects. Previously the scene was just black when the loaded model didn't contain any lighting information.
- Add: The `contactshadows` attribute now allows you to specify a factor for controlling the darkness/lightness. E.g. `<needle-engine contactshadows="1">` will make the shadows appear darker vs. `<needle-engine contactshadows=".2">` will make the contact shadow appear lighter.
- Fix: Implicit camera did not automatically set to skybox when using `background-image`. E.g. `<needle-engine background-image="<url>">` 
- Fix: Tonemapping falsely set tonemappingEsposure to undefined causing a black screen
- Fix: `background-color` attribute was not always applied. E.g. `<needle-engine background-color="#ff3333">`
- Change: License check aborts now faster instead of retrying when connection is actively refused
- Change: OrbitControls `autoTarget` does now automatically update the look at target after panning and not when rotating the camera (previously the target would be updated after any input but this resultet in undesireable behaviour when rotating around objects)
- Change: When no background-color is defined by either the loaded scene or by a `background-color` attribute then the default scene background color respects the user's accessibility setting for `prefer-dark` or `prefer-light`. This means that the background color will be set to a default light or dark value.

## [4.3.2] - 2025-03-20
#### Added
- Documentation for `Gizmos` API
- `this.context.time.fps` returning the FPS for the current frame (for a more stable FPS value `smoothedFps` can be used)

#### Removed
- Vite license plugin check does not support Node 16 anymore

#### Changes
- Improve Vite preload link injection into HTML head
- The PostprocessingManager component does now expose a `multisampling` property which is set to `"auto"` by default. By setting `multisampling` to a number it will force postprocessing to the configured samples.
- Downloading of `<needle-engine>` attributes for `skybox-image` and `environment-image` does now start earlier. Previously it would only start loading the HDRi or EXR images after the root glTF file was finished loading. Now it will start downloading earlier which improves the time until the scene is ready to be displayed.

#### Fixed
- Vite dependency-watcher plugin warning
- Vite license check plugin is now using the latest Needle CLI version
- Browser cache busting issue related to loading the root scene where range requests (e.g. when download urls without a file extension). This caused Chrome to remove files from the disc cache causing a re-download
- Three.js core postprocessing effects support
- Loading glTF files without any components (e.g. when directly downloaded from Sketchfab) was causing Needle Engine to falsely keep a reference to the loaded glTF structure. 
- Instancing issue where instancing did sometimes renderer wrong geometry when many objects where removed and added again and multiple different geometries were batched together. This was caused by a bug in the internal bucketing mechanism and has now been removed since it's not necessary anymore.

## [4.3.2-beta.5] - 2025-03-20
- Change: Improve Vite preload link injection into HTML head
- Fix: Vite dependency-watcher plugin warning

## [4.3.2-beta.4] - 2025-03-19
- Fix: Start loading earlier for `skybox-image` and `environment-image` when configured in `<needle-engine>` web component. Previously it would only start loading the HDRi or EXR images after the root glTF file was finished loading. Now it will start downloading earlier which improves the time until the scene is ready to be displayed.
- Fix: Update vite license check using the latest CLI version
- Fix: Issue related to loading the root scene where range requests (e.g. when download urls without a file extension) caused Chrome to remove previously full downloads to be removed from disc cache
- Remove: Vite license check does not support Node 16 anymore

## [4.3.2-beta.3] - 2025-03-18
- Fix: Support for three.js core postprocessing effects

## [4.3.2-beta.2] - 2025-03-18
- Add: Documentation for `Gizmos` API

## [4.3.2-beta.1] - 2025-03-17
- Fix: Bug when loading glTF files without any components where a reference to the loaded glTF structre was kept in memory causing the memory to not be freed

## [4.3.2-beta] - 2025-03-14
- Add: `this.context.time.fps` returning the FPS for the current frame (for a more stable FPS value `smoothedFps` can be used)
- Change: The PostprocessingManager component does now expose a `multisampling` property which is set to `"auto"` by default. By setting `multisampling` to a number it will force postprocessing to the configured samples.
- Fix: Issue where instancing with multiple different geometries being batched together did sometimes be cause wrong rendering when many objects where removed and added again. This was caused by a bug in the internal bucketing mechanism which is not necessary anymore with the new BatchedMesh version.

## [4.3.1] - 2025-03-14
- Add: Expose lifecylcle hooks in `Needle` global scope for usage in commonjs or without a bundler. For example this allows to subscribe to the update event with `Needle.onUpdate(ctx => console.log(ctx.time.time))`.
- Fix: OrbitControls micro-movement after a pointer event was already used. For example previously when using DragControls and starting to drag an object the camera would still move slightly before stopping during drag. This is not the case anymore now and the camera does not move anymore during interaction with other objects.
- Fix: Canvas UI render settings not being applied in one rare case causing a worldspace image not being set to double sided rendering.

## [4.3.0] - 2025-03-12
- Bump version to 4.3.0

## [4.3.0-alpha.6] - 2025-03-11
- Change: Postprocessing effects in shared volume (when exported from Unity) are now added to the Volume gameObject during initialization
- Fix: improve Rigidbody physics poststep / smoothed velocity

## [4.3.0-alpha.5] - 2025-03-06
- Add: more jsdoc comments to `Graphics.textureToCanvas` and `Mathf` methods
- Change: AudioSource tries to get AudioListener from it's own object first before it checks camera and scene
- Fix: SpriteRenderer issue where runtime instantiate and setting Sprite would in some cases not update the texture on all instances
- Fix: Issue in `Graphics.copyTexture` where the blit material was not yet created

## [4.3.0-alpha.4] - 2025-03-06
- Revert last AudioSource change

## [4.3.0-alpha.3] - 2025-03-06
- Add: WebARSessionRoot `arScale` can now be changed while in AR to modify or reset the scale.
- Change: AudioSource now creates it's own AudioListener instead of using one from the camera. 

## [4.3.0-alpha.1] - 2025-03-03
- Add: More API documentation for various core components

## [4.3.0-alpha] - 2025-02-28
- Add: SceneSwitcher `sceneLoadingStart` and `sceneLoadingProgress` events
- Add: AssetReference `urlName` property
- Fix: SceneSwitcher preloading if configured to not load scene at startup 
- Fix: UI issue where text components were not correctly handled by the EventSystem for the `hasActiveUI` property

## [4.2.5] - 2025-02-27
- Fix: keep FBX vertex color assignment when postprocessing materials
- Fix: ContactShadow flicker when point materials are in the scene
- Fix: OrbitControls keep `autoTarget` enabled in `fitCamera`
- Fix: Static `BoxCollider.add` now correctly calculates bounding box 
- Fix: InputField `onValueChanged` event is now invoked after the new value has been assigned
- Change: `getBoundingBox` now also takes a single object as well as an array of objects
- Change: DropListener now exposes `DropListenerOnDropArguments` type

## [4.2.4] - 2025-02-21
- Add: OrbitControls set to `autoTarget` now automatically updates rotation target in onPointerUp
- Fix: USDZ add safeguard against potential issue in bone sorting
- Fix: USDZ remove extra check for bone type that might prevent bone structure ordering
- Fix: Static method for `BoxCollider.add` not correctly calculating object bounds when object is rotated 
- Fix: Ignore fullscreen plane for WebXR auto center
- Fix: Issue in FBXLoader where loading FBX files with out-of-bounds material assignments lead to incorrect geometry groups and subsequent errors
- Change: Improve input typings for `isKeyDown`, `isKeyUp` and `isKeyPressed`

## [4.2.3] - 2025-02-20
- Add: InputField setter for `text` 
- Fix: OrbitControls setCameraAndLookTarget
- Fix: Issue where updating KTX transcoder was not being correctly applied for offline usage 

## [4.2.2] - 2025-02-18
- Fix: WebXRImageTracking iOS size calculation due to change by Apple
- Fix: USDZ AudioSource not generating code for `playOnAwake` anymore
- Fix: Lightmap and environment ligthing not working correctly anymore due to change in three v163 
- Change: EventSystem simplification - it is now always created once in scene root, this removes the requirement of ObjectRaycasters in the scene which simplifies the usage of component input event methods like `onPointerClick` (which previously required users to ensure there are ObjectRaycasters in the parent hierarchy)

## [4.2.0] - 2025-02-17
- Change: remove MXInk fallback codepath for pre-release OS versions
- Change: don't request "hand-tracking" on VisionOS devices unless explicit custom hand models are requested
- Fix: occluder generation in Plane/Mesh tracking should not be enforced when we have a data template

## [4.1.1] - 2025-02-14
- Fix: ParticleSystem regression where particles using a transparent PBR shader are not being rendered as transparent

## [4.1.0] - 2025-02-13
- Fix: Issue in WebXR component where disabling `usePlacementReticle` would not apply other settings to already existing WebARSessionRoot components in the scene

## [4.1.0-beta.9] - 2025-02-12
- Add: `Object3D.hideFlags` property and ContactShadows sets generated shadow object to `DontExport` to be excluded in runtime glTF export
- Fix: ContactShadows `auto()` does now check if the scene already contains contact shadows 

## [4.1.0-beta.8] - 2025-02-12
- Fix: Handle `<needle-menu>` web component being present anywhere in the document already
- Fix: Allow nextjs based projects to be deployed to Needle Cloud
- Change: `instantiate()` can now take an AssetReference as an argument as well
- Change: Improve `context.input.addEventListener` function typing 

## [4.1.0-beta.6] - 2025-02-05
- Fix: issue with `parseSync` for loading a glTF file is a file path

## [4.1.0-beta.5] - 2025-02-04
- Fix: Physics issue with mesh colliders where colliders were sometimes created with the wrong size depending on the users network speed. This was due to the change of lazily loading the physics engine in Needle Engine 4.
- Fix: Add workaround for a regression in the particle system where PBR materials would sometimes render with a wrong texture. [Issue](https://github.com/Alchemist0823/three.quarks/issues/101)
- Fix: ParticleSystem gradients set to `Random Color` 
- Fix: import WebGLNodes to ensure nodes actually run
- Change: Physics engine `addMeshCollider` scale argument is now optional and treated as scale applied to the object's world scale when creating the collider.

## [4.1.0-beta.4] - 2025-02-03
- Add: OrbitControls support for orthographic camera
- Fix: Orthographic camera aspect ratio

## [4.1.0-beta.3] - 2025-01-30
- Fix: issue where networked values with the `@syncField` decorator would not be updated correctly on instances spawned at runtime (e.g. via PlayerSync).

## [4.1.0-beta.2] - 2025-01-29
- Fix: VideoPlayer screenspace mode colorspace 
- Fix: XRRig `setAsActiveRig()` now ensures the given rig has the highest priority. Previously it was possibly immediately overidden again if another XRRig with a higher priority was active in the scene.
- Change: SpatialTrigger EventList events are now invoked without additional parameters. They did previously take a reference to the SpatialTriggerReceiver and active SpatialTrigger. If this information is important the SpatialTriggerReceiver can be saved when subscribing to the event and the trigger can be accessed using the `triggerReceiver.currentIntersected` array.
- Change: TransformGizmo now exposes the underlying three.js TransformGizmo via a new `control` property.
- Change: GroundProjection now uses the `scene.background` instead of `scene.environment`

## [4.1.0-beta.1] - 2025-01-29
- Fix: ParticleSystem custom behaviours
- Fix: OrbitControls not keeping the initial look direction if `autoTarget` was off
- Fix: Invalid Rigidbody warning caused by async physics engine loading change
- Fix: SharpeningEffect
- Update gltf-progressive including a fix for loading texture LOD 0 (the highest resolution)
- Update three.quarks dependency to 0.15.6

## [4.1.0-beta] - 2025-01-24
- Promote to beta

## [4.1.0-alpha.14] - 2025-01-24
- Fix: glsl shader error at linear to sRGB conversion

## [4.1.0-alpha.13] - 2025-01-23
- Update three.js dependency to fix issue in WebXRManager

## [4.1.0-alpha.12] - 2025-01-21
- Change: Much improved initial loading speed making Needle Engine websites load up to 1000 ms faster.  
  Improved Needle Engine website lighthouse scores for all Vite based projects.   
  Improved bundle chunking and loading for better lighthouse scores.    
  Core bundles and entrypoint glTF files are not loaded as soon as the web document is ready.
- Change: Needle Engine does now lazily import dependencies for `rapier` and `postprocessing` to reduce download and startup size.   
  This means that projects that don't use any collider or rigidbody components will not load the physics and postprocessing modules. Modules can be loaded at any time once they're need by e.g. components in the scene.

## [4.1.0-alpha.11] - 2025-01-17
- Remove: legacy Flycontrols component
- Fix: MeshCollider contact normal direction

## [4.1.0-alpha.10] - 2025-01-17
- Fix: Instanced meshes bug where sometimes an vertex count increase due to mesh compression was not handled correctly

## [4.1.0-alpha.9] - 2025-01-15
- Fix: Better AgX and Neutral tonemapping

## [4.1.0-alpha.8] - 2025-01-14
- Update three.js to r169
- Update dependencies: three-mesh-bvh to 0.8.3, three-quarks to 0.15.5, postprocessing to 6.36.6, n8ao to 1.9.3
- Fix: AR screenshot bug where the second screenshot would not look correct
- Fix: nextjs support

## [4.1.0-alpha.5] - 2025-01-13
- Fix: Issue where MeshCollider with InterleavedBufferAttributes were not created correctly
- Fix: multi-object mesh collider handling for Groups and add warning for remaining case that are not supported
- Fix: transparency trimming for screenshot should happen before screenshot is returned
- Change: Reduced mesh LOD vertex reduction to improve quality of lowest LOD 
- Update build pipeline to latest 2.7 alpha
- Update rapier dependency to 0.14.0

## [4.1.0-alpha.4] - 2025-01-10
- Add: SceneSwitcher methods for `unload()` and `reload()` the currently loaded scene

## [4.1.0-alpha.1] - 2025-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] - 2025-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] - 2025-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] - 2014-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