Module Engine Core

Destroy an object across the network. See also syncInstantiate.

Instantiate an object across the network. See also syncDestroy.

Utility functions to detect certain device types (mobile, desktop), browsers, or capabilities.

External dependencies that are loaded on demand either by the engine automatically when needed or they can be loaded manually by calling the load function.

NeedleEngineModelLoader is a namespace that provides functions to register custom model loaders and mimetype callbacks. It allows you to create custom loaders for specific file types and determine the mimetype of files based on their content.

Events regarding the websocket connection (e.g. when the connection opens)

The various events that can be dispatched by a Needle Engine IContext instance

The Needle Engine networking server supports the concept of ownership that can be requested.
This enum contains possible outgoing (Request*) and incoming (Response*) events for communicating ownership.

Typically, using the OwnershipModel class instead of dealing with those events directly is preferred.

Use to listen to room networking events like joining a networked room
For example: this.context.connection.beginListen(RoomEvents.JoinedRoom, () => { })

The Addressables class is used to register and manage AssetReference types
It can be accessed from components via Context.Current or Context.addressables (e.g. this.context.addressables)

Utility class for working with animations.

The Application class can be used to mute audio globally, and to check if the application (canvas) is currently visible (it's tab is active and not minimized).

AssetReferences can be used to easily load glTF or GLB assets

You can use AssetReference.getOrCreate to get an AssetReference for a URL to be easily loaded.
When using the same URL multiple times the same AssetReference will be returned, this avoids loading or creating the same asset multiple times.

• myAssetReference.preload() to load the asset binary without creating an instance yet.
• myAssetReference.loadAssetAsync() to load the asset and create an instance.
• myAssetReference.instantiate() to load the asset and create a new instance.
• myAssetReference.unload() to dispose allocated memory and destroy the asset instance.

Use the ButtonsFactory to create buttons with icons and functionality
Get access to the default buttons by using ButtonsFactory.instance
The factory will create the buttons if they don't exist yet, and return the existing ones if they do (this allows you to reparent or modify created buttons)

The circular buffer class can be used to cache objects that don't need to be created every frame.
This structure is used for e.g. Vector3 or Quaternion objects in the engine when calling getTempVector3 or getTempQuaternion.

Holds information about a collision event. Includes a list of contact points and the colliders involved

Holds information about physics contacts

The context is the main object that holds all the data and state of the Needle Engine.
It can be used to access the scene, renderer, camera, input, physics, networking, and more.

Use to register to various Needle Engine context events and to get access to all current instances
e.g. when being created in the DOM

Use this if a file is a external file URL. The file can be any arbitrary binary data like a videofile or a text asset

Gizmos are temporary objects that are drawn in the scene for debugging or visualization purposes
They are automatically removed after a given duration and cached internally to reduce overhead.
Use the static methods of this class to draw gizmos in the scene.

Utility class to perform various graphics operations like copying textures to canvas

Use this if a file is a external image URL

The input system is responsible for handling all input events like pointer events (mouse, touch, xr controllers) and keyboard events.

Utility class for accessing instancing related properties

Instantiation options for syncInstantiate

Received when listening to RoomEvents.JoinedRoom event

A can be used to simply add VR, AR or Quicklook buttons to your website without having to write any code.

web component. See NeedleEngineAttributes attributes for supported attributes
The needle engine web component creates and manages a needle engine context which is responsible for rendering a 3D scene using threejs.
The needle engine context is created when the src attribute is set and disposed when the needle engine is removed from the document (you can prevent this by setting the keep-alive attribute to true).
The needle engine context is accessible via the context property on the needle engine element (e.g. document.querySelector("needle-engine").context). See https://engine.needle.tools/docs/reference/needle-engine-attributes

A NeedleXRController wraps a connected XRInputDevice that is either a physical controller or a hand
You can access specific buttons using getButton and getStick
To get spatial data in rig space (position, rotation) use the gripPosition, gripQuaternion, rayPosition and rayQuaternion properties
To get spatial data in world space use the gripWorldPosition, gripWorldQuaternion, rayWorldPosition and rayWorldQuaternion properties
Inputs will also be emitted as pointer events on this.context.input - so you can receive controller inputs on objects using the appropriate input events on your components (e.g. onPointerDown, onPointerUp etc) - use the pointerType property to check if the event is from a controller or not

This class manages an XRSession to provide helper methods and events. It provides easy access to the XRInputSources (controllers and hands)

• Start a XRSession with NeedleXRSession.start(...)
• Stop a XRSession with NeedleXRSession.stop()
• Access a running XRSession with NeedleXRSession.active

The Needle Engine Pointer Event is a custom event that extends the PointerEvent. It holds additional information like the device index, the origin of the event, the mode of the event (e.g. screen or spatial), the ray in world space, the space of the device, and more.

Main class to communicate with the networking backend

This class is responsible for managing the sending and receiving of streams between peers.

Utility class to create primitive objects

OneEuroFilter is a simple low-pass filter for noisy signals. It uses a one-euro filter to smooth the signal.

Class for abstracting the concept of ownership regarding a networked object or component.
A component that is owned by another user can not be modified through networking (the server will reject changes)

Progress reporting utility. See Progress.start for usage examples.

Used by PromiseAllWithErrors

The RendererData class is used to manage the lighting settings of a scene.
It is created and used within the Needle Engine Context.

A RenderTexture can be used to render a scene to a texture automatically by assigning it to the Camera component's targetTexture property. You can then assign the RenderTexture.texture to materials to be displayed

RGBAColor is a class that represents a color with red, green, blue and alpha components.

Needle Engine component's are the main building blocks of the Needle Engine.
Derive from Behaviour to implement your own using the provided lifecycle methods.
Components can be added to any Object3D using addComponent or GameObject.addComponent.

A collection of utility methods for quickly spinning up test environments

Time is a class that provides time-related information.
It is created and used within the Needle Engine Context.

Factory to create WebXR buttons for AR, VR, Quicklook and Send to Quest
The buttons are created as HTMLButtonElements and can be added to the DOM.
The buttons will automatically hide when a XR session is started and show again when the session ends.

Interface for a camera controller component that can be attached to a camera to control it

Interface for registering custom glTF extensions to the Needle Engine GLTFLoaders. Register your plugin via addCustomExtensionPlugin

All known (types) button names for various devices and cases combined. You should use the device specific names if you e.g. know you only deal with a mouse use MouseButtonName

Event Arguments when a controller changed event is invoked (added or removed)
Access the controller via args.controller, the args.change property indicates if the controller was added or removed

Available cursor types

FBX type

Options for fitting the camera to the scene. Used in OrbitControls.fitCamera

Button names on typical controllers (since there seems to be no agreed naming)
https://w3c.github.io/gamepad/#remapping

GLTF, GLB or VRM

Provides access to the instantiated object and its clone

A loaded model

All possible model types that Needle Engine can load

Typical mouse button names for most devices

Available attributes for the <needle-engine> web component

This is the model for the postMessage event that the needle engine will send to create menu items

The supported file types that can be determined by the engine. Used in tryDetermineMimetypeFromURL and tryDetermineMimetypeFromBinary

Contains a reference to the currently active webxr session and the controller that has changed

NeedleXRSession event argument.
Use args.xr to access the NeedleXRSession

Result of a XR hit-test

An intersection that is potentially associated with a pointer event

OBJ type

Options to create an object. Used by ObjectUtils.createPrimitive

threejs callback event signature

Properties for physics simulation, like friction or bounciness.

Options for the screenshot2 function.

used to find data registered via gltf files e.g. find lightmaps for a Renderer component that were shipped inside a gltf

Needle-defined names for stylus (MX Ink)

Instantiation options for syncInstantiate

Options to create a 3D text object. Used by ObjectUtils.createText

Button names as used in the xr profile

The build time of the project

The generator used to export the scene / build the web project

The version of the Needle engine

Register a callback when an HTMLElement attribute changes.
This is used, for example, by the Skybox component to watch for changes to the environment-* and skybox-* attributes.

Register callbacks for registering custom gltf importer or exporter plugins

Use patcher for patching properties insteadof calling Object.defineProperty individually since this will cause conflicts if multiple patches need to be applied to the same property

Clear all overlay messages from the screen

Utility method to check if two materials were created from the same glTF material

Deep clones an object

Wait for a specific amount of milliseconds to pass

Will wait for a specific amount of frames to pass

Recursive disposes all referenced resources by this object. Does not traverse children

Enable a spatial debug console that follows the camera

Searches the the scene for a component of the given type.
If the contextOrScene is not provided, the current context is used.

Searches the the scene for all components of the given type.
If the contextOrScene is not provided, the current context is used.

Find all users of an object

Fits an object into a bounding volume. The volume is defined by a Box3 in world space.

Generates a QR code HTML image using https://github.com/davidshimjs/qrcodejs

Get the axis-aligned bounding box of a list of objects.

Get the camera controller for the given camera (if any)

Searches for a given component type in the given object.

Searches for a given component type in the children of the given object.

Searches for a given component type in the parent hierarchy of the given object.

Searches for a given component type in the children of the given object.

Searches for a given component type in the children of the given object.

Searches for a given component type in the parent hierarchy of the given object.

Gets the date formatted as 20240220-161993. When no Date is passed in, the current local date is used.

Returns a HTML element containing an icon. Using https://fonts.google.com/icons
As a string you should pass in the name of the icon, e.g. "add" or "delete"

Checks if a url parameter exists. Returns true if it exists but has no value (e.g. ?help) Returns false if it does not exist Returns false if it's set to 0 e.g. ?debug=0 Returns the value if it exists e.g. ?message=hello

Gets a temporary quaternion. If a quaternion is passed in it will be copied to the temporary quaternion
Temporary quaternions are cached and reused internally. Don't store them!

Gets a temporary vector. If a vector is passed in it will be copied to the temporary vector
Temporary vectors are cached and reused internally. Don't store them!

Get the world direction. Returns world forward if nothing is passed in. Pass in a relative direction to get it converted to world space (e.g. dir = new Vector3(0, 1, 1)) The returned vector will not be normalized

Get the world position of an object

True when the application runs on a local url

Returns whether an export process is currently running.

Load a 3D model file from a remote URL

Loads a PMREM texture from the given URL. This also supports the ultra-fast preprocessed environment maps (PMREM) format.

Load a gltf file from a url. This is the core method used by Needle Engine to load gltf files. All known extensions are registered here.

Better lookAt

Look at a 2D point in screen space

Generates a random id string of the given length

Generates a random id string from a list of adjectives and nouns

Remove a listener for when an XR session ends

Remove a listener for when an XR session starts

Register a callback in the engine onAfterRender event This is called every frame after the main camera has rendered

Register a callback in the engine onBeforeRender event
This is called every frame before the main camera renders

Register a callback before the engine context is cleared.
This happens if e.g. <needle-engine src> changes

Register a callback in the engine before the context is destroyed This happens once per context (before the context is destroyed)

Register a callback in the engine context created event. This happens once per context (after the context has been created and the first content has been loaded)

Register a callback in the engine start event.
This happens once at the beginning of a frame
(e.g. once when the method is registered, after is created or the src has changed)

Register a callback in the engine update event
This is called every frame

Add a listener for when an XR session ends This event is triggered when the XR session is ended, either by the user or by the application before all other XR end events

Add a listener for when an XR session starts This event is triggered when the XR session is started, either by the user or by the application before all other XR start events

Load a gltf file from a url. This is the core method used by Needle Engine to load gltf files. All known extensions are registered here.

Place an object on a surface. This will calculate the object bounds which might be an expensive operation for complex objects. The object will be visually placed on the surface (the object's pivot will be ignored).

Postprocesses the material of an object loaded by FBXLoader. It will apply necessary color conversions, remap shininess to roughness, and turn everything into MeshStandardMaterial on the object.
This ensures consistent lighting and shading, including environment effects.

Experimental attribute
Use to hook into another type's methods and run before the other methods run (similar to Harmony prefixes).
Return false to prevent the original method from running.

Can be used to simplify Promise error handling and if errors are acceptable. Promise.all will just fail if any of the provided promises fails and not return or cancel pending promises or partial results Using Promise.allSettled (or this method) instead will return a result for each promise and not automatically fail if any of the promises fails. Instead it will return a promise containing information if any of the promises failed and the actual results will be available as results array

Adds an entry to the browser history. Internally uses window.history.pushState

Registers the Needle Engine components extension

add to a class declaration to automatically register it to the TypeStore (required for HMR right now)

Unregister a callback previously registered with addAttributeChangeCallback.

Unregister callbacks for registering custom gltf importer or exporter plugins

Removes prefix or postfix

Use to resolve a url serialized in a glTF file

Download a image (must be a data url).

Take a screenshot from the current scene.
NOTE: Use screenshot2 for more options.

Take a screenshot from the current scene and return a Texture. This can applied to a surface in 3D space.

The serializable attribute should be used to annotate all serialized fields / fields and members that should be serialized and exposed in an editor

Please use serializable - this version has a typo and will be removed in future versions

Set false to prevent overlay messages from being shown

Enable or disable autofitting for the given object. Objects that are 'disabled' will be excluded in getBoundingBox calculations.
This is used by ContactShadows or OrbitControls when fitting the shadow plane or camera to the given objects or scene.

Set the camera controller for the given camera

Enforce the dev environment flag to be true or false

Mark an Object3D or component as not destroyable

Sets or adds an URL query parameter

Sets an URL parameter without reloading the website

Disable usage tracking

Replaces the current entry in the browser history. Internally uses window.history.replaceState

Set the world position of an object

Set the world position of an object

Displays an error message on screen for a certain amount of time

Displays a debug message on screen for a certain amount of time

Displays a warning message on screen for a certain amount of time

Slerp between two vectors

Decorate a field to be automatically networked synced
Primitive values are all automatically synced (like string, boolean, number).
For arrays or objects make sure to re-assign them (e.g. this.mySyncField = this.mySyncField) to trigger an update

Tries to determine the file type of a file from its URL
This method does perform a range request to the server to get the first few bytes of the file
If the file type can not be determined it will return "unknown"

create accessor callbacks for a field

Wait for a number of frames to pass.

Wait for a promise to resolve.

Wait for a number of seconds to pass.

Subscribe to an object being written to Currently supporting Vector3