Skip to main content

Cinematic

This item only works when running on the client. Client

Flies the camera over one or more points of interest and puts it back where it was.

Camera state is captured when the tour starts and restored whether the tour finished or was interrupted, which is what keeps a player from being stranded in a scriptable camera when a step ends early. 

Step.new(1, {
	Cinematic.focus(castleGate, { Hold = 3, Advance = true }),
})

Types​

CinematicOptions​

</>
interface CinematicOptions {
Hold: number?--

Seconds to linger on each stop

Distance: number?--

How far back the camera sits

Height: number?--

How far above the target it sits

Finished: ((context: ActionContext) → ())?--

Runs when the tour ends

Advance: boolean?--

Move to the next step when the tour ends

}

Framing for the tour, plus what happens when it ends.

Finished and Advance fire on the tour ending, which includes being cut short, so a player who leaves the step is never left waiting on a callback that will not come.

Functions​

focus​

constructor
</>
Cinematic.focus(
target: BasePart,--

What to look at

options: CinematicOptions?--

Framing and what happens after

) → Action

Flies the camera to one point of interest and back.

The most common opening for a tutorial: show the player where they are before asking them to do anything. 

Step.new(1, {
	Cinematic.focus(spawnStatue, {
		Hold = 2.5,
		Distance = 40,
		Height = 12,
		Advance = true,
	}),
})

tour​

constructor
</>
Cinematic.tour(
stops: {TourStop},--

Points of interest, visited in order

options: CinematicOptions?--

Defaults for stops that omit their own

) → Action

Flies the camera over several points in order.

Each stop can override the shared framing, so one landmark can sit closer than the rest:

Cinematic.tour({
	{ Target = shopModel.PrimaryPart, Hold = 2 },
	{ Target = arenaGate, Hold = 3, Distance = 60 },
	{ Target = questBoard },
}, {
	Distance = 35,
	Advance = true,
})
TIP

If a stop's target is destroyed mid-tour the tour stops there and the camera is restored, rather than the player being stuck watching nothing.

Show raw api
{
    "functions": [
        {
            "name": "focus",
            "desc": "Flies the camera to one point of interest and back.\n\nThe most common opening for a tutorial: show the player where they are before asking them to do\nanything.\n\n```lua\nStep.new(1, {\n\tCinematic.focus(spawnStatue, {\n\t\tHold = 2.5,\n\t\tDistance = 40,\n\t\tHeight = 12,\n\t\tAdvance = true,\n\t}),\n})\n```",
            "params": [
                {
                    "name": "target",
                    "desc": "What to look at",
                    "lua_type": "BasePart"
                },
                {
                    "name": "options",
                    "desc": "Framing and what happens after",
                    "lua_type": "CinematicOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Action"
                }
            ],
            "function_type": "static",
            "tags": [
                "constructor"
            ],
            "source": {
                "line": 90,
                "path": "src/Actions/Cinematic.luau"
            }
        },
        {
            "name": "tour",
            "desc": "Flies the camera over several points in order.\n\nEach stop can override the shared framing, so one landmark can sit closer than the rest:\n\n```lua\nCinematic.tour({\n\t{ Target = shopModel.PrimaryPart, Hold = 2 },\n\t{ Target = arenaGate, Hold = 3, Distance = 60 },\n\t{ Target = questBoard },\n}, {\n\tDistance = 35,\n\tAdvance = true,\n})\n```\n\n:::tip\nIf a stop's target is destroyed mid-tour the tour stops there and the camera is restored, rather\nthan the player being stuck watching nothing.\n:::",
            "params": [
                {
                    "name": "stops",
                    "desc": "Points of interest, visited in order",
                    "lua_type": "{TourStop}"
                },
                {
                    "name": "options",
                    "desc": "Defaults for stops that omit their own",
                    "lua_type": "CinematicOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Action"
                }
            ],
            "function_type": "static",
            "tags": [
                "constructor"
            ],
            "source": {
                "line": 118,
                "path": "src/Actions/Cinematic.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "CinematicOptions",
            "desc": "Framing for the tour, plus what happens when it ends.\n\n`Finished` and `Advance` fire on the tour *ending*, which includes being cut short, so a player\nwho leaves the step is never left waiting on a callback that will not come.",
            "fields": [
                {
                    "name": "Hold",
                    "lua_type": "number?",
                    "desc": "Seconds to linger on each stop"
                },
                {
                    "name": "Distance",
                    "lua_type": "number?",
                    "desc": "How far back the camera sits"
                },
                {
                    "name": "Height",
                    "lua_type": "number?",
                    "desc": "How far above the target it sits"
                },
                {
                    "name": "Finished",
                    "lua_type": "((context: ActionContext) -> ())?",
                    "desc": "Runs when the tour ends"
                },
                {
                    "name": "Advance",
                    "lua_type": "boolean?",
                    "desc": "Move to the next step when the tour ends"
                }
            ],
            "source": {
                "line": 39,
                "path": "src/Actions/Cinematic.luau"
            }
        }
    ],
    "name": "Cinematic",
    "desc": "Flies the camera over one or more points of interest and puts it back where it was.\n\nCamera state is captured when the tour starts and restored whether the tour finished or was\ninterrupted, which is what keeps a player from being stranded in a scriptable camera when a step\nends early.\n\n```lua\nStep.new(1, {\n\tCinematic.focus(castleGate, { Hold = 3, Advance = true }),\n})\n```",
    "realm": [
        "Client"
    ],
    "source": {
        "line": 18,
        "path": "src/Actions/Cinematic.luau"
    }
}