Version 0.18.0

Hello everyone, it's been quite a while since I posted an update to the pink engine. Certain developments in my own personal life (the good kind, don't worry) have kept me distracted lately. Still, I did make some neat new features for you.

Overlays

The major focus of this update is the overlay system, which provides an interface for putting images, colors or text over your pink engine screen. This can be used to create fade effects, simulate weather effects, add UI elements, show images in cutscenes, etc. The brand new test room E29 demonstrates a wide range of overlay effects for your inspiration. 

New OTM map Functions for Overlays

• add_overlay_image(image_name: str, fade_time: float = 0.0, alpha: float = 1.0, x: int = 0, y: int = 0, width: int = renpy.store.config.screen_width, height: int = renpy.store.config.screen_height, target_x: Optional[int] = None, target_y: Optional[int] = None, target_width: Optional[int] = None,  target_height: Optional[int] = None, move_time: float = 0.0, consistent: bool = False, x_arc: int = 0, y_arc: int = 0
• add_overlay_text(text: str, fade_time: float = 0.0, alpha: float = 1.0, x: int = 0, y: int = 0, width: int = renpy.store.config.screen_width, height: int = renpy.store.config.screen_height, target_x: Optional[int] = None, target_y: Optional[int] = None, target_width: Optional[int] = None, target_height: Optional[int] = None, move_time: float = 0.0, consistent: bool = False, autosize: bool = True, x_arc: int = 0, y_arc: int = 0)
• add_overlay_solid(color: str, fade_time: float = 0.0, alpha: float = 1.0, x: int = 0, y: int = 0, width: int = renpy.store.config.screen_width, height: int = renpy.store.config.screen_height, target_x: Optional[int] = None, target_y: Optional[int] = None, target_width: Optional[int] = None, target_height: Optional[int] = None, move_time: float = 0.0, consistent: bool = False, x_arc: int = 0, y_arc: int = 0)
  • These three functions are used to add the three different kinds of Overlay. The first function adds an overlay that shows an image, the second function adds an overlay that shows text, the third function adds an overlay that shows a block of solid color. For each of the three types, the first argument is the content that should be displayed: A path to the image for the image overlay, a ren'py text string (which may include formatting and dynamic variables) for the text overlay, and a hex color string of the format '#rrggbb' for the solid overlay.
    
  • The fade_time argument is the amount of time in seconds it should take for the overlay to fade in
  • The alpha argument is the alpha (translucency) that the overlay should have at the end of the fade-in 
  • The x, y, width and height arguments are used to set the size and location of the overlay. By default, the overlay will occupy the entire screen.
  • The target_x, target_y, target_width and target_height arguments are used to create an overlay that appears while moving.
  • The x_arc and y_arc arguments adds parabolic arcs to the movement from the original dimensions to the target dimensions. They are measured in the maximum pixels added or subtracted to the normal movement during the arc.
  • The move_time argument is the amount of seconds it should take to transition from the original dimension variables to the target dimensional variables.
  • The consistent argument determines whether the overlay will persist between map switches. 
  • The autosize argument is exclusive to text overlays, and will make the overlay automatically match the dimensions of the text input, rather than the given dimensions. Whenever you change the underlying text, the overlay will recalculate its size.
  • Note that the add overlay functions each return the resulting overlay, so you can write something like `$ event_overlay_1 = pink_otm_current_map.add_overlay_solid('#00b000', 0.1, 0.5)`, and then call functions on event_overlay_1.
• remove_overlay(overlay: Overlay, fade_time: float = 0.0)
• remove_all_overlays(self, fade_time: float = 0.0)

Overlay Functions

These are functions on overlay objects

• set_alpha(alpha: float, fade_time: float = 0.0)
  • Sets the alpha on the overlay to the new value. The transition between the old alpha and the new alpha will take fade_time seconds.
• set_dimensions(x: Optional[int] = None, y: Optional[int] = None, width: Optional[int] = None, height: Optional[int] = None, move_time: float = 0.0, x_arc: int = 0, y_arc: int = 0)
  • Sets the dimensions on the overlay to the new value. The transition between the old dimensions and the new dimensions will take move_time seconds.
• set_image(self, image_name: str)
  • Only available to Image overlays, switches the overlay to a difference image.
• set_text(self, text: str)
  • Only available to text overlays, switches the overlay to a difference text.
• set_color(self, color: str, fade_time: float = 0.0)
  • Only available to color overlays, switches the overlay to a different color, taking a total of fade_time seconds to transition.

New Wait Conditions for Overlays

• add_alpha_wait(overlay: Overlay, alpha: Optional[float] = None)
  • Adds a wait for the overlay to have attained a certain alpha. If the alpha is set to None, will just wait for the alpha to have fully transitioned.
• add_overlay_movement_wait(overlay: Overlay, x: int = None, y: int = None, width: int = None, height: int = None)
  • Adds a wait for the overlay to have attained certain dimensions. If the values are set to None, will just wait for the alpha to have fully transitioned.

New Labels for Overlays

• pink_otm_fade_in(fade_time, color="#000000")
• pink_otm_fade_out(fade_time, color="#000000")
  • These are two labels you can use to easily fade in and fade out a solid block of color that occupies the entire screen.

It's recommended you use these new labels instead of standard ren'py Fade transitions if you wanna fade any objects in or out of a ren'py map. The reason for this is that the pink engine doesn't transition between non-dialogue lines, which means that an objects appearance or disappearance could be hard to match with the Fade effect. With overlays, this is not an issue. Rooms E16-E18 have been updated to use the new fade effect instead.

Screen Shakers

Since I was providing a counterpart to ren'py Fade transitions, I also added a counterpart to Ren'py shake effects, for use in pink engine cutscenes. The final interactive button in test room E29 will demonstrate this functionality.

New OTM map functions for screen shakers

• add_screen_shaker(duration: float, frequency: float, x_amp: int = 0, y_amp: int = 0, phase: float = 0.0)
  • Adds a screen shaking effect to the pink engine. Note that the screen shaking does not persist between maps. The shake function takes the form of a sine function, with separate amplitudes for the vertical and horizontal dimension. If you want more chaotic shaking, you can use multiple simultaneous screen shakers with different frequencies, amplitudes and phases.
  • Note that it's recommended you don't keep up the shake effect for very long, it can be quite nauseating if it persists.
• stop_shaking()
  • Stops all active shaking currently present on the map.

New OTM map Properties for screen shakers

• is_shaking
  • Returns True if any screen shake effects are currently active, False if not. 

Easier Event Waits

There were some complaints in the pink engine Discord that the event wait system was something of a hassle to use. I agreed, so added a set of simpler callable labels that should suffice for all but the most complex cutscene elements

New Labels for Easier waits

• pink_otm_movement_wait(*objects, max_time=None, completion_wait=0.0)
  • Waits for all the given objects to have finished moving, plus an additional completion_wait seconds. If a max_time is given, it will interrupt the wait after the given number of seconds have passed.
• pink_otm_zoom_wait(max_time=None, completion_wait=0.0)
  • Waits for all ongoing zooms to be completed, plus an additional completion_wait seconds. If a max_time is given, it will interrupt the wait after the given number of seconds have passed.
• pink_otm_overlay_alpha_wait(*overlays, max_time=None, completion_wait=0.0)
  • Waits for all the given overlays to have finished changing alpha, plus an additional completion_wait seconds. If a max_time is given, it will interrupt the wait after the given number of seconds have passed.
• pink_otm_overlay_movement_wait(*overlays, max_time=None, completion_wait=0.0)
  • Waits for all the given overlays to have finished moving, plus an additional completion_wait seconds. If a max_time is given, it will interrupt the wait after the given number of seconds have passed.

Dynamic nearest_neighbor

Rather than using Ren'py nearest_neighbor variable, pink engine maps now use their own variable, allowing you to enable it on pink engine maps while keeping it disabled for the rest of your visual novel. The new variable is called `pink_otm_nearest`. It's set with a default statement in orthogonal_tiled_map.rpy, rather than with a define statement, so you can change the value during gameplay if you want (useful if you transition from zoomed out gameplay to zoomed in gameplay).

Bug Fixes

There were certain circumstances under which the pink engine would use the wrong drawing order when two objects were placed off-grid and shared tiles on a dynamic layer. This has now been fixed.