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 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): 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): 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

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): 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, callback): void

  • use this to subscribe to onAfterRender events on threejs objects

    Parameters

    Returns void

addBeforeRenderListener

  • addBeforeRenderListener(target, callback): 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?): 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

  • onCreate(opts?): Promise<boolean>

  • Parameters

    Returns Promise<boolean>

    Deprecated

    use create. This method will be removed in a future version

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

  • registerCoroutineUpdate(script, coroutine, evt): Generator<unknown, any, unknown>

  • Parameters

    Returns Generator<unknown, any, unknown>

removeAfterRenderListener

  • removeAfterRenderListener(target, callback): void

  • Parameters

    Returns void

removeBeforeRenderListener

  • removeBeforeRenderListener(target, callback): void

  • Parameters

    Returns void

removeCamera

  • removeCamera(cam?): void

  • Parameters

    Returns void

renderNow

  • renderNow(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): void

  • Parameters

    Returns void

setRequireColor

  • setRequireColor(val): void

  • Parameters

    • val: boolean

    Returns void

setRequireDepth

  • setRequireDepth(val): void

  • Parameters

    • val: boolean

    Returns void

stopAllCoroutinesFrom

  • stopAllCoroutinesFrom(script): void

  • Parameters

    Returns void

unregisterCoroutineUpdate

  • unregisterCoroutineUpdate(coroutine, evt): void

  • Parameters

    • coroutine: Generator<unknown, any, unknown>
    • evt: FrameEvent

    Returns void

update

  • update(timestamp, frame?): 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, width?, height?): void

  • Parameters

    Returns void

updatePhysics

  • updatePhysics(steps): 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?): void

  • update the renderer and canvas size

    Parameters

    • force: boolean = false

    Returns void

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods