What a platformer adds

The second genre, and the instrument that tested the first. The brief was "a game that is not a shooter, without a single edit in the engine", and the value of it is not the game, it is what the attempt found.

Three hardcoded object types had already been dug out of the engine by imagining this one. Sketching it for real found five more, all in input, and they were fixed rather than worked around. GameAction stopped being an enum because there was no way to write PlatformerActions.dropThrough without editing the engine.

Nothing here imports the renderer, so all of it runs in a test with no device.

The runner #

A CharacterController walks, jumps, climbs a step and rides a lift. That is a shooter's body. A platformer's needs eleven verbs, and Runner owns all of them:

stateDiagram-v2
    direction LR
    grounded --> airborne: jump · walk off
    airborne --> grounded: land
    airborne --> airborne: air jump · dash
    airborne --> wall: touch a wall while falling
    wall --> airborne: wall jump
    wall --> grounded: drop off
    airborne --> mantle: ledge within reach
    mantle --> grounded
    grounded --> slide: dash while crouched
    slide --> grounded: slide runs out
    slide --> airborne: long jump
    grounded --> crouch: crouch
    crouch --> grounded: stand, if there is headroom
    airborne --> pound: pound
    pound --> grounded: land hard

Every one of those is a number in RunnerSettings, and each number has a reason:

Surfaces #

The engine gives a brush a surface, a word, and no opinion about what it means. Surfaces is the other half: a genre's table from that word to movement numbers.

final runner = Runner(
  body: CharacterController(world: collision, position: start),
  surfaces: Surfaces.common(),   // ice and mud
);

factory Surfaces.common() => const Surfaces(<String, MovementSettings>{
      'ice': MovementSettings(
        groundFriction: 3.0,        // almost no grip
        groundAcceleration: 12.0,   // and you gather speed slowly
      ),
      'mud': MovementSettings(
        walkSpeed: 2.6, sprintSpeed: 3.4,
        groundAcceleration: 30.0, groundFriction: 70.0,
        jumpSpeed: 6.0,
      ),
    });

The word lives in the level document, on the brush, beside the material that paints it:

{"at": [0, -0.5, 124.5], "size": [120, 1, 7], "material": "ice", "surface": "ice"}

What a level may contain #

EntityRegistry platformerRegistry({Dynamics? dynamics}) =>
    EntityRegistry(<EntityKind>[
      const PlayerSpawnKind(), const DoorKind(), const LiftKind(),
      const PlatformKind(), const ButtonKind(), const TriggerKind(),
      const ExitKind(),
      const CollectibleKind(), const HazardKind(), const CheckpointKind(),
      const PlatformerKeyKind(), CrateKind(dynamics: dynamics), const SpringKind(),
      const OneWayKind(), const ConveyorKind(), const CrumblingKind(),
      const BreakableKind(), const ClimbableKind(), const EnemyKind(),
      LightFixtureKind(PlatformerEntities.lamp,
          defaultBehavior: const FlameFlicker(),
          defaultSize: Vector3(0.4, 1.6, 0.4)),
    ]);

Enemies are brains, not a monster system #

final class Patrol extends Brain {
  // Walks a route, pauses at each end, and refuses to walk off a ledge —
  // which it finds with a sweep rather than by being told where the floor is.
}

final class Leaper extends Patrol {
  // A patrol that jumps the gap when the landing is solid.
}

Both are ordinary Brains driven by the engine's ActorSystem, with no genre-specific system or monster type. The platformer's enemies and the shooter's use the same machinery and share none of the vocabulary. For a while nothing stepped the system at all, and so there were no enemies; the tutorial's simulation step keeps that story.

The follow camera #

The game layer has no camera type and that is deliberate. A third-person one is a caller reading position differently, so it lives here.

final camera = FollowCamera(world: collision, settings: const FollowSettings(
  distance: 7.0, height: 2.6, aimHeight: 1.2,
  lag: 9.0,                 // units a second of the remaining gap
  pitch: -0.22, minPitch: -1.2, maxPitch: 0.9,
  sensitivity: 0.0035,
  nearClearance: 0.35,      // how far in front of a wall it stops
  minDistance: 1.2,
  impulseDecay: 9.0,
));

camera.look(input.lookDelta);
camera.follow(drawnPosition, dt);
sim.cameraYaw = camera.yaw;    // the camera owns "forward"

It also carries the feel:

camera.kick(Vector3(0, -0.18 * hardness, 0));  // a landing dips the view
camera.shake(0.22, seconds: 0.3);              // a ground pound
camera.widen(0.1);                             // a dash, and speed
camera.cut();                                  // a death: a cut, not a chase

Its own step order #

The sibling of the shooter's GameSimulation, and the reason that one had to leave the engine: its step reads a weapon, an arsenal, a use key and an exit, and four of those five mean nothing here.

void step(double dt) {
  // mechanisms move · the broadphase catches up · dynamics run ·
  // the body sweeps · overlaps dispatch · floor surface is read ·
  // actors think and stomps resolve · checkpoints · collectibles ·
  // the kill plane · exits
}

What the two share is the order, and it is documented in both because it is the part that is easy to get wrong and impossible to see.

random is required, and the constructor asserts that any ActorSystem handed to it rolls the identical GameRandom. Two generators is the failure it exists to stop: the dice a simulation writes into its save were its own while the dice deciding what the enemies did were the actor system's, so a restored run replayed against a seed nothing was rolling from.

final sim = PlatformerSimulation(
  runner: runner,
  collision: collision,
  input: input,
  startAt: start,           // the feet, as a level authors it
  mechanisms: mechanisms,
  dynamics: dynamics,
  actors: actors,
  random: random,           // the same GameRandom the ActorSystem rolls
  lives: 3,                 // -1, the default, is an endless run
  levelNext: level.next,    // what the chain of five is made of
  killPlane: -20.0,
);

lives and levelNext are the two fields that make a run rather than a level. lives defaults to −1, which is endless; a game that sets it counts down and ends the run at zero. levelNext is whatever the level document's "next" said, and the application follows it, which is how the demo ships five levels and no list of them anywhere in its Dart. First Steps teaches one verb a room, Ascent is the long one the game is named after, Cisterns makes water the hazard, Foundry takes the floor away under you, and Spire is ten flights over a drop with something following you up. A game that kept its own order of levels would have two orders, and the second one is always the wrong one; lives, deaths, elapsed time and coins are what the application carries across the boundary.

Events, per step #

runner.jumpedThisStep;      runner.airJumpsLeft;
runner.dashedThisStep;      runner.wallJumpedThisStep;
runner.landedThisStep;      runner.landingSpeed;
runner.poundedThisStep;     runner.mantledThisStep;
runner.slidThisStep;        runner.grabbedThisStep;

sim.takenThisStep;              // List<Collectible>
sim.reachedCheckpointThisStep;
sim.stompedThisStep;
sim.deaths;

landedThisStep reports how hard. The application used to work that out from whether the runner was grounded last frame, which cannot know the speed, so a soft landing and a twenty-metre drop produced the same puff of dust.

Ready to build one? #

The platformer tutorial assembles all of this in fourteen steps.