Log inGet started
World

Film Rig Workshop: Cinematic Camera Moves, Lenses, Titles & Transitions

README.md

filmRig

A film-making kit for Zero: make a cinematic film, intro or trailer of your world with one table. filmRig gives you 24 camera moves (crane, dolly, orbit, spline path, flyover, top-down reveal, spiral climb, rack focus, dolly zoom, handheld and more), 16 transitions between shots (dissolve, blur dissolve, true wipes, iris, fades, blinds), 8 title card styles (brush calligraphy, Japanese vertical text, clean modern, lower third, chapter title, scrolling end credits, caption, typewriter), frame shapes (2.39:1 cinemascope, 1.85, 16:9 HD, 4:3, vertical, a soft vignette) that stay correct on any screen, six real lenses by focal length (18 mm wide to 135 mm telephoto and a macro) with true field of view and depth of field, six photographic looks (vignette, grain, bloom, flare, colour grade), timed events your world reacts to, and what happens after the film (free-fly camera, slow orbit, loop, or back to the player) with a Replay button. To use it, install filmRig from ZeroMind (search "filmRig make a trailer", or zero zeromind installAsset e561f721-e789-4fd9-92f3-46600025e6a3), write your shots in one Film.cutscene({ ... }) table, put a filmRig.FilmDirector on an entity in your scene and press play (see "Make a film in three steps").

It is built on the engine's own cutscene system, so it inherits everything that gives: skip on keyboard, gamepad and touch, cues that still fire when the viewer skips, the player held still during the film, and local playback per player. Every visitor watches their own copy from the start when they arrive; nothing is replicated and nobody's camera touches anyone else's.

Install

Search ZeroMind for filmRig and install it (zero zeromind installAsset <guid> in the engine shell, or the install button). It has no dependencies (1.0.21 draws its fades, iris, blinds, pixelate and panel wipes itself, on the film clock).

Make a film in three steps

In a brand-new world, film the scene it already opens on: its starter scene scenes.main (/source/scenes/main.scene, the startup_scene in /source/.world_settings); zero scene list shows it. Put your landmarks and the FilmDirector line (step 2) in its build.luau. Only if the world has no scene under /source at all, make one at that same name, asset.create("scene", "main", { folder = "scenes" }), and open it now with zero scene load scenes.main (the startup scene is only read when the world loads, so until then pressing play shows an empty world). Do not make a second scene called plain main: two scenes named main make zero scene load main refuse as ambiguous. Give the things you want to film entity names (Tower, Arch, Fountain...) so shots can aim at them.

  1. Write a film module at /source/film/trailer.module/init.luau (its name is film.trailer):
local Film = require("filmRig.Film")

return Film.cutscene({
    frame = "scope",          -- cinemascope bars
    lens = "portrait50",      -- a real 50 mm lens: field of view and depth of field
    look = "goldenHour",      -- whole photographic look
    after = "freeFly",        -- what the visitor gets afterwards
    hidePlayer = true,        -- keep the visitor's own avatar out of the shots
    shots = {
        { move = "craneRise", dur = 8, from = { 0, 1.2, 46 }, target = "Tower" },
        { move = "followPath", dur = 7, points = { { -1, 1.6, 36 }, { 0, 1.8, 26 }, { 1, 2, 16 } }, target = "Tower", transition = "dissolve" },
        { move = "orbit", dur = 8, target = "Fountain", distance = 22, height = 6, degrees = 70, transition = "wipeLeft" },
    },
    titles = {
        { t = 1, dur = 6, style = "modern", text = "MY WORLD", sub = "A short film" },
        { t = 17, dur = 6, style = "credits", text = "My World", lines = { "Made with", { "Camera", "filmRig" } } },
    },
    events = { { t = 12, event = "lightsOn" } },
})
  1. Play it for everyone who arrives: put a FilmDirector on an entity the scene builds. In the scene's build.luau, inside content():
entity.spawn("Director").component.add("filmRig.FilmDirector", { film = "film.trailer" })

(A FilmDirector added by hand in the editor works too, but one written in build.luau is part of the scene's source and comes back on every load.)

  1. Press play. The film starts by itself for each visitor, on their own screen.

From your own code instead: require("filmRig.Film").play("film.trailer") or Film.play({ ...definition... }). React to events with Film.on("lightsOn", function(data, playback) ... end). The guides inside the package walk through two whole examples (a 30-second garden trailer, and a level flythrough that hands the camera to the player) and the full workflow: search "make a trailer of my world" or "level flythrough of my game level".

The one-change swaps

Everything is picked by a string. Change one word and the film changes:

wantchange
a different camera movethe shot's move
a different transition into a shotthe shot's transition (and transitionDur, transitionDir, transitionColor)
a different title lookthe card's style
a different frame shapeframe
a different real lens (focal length, field of view, depth of field)lens (film-wide) or a shot's own lens
a different photographic looklook
something else after the filmafter (or FilmDirector's after field)
lighter renderingquality = "low" (or "auto")

The film definition

keydefaultwhat it does
shotsnonethe camera moves, in order (table below)
titlesnonetitle cards: { t, dur, style, text, sub, ... }
eventsnone{ t, event, data? }: calls Film.on(event, fn) handlers, also when skipped
framescopeframe shape (table below) or an aspect number
lensthe look's owna real lens (wide18, standard35, portrait50, tele85, long135, macro) or a focal length in mm. The old spelling lens = "anamorphic" (a look name) still works and means look = "anamorphic"
lookcleanphotographic look (table below), or a table { base = "noir", grain = 0.08, ... }
qualityautoauto (low in the browser, on Android and small screens), high, low
afterhandToPlayerfreeFly, orbit, loop, handToPlayer, none
afterOptionsnone{ eye, at, fov, center, distance, speed, hint } for freeFly / orbit: eye/at set where the free camera starts and what it looks at (default: the last shot's final pose)
afterSkiphandToPlayerfor after = "loop": what a skip leads to
replayButtontrueshow the small "Replay film" button afterwards
transitioncutdefault transition for shots that name none
musicnonea soundClip asset (asset.resolve("theme", "soundClip")), played locally
musicVolume0.8
fadeIn / fadeOut1.5seconds of fade from / to fadeColor at the ends
subtitles, cues, skippable, skipLabel, freezePlayer, hidePlayer, renderLayers, onStart, onFinishpassed to the engine's cutscene
frameOpen, barColor1.6, blackbar slide-in seconds and colour

Shot keys

keywhat it does
movethe camera move (table below)
durseconds
targetwhat the camera looks at: { x, y, z } or an entity name
fromwhere the camera starts; default is distance from the target at height, compass angle
towhere it ends, for moves that travel (dolly, truck, craneRise, whipPan's second target)
distance, height, angleplace the camera around the target when from is not given
amounthow far the move goes (metres)
degreesorbit / arc angle
pointspath points for followPath / flyover; lookPoints for a separate aim path
fov, fovTolens field of view in degrees at start / end (overrides the lens)
lensthis shot's own real lens (tele85, macro, ...): its field of view and depth of field for this shot only
easeany cutscene easing name (inOutSine, inOutCubic, outExpo, ...)
shakehandheld noise strength (metres), on any move
focusFrom, focusrack focus from one point / entity to another (lens with depth of field)
trackwith an entity target, aim follows it live
transition, transitionDur, transitionDir, transitionColorhow this shot is entered

Moves

movewhat it does
static / lockofflocked-off camera
dolly / dollyOuttravel along the line of sight toward / away from the target
pushInslow dolly in with the lens tightening: tension
pullBackslow dolly out and up, lens widening
revealbig pull back and rise that reveals the place
truck / driftslide sideways (drift is small and slow)
craneRise / craneDownrise while tilting down to keep the target framed / descend onto it
tiltReveal / tiltDowncamera stays; aim tilts up from the ground / down from the sky to the target
orbitcircle the target by degrees
arcpartial orbit that closes in a little
followPathsmooth Catmull-Rom spline through points at constant speed
flyoverhigh pass over points or over the target, aimed ahead and down
whipPanaim whips from target to to in a blink
focusPullnear-static frame while the focus racks from focusFrom to the target
handheldsubtle noisy shake on a slow drift (shake sets strength)
dollyZoomvertigo: dolly in while the lens widens so the target holds its size
zoomlens zoom from fov to fovTo
topDowntop-down reveal: starts looking straight down from altitude above the target, then tilts and descends into a three-quarter view (distance, height, angle or to); degrees adds a turn on the way down
spiralClimbspirals up around the target's vertical axis (a tower, a stair) by degrees (default 360) at distance, rising rise metres from height, aimed a little above the camera up the axis

Transitions

transitionwhat it does
cuthard cut
fade / fadeWhite / dipToColorfade through black / white / transitionColor
flashquick white flash
dissolvecrossfade; the outgoing shot keeps moving while it melts away
blurDissolvedreamy crossfade: the outgoing shot blurs out of focus as it fades and the new shot blurs back into focus
wipe, wipeLeft, wipeRight, wipeUp, wipeDownthe new shot is revealed behind a soft moving edge
irisclosing circle and open again
blindsslats sweep shut and open (transitionDir)
pixelateblocks pop in and out
panelWipea glowing sci-fi panel slides across (transitionDir)

Every transition runs on the film's own clock, frame by frame: the screen is fully covered exactly at the cut whatever the frame rate, a paused film holds the transition still, and a frame-by-frame recording shows the same transition a live viewer sees (no black frames, no old shot coming back before the cut). The cutscene definition also carries viewTiming (per shot: when its transition starts, how long it lasts, whether the outgoing shot stays on screen), which kits such as lanternStair read to keep the outgoing shot lit and the next shot's scenery ready before its first frame.

Title styles

stylelookmain keys
brushpainted sumi ink stroke sweeps in behind a large, wide-tracked serif title; red seal stamptext, sub, seal (a character, or false)
verticalJapanese vertical writing, characters fall top to bottom, columns right to lefttext (\n = new column), sub, position (right/left/center), seal
modernwide-tracked capitals between fine rulestext, sub
lowerThirdname and role at lower left with a gold bartext, sub, accent
chapterspaced kicker, a fine rule, italic serif titlekicker, text
creditsscrolling end-credits rolltext (heading), lines (strings = section headings, "" = gap, { role, name } pairs)
captionquiet italic line low in the picture on a soft dark backing, readable over bright skies and dark scenes aliketext, y, backing (false to drop it)
typewritermonospaced characters land one by one behind a blinking carettext (\n = new line), cps (characters a second), typeDelay, align (center/left), y, backing

Every card also takes t, dur, size, font, color, y, fadeIn, fadeOut. Cards sit inside the picture, never under the bars, and scale with it. Small text (captions, subtitles, kickers, credits, lower thirds) carries a tight dark shadow under each glyph, and captions, lower thirds and typewriter lines sit on a soft dark backing, so light text stays legible on any background.

Frames

frameaspect
scope2.39:1 cinemascope
flat1.85:1
univisium2:1
widescreen169 / hd16:9 HD: no bars on a 16:9 screen, pillar- or letterboxed on any other
tv / nonethe full screen, no bars
academy4:3, pillarboxed on wide screens
square1:1
vertical9:16 phone video
softVignetteno bars: a soft, rounded dark vignette mask over the whole picture

Bars are sized from the real screen every time it changes (window resize, phone rotation), so the picture is the true aspect on a 16:9 monitor, a 4:3 tablet or an upright phone.

Lenses (real focal lengths)

Each lens is a focal length on a 35 mm full-frame camera. It sets the vertical field of view as 2 x atan(12 / f) and a matching depth of field; focus follows each shot's target.

lensfield of viewfocus
wide1818 mm, 67°f/11: deep focus, everything sharp
standard3535 mm, 38°f/5.6: natural, mostly sharp
portrait5050 mm, 27°f/2: subject sharp, background soft
tele8585 mm, 16°f/1.8: shallow, creamy background
long135135 mm, 10°f/2.8: very shallow, compressed distance
macro100 mm macro, 14°f/2.8 focusing to 15 cm: a paper-thin plane of focus for small things

Put one on the whole film (lens = "portrait50") or on one shot ({ move = "pushIn", lens = "tele85", ... }). A shot's fov still overrides the field of view. Lens.registerLens(name, { focal, fStop, maxBlur?, minFocus? }) adds your own.

Looks

lookwhat it does
cleanneutral, light vignette and bloom (45° when no lens is named)
anamorphic38° lens, shallow focus, horizontal flare streaks, slight aberration, cool grade
vintage16mmheavy vignette, coarse grain, warm faded colour
dreamywide, very shallow focus, strong soft bloom, low contrast
noirblack and white, high contrast, grain
goldenHourwarm grade, bloom and flare

Quality low (and auto in the browser, on Android or small screens) drops depth of field, chromatic aberration and lens flare and lightens grain and bloom. Focus follows each shot's target automatically.

After the film

afterwhat the visitor gets
freeFlya fly camera: WASD / left stick / on-screen stick to move, right-drag / right stick / right-thumb drag to look, E·Space / Q·Ctrl (triggers, on-screen buttons) up and down, scroll / shoulders / pinch for speed
orbitslow automatic orbit around the last target (or afterOptions.center); drag to look, scroll or pinch to zoom
loopthe film plays again
handToPlayerthe scene's own player camera comes back
noneas handToPlayer, without the Replay button

Workflow

filmRig ships a runnable workflow, makeAFilm, that makes the film with you in nine stages, one agent's job per stage: shot list (landmarks and entity names), the film module (film/trailer.module, moves and lenses), transitions and titles, timed events, look, frame and music, FilmDirector in the scene's build.luau (a brand-new world gets a scene and startup_scene first), shot review (play, cutscene seek and pause, capture from the main camera), after-film mode and a multiplayer check, and a frame-by-frame recording put on the world page. Each stage says what to produce and how to check it before it answers. Start it in the engine shell:

zero workflow start --name makeAFilm --args '{"subject":"a 40-second golden-hour trailer of my harbour town","seconds":40}'
zero workflow next --runner <you>                       # take the stage that is waiting
zero workflow answer --request <id> --value '<json>'    # hand back what the stage asked for
zero workflow status                                    # which stage the run is in

Args (all optional): subject (what the film is of), film (module name, default film.trailer), seconds (target length, default 45), record (false skips the recording stage).

What is in the package

partwhat it is
Film (module)the entry point: play, cutscene, on/off/emit, stop, skip, replay, handBack, current, build, handleCallback
FilmDirector (component)plays a film module for each visitor on load; fields film, delay, waitForWorld, after, quality, playInEdit; Film.waitForWorld(timeout) waits for the same moment when you play a film yourself
movesthe camera moves; Moves.register adds your own
transitionsthe transitions
titlesthe title cards; Titles.register adds a style
framesthe frame bars and the picture rectangle
lensthe real lenses and the looks; Lens.registerLens adds a lens, Lens.register a look
afterfree fly, orbit and the Replay button
makeAFilm (workflow)the runnable nine-stage film workflow (see Workflow)
guidesguides/how-to-make-a-trailer-cinematic-or-intro-film-of-my-world.guide (how to use, every name), guides/example-a-level-flythrough-of-my-game-level.guide (a level flythrough: walk route, orbit, spiral climb, top-down reveal, hand to the player), guides/example-a-30-second-trailer-of-a-small-garden.guide (a step-by-step example) and guides/workflow-make-a-film-step-by-step.guide (shot list → blocking → moves and lenses → transitions → titles → events → music → look → review with cutscene seek and capture → record → after-film → multiplayer)

Notes

  • The first time a film plays in a world, the engine's cutscene writes its skip binding to /source/runtimeControls/cutsceneSkip.inputMap, so leaving play asks about those files. Keep them (accept the play changes) and the question does not come back.
  • The Replay button's click is delivered to FilmDirector. If you play films from your own scene entrypoint or component instead, forward clicks: function onCallback(id, data) Film.handleCallback(id, data) end.
  • Title animation is CSS-style UI animation, so it advances with the UI's own clock; transitions that show two shots (dissolve, wipes) are driven from the film clock every frame and stay frame-accurate even when the film is paused or slowed.
  • The engine ships no brush-script typeface; the brush style composes a serif title with a painted ink stroke and seal. Install any brush .font and pass font = "<its name>" on the card to use it.
  • Films are local to each peer. Work that changes the shared world belongs in event handlers, written like any other gameplay code.

Changelog

  • 1.0.0: first release. 22 camera moves, 15 transitions, 7 title styles, 7 frame shapes, 6 lens looks, 5 after-film modes, timed events, FilmDirector.
  • 1.0.1: two new moves (topDown reveal, spiralClimb), the blurDissolve transition, the typewriter title style, widescreen169 / hd and softVignette frames, six real lenses by focal length (wide18, standard35, portrait50, tele85, long135, macro) separate from the looks (look = ..., old lens = "<look>" spelling still works) with per-shot lens, legible small text (tight glyph shadows and soft dark backings on captions, lower thirds and typewriter lines). Fixed: the first frame of a dissolve or wipe could show the render texture before the blend camera had drawn into it (a frame of undefined memory, e.g. the scene rolled over and seen from below); the overlay now waits until the blend camera has rendered. The blend camera and texture are pooled and reused instead of despawned and destroyed.
  • 1.0.2: replaying the same film module straight after stopping it no longer lets the old playback's late finish tear down the new one (its titles, lens and frame); the vertical style's subtitle gets the soft dark backing too.
  • 1.0.3: afterOptions.eye, at and fov set where the free camera starts after the film and what it looks at.
  • 1.0.4: three new guides written for how people ask: how to make a trailer, cinematic or intro film of your world (every move, transition, title, frame, lens, look and after-film mode, each swapped with one change), an example 30-second garden trailer, and a step-by-step workflow from shot list to recording. The Looks table header now says look.
  • 1.0.5: from a newcomer's run-through in an empty world. After the film, a free-fly or orbit camera that would inherit a telephoto or macro last shot is widened to 40-70 degrees unless afterOptions.fov says otherwise. The README's quick start uses the guides' film/trailer.module path and neutral names, says what to do in a brand-new world with no scene, where the FilmDirector line goes (build.luau, inside content()), and adds hidePlayer = true. The example guide covers the new-world scene, the avatar in shot and the after-film camera.
  • 1.0.6: the two superseded guides (makeACinematicFilm, exampleShortTrailer) are removed; the how-to, the example and the step-by-step workflow guide replace them. Built on the current engine library.
  • 1.0.7: a runnable workflow, makeAFilm, walks an agent through a film in nine stages (shot list, film module, transitions and titles, events, look/frame/music, FilmDirector, review, after-film and multiplayer, recording and world-page media), each saying what to produce and how to check it. The README's Workflow section and the step-by-step guide say how to start it. Built on the current engine library.
  • 1.0.8: the soft dark backing behind a vertical title's subtitle and behind typewriter text now fades in and out with the words; before, it showed for the whole card and stayed as a dark bar after the words had gone.
  • 1.0.9: recording guidance from a real take: a particle field first built, or faded, while a frame-by-frame take runs does not show in it; the makeAFilm workflow (stage 9) and the step-by-step guide (Stage 10) now say to build every field first, hold each at its film strength and skip the fades during the take.
  • 1.0.10: from a newcomer run-through in an empty world: setting startup_scene does not open the scene in the running session, so play showed an empty world. The README, the how-to and the example guide now say to open it with zero scene load main, and that the first film writes the engine cutscene's skip binding (runtimeControls/cutsceneSkip.inputMap), to keep when leaving play asks.
  • 1.0.11: a brand-new world opens on its starter scene scenes.main (/source/scenes/main.scene), so the README, both guides and the makeAFilm workflow now say to film that scene, and only in a world with no scene at all to make one at the same name (asset.create("scene", "main", { folder = "scenes" }), then zero scene load scenes.main). The old advice made a second scene called main, which made zero scene load main refuse as ambiguous.
  • 1.0.12: the film waits for the world to be on screen. FilmDirector holds the film until the world load reads visually complete (the "Entering the world" card gone), then waits delay, so the opening title is seen from its first frame; waitForWorld = false keeps the old timing, and Film.waitForWorld(timeout) does the same wait for a film you start yourself. The vertical title's subtitle now sits fully on screen beside the columns (right of the ink rule when the title stands at the left, left of the columns otherwise) or centred under them when that side has no room; before, a left-placed title ran its subtitle across the kanji and off the left edge.
  • 1.0.13: built on the current engine library (b45137c). No change to the film rig.
  • 1.0.14: built on the current engine library (c98faf2). No change to the film rig.
  • 1.0.15: built on the current engine library (33551d3). No change to the film rig.
  • 1.0.17 (the pull request branch published its own 1.0.16): the three guides remove their Film.on handlers when the scene unloads (each keeps the remover Film.on returns and calls it from onUnload). Handlers live in filmRig's module state, longer than a scene, so without it every reload of the scene added another copy and old handlers kept firing. Contributed through pull request #7.
  • 1.0.18: a second example guide, "a level flythrough of my game level": an establishing flyover, an eye-height walk route through the level, an orbit, a spiral climb, a top-down reveal of the goal and the camera handed back to the player. Built on the current engine library (2c02fe3). No change to the film rig.
  • 1.0.19: built on the current engine library (ca6727b). No change to the film rig.
  • 1.0.20: the opening paragraph (what ZeroMind shows on the package card) says how to install filmRig and play a first film. No change to the film rig.
  • 1.1.0: no more black flash or old shot coming back in a fade. Every cover transition (fade, fadeWhite, dipToColor, flash, iris, blinds, pixelate, panelWipe) is now drawn by filmRig itself, every frame, at the coverage the film clock says, instead of a screenWipes animation running on the wall clock beside the film. On a slow frame, or in a frame-by-frame recording, the old cover could lift before the cut, so a fade went black, showed the outgoing shot again for a few frames, then hard-cut. Now the screen is fully covered exactly at the cut whatever the frame rate, a paused film holds the transition, and a recorded take matches a live viewing. filmRig no longer depends on screenWipes. The cutscene definition also carries viewTiming (per shot: transition lead, length, whether the outgoing shot stays on screen) for kits that light or detail the scene around the camera, so a dissolve's outgoing shot keeps its lights (lanternStair 1.7.0 reads it).
  • 1.1.1: the letterbox bars no longer drop out for a few frames. The bars kept their slide-in animation for the whole film, so a rebuild of the screen layers around a transition could replay it: the scope bars slid off the picture and back during a fade. Once they have slid in, the bars are now a plain static layer with nothing to replay, and they stay put through every transition, live or recorded.