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).
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
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).
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)
NeedleXRSession.start(...)
NeedleXRSession.stop()
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 base class. 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
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
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
Generates a random number
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
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
Contains core functionality for Needle Engine. This includes