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

Example

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()));
  }
}

Implements

  • IContext

Constructors

constructor

Properties

alias animations assets connection domElement hash? isManagedExternally isPaused mainCameraComponent maxRenderResolution? name physics post_render_callbacks post_setup_callbacks pre_render_callbacks pre_update_callbacks pre_update_oneshot_callbacks runInBackground targetFrameRate? time xr

Accessors

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

Methods

addAfterRenderListener addBeforeRenderListener appendHTMLElement clear create createNewRenderer dispose onCreate onDestroy recreate registerCoroutineUpdate removeAfterRenderListener removeBeforeRenderListener removeCamera renderNow requestSizeUpdate restartRenderLoop setCurrentCamera setRequireColor setRequireDepth stopAllCoroutinesFrom unregisterCoroutineUpdate 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

assets

assets: AssetDatabase

Deprecated

AssetDataBase is deprecated

connection

connection: NetworkConnection

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

domElement

domElement: HTMLElement

The <needle-engine> web component

Optionalhash

hash?: string

used to append to loaded assets

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

mainCameraComponent

mainCameraComponent: undefined | Camera = undefined

The main camera component of the scene - this camera is used for rendering

OptionalmaxRenderResolution

maxRenderResolution?: Vec2

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

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)

runInBackground

runInBackground: boolean = false

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

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

currentFrameEvent

  • get currentFrameEvent(): FrameEvent

    Current event of the update cycle

    Returns FrameEvent

depthTexture

  • get depthTexture(): null | DepthTexture

    Returns null | DepthTexture

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 Needlee Engine element on the website

    Returns number

isCreated

  • get isCreated(): boolean

    Returns boolean

isInAR

  • get isInAR(): boolean

    Returns boolean

isInPassThrough

  • get isInPassThrough(): boolean

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

    Returns boolean

isInVR

  • get isInVR(): boolean

    Returns boolean

isInXR

  • get isInXR(): boolean

    Returns boolean

isRendering

  • get isRendering(): boolean

    Returns boolean

isVisibleToUser

  • get isVisibleToUser(): boolean

    returns true if the dom element is visible on screen

    Returns boolean

mainCamera

  • get mainCamera(): Camera

    The main camera of the scene - this camera is used for rendering

    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

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

    Returns undefined | XRSessionMode

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

  • addAfterRenderListener(target: Object3D, callback: OnRenderCallback): void

    use this to subscribe to onAfterRender events on threejs objects

    Parameters

    Returns void

addBeforeRenderListener

  • addBeforeRenderListener(target: Object3D, callback: OnRenderCallback): void

    use this to subscribe to onBeforeRender events on threejs objects

    Parameters

    Returns void

appendHTMLElement

clear

  • clear(): void

    Will destroy all scenes and objects in the scene

    Returns void

create

createNewRenderer

  • createNewRenderer(params?: WebGLRendererParameters): void

    calling this function will dispose the current renderer and create a new one

    Parameters

    • Optionalparams: WebGLRendererParameters

    Returns void

dispose

  • dispose(): void

    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

registerCoroutineUpdate

removeAfterRenderListener

removeBeforeRenderListener

removeCamera

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

    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

setCurrentCamera

  • setCurrentCamera(cam: Camera): void

    Parameters

    Returns void

setRequireColor

  • setRequireColor(val: boolean): void

    Parameters

    • val: boolean

    Returns void

setRequireDepth

  • setRequireDepth(val: boolean): void

    Parameters

    • val: boolean

    Returns void

stopAllCoroutinesFrom

  • stopAllCoroutinesFrom(script: IComponent): void

    Parameters

    Returns void

unregisterCoroutineUpdate

  • unregisterCoroutineUpdate(coroutine: Generator, evt: FrameEvent): void

    Parameters

    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

    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

    Parameters

    • force: boolean = false

    Returns void

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods
MMNEPVFCICPMFPCPTTAAATR