tecs.gfx.flycamera3d

A free-fly controller turns mouse and keyboard input into a 3D camera pose.

The controller is deliberately a camera tool rather than a character controller. It has no gravity or collision, so render showcases and editor views can move through large scenes without creating physics geometry. Click the left mouse button to enter relative mouse mode, press Tab to release it, and call update from a frame-phase system:

const controller = tecs.gfx.flycamera3d.new(
    app.input, app.window, camera,
    {moveSpeed = 5, sprintMultiplier = 4}
)

world:addSystem({
    name = "game.FlyCamera",
    phase = tecs.ecs.phases.Update,
    run = function(dt: number)
        controller:update(dt)
    end,
})

WASD moves along the view, Q and E move down and up in world space, and Shift multiplies the speed. The constructor caches physical scancodes, and update allocates nothing.

Module contents

Constructors

ConstructorDescription
new

Types

TypeKindDescription
ControllerrecordControls one perspective camera with relative mouse and keyboard input.
OptionstypeDefines optional free-fly camera behavior.

Constructors#

newconstructor#

function new(source: input.Input, target: window.Window, camera: Camera3D, options: Options?): Controller

Arguments

NameTypeDescription
sourceinput.Input
targetwindow.Window
cameraCamera3D
optionsOptions?

Returns

TypeDescription
Controller

Types#

Controllerrecord#

record Controller
    camera: Camera3D
    moveSpeed: number
    sprintMultiplier: number
    lookSensitivity: number
    maxPitch: number
    yaw: number
    pitch: number
    captured: boolean
    setCaptured: function(exclusive self: Controller, captured: boolean): boolean
    update: function(exclusive self: Controller, dt: number): nil
end

Controls one perspective camera with relative mouse and keyboard input.

Methods

setCaptured#
setCaptured: function(exclusive self: Controller, captured: boolean): boolean

Requests or releases relative mouse mode.

Arguments
NameTypeDescription
exclusive selfController
capturedboolean

The caller passes true to hide and capture the pointer or false to release it.

Returns
TypeDescription
boolean

Returns whether the platform reached the requested state.

update#
update: function(exclusive self: Controller, dt: number): nil

Applies this frame's input to the camera.

A left click captures the pointer and returns without consuming the absolute motion that produced that click. Tab releases it. While captured, WASD moves along the view, Q and E move vertically, Shift sprints, and relative mouse motion changes yaw and pitch.

Arguments
NameTypeDescription
exclusive selfController
dtnumber

The caller supplies a non-negative frame duration in seconds.

Returns
TypeDescription
nil

Fields

camera#
camera: Camera3D

Read-only. Refers to the camera whose pose update changes.

moveSpeed#
moveSpeed: number

Caller-writable. Sets ordinary movement speed in world units per second.

sprintMultiplier#
sprintMultiplier: number

Caller-writable. Multiplies movement speed while Shift is held.

lookSensitivity#
lookSensitivity: number

Caller-writable. Sets radians of rotation per mouse-motion unit.

maxPitch#
maxPitch: number

Caller-writable. Limits absolute pitch in radians below pi divided by two.

yaw#
yaw: number

Read-only. Reports the current left-right heading in radians.

pitch#
pitch: number

Read-only. Reports the current up-down angle in radians.

captured#
captured: boolean

Read-only. Reports whether this controller currently owns relative mouse input.

Optionstype#

type Options = {
    --- Caller-writable. Sets ordinary movement speed in world units per second
    --- and defaults to 5.
    moveSpeed: number?,

    --- Caller-writable. Multiplies movement speed while Shift is held and
    --- defaults to 4.
    sprintMultiplier: number?,

    --- Caller-writable. Sets radians of rotation per mouse-motion unit and
    --- defaults to 0.0025.
    lookSensitivity: number?,

    --- Caller-writable. Limits absolute pitch in radians and defaults to 89
    --- degrees.
    maxPitch: number?
}

Defines optional free-fly camera behavior.