Class Context

The Needle Engine context is the main access point that holds all the data and state of a Needle Engine application. It can be used to access the Context.scene, Context.renderer, Context.mainCamera, Context.input, Context.physics, Context.time, Context.connection (networking), and more.

The context is automatically created when using the <needle-engine> web component.

Example: Accessing the context from a [component](https://engine.needle.tools/docs/api/Behaviour):

import { Behaviour } from "@needle-tools/engine";
import { Mesh, BoxGeometry, MeshBasicMaterial } from "three";
export class MyScript extends Behaviour {
  start() {
    console.log("Hello from MyScript");
    this.context.scene.add(new Mesh(new BoxGeometry(), new MeshBasicMaterial()));
  }
}

Example: Accessing the context from a [hook](https://engine.needle.tools/docs/scripting.html#hooks) without a component e.g. from a javascript module or svelte or react component.

import { onStart } from "@needle-tools/engine";

onStart((context) => {
  console.log("Hello from onStart hook");
  context.scene.add(new Mesh(new BoxGeometry(), new MeshBasicMaterial()));
});

Implements

  • IContext

Constructors

constructor

Properties

alias animations application assets composer connection domElement focusRectSettings hash? input isManagedExternally isPaused lodsManager mainCameraComponent mainLight maxRenderResolution? menu name physics post_render_callbacks post_setup_callbacks pre_render_callbacks pre_update_callbacks pre_update_oneshot_callbacks renderer runInBackground scene sceneLighting targetFrameRate? time xr

Accessors

arOverlayElement currentFrameEvent depthTexture devicePixelRatio domHeight domWidth domX domY focusRect focusRectSize isCreated isInAR isInPassThrough isInVR isInXR isRendering isVisibleToUser mainCamera opaqueColorTexture rendererData resolutionScaleFactor rootSourceId version xrCamera xrFrame xrSession xrSessionMode All Current DefaultTargetFrameRate DefaultWebGLRendererParameters

Methods

addAfterRenderListener addBeforeRenderListener appendHTMLElement clear createNewRenderer dispose onCreate onDestroy recreate removeAfterRenderListener removeBeforeRenderListener removeCamera renderNow requestSizeUpdate restartRenderLoop setCameraFocusRect setCurrentCamera setRequireColor setRequireDepth update updateAspect updatePhysics updateSize

Constructors

constructor

Properties

alias

alias: undefined | null | string

An alias for the context

animations

animations: AnimationsRegistry

access animation mixer used by components in the scene

application

application: Application

access application state (e.g. if all audio should be muted)

assets

assets: AssetDatabase

Deprecated

AssetDatabase is deprecated

composer

composer: null | EffectComposer | EffectComposer = null

The effect composer can be used to render postprocessing effects. If assigned then it will automatically render the scene every frame.

connection

connection: NetworkConnection

access networking methods (use it to send or listen to messages or join a networking backend)

domElement

domElement: HTMLElement | NeedleEngineWebComponent

The <needle-engine> web component

ReadonlyfocusRectSettings

focusRectSettings: FocusRectSettings = ...

Settings when a focus rect is set. Use setCameraFocusRect(...) to do so.
This can be used to offset the renderer center e.g. to a specific DOM element.

Optionalhash

hash?: string

used to append to loaded assets

input

input: Input

access input data (e.g. click or touch events)

isManagedExternally

isManagedExternally: boolean = false

When the renderer or camera are managed by an external process (e.g. when running in r3f context). When this is false you are responsible to call update(timestamp, xframe.
It is also currently assumed that rendering is handled performed by an external process

isPaused

isPaused: boolean = false

set to true to pause the update loop. You can receive an event for it in your components. Note that script updates will not be called when paused

ReadonlylodsManager

lodsManager: LODsManager

Access the LODs manager to control LOD behavior in the context

mainCameraComponent

mainCameraComponent: undefined | Camera = undefined

The main camera component of the scene - this camera is used for rendering.
Use setCurrentCamera for updating the main camera.

mainLight

mainLight: null | ILight = null

The main light in the scene

OptionalmaxRenderResolution

maxRenderResolution?: Vec2

Clamps the renderer max resolution. If undefined the max resolution is not clamped. Default is undefined

Readonlymenu

menu: NeedleMenu

Access the needle menu to add or remove buttons to the menu element

name

name: string

The name of the context

physics

physics: Physics

access physics related methods (e.g. raycasting). To access the phyiscs engine use context.physics.engine

Readonlypost_render_callbacks

post_render_callbacks: Function[] = []

called every frame after rendering (after all component events)

Readonlypost_setup_callbacks

post_setup_callbacks: Function[] = []

callbacks called once after the context has been created

Readonlypre_render_callbacks

pre_render_callbacks: (frame: null | XRFrame) => void[] = []

called every frame before rendering (after all component events)

Readonlypre_update_callbacks

pre_update_callbacks: Function[] = []

called every frame at the beginning of the frame (after component start events and before earlyUpdate)

Readonlypre_update_oneshot_callbacks

pre_update_oneshot_callbacks: Function[] = []

called every frame befroe update (this list is emptied every frame)

renderer

renderer: WebGLRenderer

The renderer is used to render the scene. It is automatically created when the context is created.

runInBackground

runInBackground: boolean = false

When enabled the application will run while not visible on the page

scene

scene: Scene

The scene contains all objects in the hierarchy and is automatically rendered by the context every frane.

sceneLighting

sceneLighting: RendererData

Access the scene lighting manager to control lighting settings in the context

OptionaltargetFrameRate

targetFrameRate?: number | { value?: number }

Set to the target framerate you want your application to run in (you can use ?stats to check the fps) Set to undefined if you want to run at the maximum framerate

time

time: Time

access timings (current frame number, deltaTime, timeScale, ...)

xr

xr: null | NeedleXRSession = null

shorthand for NeedleXRSession.active
Automatically set by NeedleXRSession when a XR session is active

Returns

the active XR session or null if no session is active

Accessors

arOverlayElement

  • get arOverlayElement(): HTMLElement

    The AR overlay element is used to display 2D HTML elements while a AR session is active.

    Returns HTMLElement

currentFrameEvent

  • get currentFrameEvent(): FrameEvent

    Current event of the update cycle (e.g. FrameEvent.EarlyUpdate or FrameEvent.OnBeforeRender)

    Returns FrameEvent

depthTexture

  • get depthTexture(): null | DepthTexture

    Returns null | DepthTexture

devicePixelRatio

  • get devicePixelRatio(): number | "auto" | "manual"

    Control the renderer devicePixelRatio.
    Options

    • auto - Needle Engine automatically sets the pixel ratio to the current window.devicePixelRatio.
    • manual - Needle Engine will not change the renderer pixel ratio. You can set it manually.
    • number - Needle Engine will set the pixel ratio to the given number. The change will be applied to the renderer and the composer (if used) at the end of the current frame.

    Returns number | "auto" | "manual"

  • set devicePixelRatio(val: number | "auto" | "manual"): void

    Control the renderer devicePixelRatio.
    Options

    • auto - Needle Engine automatically sets the pixel ratio to the current window.devicePixelRatio.
    • manual - Needle Engine will not change the renderer pixel ratio. You can set it manually.
    • number - Needle Engine will set the pixel ratio to the given number. The change will be applied to the renderer and the composer (if used) at the end of the current frame.

    Parameters

    • val: number | "auto" | "manual"

    Returns void

domHeight

  • get domHeight(): number

    The height of the <needle-engine> element on the website

    Returns number

domWidth

  • get domWidth(): number

    The width of the <needle-engine> element on the website

    Returns number

domX

  • get domX(): number

    the X position of the <needle-engine> element on the website

    Returns number

domY

  • get domY(): number

    the Y position of the <needle-engine> element on the website

    Returns number

focusRect

  • get focusRect(): null | FocusRect

    Returns null | FocusRect

focusRectSize

  • get focusRectSize(): | null
    | { height: number; width: number; x: number; y: number }

    Returns null | { height: number; width: number; x: number; y: number }

isCreated

  • get isCreated(): boolean

    Checks if the context is fully created and ready

    Returns boolean

    true if the context is fully created and ready

isInAR

  • get isInAR(): boolean

    Shorthand for this.xrSessionMode === "immersive-ar"

    Returns boolean

    true if a webxr AR session is currently active.

isInPassThrough

  • get isInPassThrough(): boolean

    If a XR session is active and in pass through mode (immersive-ar on e.g. Quest)

    Returns boolean

    true if the XR session is in pass through mode

isInVR

  • get isInVR(): boolean

    Shorthand for this.xrSessionMode === "immersive-vr"

    Returns boolean

    true if a webxr VR session is currently active.

isInXR

  • get isInXR(): boolean

    Is a XR session currently active and presenting?

    Returns boolean

    true if the xr renderer is currently presenting

isRendering

  • get isRendering(): boolean

    Returns boolean

    true while the WebGL renderer is rendering (between onBeforeRender and onAfterRender events)

isVisibleToUser

  • get isVisibleToUser(): boolean

    Returns boolean

    true if the <needle-engine> DOM element is visible on screen (context.domElement)

mainCamera

  • get mainCamera(): Camera

    The main camera of the scene - this camera is used for rendering
    Use setCurrentCamera for updating the main camera.

    Returns Camera

  • set mainCamera(cam: null | Camera): void

    Set the main camera of the scene. If set to null the camera of the mainCameraComponent will be used - this camera is used for rendering

    Parameters

    Returns void

opaqueColorTexture

  • get opaqueColorTexture(): null | Texture

    Returns null | Texture

rendererData

resolutionScaleFactor

  • get resolutionScaleFactor(): number

    use to scale the resolution up or down of the renderer. default is 1

    Returns number

  • set resolutionScaleFactor(val: number): void

    use to scale the resolution up or down of the renderer. default is 1

    Parameters

    • val: number

    Returns void

rootSourceId

  • get rootSourceId(): undefined | string

    The source identifier(s) of the root scene(s) loaded into this context. When using <needle-engine> web component this will be the src attribute(s).

    Returns undefined | string

    The source identifier for of the root scene

version

  • get version(): string

    The needle engine version

    Returns string

xrCamera

  • get xrCamera(): undefined | WebXRArrayCamera

    Returns undefined | WebXRArrayCamera

    the current WebXR camera while the WebXRManager is active (shorthand for context.renderer.xr.getCamera())

xrFrame

xrSession

  • get xrSession(): null | XRSession

    access the raw XRSession object (shorthand for context.renderer.xr.getSession()). For more control use NeedleXRSession.active

    Returns null | XRSession

xrSessionMode

  • get xrSessionMode(): undefined | XRSessionMode

    Shorthand for this.xr?.mode. AR or VR

    Returns undefined | XRSessionMode

    the current XR session mode (immersive-vr or immersive-ar)

StaticAll

StaticCurrent

  • get Current(): Context

    The currently active context. Only set during the update loops

    Returns Context

StaticDefaultTargetFrameRate

  • get DefaultTargetFrameRate(): undefined | number

    When a new context is created this is the framerate that will be used by default

    Returns undefined | number

  • set DefaultTargetFrameRate(val: undefined | number): void

    When a new context is created this is the framerate that will be used by default

    Parameters

    • val: undefined | number

    Returns void

StaticDefaultWebGLRendererParameters

  • get DefaultWebGLRendererParameters(): WebGLRendererParameters

    The default parameters that will be used when creating a new WebGLRenderer.
    Modify in global context to change the default parameters for all new contexts.

    Returns WebGLRendererParameters

    Example

    import { Context } from "@needle-tools/engine";
    Context.DefaultWebGLRendererParameters.antialias = false;

Methods

addAfterRenderListener

addBeforeRenderListener

appendHTMLElement

clear

  • clear(): void

    Clears the context and destroys all scenes and objects in the scene.
    The ContextCleared event is called at the end.
    This is automatically called when e.g. the src attribute changes on <needle-engine>
    or when the web component is removed from the DOM

    Returns void

createNewRenderer

  • createNewRenderer(params?: WebGLRendererParameters): WebGLRenderer

    Calling this function will dispose the current renderer and create a new one which will then be assigned to the context. It can be used to create a new renderer with custom WebGLRendererParameters.
    Note: Instead you can also modify the static Context.DefaultWebGlRendererParameters before the context is created.
    Note: This method is recommended because it re-uses an potentially already existing canvas element. This is necessary to keep input event handlers from working (e.g. components like OrbitControls subscribe to input events on the canvas)

    Parameters

    • Optionalparams: WebGLRendererParameters

    Returns WebGLRenderer

    the newly created renderer

dispose

  • dispose(): void

    Dispose all allocated resources and clears the scene. This is automatically called e.g. when the <needle-engine> component is removed from the DOM.

    Returns void

onCreate

onDestroy

  • onDestroy(): void

    Returns void

    Deprecated

    use dispose()

recreate

  • recreate(): void

    This will recreate the whole needle engine context and dispose the whole scene content
    All content will be reloaded (loading times might be faster due to browser caches)
    All scripts will be recreated

    Returns void

removeAfterRenderListener

removeBeforeRenderListener

removeCamera

  • removeCamera(cam?: null | Camera): void

    Remove the camera from the mainCamera stack (if it has been set before with setCurrentCamera)

    Parameters

    Returns void

renderNow

  • renderNow(camera?: Camera): boolean

    Parameters

    Returns boolean

requestSizeUpdate

  • requestSizeUpdate(): void

    will request a renderer size update the next render call (will call updateSize the next update)

    Returns void

restartRenderLoop

  • restartRenderLoop(): boolean

    Sets the animation loop.
    Can not be done while creating the context or when disposed

    Returns boolean

setCameraFocusRect

  • setCameraFocusRect(
        rect: null | FocusRect,
        settings?: Partial<FocusRectSettings>,
    ): void

    Set a rect or dom element. The camera center will be moved to the center of the rect.
    This is useful if you have Needle Engine embedded in a HTML layout and while you want the webgl background to fill e.g. the whole screen you want to move the camera center to free space.
    For that you can simply pass in the rect or HMTL div that you want the camera to center on.

    Parameters

    • rect: null | FocusRect

      The focus rect or null to disable

    • Optionalsettings: Partial<FocusRectSettings>

      Optional settings for the focus rect. These will override the focusRectSettings property

    Returns void

setCurrentCamera

  • setCurrentCamera(cam: Camera): void

    Change the main camera

    Parameters

    Returns void

setRequireColor

  • setRequireColor(val: boolean): void

    Parameters

    • val: boolean

    Returns void

setRequireDepth

  • setRequireDepth(val: boolean): void

    Parameters

    • val: boolean

    Returns void

update

  • update(timestamp: number, frame?: null | XRFrame): void

    Performs a full update step including script callbacks, rendering (unless isManagedExternally is set to false) and post render callbacks

    Parameters

    • timestamp: number
    • Optionalframe: null | XRFrame

    Returns void

updateAspect

  • updateAspect(
        camera: PerspectiveCamera | OrthographicCamera,
        width?: number,
        height?: number,
    ): void

    Update the camera aspect ratio or orthorgraphic camera size. This is automatically called when a DOM size change is detected.

    Parameters

    • camera: PerspectiveCamera | OrthographicCamera
    • Optionalwidth: number
    • Optionalheight: number

    Returns void

updatePhysics

  • updatePhysics(steps: number): void

    Call to manually perform physics steps.
    By default the context uses the physicsSteps property to perform steps during the update loop
    If you just want to increase the accuracy of physics you can instead set the physicsSteps property to a higher value

    Parameters

    • steps: number

    Returns void

updateSize

  • updateSize(force?: boolean): void

    Update the renderer and canvas size. This is also automatically called when a DOM size change is detected.

    Parameters

    • force: boolean = false

    Returns void

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods