# Needle Engine — Core API Reference

## Table of Contents
- [Lifecycle Methods](#lifecycle-methods-complete)
- [Decorators](#decorators)
- [Context API](#context-api-thiscontext)
- [GameObject Utilities](#gameobject-utilities)
- [Finding Objects](#finding-objects)
- [Coroutines](#coroutines)
- [Asset Loading at Runtime](#asset-loading-at-runtime)
- [Renderer and Materials](#renderer-and-materials)
- [Object3D Extensions](#object3d-extensions)
- [Utilities](#utilities)
- [Vite Plugin Options](#vite-plugin-options)

---

## Lifecycle Methods (complete)

All methods are optional — only implement what you need.

```ts
class MyComponent extends Behaviour {
  // Initialization
  awake()        // first, before Start, even if disabled
  onEnable()     // whenever component/GO becomes active
  start()        // once, on first enabled frame

  // Per-frame
  earlyUpdate()  // every frame, before update()
  update()       // every frame
  lateUpdate()   // every frame, after all update() runs
  onBeforeRender(frame: XRFrame | null)  // just before Three.js renders
  onAfterRender()                        // just after Three.js renders

  // Deactivation / cleanup
  onDisable()    // when component/GO becomes inactive
  onDestroy()    // called by destroy(obj) — NOT by removeComponent()

  // Pointer events (requires an EventSystem + Raycaster in the scene)
  onPointerEnter?(args: PointerEventData)   // pointer enters this object
  onPointerMove?(args: PointerEventData)    // pointer moves over this object
  onPointerExit?(args: PointerEventData)    // pointer leaves this object
  onPointerDown?(args: PointerEventData)    // pointer button pressed on this object
  onPointerUp?(args: PointerEventData)      // pointer button released
  onPointerClick?(args: PointerEventData)   // full click on this object

  // XR events
  supportsXR?(mode: XRSessionMode): boolean            // filter which XR modes this component handles
  onBeforeXR?(mode: XRSessionMode, args: XRSessionInit) // modify session init params
  onEnterXR?(args: NeedleXREventArgs)                  // joined an XR session
  onUpdateXR?(args: NeedleXREventArgs)                 // per-frame during XR
  onLeaveXR?(args: NeedleXREventArgs)                  // left the XR session
  onXRControllerAdded?(args: NeedleXRControllerEventArgs)   // controller connected
  onXRControllerRemoved?(args: NeedleXRControllerEventArgs) // controller disconnected

  // Physics (requires Needle Collider component on same GameObject)
  onCollisionEnter(col: Collision)
  onCollisionStay(col: Collision)
  onCollisionExit(col: Collision)
  onTriggerEnter(col: Collision)
  onTriggerStay(col: Collision)
  onTriggerExit(col: Collision)
}
```

---

## Decorators

| Decorator | Purpose |
|---|---|
| `@registerType` | Required on every component — registers the class for GLB deserialization |
| `@serializable()` | Serialize/deserialize a primitive (number, string, boolean) |
| `@serializable(Type)` | Serialize/deserialize a typed field (Object3D, Texture, Color, etc.) |
| `@syncField()` | Auto-sync field over the network in a SyncedRoom |
| `@syncField(onChange)` | Sync + call a callback when value changes remotely |


### Serializable Types

```ts
// Primitives — no type argument needed
@serializable() myNumber!: number;
@serializable() myString!: string;
@serializable() myBool!: boolean;

// Complex types — pass the constructor
import { RGBAColor, AssetReference } from "@needle-tools/engine";
import { Object3D, Texture, Vector2, Vector3, Color } from "three";

@serializable(Object3D)      myRef!: Object3D;
@serializable(Texture)       tex!: Texture;
@serializable(RGBAColor)     col!: RGBAColor;
@serializable(AssetReference) asset!: AssetReference;
@serializable(Vector3)       pos!: Vector3;
```

---

## Context API (`this.context`)

```ts
this.context.scene          // THREE.Scene
this.context.mainCamera     // THREE.Camera (currently active)
this.context.renderer       // THREE.WebGLRenderer
this.context.domElement     // <needle-engine> HTML element

// Time
this.context.time.frame       // frame counter (number)
this.context.time.deltaTime   // seconds since last frame (affected by timeScale)
this.context.time.time        // total elapsed seconds
this.context.time.realtimeSinceStartup
this.context.time.timeScale   // default 1; affects deltaTime, animation, and audio

// Input — polling API (check in update())
this.context.input.getPointerDown(index)     // pointer just pressed this frame
this.context.input.getPointerUp(index)       // pointer just released this frame
this.context.input.getPointerPressed(index)  // pointer currently held
this.context.input.getPointerPosition(index) // {x, y} in screen pixels
this.context.input.getPointerPositionDelta(index)  // movement since last frame
this.context.input.getPointerPressedCount()  // how many pointers are pressed
this.context.input.mousePosition             // shortcut for pointer 0 position
this.context.input.getKeyDown(key)           // "Space", "ArrowLeft", "a", etc.
this.context.input.getKeyUp(key)
this.context.input.getKeyPressed(key)

// Input — event-based API (subscribe/unsubscribe)
this.context.input.addEventListener("pointerdown", (evt) => { /* NEPointerEvent */ });
this.context.input.addEventListener("pointerup", callback);
this.context.input.addEventListener("pointermove", callback);
this.context.input.addEventListener("keydown", callback);
this.context.input.removeEventListener("pointerdown", callback);

// Component pointer callbacks (require EventSystem + Raycaster in the scene):
// onPointerEnter, onPointerMove, onPointerExit, onPointerDown, onPointerUp, onPointerClick
// These fire on the specific object the pointer interacts with (see Lifecycle Methods)

// Physics — two raycast systems for different purposes:
// 1. Visual raycast: hits rendered geometry (no collider needed)
//    Automatically builds MeshBVH (three-mesh-bvh) on web workers — falls back to standard
//    three.js raycasting until BVH is ready. Works with procedural geometry too.
//    Use for: UI interaction, picking visible objects, click detection

// Simplest usage — uses current pointer position, works in pointer event handlers:
const hits = this.context.physics.raycast();

// With options:
this.context.physics.raycast({ maxDistance: 100, layerMask: 0xff, ignore: [this.gameObject] })

// From a specific pixel position (e.g. in a raw pointerdown handler):
// IMPORTANT: screenPoint is in normalized device coordinates (-1 to 1), NOT pixels!
const hits = this.context.physics.raycast({
  screenPoint: new Vector2(
    (e.clientX / window.innerWidth) * 2 - 1,
    -(e.clientY / window.innerHeight) * 2 + 1
  ),
});

// DO NOT pass raw pixel coords as screenPoint — this is wrong:
// ctx.physics.raycast({ screenPoint: new Vector2(e.clientX, e.clientY) }) // WRONG!

// 2. Physics engine raycast: hits Rapier colliders only
//    Use for: ground detection, line-of-sight, physics-based queries
this.context.physics.engine?.raycast(origin, direction, { maxDistance, solid })
this.context.physics.engine?.raycastAndGetNormal(origin, direction)
this.context.physics.engine?.sphereOverlap(position, radius)

// Access Rapier world directly for advanced queries:
this.context.physics.engine.world            // underlying Rapier world

// Network
this.context.connection                      // core networking manager (usable directly or via SyncedRoom)
```

---

## GameObject Utilities

```ts
import { instantiate, destroy, GameObject } from "@needle-tools/engine";

// Component access
go.getComponent(Type)
go.getComponentInChildren(Type)
go.getComponentInParent(Type)
go.getComponents(Type)         // all matching on same GO
go.getComponentsInChildren(Type)

// Lifecycle
instantiate(source, opts?)              // preferred — clone; opts: { position, rotation, parent }
destroy(obj)                            // destroys GO + calls onDestroy on components
obj.removeComponent(comp)               // removes without calling onDestroy

// Active state
go.visible = false           // hides in scene (still ticks)
GameObject.setActive(go, false)  // disables lifecycle callbacks

// Hierarchy
go.contains(otherObj)        // true if otherObj is a descendant (Needle extension on Object3D)

// World-space properties (Needle extensions on Object3D)
go.worldPosition             // get/set world position (Vector3)
go.worldQuaternion           // get/set world rotation (Quaternion)
go.worldScale                // get/set world scale (Vector3)
go.worldForward              // forward direction in world space (Vector3)
go.worldRight                // right direction in world space (Vector3)
go.worldUp                   // up direction in world space (Vector3)

// Tag / name
go.name          // string
go.userData.tags // string[] (set from Unity via Tag component)
```

---

## Finding Objects

```ts
import { findObjectOfType, findObjectsOfType } from "@needle-tools/engine";

findObjectOfType(MyComponent, ctx)          // first match in scene
findObjectsOfType(MyComponent, ctx)         // all matches
ctx.scene.getObjectByName("Player")         // by name (Three.js built-in)
```

---

## Coroutines

Generator functions that can yield across frames:

```ts
import { WaitForSeconds, WaitForFrames, delayForFrames } from "@needle-tools/engine";

start() {
  this.startCoroutine(this.flashLight());
}

*flashLight() {
  while (true) {
    this.light.visible = !this.light.visible;
    yield WaitForSeconds(0.5);   // wait 0.5 seconds
    // yield;                    // wait exactly one frame
    // yield WaitForFrames(10);  // wait N frames
  }
}

// Stop all coroutines on this component:
this.stopAllCoroutines();

// Async alternative (returns a Promise):
await delayForFrames(5);
```

---

## Asset Loading at Runtime

```ts
import { AssetReference } from "@needle-tools/engine";

// Declare in component (set in Unity Inspector)
@serializable(AssetReference) prefab!: AssetReference;

async start() {
  // Load and instantiate
  const instance = await this.prefab.instantiate({ parent: this.gameObject });

  // Or just load the GLTF (no instantiate)
  const gltf = await this.prefab.loadAssetAsync();
}
```

Load a GLB by URL at runtime:
```ts
import { AssetReference } from "@needle-tools/engine";

const ref = AssetReference.getOrCreate(this.context.domElement.baseURI, "assets/extra.glb");
const instance = await ref.instantiate({ parent: this.gameObject });
```

Load any asset directly (without AssetReference):
```ts
import { loadAsset } from "@needle-tools/engine";

const model = await loadAsset("assets/model.glb");
const obj = model.scene; // ← Object3D is on .scene, not the return value itself
obj.traverse(n => { /* ... */ });
```

> **`loadAsset()` returns a model wrapper** (with `.scene`, `.animations`, etc.) — not an Object3D directly. The wrapper type is universal regardless of format (GLB, FBX, OBJ, USDZ). Use `model.scene` to get the root Object3D.

> **Caching:** `AssetReference.getOrCreate()` caches by URL and returns the **same Object3D** on repeated calls. Adding a cached object to the scene again just moves it. Use `.instantiate()` for independent copies.

> **Note:** Needle Engine automatically handles KTX, Draco, and meshopt decompression — no loader setup needed.

---

## Renderer and Materials

### Accessing meshes and materials
The `Renderer` component wraps Three.js meshes/materials. It's present on objects exported from Unity/Blender, but not automatically created for code-only objects — add it manually with `addComponent(Renderer)`, or access materials directly via Three.js (`(obj as Mesh).material`).

```ts
import { Renderer } from "@needle-tools/engine";

const renderer = this.gameObject.getComponent(Renderer);

// Materials
renderer.sharedMaterial            // first material (read/write)
renderer.sharedMaterials           // all materials (array, index-assignable)
renderer.sharedMaterials[0] = mat; // replace a material by index

// Meshes
renderer.sharedMesh                // first Mesh/SkinnedMesh Object3D
renderer.sharedMeshes              // all mesh Object3Ds (for multi-material groups)

// GPU Instancing — draws identical meshes in a single draw call for performance
// In Unity/Blender: enable on the material or via the Needle UI on the object
// In code:
Renderer.setInstanced(obj, true);  // enable instancing (also creates Renderer if missing)

// Visibility (without affecting hierarchy or component state)
Renderer.setVisible(obj, false);
```

### MaterialPropertyBlock — per-object material overrides
Overrides material properties (color, texture, roughness, etc.) on a **per-object** basis without creating new material instances. Multiple objects can share the same material but look different. Overrides are applied in `onBeforeRender` and restored in `onAfterRender`.

```ts
import { MaterialPropertyBlock } from "@needle-tools/engine";
import { Color, Texture } from "three";

// Get or create a property block for an object (never use the constructor directly)
const block = MaterialPropertyBlock.get(myMesh);

// Override properties
block.setOverride("color", new Color(1, 0, 0));
block.setOverride("roughness", 0.2);
block.setOverride("map", myTexture);

// Override with UV transform (e.g. for lightmaps)
block.setOverride("lightMap", lightmapTex, {
  offset: new Vector2(0.5, 0.5),
  repeat: new Vector2(2, 2)
});

// Read back
const color = block.getOverride("color")?.value;

// Remove overrides
block.removeOveride("color");     // remove one
block.clearAllOverrides();         // remove all
block.dispose();                   // remove the entire property block

// Check if an object has overrides
MaterialPropertyBlock.hasOverrides(myMesh);
```

Overrides are registered on the **Object3D**, not on the material — if you swap the material, overrides still apply to the new one. Use `dispose()` or `clearAllOverrides()` to remove them.

Common use cases: per-object colors/tinting, lightmaps, reflection probes, see-through/x-ray effects.

---

## Object3D Extensions

Needle Engine patches Three.js `Object3D.prototype` with convenience properties. These work on **any** Object3D in the scene.

### World transforms (getter + setter)
```ts
// GET — returns a temporary Vector3/Quaternion (don't store references, copy if needed)
obj.worldPosition       // Vector3 — world-space position
obj.worldQuaternion     // Quaternion — world-space rotation
obj.worldRotation       // Vector3 — world-space euler (degrees)
obj.worldScale          // Vector3 — world-space scale

// SET — must assign to apply (mutating the returned vector won't update the transform)
obj.worldPosition = new Vector3(1, 2, 3);     // sets world position
obj.worldQuaternion = myQuat;                  // sets world rotation
obj.worldScale = new Vector3(2, 2, 2);         // sets world scale

// Direction vectors (read-only)
obj.worldForward        // Vector3 — forward direction in world space (0,0,1 rotated)
obj.worldRight          // Vector3 — right direction
obj.worldUp             // Vector3 — up direction

// worldForward also has a setter — point an object in a direction:
obj.worldForward = targetDirection;
```

The getters return **temporary vectors** from an internal pool — they're overwritten on the next call. You can read and re-assign them directly (`obj.worldPosition = other.worldPosition`). For temporary math use `getTempVector()`. Only use `.clone()` when you must store a value across frames — never in per-frame code.

### Component access
```ts
obj.getComponent(MyComponent)           // first component of type
obj.getComponentInChildren(MyComponent) // search children recursively
obj.getComponentInParent(MyComponent)   // search parents recursively
obj.getComponents(MyComponent)          // all of type on this object
obj.getComponentsInChildren(MyComponent)
obj.addComponent(MyComponent)           // add a new component
```

### Other extensions
```ts
obj.guid                  // get/set — unique identifier for networking (string | undefined)
obj.contains(otherObj)    // true if otherObj is a descendant
obj.activeSelf            // get/set active state (same as GameObject.setActive)
```

`guid` is used by the networking system to identify objects across clients. Objects exported from Unity/Blender have guids automatically. For runtime-created objects, set `obj.guid = "my-id"` if they need to participate in networking (e.g. `syncInstantiate`, `SyncedTransform`).

### Bounding box and fitting
```ts
import { getBoundingBox, fitObjectIntoVolume } from "@needle-tools/engine";

// Get the bounding box of one or more objects
const box = getBoundingBox(myObject);                          // single object
const box = getBoundingBox([obj1, obj2, obj3]);                // multiple objects
const box = getBoundingBox(myObject, [ignoreThisChild]);       // with objects to ignore
const box = getBoundingBox(myObject, undefined, camera.layers); // filter by layer

const size = box.getSize(new Vector3());
const center = box.getCenter(new Vector3());

// Fit an object into a target volume (scale + position)
fitObjectIntoVolume(myObject, targetVolume);
```

---

## Async Modules (`NEEDLE_ENGINE_MODULES`)

Heavy dependencies (physics, postprocessing, etc.) are loaded on demand, not bundled into the main entry point. **You do NOT need to call these for normal usage** — physics and postprocessing initialize automatically when their components are used. These are for advanced use cases like accessing the raw Rapier API or pmndrs postprocessing module directly.

```ts
import { NEEDLE_ENGINE_MODULES } from "@needle-tools/engine";

// Available modules:
NEEDLE_ENGINE_MODULES.RAPIER_PHYSICS    // Rapier physics (WASM)
NEEDLE_ENGINE_MODULES.POSTPROCESSING    // pmndrs postprocessing
NEEDLE_ENGINE_MODULES.POSTPROCESSING_AO // N8AO ambient occlusion
NEEDLE_ENGINE_MODULES.MaterialX         // MaterialX materials (WASM)
NEEDLE_ENGINE_MODULES.PEERJS           // PeerJS for networking

// Each module has:
await module.load();    // trigger load + wait for it
await module.ready();   // wait for load (doesn't trigger one)
module.MODULE           // the loaded module (undefined until loaded)
module.MAYBEMODULE      // null until loaded, then same as MODULE
```

---

## Utilities

All imported from `@needle-tools/engine`.

### Math (`Mathf`)
```ts
import { Mathf } from "@needle-tools/engine";

Mathf.lerp(a, b, t)                    // linear interpolation
Mathf.clamp(value, min, max)            // clamp to range
Mathf.clamp01(value)                    // clamp to [0, 1]
Mathf.remap(value, inMin, inMax, outMin, outMax)  // remap between ranges
Mathf.moveTowards(current, target, step)           // step toward target
Mathf.inverseLerp(a, b, value)          // find t given value
Mathf.toDegrees(radians)
Mathf.toRadians(degrees)
Mathf.random(min, max)                  // random in range (or random from array)
Mathf.easeInOutCubic(t)                 // easing function
```

### Temporary objects (avoid per-frame allocations)
```ts
import { getTempVector, getTempQuaternion } from "@needle-tools/engine";

// Returns reusable objects from a circular buffer — no GC pressure
const v = getTempVector(1, 0, 0);       // temporary Vector3
const q = getTempQuaternion();           // temporary Quaternion
// Don't store references — they get reused. Clone if you need to keep them.
```

### Device detection (`DeviceUtilities`)
```ts
import { DeviceUtilities } from "@needle-tools/engine";

DeviceUtilities.isDesktop()         // Windows/Mac (not headsets)
DeviceUtilities.isMobileDevice()    // phone or tablet
DeviceUtilities.isiOS()             // iPhone, iPad, Vision Pro
DeviceUtilities.isAndroidDevice()
DeviceUtilities.isQuest()           // Meta Quest
DeviceUtilities.isVisionOS()        // Apple Vision Pro
DeviceUtilities.isSafari()
DeviceUtilities.supportsQuickLookAR()  // USDZ/QuickLook support
```

### Timing and delays
```ts
import { delay, delayForFrames, WaitForSeconds, WaitForFrames, WaitForPromise } from "@needle-tools/engine";

// Async
await delay(1000);                       // wait 1 second
await delayForFrames(5);                 // wait 5 frames

// In coroutines
yield WaitForSeconds(0.5);
yield WaitForFrames(10);
yield WaitForPromise(fetch("/api"));     // wait for a promise to resolve
```

### User interaction
```ts
import { awaitInputAsync } from "@needle-tools/engine";

// Wait for the first user interaction (useful for audio autoplay policy)
await awaitInputAsync();
audioSource.play();
```

### URL parameters
```ts
import { getParam, setParamWithoutReload } from "@needle-tools/engine";

const room = getParam("room");                    // read ?room=xyz from URL
setParamWithoutReload("room", "my-room");          // update URL without page reload
```

### Debug messages (on-screen balloon)
```ts
import { showBalloonMessage, showBalloonWarning, showBalloonError } from "@needle-tools/engine";

showBalloonMessage("Hello!");           // info message on screen
showBalloonWarning("Watch out!");       // warning (yellow)
showBalloonError("Something broke!");   // error (red)
```

### Debug console
Append `?console` to the URL to show an on-screen debug console (uses vConsole). Useful for debugging on mobile devices where dev tools aren't available.

### Screenshots
```ts
import { screenshot2, saveImage } from "@needle-tools/engine";

// Simple screenshot (returns data URL)
const dataUrl = screenshot2({ width: 1920, height: 1080 });
saveImage(dataUrl, "screenshot.png");

// Screenshot as texture (apply to a material)
const tex = screenshot2({ type: "texture", width: 512, height: 512 });

// Screenshot as blob
const blob = await screenshot2({ type: "blob" });

// Share via Web Share API
await screenshot2({ type: "share", title: "My Scene" });

// Transparent background
screenshot2({ transparent: true, trim: true });

// XR screenshot (composites 3D scene over camera feed — requires "camera-access" feature)
// Works in AR sessions when camera-access has been requested via onBeforeXR
const xrScreenshot = screenshot2({ width: 1080, height: 1920 });
```

### QR Code
```ts
import { generateQRCode } from "@needle-tools/engine";
const qr = generateQRCode({ text: "https://mysite.com" });
```

---

## Vite Plugin Options

The `needlePlugins` function accepts user settings as the third argument. These control build behavior, optimization, and features.

```ts
import { defineConfig } from "vite";
import { needlePlugins } from "@needle-tools/engine/vite";

export default defineConfig(async ({ command }) => ({
  plugins: [
    ...(await needlePlugins(command, {}, {
      // Key options:

      // Make all external CDN URLs local for offline/self-contained deployments
      makeFilesLocal: true,          // download everything
      // or: makeFilesLocal: "auto", // auto-detect which features to include
      // or: makeFilesLocal: { enabled: true, features: ["draco", "ktx2"] },

      // PWA support (also install vite-plugin-pwa)
      pwa: true,                     // enable with defaults
      // or: pwa: { /* VitePWAOptions */ },

      // Physics engine — set to false to tree-shake Rapier and reduce bundle size
      useRapier: false,

      // Build pipeline — compression and optimization of glTF files
      noBuildPipeline: false,        // default: runs optimization
      buildPipeline: {
        accessToken: process.env.NEEDLE_CLOUD_TOKEN,  // use Needle Cloud for compression
      },

      // Other options:
      // noAsap: true,              // disable glTF preload links
      // noPoster: true,            // disable poster image generation
      // openBrowser: true,         // auto-open browser on local network IP
    })),
  ],
}));
```

### `makeFilesLocal` features
Downloads external CDN URLs at build time for fully self-contained deployments. Available features: `draco`, `ktx2`, `materialx`, `xr`, `skybox`, `fonts`, `needle-fonts`, `needle-models`, `needle-avatars`, `polyhaven`, `cdn-scripts`, `github-content`, `threejs-models`, `needle-uploads`.