gale.cutscene.actions module

This file contains the concrete cutscene beats gale.cutscene ships with: Wait (a pure pause), ShowImage, PlayAnimation (a “video” – see its own docstring for why that’s a deliberate, dependency-free choice), MoveActor, SetActorAnimation, and Dialogue. Every one of them is a gale.sequence.Step, so duration/advance_on_input (and gale.sequence.StepGroup, for running several of them side by side) all just work. Write your own Step subclasses for anything game-specific a cutscene needs beyond these.

Author: Alejandro Mujica (aledrums@gmail.com)

class gale.cutscene.actions.Wait(duration=None, advance_on_input=None)

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)

class gale.cutscene.actions.ShowImage(image, position=(0, 0), **kwargs)

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)

Override to draw whatever this step shows while active.

Parameters:

surface (Surface) – The surface to draw on.

Return type:

None

class gale.cutscene.actions.PlayAnimation(animation, position=(0, 0), **kwargs)

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)

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)

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)

Override to draw whatever this step shows while active.

Parameters:

surface (Surface) – The surface to draw on.

Return type:

None

is_complete()

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.actions.MoveActor(actor, target, duration, **kwargs)

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)

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)

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.actions.SetActorAnimation(actor, animation, **kwargs)

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)

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()

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.actions.Dialogue(speaker, text, font, box_rect=None, text_color=(255, 255, 255), speaker_color=(255, 220, 120), box_color=(20, 20, 20), **kwargs)

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)

Override to draw whatever this step shows while active.

Parameters:

surface (Surface) – The surface to draw on.

Return type:

None