# bevy_director
Shots, sequences, and a camera you can direct. An Unreal-Sequencer-shaped
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.
What it is not: a tween library (see bevy_tweening), an animation graph
(see bevy_animation), or a UI. The viewfinder authors sequences in-game
with a keyboard and gizmos, no widgets.
## Quickstart
```rust,ignore
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, .. }` (captions,
stingers), 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.
## The viewfinder (feature `viewfinder`, on by default)
The director's chair, no widgets: press Backquote in your running game.
| Backquote | Toggle the viewfinder (possesses the camera at the current view) |
| WASD + mouse | Fly and look |
| Q / E | Sink / rise |
| Wheel | Fly speed (Ctrl+Wheel: fov) |
| K | Capture the framing as a key at the playhead |
| [ / ] | Scrub (Shift: single frame) |
| P | Preview the working take |
| Delete | Remove the nearest key |
| Ctrl+S | Write `assets/sequences/<name>.dir.ron` (native only) |
Gizmos draw every shot's path, keys, aim rays, and the playhead ghost
while the viewfinder is up.
## The `.dir.ron` format
```ron
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: "caption_one")],
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);
`constant_speed` rails cover equal distance in equal time via an
arc-length table, the piece Bevy itself does not ship.
## Glossary for Unreal refugees
| Level Sequence asset | `SequenceAsset` (`.dir.ron`) |
| Sequencer (the editor) | the viewfinder |
| Camera Cuts track | the shot list itself |
| CineCameraActor | a `CineCamera` entity |
| Ease In/Out on a section | `Blend` (`blend_in` / `blend_out`) |
| Camera Rail rig | `Rig::Rail` |
| Crane / orbit rig | `Rig::Orbit` |
| Transform keyframes | `Rig::Keys` |
| Look-at Tracking | `Look::At { target, damping }` |
| Filmback | `Filmback` presets (Super35 default) |
| Focal Length | `FovSpec::FocalLengthMm` |
| Focus Settings | `FocusTrack` -> bevy `DepthOfField` |
| Event track | `Marker` -> `MarkerReached` |
| Play Rate | `SequencePlayer::rate` (negative plays backward) |
| Possess / Eject | the handoff and `DirectorPhase::Handback` |
| Pilot camera | viewfinder fly mode |
| Camera Shake | `Shake` (seeded, deterministic) |
## Features
- `viewfinder` (default): the in-game capture mode. Implies `gizmos`.
- `gizmos` (default): path and key overlay drawing.
With both off, the crate is the data model, the evaluator, the RON
loader, and the playback state machine: enough to ship cutscenes.
## Compatibility
| 0.19 | 0.1 |
## License
Dual-licensed under MIT or Apache-2.0, at your option.