Brighterscript Game Engine

FreeFlyCameraController

A reusable free-fly camera control scheme: yaw/pitch relative to the camera's current (roll-adjusted) orientation, forward/back drive, roll, and a ground-plane clamp so driving forward can't cross the ground. Not a GameEntity - a Room (or any owner) constructs one and forwards its own onInput/onUpdate calls to it. Extracted from examples/terrain's original FreeFlyCameraController (issue #148); that example now layers its own room-switching/debug-toggle/hint-text glue on top of this.

Properties

  • camera (BGE.Camera3d)
  • groundPlane (BGE.Math.Plane)
  • turnSpeed (float) — radians/sec
  • driveSpeed (integer) — radians/sec
  • rollSpeed (integer) — units/sec
  • pitchSpeed (float) — degrees/sec
  • maxDownwardTilt (float) — Bounds the pitch input accumulator to reduce (not eliminate) how close repeated ' pitch input can drive the camera toward Camera3d.getLevelUpVector()'s degenerate ' near-vertical case; under sustained roll+pitch combinations the actual world-space ' angle isn't strictly bounded by this alone.
  • minHeightAboveGround (float) — radians (~69 degrees)
  • lastInput (BGE.GameInput) — Protected, not private: a subclass adding its own per-frame button handling (e.g. ' examples/terrain's hold-to-toggle-debug) needs to see the same input this frame.

Constructor

new FreeFlyCameraController( camera: BGE.Camera3d, groundPlane: BGE.Math.Plane, ): FreeFlyCameraController

Binds to this specific camera instance for its lifetime - it does not re-resolve the active camera from Game/Renderer each frame like some example code does. If the consumer later calls Game.setCamera() with a different camera, this controller keeps driving the one it was built with; construct a new controller for the new camera.

Parameters

  • camera (BGE.Camera3d) — the camera to drive
  • groundPlane (BGE.Math.Plane) — the plane clampAboveGround() keeps the camera above

Instance Methods

onInput(input: BGE.GameInput): void

Forward a Room/GameEntity's own onInput() call here. Tracks roll/pitch/drive direction from the "replay"/"options" (roll), "rewind"/"fastforward" (pitch) and directional (drive/turn) buttons, and resets roll/pitch to their initial values on "play".

Parameters

Returns

  • void

update(dt: float): void

Forward a Room/GameEntity's own onUpdate() call here. Applies yaw/drive from the last onInput()'s directional input, plus any active roll/pitch, to the camera.

Parameters

  • dt (float) — seconds since the last frame

Returns

  • void

setInitialPitch(radians: float): void

Sets the controller's starting pitch (radians, same sign convention as the internal pitch accumulator) and resets the camera to face straight down -z before applying it - both an initial setup call and the "play" button's reset use this, so the internal accumulator and the actually-applied rotation never drift apart the way they would if a caller rotated camera.orientation directly without seeding the accumulator to match (the pitch clamp would then only bound input on top of an untracked offset, and "play" would reset to level instead of back to this default).

Parameters

  • radians (float)

Returns

  • void

clampAboveGround(candidate: BGE.Math.Vector): BGE.Math.Vector

Pushes a candidate camera position back above the ground plane by at least minHeightAboveGround, along the plane's own normal - keeps the camera from flying through the ground regardless of the plane's orientation.

Parameters

  • candidate (BGE.Math.Vector)

Returns

  • BGE.Math.Vector