FreeNavigation

Extends: Control

Source: FreeNavigation.ts:152

Free-flight camera navigation.

• W/S — move forward/backward
• A/D — strafe left/right
• Space/Ctrl — increase/decrease altitude
• Shift — hold to move without changing the camera height above the ellipsoid
• Q/E — roll
• Mouse — look around
• Mouse wheel — adjust movement speed
• Right mouse button — hold to keep the point under the screen center in the center
• F — activate and deactivate the control, see toggleKey

Yaw follows the local ellipsoid normal, while pitch uses the camera's right vector. The camera preserves its orientation relative to the local horizon while moving.

By default, pointer lock allows unrestricted mouse rotation. Pressing Escape releases the pointer and deactivates the control. Set pointerLock to false to use regular mouse movement instead.

The control conflicts with the Navigation control, so an active Navigation is deactivated while the free navigation is active, and restored back on deactivation.

Fires

• event:move
• event:rotate
• event:speedchange
• event:activate
• event:deactivate

Constructor

Parameters

• options (IFreeNavigationParams, optional) — Free navigation options:
  • options.speed (number, optional) — Initial selected movement speed in m/s. Default is 0
  • options.minSpeed (number, optional) — Minimal selected movement speed in m/s. Default is -300
  • options.maxSpeed (number, optional) — Maximal selected movement speed in m/s. Default is 1000000
  • options.speedStep (number, optional) — Mouse wheel speed step near the zero speed in m/s. Default is 1
  • options.speedFactor (number, optional) — Relative speed increment per one mouse wheel step. Default is 0.45
  • options.lookSensitivity (number, optional) — Camera rotation angle in radians per mouse move pixel
  • options.rollSpeed (number, optional) — Q/E roll angular speed in radians per second the smoothed roll velocity approaches
  • options.accelerationTime (number, optional) — Acceleration smoothing time in seconds. Default is 0.6
  • options.decelerationTime (number, optional) — Deceleration smoothing time in seconds. Default is 0.4
  • options.pitchLimit (number, optional) — Maximal pitch angle above and below the local horizon in radians
  • options.invertY (boolean, optional) — Inverts vertical mouse rotation direction. Default is false
  • options.pointerLock (boolean, optional) — Locks and hides the mouse pointer. Default is true
  • options.toggleKey (number, optional) — Key code which activates and deactivates the control, it works while the control is inactive as well. Zero disables it. Default is input.KEY_F
  • options.showInfo (boolean, optional) — Shows the movement speed and the key hint. Default is false

Instance Methods

toggle()

Activates the control when it is inactive and deactivates it otherwise.

setSpeed(speed: number)

Sets selected movement speed in meters per second, clamped to the min and max speed.

Parameters

• speed (number) — Speed in m/s.

stepSpeed(steps: number)

Changes the movement speed by the given number of wheel steps.

The speed step increases with the current speed. Changes are reversible, and zero speed is always reachable.

Parameters

• steps (number) — Number of the wheel steps, negative decreases the speed.

isPointerLocked(): boolean

True when the mouse pointer is locked by the control.

Returns

• boolean

requestPointerLock()

Locks and hides the mouse pointer over the canvas.

exitPointerLock()

Releases the mouse pointer.

lockTarget(point?: Vec3)

Locks the target point, so the camera keeps looking at it wherever it moves,

Parameters

• point (Vec3, optional) — Target point in the cartesian coordinates.

unlockTarget()

Releases the locked target point.

stop()

Stops the camera movement and releases the locked target point.

_limitPitch( angle: number, forward: Vec3, right: Vec3, localUp: Vec3, ): number

Clamps the pitch rotation angle.

Parameters

• angle (number) — Pitch angle in radians.
• forward (Vec3) — Camera forward vector.
• right (Vec3) — Camera right vector.
• localUp (Vec3) — Local reference frame up direction.

Returns

• number

_handleRoll()

Rollls the camera around its forward axis and keeps its angular velocity smoothed.

_handleMove()

Moves the camera and keeps its orientation in the local reference frame.

oninit()

Inherited from Control#oninit

Overrides: Control#oninit

Control initialization function have to be overridden.

onadd()

Inherited from Control#onadd

Overrides: Control#onadd

Control renderer assigning function have to be overridden.

onremove()

Inherited from Control#onremove

Overrides: Control#onremove

Control remove function have to be overridden.

onactivate()

Inherited from Control#onactivate

Overrides: Control#onactivate

Control activation function have to be overridden.

ondeactivate()

Inherited from Control#ondeactivate

Overrides: Control#ondeactivate

Control deactivation function have to be overriden.

addTo()

Inherited from Control#addTo

Overrides: Control#addTo

Assign renderer to the control.

remove()

Inherited from Control#remove

Overrides: Control#remove

Removes control.

activate()

Inherited from Control#activate

Overrides: Control#activate

Activate control.

deactivate()

Inherited from Control#deactivate

Overrides: Control#deactivate

Deactivate control.

isActive()

Inherited from Control#isActive

Overrides: Control#isActive

Is control active.

Instance Fields

speed

Returns selected movement speed in meters per second.

Returns

• number

speed

Sets selected movement speed in meters per second.

Parameters

• speed (number) — Speed in m/s.

targetPoint

Locked target point in the cartesian coordinates, or null when no target is locked.

Returns

• Vec3 | null

name

Inherited from Control#name

Overrides: Control#name

Returns control name.

Returns

• string