Ren'Py Layered Image Masks

Overview

Have you ever wanted to have a way to easily mask out parts of your sprites, perhaps to display them as a side image or as a cut-in to indicate the character is off-screen? This short, simple code will let you do that by allowing you to easily apply an AlphaMask to a layered image.

Masked images can be used for a variety of purposes, including:

• Sprite cut-ins
  • This can be useful to communicate a sprite's expression in a variety of circumstances where the full sprite may not be suitable e.g. for phone call dialogue, dialogue where the character is not within the POV character's view, to prevent sprite crowding, for dialogue on backgrounds like the inside of cars or top-down views, tutorials, snappy close-ups, etc.
• Side images
• Custom dialogue systems (e.g. speech bubbles, comic book-style presentation, phone message screens or social media UI)

A tutorial for how to use this tool is on my website here: How to Mask Images in Ren'Py

Description

As of Ren'Py engine version 7.6/8.1, you cannot apply an AlphaMask to a layered image without creating a separate AlphaMask for every layered image attribute combination. This code adds a class similar to LayeredImageProxy which will allow you to input the name of a layered image as well as an image to use for the mask shape (and optionally a foreground and/or background to display with the sprite). You will then be able to display the masked image with any combination of attributes the layered image would normally take.

Instructions

The free version includes a LayeredImageMask displayable class, along with explanatory comments and an example declaration. Add the file alphamask_layeredimage.rpy to your project and then you can declare LayeredImageMask displayables for your layered images.

There is also an extra file available for a minimum donation if you have some extra money to spare. This file has several additional features, described in the following section. You will add layered_image_mask_tips.rpy to your project, and then you can read through the examples and adjust the code there to your liking.

Features

Free Version

Extra Paid File

LayeredImageMask displayable class Explanatory comments Example declaration

Additional example declarations Tips and example code showing how to reduce repeated code for similar masked image declarations Optional special code which will auto-declare masked versions of all of the layered images (or layered image proxies) in your game. You will pick an attribute name (e.g. cutin) and if you have an image layeredimage eileen sitting, then a masked version layeredimage eileen sitting cutin will be declared automatically. Optional special code to declare a layer which the masked images should automatically appear on. Useful especially if you use camera movements, and character cut-ins should "stick" to the camera rather than act as part of the physical scene. Optional special code to remove the default transform from being applied to an image with the mask attribute, which means you can set up a position for the masked images in the declaration (e.g. top right corner) and that will be its default position.

Use

Sample set up code:

image eileen cutin = LayeredImageMask("eileen", Transform(crop=(230, 0, 564, 953)), mask="gui/mask.png")

This will allow you to show images like show eileen cutin happy_eyes and modify the expression however you like as you would a regular sprite.

Compatibility

This code has been tested for compatibility with Ren'Py 7.5-7.6 and Ren'Py 8.0-8.2. It is expected to be compatible with earlier Ren'Py versions which include LayeredImageProxy.

This script is also forwards-compatible - if Ren'Py builds AlphaMask + layered image functionality into later versions of the engine, and you would like to replace your declaration with the official engine version, you will only need to update your initial image eileen cutin declaration, not any of your script. I plan to maintain this code at least until it becomes an engine feature.

Terms of Use

Both the free version and any paid addons have the same terms of use.

You may:

• Use this code in commercial and noncommercial projects, provided it is packaged into an archived .rpa file. The code to do so is included in the code file.
• Modify and edit the code to suit your needs

You may not:

• Resell all or part of the code as-is or sell it with modifications
• Release any projects created using this code without providing attribution

Attribution must be credited as Feniks, with a link either to the page with this code or to https://feniksdev.com

Final Notes

I try to ensure that this code remains up-to-date with modern Ren'Py versions. If you encounter an issue with the code after an engine update, you can use the forums below to report the issue. You can also report any bugs you encounter in the forums.

For more Ren'Py tutorials, check out my website https://feniksdev.com - A tutorial specifically on how to use this tool, How to Mask Images in Ren'Py, is available now!

Credits

• Sylvie sprite by Deji from The Question (not included in the download)
• Background art by Mugenjoncel from The Question (not included in the download)
• Screenshot with Raenelle and Sebastien from Reanimation Scheme by Wind Chimes Games