Needle Core Components

Built-in components that map to Unity, Blender, and three.js functionality.

Complete Reference

For the full API documentation, see engine.needle.tools/docs/api

Custom Components

You can always create your own components or add wrappers for components we haven't provided yet.

🔊 Audio

Component	Description
`AudioListener`	Receives audio in the scene (attach to camera)
`AudioSource`	Plays audio clips with spatial audio support

🎬 Animation

Component	Description
`Animator`	State machine with AnimatorController, transitions, and conditions
`Animation`	Basic animation playback (single clip)
`PlayableDirector`	Timeline sequences for animation, audio, state control

📷 Camera & Controls

Component	Description
`Camera`	Scene rendering viewpoint (perspective/orthographic)
`OrbitControls`	Rotate, zoom, and pan around target • Sample
`ViewBox`	Defines visible area bounds

🎨 Rendering

Component	Description
`Light`	Directional, Point, Spot lights with shadow support and baking
`MeshRenderer`	Renders meshes with lightmapping and instancing
`SkinnedMeshRenderer`	Renders animated/deformable meshes
`SpriteRenderer`	Renders 2D sprites and animations • Sample
`ParticleSystem`	Particle effects system • Sample
`VideoPlayer`	Video playback, streaming (MediaStream, M3U8) • Sample
`XRFlag`	Control visibility by mode (VR/AR/Desktop)
`DeviceFlag`	Control visibility by device type
`GroundProjection`	Project environment texture on ground • Sample
`SeeThrough`	Fade objects obscuring view • Sample
`ShadowCatcher`	Invisible shadow receiver • Sample
`ContactShadows`	Realtime contact shadows • Sample
`Volume`	Post-processing effects (see below) • Sample

Postprocessing

Postprocessing effects use the pmndrs postprocessing library under the hood. This means you can also easily add your own custom effects and get an automatically optimized postprocessing pass.

For Unity Users

For Needle Engine Postprocessing in Unity you need to use URP (Universal Render Pipeline)


`Volume`	Add effects below
Effects
`Antialiasing`	extra Unity Component
`BloomEffect`	via Volume asset
`Chromatic Aberration`	via Volume asset
`Color Adjustments / Color Correction`	via Volume asset
`Depth Of Field`	via Volume asset
`Tilt Shift Effect`	via Volume asset or separate component
`Vignette`	via Volume asset
`ToneMappingEffect`	via Volume asset or separate component
`PixelationEffect`	via Volume asset or separate component
`Screenspace Ambient Occlusion N8`	via Volume asset or separate component
`Screenspace Ambient Occlusion`	via Volume asset or separate component
`SharpeningEffect`	via Volume asset or separate component
Your custom effect	Example on Stackblitz, Example in docs

🌐 Networking & Multiplayer

Component	Description
`SyncedRoom`	Enable multiplayer networking (required for all networked features)
`Networking`	Configure custom backend server (defaults to Needle servers)
`SyncedTransform`	Sync object position, rotation, scale across clients
`SyncedCamera`	Sync camera view to other users with custom rendering
`PlayerSync`	Instantiate object per connected user (avatars, etc.)
`Voip`	Voice chat with spatial audio • Sample
`ScreenCapture`	Screen sharing capabilities • Sample

🖱️ Interaction

Component	Description
`DragControls`	Drag objects in scene (requires raycaster in parent, e.g. ObjectRaycaster)
`Duplicatable`	Duplicate objects by dragging (requires DragControls)
`OrbitControls`	Camera orbit, zoom, and pan controls
`SmoothFollow`	Smooth interpolation to another object's transform
`DeleteBox`	Destroys Deletable objects entering the box
`Deletable`	Object can be deleted when entering DeleteBox
`DropListener`	Receive file drop events for uploads
`SpatialTrigger`	Raise events when objects enter space/area
`SpatialTriggerReceiver`	Receive events from SpatialTrigger
`CursorFollow`	Make object follow cursor • Sample
`ScrollFollow`	Bind scroll to animations/timeline • Sample
`HoverAnimation`	Animate on hover

Physics

Component	Description
`Rigidbody`	Physical body with gravity, mass, drag (dynamic/kinematic/static)
`BoxCollider`	Box-shaped collision volume
`SphereCollider`	Sphere-shaped collision volume
`CapsuleCollider`	Capsule-shaped collision volume
`MeshCollider`	Complex collision matching mesh geometry
Physics Materials	Control friction, bounciness, and other physical properties
`Attractor`	Attract or repel rigidbodies • Sample

Colliders as Triggers

Set any collider to isTrigger = true to detect overlaps without physical collision response.

🥽 XR / WebXR

Read the full XR documentation

Component	Description
`WebXR`	Enable VR, AR, passthrough, and avatar rendering
`USDZExporter`	Enable QuickLook AR on iOS (USDZ format)
`WebARSessionRoot`	AR scene placement and scale (defines center/alignment)
`XRRig`	Define user start position in VR
`WebARCameraBackground`	Access AR camera feed for effects/rendering
`WebXRImageTracking`	Track images and instantiate objects • Sample
`WebXRPlaneTracking`	Create meshes/colliders for tracked planes
`XRControllerModel`	Render VR controllers or hand models
`XRControllerMovement`	Default movement and teleport controls
`XRControllerFollow`	Make objects follow hands or controllers
`XRFlag`	Control visibility by mode (VR/AR/FirstPerson/ThirdPerson)

🔧 Debugging

Component	Description
`GridHelper`	Draws debug grid
`BoxGizmo`	Draws debug box
`AxesHelper`	Draws XYZ axes

Gizmos in Code

Use static Gizmos methods for drawing debug lines and shapes in your scripts. See Gizmos API

📁 Runtime File Input/Output

Component	Description
`GltfExport`	Export glTF from runtime (experimental)
`DropListener`	Receive file drop events for uploads and networking

🖼️ UI

Spatial UI components map from Unity UI (Canvas, not UI Toolkit) to three-mesh-ui. UI can be animated.

Component	Description
`Canvas`	Unity UI system (World Space mode required)
`Text`	Render text with custom fonts (auto-generated atlas). Use Legacy/Text, not TextMeshPro
`Button`	Click events with onClick. Works in 3D and UI. Use Legacy/Text for labels
`Image`	Renders sprite images
`RawImage`	Renders textures
`InputField`	Text input field

HTML + Spatial UI

For cross-platform projects (VR, AR, desktop), mix spatial and HTML UI:

HTML: 2D interfaces for best accessibility
Spatial UI: 3D interfaces with depth (e.g., button hover states)

🔀 Scene Management

Component	Description
`SceneSwitcher`	Load/unload scenes, prefabs, glTF files with preload, swipe, keyboard, URL navigation

🛠️ Editor Only (Unity/Blender)

Component	Description
`Needle Engine`	Main component for managing web project(s) (install, start, deploy)
`EditorSync`	Sync material/component changes to runtime without reload (hot reload)

Complete API Documentation

For detailed TypeScript API documentation with all methods, properties, and types:

📖 View Complete API Reference →

The API documentation includes:

All component classes and their methods
Component lifecycle hooks
Event handlers and callbacks
Type definitions and interfaces
Code examples and usage patterns

Learn How to Use Components

Create Custom Components - Build your own interactive components
Component Lifecycle Methods - awake, start, update, onEnable, etc.
Input Event Methods - Handle pointer, touch, and keyboard input
Physics Event Methods - Collision and trigger callbacks
XR Event Methods - WebXR-specific events

Integration Guides

Unity Integration - Using components in Unity
Blender Integration - Using components in Blender
three.js Integration - Using components in web projects

Tutorials

TypeScript Essentials - Learn TypeScript for components
For Unity Developers - Component system differences from Unity

How-To Guides

Handle User Input - Mouse, touch, keyboard, VR controllers
Enable Networking - Multiplayer and sync
Enable WebXR - VR and AR experiences
Export 3D Content - Meshes, materials, animations

Additional Reference

Scripting Examples - Common code patterns
TypeScript Decorators - @serializable and more
Time API - deltaTime and time management