Module Engine Core

Contains core functionality for Needle Engine. This includes

  • Context Management
  • Asset Loading
  • Component Lifecycle
  • Time Handling
  • XR support
  • Unified Input Handling
  • Needle Menu
  • Networking
  • Physics, Collisions, Raycasting
  • Math and Filtering Helpers
  • Rendering Utilities
  • Debugging Utilities, Gizmos
  • User agent detection
  • and more.

Networking

syncDestroy

Destroy an object across the network. See also syncInstantiate.

syncInstantiate

Instantiate an object across the network. See also syncDestroy.

Other

BlobStorage
DeviceUtilities

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

InternalScreenshotUtils
NEEDLE_ENGINE_FEATURE_FLAGS
NEEDLE_ENGINE_MODULES

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

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.

PreviewHelper
ConnectionEvents

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

ContextEvent

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

OwnershipEvent

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.

RoomEvents

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

Addressables

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)

AnimationUtils

Utility class for working with animations.

AnimatorStateInfo
Application

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).

AssetDatabase
AssetReference

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.
ButtonsFactory

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)

CircularBuffer

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.

Collision

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

ComponentLifecycleEvents
ContactPoint

Holds information about physics contacts

Context

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.

ContextArgs
ContextCreateArgs
ContextRegistry

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

CustomShader
FileReference

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

FileSpawnModel
Gizmos

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.

Graphics

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

ImageReference

Use this if a file is a external image URL

Input

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

InstancingUtil

Utility class for accessing instancing related properties

InstantiateIdProvider
InstantiateOptions

Instantiation options for syncInstantiate

JoinedRoomResponse

Received when listening to RoomEvents.JoinedRoom event

KeyEventArgs
LeftRoomResponse
LightData
LoadingProgressArgs
NeedleButtonElement

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

NeedleEngineWebComponent

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).

NeedleXRController

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

NeedleXRSession

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
NeedleXRSync
NeedleXRUtils
NEKeyboardEvent
NEPointerEvent

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.

NetworkConnection

Main class to communicate with the networking backend

NetworkedStreams

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

NewInstanceModel
ObjectUtils

Utility class to create primitive objects

OneEuroFilter

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

OneEuroFilterXYZ
OwnershipModel

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)

PeerHandle
PeerNetworking
Physics
PlayerView
PlayerViewManager
Progress

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

PromiseErrorResult

Used by PromiseAllWithErrors

RapierPhysics
RaycastOptions
RendererData

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

RenderTexture

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

RenderTextureSerializer
RGBAColor

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

SceneLightSettings

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.

SerializationContext
ShapeOverlapResult
SphereIntersection
StateMachineBehaviour
StreamEndedEvent
StreamReceivedEvent
TestSceneUtils

A collection of utility methods for quickly spinning up test environments

Time

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

UriSerializer
UserJoinedOrLeftRoomModel
Watch
WebXRButtonFactory

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.

IBeforeNetworkedDestroy
IBoxCollider
ICameraController

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

ICollider
IComponent
IConnectionData
IEventList
IGameObject
IHasGuid
IInput
ILight
IModel
INeedleEngineComponent
INeedleGLTFExtensionPlugin

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

INeedleGltfLoader
INeedleXRSessionEventReceiver
INetworkConnection
INetworkingWebsocketUrlProvider
IPhysics
IPhysicsEngine
IPointerHitEventReceiver
IRaycastOptions
IRenderer
IRigidbody
ISerializable
ISharedMaterials
ISphereCollider
ITime
IWatch
IXRRig
UIDProvider
ButtonName

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

ControllerChangedEvt

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

CursorTypeName

Available cursor types

FBX

FBX type

GamepadButtonName

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

GLTF

GLTF, GLB or VRM

InstantiateContext

Provides access to the instantiated object and its clone

LoadedModel

A loaded model

Model

All possible model types that Needle Engine can load

MouseButtonName

Typical mouse button names for most devices

NeedleEngineAttributes

Available attributes for the <needle-engine> web component

NeedleMenuPostMessageModel

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

NeedleMimetype

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

NeedleXRControllerEventArgs

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

NeedleXREventArgs

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

NeedleXRHitTestResult

Result of a XR hit-test

NEPointerEventIntersection

An intersection that is potentially associated with a pointer event

OBJ

OBJ type

ObjectOptions

Options to create an object. Used by ObjectUtils.createPrimitive

OnRenderCallback

threejs callback event signature

PhysicsMaterial

Properties for physics simulation, like friction or bounciness.

ScreenshotOptions

Options for the screenshot2 function.

SourceIdentifier

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

StylusButtonName

Needle-defined names for stylus (MX Ink)

SyncInstantiateOptions

Instantiation options for syncInstantiate

TextOptions

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

XRControllerButtonName

Button names as used in the xr profile

BUILD_TIME

The build time of the project

GENERATOR

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

VERSION

The version of the Needle engine

__internalNotifyObjectDestroyed
addAttributeChangeCallback

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.

addComponent
addCustomExtensionPlugin

Register callbacks for registering custom gltf importer or exporter plugins

addNewComponent
addPatch

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

applyHMRChanges
beginListenDestroy
beginListenInstantiate
clearBalloonMessages

Clear all overlay messages from the screen

compareAssociation

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

copyTexture
createMotion
deepClone

Deep clones an object

delay

Wait for a specific amount of milliseconds to pass

delayForFrames

Will wait for a specific amount of frames to pass

deserializeObject
destroy
destroyComponentInstance
determineMimeTypeFromExtension
disposeObjectResources

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

disposeStream
enableSpatialConsole

Enable a spatial debug console that follows the camera

exportAsGLTF
findByGuid
findObjectOfType

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

findObjectsOfType

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

findResourceUsers

Find all users of an object

fitObjectIntoVolume

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

foreachComponent
foreachComponentEnumerator
forward
generateQRCode

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

generateSeed
getBoundingBox

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

getCameraController

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

getComponent

Searches for a given component type in the given object.

getComponentInChildren

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

getComponentInParent

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

getComponents

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

getComponentsInChildren

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

getComponentsInParent

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

getFormattedDate

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

getIconElement

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"

getIconTexture
getLoader
getOrAddComponent
getParam

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

getParentHierarchyPath
getPath
getPeerjsInstance
getPeerOptions
getResourceUserCount
getTempColor
getTempQuaternion

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!

getTempVector

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!

getUrlParams
getVisibleInCustomShadowRendering
getWorldDirection

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

getWorldEuler
getWorldPosition

Get the world position of an object

getWorldQuaternion
getWorldRotation
getWorldScale
hideDebugConsole
instantiate
isActiveInHierarchy
isActiveSelf
isAndroidDevice
isAnimationAction
isComponent
isDesktop
isDestroyed
isDevEnvironment

True when the application runs on a local url

isDisposed
isExporting

Returns whether an export process is currently running.

isGLTFModel
isHostedOnGlitch
isHotReloadEnabled
isIconElement
isiOS
isiPad
isIPad
isLocalNetwork
isMacOS
isMobileDevice
isMozillaXR
isQuest
isResourceTrackingEnabled
isSafari
isUsingInstancing
loadAsset

Load a 3D model file from a remote URL

loadPMREM

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

loadSync

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.

logHierarchy
lookAtInverse
lookAtObject

Better lookAt

lookAtScreenPoint

Look at a 2D point in screen space

makeId

Generates a random id string of the given length

makeIdFromRandomWords

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

markAsInstancedRendered
microphonePermissionsGranted
offXRSessionEnd

Remove a listener for when an XR session ends

offXRSessionStart

Remove a listener for when an XR session starts

onAfterRender

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

onBeforeRender

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

onClear

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

onDestroy

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

onInitialized

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)

onStart

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)

onUpdate

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

onXRSessionEnd

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

onXRSessionStart

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

parseSync

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.

placeOnSurface

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).

postprocessFBXMaterials

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.

prefix

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.

PromiseAllWithErrors

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

pushState

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

randomNumber

Generates a random number

registerComponent
registerComponentExtension

Registers the Needle Engine components extension

registerExportExtensions
registerExtensions
registerLoader
registerPrefabProvider
registerType

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

removeAttributeChangeCallback

Unregister a callback previously registered with addAttributeChangeCallback.

removeComponent
removeCustomImportExtensionType

Unregister callbacks for registering custom gltf importer or exporter plugins

removePatch

Removes prefix or postfix

resolveUrl

Use to resolve a url serialized in a glTF file

sanitizeString
saveImage

Download a image (must be a data url).

screenshot

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

screenshot2

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

sendDestroyed
serializable

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

serializeable

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

serializeObject
setActive
setAllowBalloonMessages

Set false to prevent overlay messages from being shown

setAllowOverlayMessages
setAutoFitEnabled

Enable or disable autofitting for the given object

setCameraController

Set the camera controller for the given camera

setDestroyed
setDevEnvironment

Enforce the dev environment flag to be true or false

setDisposable
setDontDestroy

Mark an Object3D or component as not destroyable

setOrAddParamsToUrl

Sets or adds an URL query parameter

setParam
setParamWithoutReload

Sets an URL parameter without reloading the website

setPeerOptions
setResourceTrackingEnabled

Disable usage tracking

setState

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

setVisibleInCustomShadowRendering
setWorldEuler
setWorldPosition

Set the world position of an object

setWorldPositionXYZ

Set the world position of an object

setWorldQuaternion
setWorldQuaternionXYZW
setWorldRotation
setWorldRotationXYZ
setWorldScale
showBalloonError

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

showBalloonMessage

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

showBalloonWarning

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

showDebugConsole
slerp

Slerp between two vectors

syncField

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

textureToCanvas
tryDetermineMimetypeFromURL

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"

tryFindObject
unwatchWrite
validate

create accessor callbacks for a field

WaitForFrames

Wait for a number of frames to pass.

WaitForPromise

Wait for a promise to resolve.

WaitForSeconds

Wait for a number of seconds to pass.

watchWrite

Subscribe to an object being written to Currently supporting Vector3