flutter3d
Showcase Changelog 62 packages API reference

Cutscenes

since 1.0.0-rc.1 Simulation, audio and XR

A cutscene is a few seconds where the game takes the camera, says something, and changes the world: a door opens, a monster wakes. If any of that is done by timers in the frame, a replay or a skipped cutscene ends somewhere else. Sequence.read takes the cutscene as a document, and SequencePlayer plays it in the fixed step, so skipping it, saving in the middle of it and replaying it all end in the same place.

This page plays an eight-second scene in a dark hall. The camera comes in from the door and round to the altar. Three seconds in, a lamp is lit on the altar, and at five and a half the gate behind it rises. Then it starts over.

Step 1: The document #

Times are in seconds. camera is a list of keys, each with where the eye is, what it looks at and, if it says, its vertical field of view in degrees, forty-five otherwise. With ease the camera slows into and out of each key. subtitles are lines with a start and an end, fade is how dark the picture is at a few moments, and signals are names, with data, that the game is told about on their step. A sequence can also have actors cues that walk an actor to a mark over the navigation mesh, turn it, stand it, play a clip once or hand it back to its brain. This page has none.

/// Seconds in the document; every moment is turned into the step it
/// falls on at the game's rate when it is read.
static const Map<String, Object?> document = <String, Object?>{
  'seconds': 8,
  'camera': <String, Object?>{
    'ease': true,
    'keys': <Object?>[
      <String, Object?>{
        't': 0,
        'at': <double>[0, 3, 13],
        'look': <double>[0, 1, 0],
      },
      <String, Object?>{
        't': 3,
        'at': <double>[7, 2.5, 5],
        'look': <double>[0, 1, -1],
      },
      <String, Object?>{
        't': 5.5,
        'at': <double>[4, 1.8, -1],
        'look': <double>[0, 1.2, -4],
      },
      <String, Object?>{
        't': 8,
        'at': <double>[1.5, 2.2, 3],
        'look': <double>[0, 1.4, -4],
        'fov': 38,
      },
    ],
  },
  'subtitles': <Object?>[
    <String, Object?>{
      'from': 0.5,
      'to': 3,
      'text': 'The hall has been dark a long time.',
    },
    <String, Object?>{
      'from': 3.5,
      'to': 6.5,
      'text': 'Something at the altar is waking.',
    },
  ],
  'fade': <Object?>[
    <String, Object?>{'t': 0, 'value': 0.8},
    <String, Object?>{'t': 1.5, 'value': 0},
  ],
  'signals': <Object?>[
    <String, Object?>{'t': 3, 'name': 'lamp'},
    <String, Object?>{
      't': 5.5,
      'name': 'gate',
      'data': <String, Object?>{'height': 2.5},
    },
  ],
};

Step 2: Read it at the game's rate #

Every moment is turned into the step it falls on, once, when the document is read. A document with problems gives no sequence, and every problem comes back with where it is.

/// The page's document read into a [Sequence] at [stepsPerSecond]. Throws a
/// [FormatException] listing the problems when it does not read.
static Sequence readSequence() {
  final SequenceRead read = Sequence.read(
    document,
    stepsPerSecond: stepsPerSecond,
  );
  final Sequence? sequence = read.sequence;
  if (sequence == null) throw FormatException(read.problems.join('\n'));
  return sequence;
}

Step 3: Step it, and answer the signals #

SequencePlayer keeps a single integer, the step it is on. advance moves it one step, and every signal that step reaches is published onto the player's events bus as a SequenceSignal, once each and in order. The game answers them the way it answers any other event, with a subscriber on that bus. Here it lights the lamp and raises the gate by the height the signal carries.

In a game the bus is the engine's: a genre's simulation hands its cutscenes its own, so a signal lands on the step channel among the step's other events. This page steps the cutscene by hand, with no EngineLoop, so it hands a DirectBus, which delivers each signal as it is published.

/// A player whose signals [stage] answers: they are published onto a bus
/// [stage] listens on. A game stepped by an `EngineLoop` hands its own;
/// this page steps the cutscene by hand, so a [DirectBus] does.
static SequencePlayer _playedTo(Sequence sequence, _Stage stage) {
  final DirectBus bus = DirectBus();
  stage.listenTo(bus);
  return SequencePlayer(sequence, events: bus);
}
/// One fixed step of the game while the cutscene plays: the player moves
/// on a step and publishes what it reaches, and the game's subscriber
/// answers.
static void _stepOnce(SequencePlayer player) => player.advance();
/// The game's answer to each signal, subscribed on the bus the cutscene
/// publishes onto: heard in order, on the step it fired.
Registration listenTo(EventRegistry bus) => bus.onStep<SequenceSignal>(
  'cutscenes.answer',
  (Delivered<SequenceSignal> delivered) {
    final SequenceSignal signal = delivered.event;
    heard.add(signal.signal);
    switch (signal.signal) {
      case 'lamp':
        lampLit = true;
      case 'gate':
        gateHeight = (signal.data['height'] as num?)?.toDouble() ?? 2.0;
    }
  },
);

Step 4: The camera between steps #

What the cutscene shows is not part of the simulation. A replay or a server needs the step and the signals, never the camera, so the picture is read by a SequenceView from flutter3d_camera, made once for the sequence and asked about the player every frame. The picture is drawn between two steps, so cameraOf takes alpha, how far the frame is from the last step to the next. The eye and the point it looks at each run along a curve through their keys, and pass through each key on its step exactly. The fade and the subtitles are read the same way, with fadeOf and subtitleOf.

// Drawn between two steps: alpha is how far the frame is past the last.
final double alpha = _carry * stepsPerSecond;
final Vector3 eye = Vector3.zero(), look = Vector3.zero();
final double? fieldOfView = _view.cameraOf(
  _player,
  eye,
  look,
  alpha: alpha,
);
if (fieldOfView != null) {
  context.camera
    ..setPosition(eye.x, eye.y, eye.z)
    ..lookAt(look);
}

Step 5: The fade #

fadeOf is 0 for a clear picture and 1 for black. This page applies it as exposure, so the whole picture darkens.

/// The fade darkens the whole picture: a fade of one is black.
@override
RenderSettings settings(DemoContext context) => RenderSettings(
  exposure: RenderSettings.defaultExposure * (1.0 - _view.fadeOf(_player)),
);

Step 6: Skip #

A skip is the remaining steps of the cutscene run straight away without being drawn. Every signal on the way still fires, in order, so the lamp is lit and the gate is up whether the scene was watched or skipped. In a game this goes through EngineLoop.runSteps, which also records the skipped steps on the tape, so a replay steps through them too.

/// A skip is the rest of the cutscene stepped without being drawn: every
/// signal still fires, in order, so the game ends where watching it ends.
static void _skip(SequencePlayer player) {
  while (!player.isFinished) {
    _stepOnce(player);
  }
}

Step 7: What has to hold #

A player stepped to the end and a player skipped after a second and a half have to agree: the same step, the lamp lit, the gate at 2.5 m, and the signals heard as lamp then gate, once each. A player restored at four seconds, after the lamp, has to fire only the gate. The camera has to end on its last key, at 38 degrees, and the fade has to end clear.

final Sequence sequence = readSequence();
final SequenceView view = SequenceView(sequence);
// Watched: one step a frame to the end.
final _Stage seen = _Stage();
final SequencePlayer watched = _playedTo(sequence, seen);
while (!watched.isFinished) {
  _stepOnce(watched);
}
// Skipped a second and a half in, before either signal.
final _Stage hurried = _Stage();
final SequencePlayer skipped = _playedTo(sequence, hurried);
for (var i = 0; i < 90; i++) {
  _stepOnce(skipped);
}
_skip(skipped);
if (!seen.sameAs(hurried) || skipped.step != watched.step) {
  throw StateError('skipped: $hurried; watched: $seen');
}
if (!listEquals(seen.heard, <String>['lamp', 'gate']) ||
    seen.gateHeight != 2.5) {
  throw StateError('the signals were not answered: $seen');
}
// Restored past the lamp, the lamp does not fire a second time.
final _Stage later = _Stage();
final SequencePlayer restored = _playedTo(sequence, later)
  ..restore(<String, Object?>{'step': 4 * stepsPerSecond});
_skip(restored);
if (!listEquals(later.heard, <String>['gate'])) {
  throw StateError('a restore fired ${later.heard}');
}
// The camera ends on its last key, the fade on clear.
final Vector3 eye = Vector3.zero(), look = Vector3.zero();
if (view.cameraOf(skipped, eye, look) != 38.0 * math.pi / 180.0 ||
    eye.distanceTo(Vector3(1.5, 2.2, 3.0)) > 1e-6 ||
    view.fadeOf(skipped) != 0.0) {
  throw StateError('the camera or the fade did not end where written');
}

Note. This page has no text layer over its picture, so its subtitles are read but not shown. The dungeon draws them, with the fade, over the cutscene's camera. The fade here starts at 0.8 rather than black, because a page is also checked on its first frame and a black frame would look like one that drew nothing. A skip runs all the remaining steps in one frame, which costs whatever those steps cost. Actor cues need an ActorSystem and a navigation mesh, and are shown in the dungeon's sanctum rather than here.