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…
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.
- Write a film module at
/source/film/trailer.module/init.luau(its name isfilm.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" } },
})
- Play it for everyone who arrives: put a FilmDirector on an entity the scene builds. In the
scene's
build.luau, insidecontent():
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.)
- 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:
| want | change |
|---|---|
| a different camera move | the shot's move |
| a different transition into a shot | the shot's transition (and transitionDur, transitionDir, transitionColor) |
| a different title look | the card's style |
| a different frame shape | frame |
| a different real lens (focal length, field of view, depth of field) | lens (film-wide) or a shot's own lens |
| a different photographic look | look |
| something else after the film | after (or FilmDirector's after field) |
| lighter rendering | quality = "low" (or "auto") |
The film definition
| key | default | what it does |
|---|---|---|
shots | none | the camera moves, in order (table below) |
titles | none | title cards: { t, dur, style, text, sub, ... } |
events | none | { t, event, data? }: calls Film.on(event, fn) handlers, also when skipped |
frame | scope | frame shape (table below) or an aspect number |
lens | the look's own | a 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" |
look | clean | photographic look (table below), or a table { base = "noir", grain = 0.08, ... } |
quality | auto | auto (low in the browser, on Android and small screens), high, low |
after | handToPlayer | freeFly, orbit, loop, handToPlayer, none |
afterOptions | none | { 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) |
afterSkip | handToPlayer | for after = "loop": what a skip leads to |
replayButton | true | show the small "Replay film" button afterwards |
transition | cut | default transition for shots that name none |
music | none | a soundClip asset (asset.resolve("theme", "soundClip")), played locally |
musicVolume | 0.8 | |
fadeIn / fadeOut | 1.5 | seconds of fade from / to fadeColor at the ends |
subtitles, cues, skippable, skipLabel, freezePlayer, hidePlayer, renderLayers, onStart, onFinish | passed to the engine's cutscene | |
frameOpen, barColor | 1.6, black | bar slide-in seconds and colour |
Shot keys
| key | what it does |
|---|---|
move | the camera move (table below) |
dur | seconds |
target | what the camera looks at: { x, y, z } or an entity name |
from | where the camera starts; default is distance from the target at height, compass angle |
to | where it ends, for moves that travel (dolly, truck, craneRise, whipPan's second target) |
distance, height, angle | place the camera around the target when from is not given |
amount | how far the move goes (metres) |
degrees | orbit / arc angle |
points | path points for followPath / flyover; lookPoints for a separate aim path |
fov, fovTo | lens field of view in degrees at start / end (overrides the lens) |
lens | this shot's own real lens (tele85, macro, ...): its field of view and depth of field for this shot only |
ease | any cutscene easing name (inOutSine, inOutCubic, outExpo, ...) |
shake | handheld noise strength (metres), on any move |
focusFrom, focus | rack focus from one point / entity to another (lens with depth of field) |
track | with an entity target, aim follows it live |
transition, transitionDur, transitionDir, transitionColor | how this shot is entered |
Moves
| move | what it does |
|---|---|
static / lockoff | locked-off camera |
dolly / dollyOut | travel along the line of sight toward / away from the target |
pushIn | slow dolly in with the lens tightening: tension |
pullBack | slow dolly out and up, lens widening |
reveal | big pull back and rise that reveals the place |
truck / drift | slide sideways (drift is small and slow) |
craneRise / craneDown | rise while tilting down to keep the target framed / descend onto it |
tiltReveal / tiltDown | camera stays; aim tilts up from the ground / down from the sky to the target |
orbit | circle the target by degrees |
arc | partial orbit that closes in a little |
followPath | smooth Catmull-Rom spline through points at constant speed |
flyover | high pass over points or over the target, aimed ahead and down |
whipPan | aim whips from target to to in a blink |
focusPull | near-static frame while the focus racks from focusFrom to the target |
handheld | subtle noisy shake on a slow drift (shake sets strength) |
dollyZoom | vertigo: dolly in while the lens widens so the target holds its size |
zoom | lens zoom from fov to fovTo |
topDown | top-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 |
spiralClimb | spirals 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
| transition | what it does |
|---|---|
cut | hard cut |
fade / fadeWhite / dipToColor | fade through black / white / transitionColor |
flash | quick white flash |
dissolve | crossfade; the outgoing shot keeps moving while it melts away |
blurDissolve | dreamy crossfade: the outgoing shot blurs out of focus as it fades and the new shot blurs back into focus |
wipe, wipeLeft, wipeRight, wipeUp, wipeDown | the new shot is revealed behind a soft moving edge |
iris | closing circle and open again |
blinds | slats sweep shut and open (transitionDir) |
pixelate | blocks pop in and out |
panelWipe | a 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
| style | look | main keys |
|---|---|---|
brush | painted sumi ink stroke sweeps in behind a large, wide-tracked serif title; red seal stamp | text, sub, seal (a character, or false) |
vertical | Japanese vertical writing, characters fall top to bottom, columns right to left | text (\n = new column), sub, position (right/left/center), seal |
modern | wide-tracked capitals between fine rules | text, sub |
lowerThird | name and role at lower left with a gold bar | text, sub, accent |
chapter | spaced kicker, a fine rule, italic serif title | kicker, text |
credits | scrolling end-credits roll | text (heading), lines (strings = section headings, "" = gap, { role, name } pairs) |
caption | quiet italic line low in the picture on a soft dark backing, readable over bright skies and dark scenes alike | text, y, backing (false to drop it) |
typewriter | monospaced characters land one by one behind a blinking caret | text (\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
| frame | aspect |
|---|---|
scope | 2.39:1 cinemascope |
flat | 1.85:1 |
univisium | 2:1 |
widescreen169 / hd | 16:9 HD: no bars on a 16:9 screen, pillar- or letterboxed on any other |
tv / none | the full screen, no bars |
academy | 4:3, pillarboxed on wide screens |
square | 1:1 |
vertical | 9:16 phone video |
softVignette | no 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.
| lens | field of view | focus |
|---|---|---|
wide18 | 18 mm, 67° | f/11: deep focus, everything sharp |
standard35 | 35 mm, 38° | f/5.6: natural, mostly sharp |
portrait50 | 50 mm, 27° | f/2: subject sharp, background soft |
tele85 | 85 mm, 16° | f/1.8: shallow, creamy background |
long135 | 135 mm, 10° | f/2.8: very shallow, compressed distance |
macro | 100 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
| look | what it does |
|---|---|
clean | neutral, light vignette and bloom (45° when no lens is named) |
anamorphic | 38° lens, shallow focus, horizontal flare streaks, slight aberration, cool grade |
vintage16mm | heavy vignette, coarse grain, warm faded colour |
dreamy | wide, very shallow focus, strong soft bloom, low contrast |
noir | black and white, high contrast, grain |
goldenHour | warm 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
| after | what the visitor gets |
|---|---|
freeFly | a 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 |
orbit | slow automatic orbit around the last target (or afterOptions.center); drag to look, scroll or pinch to zoom |
loop | the film plays again |
handToPlayer | the scene's own player camera comes back |
none | as 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
| part | what 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 |
moves | the camera moves; Moves.register adds your own |
transitions | the transitions |
titles | the title cards; Titles.register adds a style |
frames | the frame bars and the picture rectangle |
lens | the real lenses and the looks; Lens.registerLens adds a lens, Lens.register a look |
after | free fly, orbit and the Replay button |
makeAFilm (workflow) | the runnable nine-stage film workflow (see Workflow) |
| guides | guides/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
cutscenewrites 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
brushstyle composes a serif title with a painted ink stroke and seal. Install any brush.fontand passfont = "<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 (
topDownreveal,spiralClimb), theblurDissolvetransition, thetypewritertitle style,widescreen169/hdandsoftVignetteframes, six real lenses by focal length (wide18,standard35,portrait50,tele85,long135,macro) separate from the looks (look = ..., oldlens = "<look>"spelling still works) with per-shotlens, 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
verticalstyle's subtitle gets the soft dark backing too. - 1.0.3:
afterOptions.eye,atandfovset 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.fovsays otherwise. The README's quick start uses the guides'film/trailer.modulepath and neutral names, says what to do in a brand-new world with no scene, where the FilmDirector line goes (build.luau, insidecontent()), and addshidePlayer = 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
verticaltitle's subtitle and behindtypewritertext 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_scenedoes 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 withzero 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" }), thenzero scene load scenes.main). The old advice made a second scene calledmain, which madezero scene load mainrefuse 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 = falsekeeps the old timing, andFilm.waitForWorld(timeout)does the same wait for a film you start yourself. Theverticaltitle'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.onhandlers when the scene unloads (each keeps the removerFilm.onreturns and calls it fromonUnload). 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.
Scoped to this part · feeds back into the world's score.