Module Built-in Components

Contains Needle Engine Core Components.

This includes

All these components are available wherever Needle Engine is used.

Animation and Sequencing

Animation

Animation component to play animations on a GameObject

Animator

The Animator component plays and manages animations on a GameObject. It works with an AnimatorController to handle state transitions and animation blending. A new AnimatorController can be created from code via AnimatorController.createFromClips.

PlayableDirector

The PlayableDirector component is the main component to control timelines in needle engine. It is used to play, pause, stop and evaluate timelines.
Assign a TimelineAsset to the playableAsset property to start playing a timeline.

Asset Management

DropListener

The DropListener component is used to listen for drag and drop events in the browser and add the dropped files to the scene
It can be used to allow users to drag and drop glTF files into the scene to add new objects.

GltfExport
SceneSwitcher

The SceneSwitcher can be used to dynamically load and unload extra content
Available scenes are defined in the scenes array.
Loaded scenes will be added to the SceneSwitcher's GameObject as a child and removed when another scene is loaded by the same SceneSwitcher.
Live Examples

Camera Controls

Camera

Camera component that handles rendering from a specific viewpoint in the scene. Supports both perspective and orthographic cameras with various rendering options. Internally, this component uses PerspectiveCamera and OrthographicCamera three.js objects.

CharacterController
CharacterControllerInput
OrbitControls

The OrbitControls component is used to control a camera using the OrbitControls from three.js library.
The three OrbitControls object can be accessed via the controls property.
The object being controlled by the OrbitControls (usually the camera) can be accessed via the controllerObject property.

Effects

Antialiasing
BloomEffect

Bloom can be used to make bright areas in the scene glow.

ChromaticAberration
ColorAdjustments
DepthOfField
EffectWrapper
PixelationEffect
PostProcessingEffect

PostProcessingEffect is a base class for post processing effects that can be applied to the scene.
To create a custom post processing effect, extend this class and override the onCreateEffect method and call registerCustomEffectType to make it available in the editor.

ScreenSpaceAmbientOcclusion

Screenspace Ambient Occlusion post-processing effect.
We recommend using ScreenSpaceAmbientOcclusionN8 instead.

ScreenSpaceAmbientOcclusionN8

Screen Space Ambient Occlusion (SSAO) effect.

SharpeningEffect
TiltShiftEffect
ToneMappingEffect
Vignette
Volume

The Volume/PostprocessingManager component is responsible for managing post processing effects.
Add this component to any object in your scene to enable post processing effects.

Everywhere Actions

ChangeMaterialOnClick
ChangeTransformOnClick
EmphasizeOnClick
HideOnStart
PlayAnimationOnClick
PlayAudioOnClick
SetActiveOnClick
TapGestureTrigger
VisibilityAction

Helpers

AxesHelper

Component that visualizes the axes of an object in the scene. Renders colored lines representing the X (red), Y (green) and Z (blue) axes.

BoxGizmo

BoxGizmo is a component that displays a box around the object in the scene. It can optionally expand to the object's bounds.

BoxHelperComponent

A component that creates a bounding box around an object and provides intersection testing functionality.

GltfExportBox

A component that creates a bounding box around an object and provides intersection testing functionality.

GridHelper

GridHelper is a component that allows to display a grid in the scene.

TransformGizmo

TransformGizmo displays manipulation controls for translating, rotating, and scaling objects in the scene. It wraps three.js TransformControls and provides keyboard shortcuts for changing modes and settings.

Interactivity

CharacterControllerInput
Deletable

Objects with this component can be destroyed by the DeleteBox component.

DeleteBox

A box-shaped area that can be used to delete objects that get into it. Useful for sandbox-style builders or physics simulations.

DragControls

DragControls allows you to drag objects around in the scene. It can be used to move objects in 2D (screen space) or 3D (world space). Debug mode can be enabled with the URL parameter ?debugdrag, which shows visual helpers and logs drag operations.

Duplicatable

The Duplicatable component is used to duplicate a assigned GameObject when a pointer event occurs on the GameObject.
It implements the IPointerEventHandler interface and can be used to expose duplication to the user in the editor without writing code.

EventTrigger

The EventTrigger component is used to trigger events when certain pointer events occur on the GameObject. It implements the IPointerEventHandler interface and can be used to expose events to the user in the editor without writing code.

OpenURL

OpenURL behaviour opens a URL in a new tab or window.

SmoothFollow

SmoothFollow makes the Object3D (GameObject) smoothly follow another target Object3D.
It can follow the target's position, rotation, or both.

SpatialTrigger

A spatial trigger component that detects objects within a box-shaped area. Used to trigger events when objects enter, stay in, or exit the defined area

SpatialTriggerReceiver

Component that receives and responds to spatial events, like entering or exiting a trigger zone. Used in conjunction with SpatialTrigger to create interactive spatial events.

Multimedia

AudioListener

AudioListener represents a listener that can hear audio sources in the scene. This component creates and manages a Three.js three#AudioListener, automatically connecting it to the main camera or a Camera in the parent hierarchy.

AudioSource

Plays audio clips in the scene, with support for spatial positioning.

VideoPlayer

The VideoPlayer component can be used to playback video clips from urls, streams or m3u8 playlists (livestreams)

Networking

Avatar
Networking

Provides configuration to the built-in networking system. This component supplies websocket URLs for establishing connections. It implements the INetworkingWebsocketUrlProvider interface.

PlayerColor

PlayerColor assigns a unique color for each user in the room to the object it is attached to.
The color is generated based on the user's ID.

ScreenCapture

The ScreenCapture component allows you to share your screen, camera or microphone with other users in the networked room.
When the stream is active the video will be displayed on the VideoPlayer component attached to the same GameObject.

SpectatorCamera

Provides functionality to follow and spectate other users in a networked environment. Handles camera switching, following behavior, and network synchronization for spectator mode.

SyncedCamera

SyncedCamera is a component that syncs the camera position and rotation of all users in the room.
A prefab can be set to represent the remote cameras visually in the scene.

SyncedRoom

SyncedRoom is a behaviour that will attempt to join a networked room based on the URL parameters or a random room.
It will also create a button in the menu to join or leave the room.
You can also join a networked room by calling the core methods like this.context.connection.joinRoom("roomName").

SyncedTransform

SyncedTransform synchronizes the position and rotation of a game object over the network. It handles ownership transfer, interpolation, and network state updates automatically.

Voip

The Voice over IP component (VoIP) allows you to send and receive audio streams to other users in the same networked room.
It requires a networking connection to be working (e.g. by having an active SyncedRoom component in the scene or by connecting to a room manually).

Physics

BoxCollider

BoxCollider represents a box-shaped collision volume. Ideal for rectangular objects or objects that need a simple cuboid collision boundary.

CapsuleCollider

CapsuleCollider represents a capsule-shaped collision volume (cylinder with hemispherical ends). Ideal for character controllers and objects that need a rounded collision shape.

Collider

Collider is the base class for all colliders. A collider is a physical shape that is used to detect collisions with other objects in the scene.
Colliders are used in combination with a Rigidbody to create physical interactions between objects.
Colliders are registered with the physics engine when they are enabled and removed when they are disabled.

MeshCollider

MeshCollider creates a collision shape from a mesh geometry. Allows for complex collision shapes that match the exact geometry of an object.

Rigidbody

A Rigidbody is used together with a Collider to create physical interactions between objects in the scene.

SphereCollider

SphereCollider represents a sphere-shaped collision volume. Useful for objects that are roughly spherical in shape or need a simple collision boundary.

Rendering

ContactShadows

ContactShadows is a component that allows to display contact shadows in the scene.

GroundProjectedEnv

GroundProjectedEnv creates a ground projection of the current environment map.

Light

The Light component creates a light source in the scene. Supports directional, spot, and point light types with various customization options. Lights can cast shadows with configurable settings and can be set to baked or realtime rendering.

LODGroup

LODGroup allows to create a group of LOD levels for an object.

MeshRenderer
ParticleSystem

The ParticleSystem component efficiently handles the motion and rendering of many individual particles.

ReflectionProbe
Renderer
ShadowCatcher

ShadowCatcher can be added to an Object3D to make it render shadows (or light) in the scene. It can also be used to create a shadow mask, or to occlude light.
If the GameObject is a Mesh, it will apply a shadow-catching material to it - otherwise it will create a quad with the shadow-catching material.

SkinnedMeshRenderer
Sprite

A sprite is a mesh that represents a 2D image

Volume

The Volume/PostprocessingManager component is responsible for managing post processing effects.
Add this component to any object in your scene to enable post processing effects.

User Interface

BaseUIComponent

Derive from this class if you want to implement your own UI components.
It provides utility methods and simplifies managing the underlying three-mesh-ui hierarchy.

Button
Canvas
CanvasGroup
EventSystem
Graphic
GridLayoutGroup
HorizontalLayoutGroup
Image
InputField
MaskableGraphic
NeedleMenu

Provides configuration options for the built-in Needle Menu. Needle Menu uses HTML in 2D mode, and automatically switches to a 3D menu in VR/AR mode.

RawImage
RectTransform

Derive from this class if you want to implement your own UI components.
It provides utility methods and simplifies managing the underlying three-mesh-ui hierarchy.

Text
UIRootComponent

Derive from this class if you want to implement your own UI components.
It provides utility methods and simplifies managing the underlying three-mesh-ui hierarchy.

VerticalLayoutGroup

Utilities

DeviceFlag
XRFlag

XR

Avatar
USDZExporter

Exports the current scene or a specific object as USDZ file and opens it in QuickLook on iOS/iPadOS/visionOS.
The USDZ file is generated using the Needle Engine ThreeUSDZExporter.
The exporter supports various extensions to add custom behaviors and interactions to the USDZ file.
The exporter can automatically collect Animations and AudioSources and export them as playing at the start.
The exporter can also add a custom QuickLook overlay with a call to action button and custom branding.

WebARSessionRoot

The WebARSessionRoot is the root object for a WebAR session and used to place the scene in AR.
It is also responsible for scaling the user in AR and optionally creating a XR anchor for the scene placement.

WebXR

WebXR component to enable VR, AR and Quicklook on iOS in your scene.
It provides a simple wrapper around the NeedleXRSession API and adds some additional features like creating buttons or enabling default movement behaviour.

WebXRImageTracking
WebXRPlaneTracking

Use this component to track planes and meshes in the real world when in immersive-ar (e.g. on Oculus Quest).

XRControllerFollow

Add this script to an object and set side to make the object follow a specific controller.

XRControllerMovement

XRControllerMovement is a component that allows to move the XR rig using the XR controller input.

XRFlag
XRRig

A user in XR (VR or AR) is parented to an XR rig during the session.
When moving through the scene the rig is moved instead of the user.

Other

ClearFlags

The ClearFlags enum is used to determine how the camera clears the background

DragMode

The DragMode determines how an object is dragged around in the scene.

__Ignore
ActionBuilder
ActionCollection
ActionModel
AlignmentConstraint

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.

AnimationCurve

AnimationCurve is a representation of a curve that can be used to animate values over time.

AnimationExtension
AnimationTrackHandler

A TrackHandler is responsible for evaluating a specific type of timeline track.
A timeline track can be an animation track, audio track, signal track, control track etc and is controlled by a PlayableDirector.

AnimatorController

Controls the playback of animations using a state machine architecture.

AudioExtension
AudioTrackHandler

A TrackHandler is responsible for evaluating a specific type of timeline track.
A timeline track can be an animation track, audio track, signal track, control track etc and is controlled by a PlayableDirector.

AvatarLoader

Handles loading and instantiating avatar models from various sources. Provides functionality to find and extract important parts of an avatar (head, hands).

AvatarMarker

This is used to mark an object being controlled / owned by a player
This system might be refactored and moved to a more centralized place in a future version

AvatarModel

Represents an avatar model with head and hands references. Used for representing characters in 3D space.

BasicIKConstraint

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.

BehaviorExtension

internal USDZ behaviours extension

BehaviorModel
Behaviour

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.

CallInfo
CameraTargetReachedEvent
ColorBySpeedModule
ColorOverLifetimeModule
ControlTrackHandler

A TrackHandler is responsible for evaluating a specific type of timeline track.
A timeline track can be an animation track, audio track, signal track, control track etc and is controlled by a PlayableDirector.

CustomBranding

Custom branding for the QuickLook overlay, used by USDZExporter.

DocumentExtension
EmissionModule
EnvironmentScene
EventList

The EventList is a class that can be used to create a list of event listeners that can be invoked

EventListEvent
FieldWithDefault
FixedJoint
GameObject

Base class for objects in Needle Engine. Extends Object3D from three.js. GameObjects can have components attached to them, which can be used to add functionality to the object. They manage their components and provide methods to add, remove and get components.

Gradient
GraphicRaycaster
GroupActionModel
HingeJoint
InheritVelocityModule
InstanceHandle

The instance handle is used to interface with the mesh that is rendered using instancing.

InstancingHandler

Handles instancing for Needle Engine.

Interactable
Keyframe

Keyframe is a representation of a keyframe in an AnimationCurve.

LimitVelocityOverLifetimeModule
LODModel
LogStats

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.

LookAt

LookAt behaviour makes the object look at a target object or the camera.
It can also invert the forward direction and keep the up direction.

LookAtConstraint

A LookAtConstraint is used by OrbitControls to make the camera look at a target.

MainModule
MarkerModel
MinMaxCurve
MinMaxGradient
NeedleUSDZExporter
NestedGltf

The nested gltf is a component that is used to load a gltf file when the component becomes active (start)
It will load the gltf file and instantiate it as a child of the parent of the GameObject that has this component

NoiseModule
ObjectRaycaster
OffsetConstraint

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.

Outline

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.

Padding
ParticleBurst
ParticleSubEmitter
ParticleSystemBaseBehaviour
PhysicsExtension
PointerEventData

This pointer event data object is passed to all event receivers that are currently active
It contains hit information if an object was hovered or clicked
If the event is received in onPointerDown or onPointerMove, you can call setPointerCapture to receive onPointerMove events even when the pointer has left the object until you call releasePointerCapture or when the pointerUp event happens
You can get additional information about the event or event source via the event property (of type NEPointerEvent)

PostProcessingHandler

PostProcessingHandler is responsible for applying post processing effects to the scene. It is internally used by the Volume component

PreliminaryAction

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.

PreliminaryTrigger

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.

Rect
RegisteredAnimationInfo
RemoteSkybox

RemoteSkybox is a component that allows you to set the skybox of a scene from a URL or a local file.
It supports .hdr, .exr, .jpg, .png files.

RendererLightmap
RotationBySpeedModule
RotationOverLifetimeModule
ShapeModule
SignalAsset
SignalMarkerModel
SignalReceiver

SignalReceiver is a component that listens for signals and invokes a reaction when a signal is received. Signals can be added to a signal track on a timeline

SignalReceiverEvent
SignalTrackHandler

A TrackHandler is responsible for evaluating a specific type of timeline track.
A timeline track can be an animation track, audio track, signal track, control track etc and is controlled by a PlayableDirector.

Size
SizeBySpeedModule
SizeOverLifetimeModule
SpatialGrabRaycaster
SpatialHtml

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.

SpriteData
SpriteRenderer

The sprite renderer renders a sprite on a GameObject using an assigned spritesheet (SpriteData).

SpriteSheet
TeleportTarget

This component is just used as a marker on objects for WebXR teleportation
The default XRControllerMovement script checks if this component is on the object you are pointing at and if so it will teleport to that location if triggered
If the component is not present it won't teleport

TextBuilder
TextExtension
TextureSheetAnimationModule
TrackHandler

A TrackHandler is responsible for evaluating a specific type of timeline track.
A timeline track can be an animation track, audio track, signal track, control track etc and is controlled by a PlayableDirector.

TrailModule
TransformData
TriggerBuilder
TriggerModel
UIRaycastUtils
UsageMarker

Marks an object as currently being interacted with. For example, DragControls set this on the dragged object to prevent DeleteBox from deleting it.

USDDocument
USDObject
USDWriter
USDZExporterContext
USDZText
USDZUIExtension
VariantAction
VelocityOverLifetimeModule
VolumeParameter
WebARCameraBackground

WebARCameraBackground is a component that allows to display the camera feed as a background in an AR session to more easily blend the real world with the virtual world or applying effects to the camera feed.

WebXRImageTrackingModel

WebXRImageTracking allows you to track images in the real world and place objects on top of them.
This component is only available in WebXR sessions.
The WebXRImageTrackingModel contains the image to track, the object to place on top of the image, and the size of the image as well as settings for the tracking.
Used by the WebXRImageTracking component

WebXRTrackedImage
XRControllerModel

XRControllerModel is a component that allows to display controller models or hand models in an XR session.

XRState
IEffectProvider
IInputEventArgs
IPointerClickHandler
IPointerDownHandler
IPointerEnterHandler
IPointerEventHandler

Implement on your component to receive input events via the EventSystem component

IPointerExitHandler
IPointerMoveHandler
IPointerUpHandler
ISceneEventListener

The ISceneEventListener is called by the SceneSwitcher when a scene is loaded or unloaded.
It must be added to the root object of your scene (that is being loaded) or on the same object as the SceneSwitcher
It can be used to e.g. smooth the transition between scenes or to load additional content when a scene is loaded.

ITimelineAnimationOverride

Experimental interface for receiving timeline animation callbacks. Register at the PlayableDirector

UsdzBehaviour
DropListenerNetworkEventArguments

Network event arguments passed between clients when using the DropListener with networking

DropListenerOnDropArguments

Arguments provided to handlers when an object is dropped or added to the scene

WebXRPlaneTrackingEvent

Used by WebXRPlaneTracking to track planes in the real world.

XRPlaneContext

Used by WebXRPlaneTracking to track planes in the real world.

PostProcessingEffectOrder

Default order for post-processing effects. This can be used to sort effects by their rendering order when creating custom effects. E.g. in your custom effect, you can set order: PostProcessingEffectOrder.Bloom + 1; to ensure it gets rendered after the bloom effect. OR order: PostProcessingEffectOrder.Bloom - 1; to ensure it gets rendered before the bloom effect.

decompressGpuTexture

Reads back a texture from the GPU (can be compressed, a render texture, or anything), optionally applies RGBA colorScale to it, and returns CPU data for further usage. Note that there are WebGL / WebGPU rules preventing some use of data between WebGL contexts.

imageToCanvas

This method uses a '2d' canvas context for pixel manipulation, and can apply a color scale or Y flip to the given image. Unfortunately, canvas always uses premultiplied data, and thus images with low alpha values (or multiplying by a=0) will result in black pixels.

makeNameSafeForUSD
registerCustomEffectType