gale.cutscene package

gale.cutscene: a small toolkit for scripted, non-interactive scenes – a Cutscene (a gale.sequence.Sequence) of beats that show an image, play a frame-animation “video”, move an actor to a mark, switch an actor’s animation/pose, or show a line of dialogue, each one lasting either a fixed duration or until a specific input advances it (see gale.sequence.Step). Combine several beats to run at once with gale.sequence.StepGroup (e.g. a character moving while a line of dialogue plays over it).

See docs/examples/cutscene.rst for a walkthrough.

Author: Alejandro Mujica (aledrums@gmail.com)

class gale.cutscene.Cutscene(beats, actors=None, on_finished=None)[source]

Bases: Sequence

A cutscene: a Sequence of beats, plus the one bit of bookkeeping that’s specific to cutscenes rather than sequences in general – ticking/rendering any actors involved every frame so they keep animating even on beats that don’t otherwise touch them (a character idling in the background while another one is talking, for instance).

Usage example:

cutscene = Cutscene(
[

MoveActor(hero, (400, 200), duration=1.5), Dialogue(“Hero”, “This way!”, font, advance_on_input=”confirm”),

], actors=[hero], on_finished=lambda: state_machine.change(“play”),

)

# In the game loop: cutscene.update(dt) cutscene.render(surface) # And forward input from wherever your game dispatches it: cutscene.on_input(input_id, input_data)

Parameters:

  • beats (List[Step])

  • actors (Sequence[Any] | None)

  • on_finished (Callable[[], None] | None)

update(dt)[source]
Parameters:

dt (float) – Time elapsed (in seconds) since the last update.

Return type:

None

render(surface)[source]
Parameters:

surface (Surface) – The surface to draw on.

Return type:

None

class gale.cutscene.Dialogue(speaker, text, font, box_rect=None, text_color=(255, 255, 255), speaker_color=(255, 220, 120), box_color=(20, 20, 20), **kwargs)[source]

Bases: Step

Shows a speaker name and a line of text in a simple box until this step completes – usually via advance_on_input, the classic “press a key to continue” dialogue box, though duration works too for an auto-advancing line. Draws a plain rectangle behind the text by default; override render (or subclass) for a game’s own dialogue box art/gale.ui widgets instead.

Usage example:

Dialogue(“Elder”, “The forest holds many secrets…”, font, advance_on_input=”confirm”)

Parameters:

  • speaker (str)

  • text (str)

  • font (Font)

  • box_rect (Rect | None)

  • text_color (Any)

  • speaker_color (Any)

  • box_color (Any)

  • kwargs (Any)

render(surface)[source]

Override to draw whatever this step shows while active.

Parameters:

surface (Surface) – The surface to draw on.

Return type:

None

class gale.cutscene.MoveActor(actor, target, duration, **kwargs)[source]

Bases: Step

Moves actor.position linearly from wherever it is when this step becomes active to target, over duration seconds – the classic “walk to the mark” cutscene beat. actor is duck-typed: any object exposing a mutable, pygame.Vector2-compatible .position works (an Agent, a custom Player class, …), so this plugs into whatever character class the game already has without gale.cutscene needing to know its shape.

Usage example:

MoveActor(hero, target=(400, 200), duration=1.5)

Parameters:

  • actor (Any)

  • target (Tuple[float, float])

  • duration (float)

  • kwargs (Any)

enter(*args, **kwargs)[source]

Called once when the Sequence makes this step the active one. Resets the bookkeeping duration/advance_on_input rely on.

Parameters:

  • kwargs (Any) – Accepted for subclasses that need extra setup data; unused by the base implementation.

  • args (Any)

  • kwargs

Return type:

None

update(dt)[source]

Override to do this step’s per-frame work. Called every tick while this step is active, after elapsed has already been advanced by dt.

Parameters:

dt (float) – Time elapsed (in seconds) since the last update.

Return type:

None

class gale.cutscene.PlayAnimation(animation, position=(0, 0), **kwargs)[source]

Bases: Step

Plays a gale.animation.Animation as this step’s content – gale’s stand-in for “play a video”. Deliberately not real video-codec (mp4/webm) playback: gale never depends on a decoder library (ffmpeg, OpenCV, …), the same way gale.tilemap never depends on gale.physics. Pre-render the real footage as a frame sequence (most video editors, and ffmpeg itself, can export a PNG-per-frame sequence) and load those the same way any other sprite animation would.

Complete once the animation runs out of loops, or via duration/advance_on_input if it loops forever (loops=None) and only those should end it.

Usage example:

frames = [pygame.image.load(f”intro_{i:03d}.png”) for i in range(90)] PlayAnimation(Animation(frames, time_interval=1 / 30, loops=1))

Parameters:

  • animation (Animation)

  • position (Tuple[float, float])

  • kwargs (Any)

enter(*args, **kwargs)[source]

Called once when the Sequence makes this step the active one. Resets the bookkeeping duration/advance_on_input rely on.

Parameters:

  • kwargs (Any) – Accepted for subclasses that need extra setup data; unused by the base implementation.

  • args (Any)

  • kwargs

Return type:

None

update(dt)[source]

Override to do this step’s per-frame work. Called every tick while this step is active, after elapsed has already been advanced by dt.

Parameters:

dt (float) – Time elapsed (in seconds) since the last update.

Return type:

None

render(surface)[source]

Override to draw whatever this step shows while active.

Parameters:

surface (Surface) – The surface to draw on.

Return type:

None

is_complete()[source]
Returns:

Whether this step is done and the Sequence should move to the next one. The default implementation is True once duration has elapsed or advance_on_input has been pressed, and False otherwise – override (calling super() too, if duration/advance_on_input should still apply) to add a custom condition.

Return type:

bool

class gale.cutscene.SetActorAnimation(actor, animation, **kwargs)[source]

Bases: Step

Switches actor.animation to a different gale.animation.Animation (a pose/expression change, e.g. “surprised” instead of “idle”), then completes right away, unless duration/advance_on_input say otherwise. actor is duck-typed the same way MoveActor’s is: any object with a settable .animation attribute.

Usage example:

SetActorAnimation(hero, surprised_animation)

Parameters:

  • actor (Any)

  • animation (Animation)

  • kwargs (Any)

enter(*args, **kwargs)[source]

Called once when the Sequence makes this step the active one. Resets the bookkeeping duration/advance_on_input rely on.

Parameters:

  • kwargs (Any) – Accepted for subclasses that need extra setup data; unused by the base implementation.

  • args (Any)

  • kwargs

Return type:

None

is_complete()[source]
Returns:

Whether this step is done and the Sequence should move to the next one. The default implementation is True once duration has elapsed or advance_on_input has been pressed, and False otherwise – override (calling super() too, if duration/advance_on_input should still apply) to add a custom condition.

Return type:

bool

class gale.cutscene.ShowImage(image, position=(0, 0), **kwargs)[source]

Bases: Step

Displays a single image (a title card, a still illustration for a story beat, …) until this step completes.

Usage example:

ShowImage(pygame.image.load(“chapter_1.png”), duration=3.0, advance_on_input=”confirm”)

Parameters:

  • image (Surface)

  • position (Tuple[float, float])

  • kwargs (Any)

render(surface)[source]

Override to draw whatever this step shows while active.

Parameters:

surface (Surface) – The surface to draw on.

Return type:

None

class gale.cutscene.Wait(duration=None, advance_on_input=None)[source]

Bases: Step

Does nothing on its own – a pure pause. Useful inside a gale.sequence.StepGroup to give the group itself a duration/advance_on_input distinct from its children’s, or on its own as a beat with nothing to show (“hold on black for half a second”).

Parameters:

  • duration (float | None)

  • advance_on_input (str | None)

Submodules