On Patrol: Sequences and Loops with Keyframes

So far each animation has been a single move — one glide (Part 1), one spin (Part 2). Real game motion is usually a routine: go here, then there, then back. A patrolling guard. A sweeping security drone. An elevator visiting floors. This lesson chains keyframes into a sequence and uses ping-pong playback to get a round trip almost for free.

Keyframes stack

<!-- section-art:keyframes-stack -->

Stacked Path

A keyframe list is a recipe read top to bottom, and the crucial rule is: each delta starts where the last one finished. The deltas stack.

# A keyframe list is a recipe read top to bottom. Each delta says "change
# the transform THIS much, over THIS long." Deltas stack: the entity ends
# each step where the last one left it, then the next step begins from there.
Leg1 := keyframed_movement_delta:
    Duration := 2.0
    Transform := transform:
        Translation := vector3{ Forward := 400.0, Left := 0.0, Up := 0.0 }
Leg2 := keyframed_movement_delta:
    Duration := 2.0
    Transform := transform:
        Translation := vector3{ Forward := 0.0, Left := 400.0, Up := 0.0 }

Run array{ Leg1, Leg2 } and the entity goes 400 forward, then 400 left — ending diagonally out from where it began, because Leg2 picks up where Leg1 stopped. Stack three or four legs and you can trace any path you like.

The lazy genius of ping-pong

For a patrol you want the guard to walk out and come back. You could write the return legs by hand — but there's a far cleaner way. Ping-pong playback plays your list forward, then automatically reverses it, forever:

pingpong_keyframed_movement_playback_mode{} — play the keyframes forward to the end, then play them backward to the start, then forward again… endlessly.

So you describe only the trip out. Ping-pong gives you the trip back for free. Half the code, a perfect round trip.

A guard that paces the vault — and tells us about it

using { /Verse.org/SceneGraph }
using { /Verse.org/SceneGraph/KeyframedMovement }
using { /Verse.org/Simulation }
using { /Verse.org/SpatialMath }
using { /UnrealEngine.com/Temporary/Diagnostics }

# Bolt this onto an entity with a Keyframed Movement component to make it
# PATROL: walk out to a far point, then back, forever — like a guard pacing
# a hallway or a security drone sweeping a vault.
patrol_component := class<final_super>(component):

    # How far the patrol walks before turning back, in units.
    @editable
    var PatrolDistance<public>:float = 600.0

    # Seconds for ONE leg (out OR back).
    @editable
    var LegSeconds<public>:float = 3.0

    OnBeginSimulation<override>():void =
        (super:)OnBeginSimulation()

        if (Mover := Entity.GetComponent[keyframed_movement_component]):
            # The single outbound leg: glide PatrolDistance to the left,
            # easing in and out so each turn feels like a real pause-and-go.
            Outbound := keyframed_movement_delta:
                Duration := LegSeconds
                Easing := ease_in_out_cubic_bezier_easing_function{}
                Transform := transform:
                    Translation := vector3:
                        Left := PatrolDistance
                        Forward := 0.0
                        Up := 0.0

            # Ping-pong: play the leg forward, then reverse it, forever.
            Mover.SetKeyframes(array{Outbound}, pingpong_keyframed_movement_playback_mode{})
            Mover.Play()

            # Listen for the turn-around so we could react (sound, score, etc.).
            Mover.KeyframeReachedEvent.Subscribe(OnReachedWaypoint)

    # Fires each time a keyframe is hit. Keyframe is the index reached;
    # IsReversed is true when we're on the way back.
    OnReachedWaypoint(Reached:tuple(int, logic)):void =
        # A real game might play a footstep here or flip a patrol flag.
        Print("Patrol reached a waypoint")

Two new techniques here:

1. Ping-pong does the round trip. We define a single Outbound leg — glide left by PatrolDistance. With pingpong... mode the guard walks out, then the engine reverses the leg so it walks right back, then out again, forever. The ease_in_out easing makes each end feel like a genuine pause-and-pivot rather than a hard bounce.

2. The animation tells your code what it's doing. The mover exposes events. We subscribe to KeyframeReachedEvent, which fires every time the animation hits a keyframe — i.e. every time the guard reaches an end of its route. The handler receives a tuple(int, logic): which keyframe was reached, and whether we're playing in reverse. From here you'd play a footstep, trigger an alarm if a player is near, or tick a score. The motion and the game logic stay in sync without you polling positions every frame.

Other handy events on the mover: FinishedEvent (a one-shot animation ended), PlayedEvent, PausedEvent, StoppedEvent. Subscribe to react; never busy-wait.

Building bigger routes

<!-- section-art:building-bigger-routes -->

Patrol Shapes

Want a four-corner sweep instead of a straight pace? Just stack more legs before handing them over:

loop snaps home and repeats; pingpong retraces the path in reverse. Same legs, two different patrol shapes — your choice of playback mode decides the personality.

Recap

• Keyframes stack: each delta begins where the previous one ended, so a list traces a path.
• Ping-pong playback plays the list forward then backward forever — describe the trip out, get the trip back free.
• The mover fires events (KeyframeReachedEvent, FinishedEvent, …); subscribe to keep game logic in sync with motion instead of polling.
• loop vs pingpong over the same legs gives a repeating circuit vs. a back-and-forth retrace.

Last stop — the Capstone: Build a Moving Platform Players Can Ride — where everything here becomes a working elevator that carries the player.