bevy_director

Camera director, shots, sequences: an Unreal-Sequencer-inspired cinematic layer for Bevy 0.19. Sequences are RON assets made of shots, shots are camera rigs (eased keys, constant-speed dolly rails, orbits) with a film-literate lens (focal length against a filmback, focus pulls, aperture, exposure), and playback hands off from your gameplay camera and glides back onto it when the take ends.

Quickstart

use bevy::prelude::*;
use bevy_director::prelude::*;

app.add_plugins(DirectorPlugin);

// Let the director borrow the frame: gate your own camera-driving
// system so it yields during a take and runs during the glide home.
app.add_systems(Update, my_camera_rig.run_if(gameplay_camera_free));

// Anywhere, later:
commands.play_sequence(asset_server.load("sequences/intro.dir.ron"));

The director finds your active Camera3d, snapshots it, swaps is_active to its own CineCamera (spawning a plain one if you did not provide one; spawn your own to keep your post stack), plays the shots, and at the end blends toward wherever your live camera is by then, sampling it every frame. Control can return to the player while the camera is still gliding.

Listen for SequenceStarted, MarkerReached { name, .. } (cues, stingers; on-screen text has its own track now), and SequenceFinished { reason } (story flags belong here, never on markers). commands.skip_sequence() jumps to the end and takes the normal blend home; stop_sequence() cuts hard.

Director's Cut (feature editor, opt-in)

Director's Cut is the docked, mouse-driven authoring surface. It uses the same ViewfinderSession, evaluator, and .dir.ron assets as the runtime, so there is no conversion or editor-only project format.

use bevy::prelude::*;
use bevy_director::prelude::*;

App::new()
    .add_plugins((DefaultPlugins, DirectorsCutPlugin))
    .run();

Run the included stage with:

cargo run --example directors_cut --features editor

Press Backquote to possess the camera; Director's Cut opens automatically. Press Tab to switch between the editor cursor and camera piloting.

New/Open/Save use assets/sequences/<sequence name>.dir.ron by default. The Open panel lists that folder; loading a file also renames the working take after it, so a following Ctrl+S writes back to the same file. The filename field accepts either a plain name or the full .dir.ron filename; the extension is added exactly once. Set DirectorsCutConfig::sequence_path when a fixed path is preferable; the Open panel then lists that file's folder instead. The editor feature is not enabled by default, keeping UI and picking out of shipping builds unless requested.

Integrating with a live game

The editor runs inside your game, over the live scene. That is the point: you frame shots against real lighting, real actors, real physics. It also means the game still sees the same keyboard and mouse while you direct. Anything you do not gate will fight the editor: the character walks away while you fly the camera on WASD, or a click-to-grab-cursor handler locks the pointer mid-drag and the timeline scrub sticks.

The crate tells you when to stand down. DirectorState.phase says who owns the frame, and three run conditions wrap the common cases:

The prerequisites, in order of pain avoided:

1. Yield the camera. Run your camera rig under gameplay_camera_free, as in the quickstart.

2. Yield the keyboard and mouse. While the director is not Idle, stop reading gameplay input. Per-system run_if(director_idle) works; if your game has a state machine, one bridge system is cleaner because every state-gated system and input context follows automatically:

   fn yield_to_director(
       director: Res<DirectorState>,
       state: Res<State<GameState>>,
       mut next: ResMut<NextState<GameState>>,
   ) {
       match (director.phase, state.get()) {
           (DirectorPhase::Viewfinder, GameState::Playing) => {
               next.set(GameState::Directing)
           }
           (DirectorPhase::Idle, GameState::Directing) => {
               next.set(GameState::Playing)
           }
           _ => {}
       }
   }
   

3. Leave the cursor alone. The viewfinder manages the cursor itself: locked while piloting, free while the editor cursor is up, and your previous grab state is restored on eject. A gameplay system that re-locks the cursor on click breaks timeline dragging; gate it like the rest of the input.

4. Drive gameplay off the default clock. The Freeze button pauses Time<Virtual>, so actors hold still while you frame a shot. Systems that read Time<Real> ignore the freeze. The editor itself runs on real time, so flying, scrubbing, and previewing keep working in a frozen world; ejecting resumes the clock if the editor paused it. A physics engine with its own clock (avian's Time<Physics>, for example) needs a small mirror system that pauses it whenever Time<Virtual> is paused.

Key bindings that overlap are harmless once input is gated: the editor's pilot/editor toggle defaults to Tab, and if your game also binds Tab, the two never see it at the same time. Rebind via DirectorsCutConfig::toggle if you want a different key.

DirectorsCutState is a public resource; open tells you whether the dock is up if you want to gate anything the run conditions do not cover.

Development vs shipping

Enabling a Cargo feature only makes its code available. A tool becomes active—and starts reading its shortcuts—only when its plugin is added to the app.

For a game that authors cinematics during development but ships only the RON player, expose the editor through a game-specific feature:

[features]
director_editor = ["bevy_director/editor"]

[dependencies]
bevy_director = { version = "0.3", default-features = false }

Select the plugin at compile time:

#[cfg(feature = "director_editor")]
app.add_plugins(DirectorsCutPlugin);

#[cfg(not(feature = "director_editor"))]
app.add_plugins(DirectorPlugin);

Use the authoring build to create and save the asset:

cargo run --features director_editor

Then run or release the normal game without that feature:

cargo run
cargo build --release

The shipping build loads and plays the saved asset normally:

commands.play_sequence(asset_server.load("sequences/intro.dir.ron"));

It contains no Director's Cut UI or editor shortcuts because DirectorsCutPlugin is not installed. This also makes Director's Cut usable as a temporary authoring tool whose only shipped output is the .dir.ron sequence.

The editor's infinite grid appears only while the viewfinder is active. Disable it when the game already supplies an authoring grid:

app.insert_resource(DirectorsCutConfig {
    show_grid: false,
    ..default()
});

The spawned entity is marked with DirectorsCutGrid; you can despawn it and add your own InfiniteGrid and InfiniteGridSettings when you need custom colors, spacing, or fade distance.

Viewfinder (feature viewfinder, on by default)

The director's chair, no widgets: press Backquote in your running game.

Gizmos draw every shot's path, keys, aim rays, and the playhead ghost while the viewfinder is up.

.dir.ron format

SequenceAsset(
    name: "intro",
    shots: [
        Shot(
            start: 0.0, duration: 8.0,
            rig: Rail(
                points: [(-2.0, 2.0, -6.0), (0.0, 2.2, 0.0), (2.0, 2.5, 6.0)],
                constant_speed: true,
                progress: ScalarTrack(keys: [
                    ScalarKey(time: 0.0, value: 0.0, ease: SmoothStep),
                    ScalarKey(time: 8.0, value: 1.0),
                ]),
            ),
            look: At(target: Entity("gate"), damping: Some(8.0)),
            lens: Lens(
                fov: FocalLengthMm(track: ScalarTrack(keys: [ScalarKey(time: 0.0, value: 35.0)])),
                focus: Some(Target(target: Entity("gate"))),
                aperture_f_stops: Some(ScalarTrack(keys: [ScalarKey(time: 0.0, value: 2.0)])),
            ),
        ),
    ],
    markers: [Marker(time: 1.0, name: "stinger_one")],
    texts: [
        TextBlock(
            start: 1.0, duration: 3.0,
            text: "THE GATE",
            anchor: Center,
            fade_in: 0.5, fade_out: 0.5,
        ),
    ],
    blend_out: Some(Blend(secs: 1.5, ease: SmoothStep)),
)

Rules worth knowing: shot starts are absolute and sorted; a shot with no blend_in cuts hard; during a blend the previous shot is sampled clamped (extend it into the overlap for a moving crossfade); markers fire only while playing across them (skips and seeks never retro-fire); text blocks are the opposite — level-triggered, so whatever the playhead sits inside is visible at the fade-resolved alpha, and they may overlap each other and span camera cuts (their window is half-open, and anything past the last shot's end never shows because playback stops there); constant_speed rails cover equal distance in equal time via an arc-length table, the piece Bevy itself does not ship.

Text overlays

Text blocks carry a duration, fades, an anchor (Center for title cards, LowerThird for subtitles, TopCenter for location stamps), and a style (size, color, shadow, optional background box). The core crate always parses and evaluates them: every frame, the ActiveTexts resource holds the blocks visible right now with their fade alphas, which is the whole contract for rendering captions with your own UI (localization included: treat text as a key and look it up when you draw).

The titles feature adds the built-in renderer, TitlesPlugin: bevy_ui text on the cine camera with the fades applied for you. Because the overlay targets the cine camera, layout happens inside its viewport, so anchors respect the letterbox crop with no extra work. It enables Bevy's default_font so text renders out of the box; set TitlesConfig::font to ship your own face (if you assemble Bevy features by hand and text is invisible, the missing default font is why). DirectorsCutPlugin installs it automatically so the TEXT lane previews exactly what ships. Markers remain the right tool for cues and stingers; captions belong to text blocks now.

Glossary for Unreal users

Features

• viewfinder (default): the in-game capture mode. Implies gizmos.
• gizmos (default): path and key overlay drawing.
• titles (opt-in): the built-in text overlay renderer (TitlesPlugin) for the sequence's text blocks. Pulls bevy_ui/bevy_text and the default font. The text data model and ActiveTexts evaluation are in the core crate regardless.
• editor (opt-in): Director's Cut dock, camera inspector, timeline, undo/redo, and the Open panel. Implies viewfinder and titles.

With everything off, the crate is the data model, the evaluator, the RON loader, and the playback state machine: enough to ship cutscenes.

Compatibility

License

Dual-licensed under MIT or Apache-2.0, at your option.