Using layers in Ren'Py

Sometimes you might want some custom layers in Ren'Py.

There is some information over in the documentation here: https://www.renpy.org/doc/html/displaying_images.html#layer

It explains what the 4 default layers (master, transient, screens and overlay) are for and the order they are in.

To add some additional ones you'll want to add a line of code to the bottom of the options.rpy file, like this:

    config.layers = [ 'zero', 'master', 'transient', 'belowmid', 'midlayer', 'abovemid', 'screens', 'overlay']
 
That gives us another four layers to play with, of course you can have more or less and in any order, just remember to test things to make sure you have the layers in the order you want!

I put a new layer called zero right at the bottom, I typically fill this with a solid colour so that the player never accidentally sees the default transparent background. Then the others that I will use for art / displayables are between transient and screens, you might find it better to have some below transient, just experiment to see what happens where!

Here is a script.rpy file as an example of showing things on custom layers:

image nrblack = "#181818"

image skyani:
    "sky1.png" with Dissolve(1.5, alpha=True)
    pause 1.5
    "sky2.png" with Dissolve(1.5, alpha=True)
    pause 1.5
    "sky3.png" with Dissolve(1.5, alpha=True)
    pause 1.5
    "sky2.png" with Dissolve(1.5, alpha=True)
    pause 1.5
    repeat 20

label start:

    show nrblack onlayer zero

    show skyani onlayer belowmid with dissolve
    centered "A simple animated sky background."
    centered "Followed by some midground."
    show midground onlayer midlayer with dissolve
    centered "Finally the foreground."
    show foreground onlayer abovemid with dissolve

    pause

    centered "Now we should hide all of the relevent layers to get ready for the next scene..."

    hide skyani onlayer belowmid
    hide midground onlayer midlayer
    hide foreground onlayer abovemid with dissolve

    "That's it!"

    return


The main thing to note is the onlayer followed by the custom layer name which you'll need on both the show and hide statements.

The two images that aren't defined (midground and foreground) are files names midground.png and foreground.png which are in the images folder, Ren'Py picks these up automatically so they don't need to be manually defined!

This particular example could more easily be achieved just by using show and letting Ren'Py put them in the order they are declared onto the screen, but if you're reading this you probably have run into some case where the standard behaviour isn't enough for your needs and layers might be useful!

Don't forget to hide the images on the layers when you are done with them! XD

Gif:

As a quick aside you may have noticed that the sky animation is set to repeat 20 times, instead of infinitely (repeat). I have started doing this mainly because I noticed quite a lot of system resources being used when multiple infinite animations are displayed at once (as you can imagine!). I'm still trying to get my head around the best practices for being efficient with animations in terms of system resource, so I can't offer much advice in that area, but with only one animation running at a time you shouldn't have any problems!