AGS 4: AnimatedOverlay

[ivan-mogilko]

Resolve #2811

Implement a new type called AnimatedOverlay which is an extension of Overlay. I decided to go with a separate type, because there's a concern about keeping existing Overlay simple. Also, there's a number of cases where overlay is returned for a built-in object (such as speech text, portrait, etc), which probably should not have any extra functionalities in them.

AnimatedOverlay is declared as:

builtin managed struct AnimatedOverlay extends Overlay
{
  /// Creates a AnimatedOverlay object on the screen layer, optionally using a initial sprite
  import static AnimatedOverlay* CreateAnimated(int x, int y, int slot = 0, bool pauseWithGame = true); // $AUTOCOMPLETESTATICONLY$
  /// Creates a AnimatedOverlay object on the room layer, optionally using a initial sprite
  import static AnimatedOverlay* CreateRoomAnimated(int x, int y, int slot = 0, bool pauseWithGame = true); // $AUTOCOMPLETESTATICONLY$
  /// Animates the overlay using the specified view loop.
  import void Animate(int view, int loop, int delay, RepeatStyle=eOnce, BlockingStyle=eNoBlock, Direction=eForwards, int frame=0, int volume=100);
  /// Gets whether the overlay is currently animating.
  import readonly attribute bool Animating;
  /// Gets the current frame number during an animation.
  import readonly attribute int  Frame;
  /// Gets the current loop number during an animation.
  import readonly attribute int  Loop;
  /// Gets whether the overlay's animation is paused when the game is paused.
  import readonly attribute bool PauseWithGame;
  /// Gets the current view number during an animation.
  import readonly attribute int  View;
};

The Animate command and properties are mostly mimicking existing Button example.
The standing out parameter is "PauseWithGame". While Button animation do not pause when the game gets paused, because the GUI is not paused at all, but Overlays may be used for various purposes, and be created in room or screen layer. So I decided to make this a parameter passed when creating animated overlay.

Internally, AnimatedOverlay consists of a normal overlay itself, and a additional object which describes animation and controls its flow, connecting to overlay. The connection between these two is done using reference tables. This ensures that overlays own update is not affected performance-wise. Overlay animations are updated separately, and they just change referenced overlay's graphic value.

I'd like to hear any comments on the API. For instance, I might perhaps make "pause with gui" a enum, for better clarity.

[ericoporto]

Hey, I think the ccAddExternalFunctions(overlay_api); in ac/overlay.cpp is missing now, which causes the unresolved imports in the GHA pipeline.

About the API, the pause sensitivity is with the PauseGame () function and with the GUIs that have the config "when visible pause game" only?

[ivan-mogilko]

About the API, the pause sensitivity is with the PauseGame () function and with the GUIs that have the config "when visible pause game" only?

Yes. This parameter can be used to keep animated overlay on while the "pausing" guis are displayed, because normally animations are not updated when the game is paused.