Triggering Cinematic Flyby Camera Sequences in RollingQuest

A flyby is a cinematic camera move where the view temporarily leaves the player and travels to a specific location in the level. During a flyby, player control is paused — the ball sits still while the camera does its work. Use flybys to point out the exit, reveal a secret area, or add dramatic flair to a story moment.

The Two Ways to Start a Flyby

The Flyby namespace exposes two functions:

Function	Use when…
`Flyby.startZoomAt(...)`	You want a simple zoom-to-a-block-and-return in one call
`Flyby.start(events)`	You want full control over a multi-step sequence

`Flyby.startZoomAt` — Simple Zoom to a Block

startZoomAt is the quickest way to show the player a specific block. You give it a location, how the camera should face that block, and three durations.

Signatures

--- Zoom to a BlockSlot
function Flyby.startZoomAt(
    slot: BlockSlot,
    face: Face,
    orientation: Orientation,
    look: CameraLookPosition,
    goingDuration: number,
    waitDuration: number,
    returnDuration: number
): any

--- Zoom to raw grid coordinates
function Flyby.startZoomAt(
    x: integer,
    y: integer,
    z: integer,
    face: Face,
    orientation: Orientation,
    look: CameraLookPosition,
    goingDuration: number,
    waitDuration: number,
    returnDuration: number
): any

Parameters Explained

slot / x, y, z — The target block’s position. BlockSlot is an object with integer x, y, z fields; you can also construct one with BlockSlot.new(x, y, z). face: Face — Which face of the block the camera looks at. Combines with orientation to determine the exact camera angle.

Value	Meaning
`Face.Up`	Look at the top face
`Face.Down`	Look at the bottom face
`Face.Left`	Look at the left face
`Face.Right`	Look at the right face
`Face.Front`	Look at the front face
`Face.Back`	Look at the back face

orientation: Orientation — The compass rotation of the camera view when looking at the chosen face.

Value	Meaning
`Orientation.North`	0° (default)
`Orientation.East`	90° clockwise
`Orientation.South`	180°
`Orientation.West`	270° clockwise

look: CameraLookPosition — Vertical tilt of the camera.

Value	Meaning
`CameraLookPosition.Center`	Level view
`CameraLookPosition.Up`	Tilted upward
`CameraLookPosition.Down`	Tilted downward

goingDuration — Seconds the camera takes to travel to the target. waitDuration — Seconds the camera holds at the target before returning. returnDuration — Seconds the camera takes to travel back to the ball.

`Flyby.start` — Full Custom Sequence

For multi-stop sequences, build an array of FlybyEvent objects and pass them to Flyby.start.

--- @param events FlybyEvent[]
function Flyby.start(events): any

`FlybyEvent` Static Constructors

Method	Description
`FlybyEvent.moveTo(slot, face, orientation, look, duration)`	Move to a block slot
`FlybyEvent.moveTo(x, y, z, face, orientation, look, duration)`	Move to raw coordinates
`FlybyEvent.moveToBall(look, duration)`	Move back to the ball
`FlybyEvent.rawMoveTo(position, rotation, look, duration)`	Move to a world-space `Vector3` + `Quaternion`
`FlybyEvent.wait(duration)`	Hold the camera in place
`FlybyEvent.message(message)`	Display an overlay message
`FlybyEvent.message(message, backgroundColor)`	Display a colored overlay message
`FlybyEvent.script(closure)`	Run an arbitrary Lua function mid-sequence

Each factory returns a FlybyEvent you insert into the events array passed to Flyby.start.

`FlybyEvent` Properties

FlybyEvent.type       -- integer: the type identifier of the event (read-only)
FlybyEvent.isFinished -- boolean: true once this event has completed (read-only)

Example 1 — Show the Exit on Level Start

Attach this script to the Level entity. When the level starts, the camera zooms to the exit block (assumed to be at grid position 8, 0, 8), waits for 2 seconds so the player can see it, then returns. A closeable dialog prompt replaces the standard UI until the player dismisses it.

-- Level script

-- Coordinates of the exit block in the level grid
local EXIT_X = 8
local EXIT_Y = 0
local EXIT_Z = 8

function OnStart(self)
    -- Zoom to the exit: 1.2s travel, 2s hold, 1s return
    Flyby.startZoomAt(
        EXIT_X, EXIT_Y, EXIT_Z,
        Face.Up,
        Orientation.North,
        CameraLookPosition.Center,
        1.2,  -- goingDuration
        2.0,  -- waitDuration
        1.0   -- returnDuration
    )

    -- After the flyby finishes (1.2 + 2.0 + 1.0 = 4.2s), show instructions
    Level.delayAction(4.2, function()
        Dialog.createCloseable(
            "That's your exit! Collect all the keys to unlock it.",
            Color.new(0.05, 0.05, 0.25, 0.9)
        )
    end)
end

Level.delayAction does not pause the flyby — both run concurrently. Calculate the total flyby duration (goingDuration + waitDuration + returnDuration) and use that as your delay so the dialog appears only after the camera has fully returned.

Example 2 — Multi-Stop Cinematic Intro

This example builds a three-stop sequence: the camera starts at the key pickup area, moves to the exit, shows a message, then returns to the ball.

function OnStart(self)
    local titleColor = Color.new(0.0, 0.1, 0.3, 0.88)

    Flyby.start({
        -- Step 1: move to the key cluster (2 seconds travel, 1.5s hold)
        FlybyEvent.moveTo(
            BlockSlot.new(2, 0, 4),
            Face.Up,
            Orientation.North,
            CameraLookPosition.Center,
            2.0
        ),
        FlybyEvent.wait(1.5),

        -- Step 2: display a hint while holding at the keys
        FlybyEvent.message("Grab the keys here!", titleColor),
        FlybyEvent.wait(1.5),

        -- Step 3: sweep to the exit block
        FlybyEvent.moveTo(
            BlockSlot.new(8, 0, 8),
            Face.Up,
            Orientation.South,
            CameraLookPosition.Down,
            2.0
        ),
        FlybyEvent.wait(1.0),

        -- Step 4: show where to go
        FlybyEvent.message("Then reach this exit!", titleColor),
        FlybyEvent.wait(1.5),

        -- Step 5: return to the ball
        FlybyEvent.moveToBall(CameraLookPosition.Center, 1.5),

        -- Step 6: run a Lua callback once back at the ball
        FlybyEvent.script(function()
            Dialog.createCloseable(
                "Good luck!",
                Color.new(0.05, 0.25, 0.05, 0.9)
            )
        end),
    })
end

Use FlybyEvent.script at the end of a sequence to trigger dialogs, unlock doors, or award items exactly when the camera finishes — no need to manually time a Level.delayAction call.

Key Things to Remember

Player control is suspended for the entire duration of a flyby. Do not start a flyby in response to time-critical events (for example, immediately when the ball is near a hazard) unless you intentionally want to pause the action.

BlockSlot is the grid coordinate type used by Flyby.startZoomAt and FlybyEvent.moveTo. Create one with BlockSlot.new(x, y, z) or read it from any entity’s .blockSlot property (for example, Level.currentBall.blockSlot).
Face and Orientation together control the exact camera angle. Experiment with Face.Up + Orientation.North as a starting point — it gives a top-down bird’s-eye view.
CameraLookPosition adds a vertical tilt: Down is useful for showing something on the floor of the block, Up for something on the ceiling.

Get Started

Core Concepts

Recipes

Triggering Cinematic Flyby Camera Sequences in RollingQuest

The Two Ways to Start a Flyby

`Flyby.startZoomAt` — Simple Zoom to a Block

Signatures

Parameters Explained

`Flyby.start` — Full Custom Sequence

`FlybyEvent` Static Constructors

`FlybyEvent` Properties

Example 1 — Show the Exit on Level Start

Example 2 — Multi-Stop Cinematic Intro

Key Things to Remember

​The Two Ways to Start a Flyby

​Flyby.startZoomAt — Simple Zoom to a Block

​Signatures

​Parameters Explained

​Flyby.start — Full Custom Sequence

​FlybyEvent Static Constructors

​FlybyEvent Properties

​Example 1 — Show the Exit on Level Start

​Example 2 — Multi-Stop Cinematic Intro

​Key Things to Remember

The Two Ways to Start a Flyby

`Flyby.startZoomAt` — Simple Zoom to a Block

Signatures

Parameters Explained

`Flyby.start` — Full Custom Sequence

`FlybyEvent` Static Constructors

`FlybyEvent` Properties

Example 1 — Show the Exit on Level Start

Example 2 — Multi-Stop Cinematic Intro

Key Things to Remember