Ren'Py Gallery Framework

This framework (BobCGallery) is intended to be an easy way to add a CG gallery to your Ren'Py game, potentially with (almost) no code! It also provides lint validation for your game script's use of gallery images.

Directions for use are included in the source file, or follow along below!

This framework is provided under the Unlicense and released into the public domain, and no attribution or further licensing is necessary. Feel free to modify it to suit your use case! (If you do wish to attribute me, a link to bobcgames.com would be greatly appreciated.)

This framework is provided "as is" without warranty of any kind. Basic help can be provided in the project discussion board, or visit the Ren'Py Discord server for more complex customizations.

Also check out my other Ren'Py Frameworks, Tools, and Game Dev Resources!

---

How To Use

The TL;DR is: Download the file, follow the instructions for adding images to the framework, and show (or just unlock) CGs in your game!

Download The File

To get started, download the 0bobcgallery.rpy file and drop it into the game/ folder of your Ren'Py game project.

(Do not rename this file, or functionality may not behave properly, or your game may not run.)

(Optional) Add Images To Auto-Import

You can add images to the framework without writing (or updating) a single line of code!

In the /images directory of your game, create a folder named bobcgallery and add CG images (jpg, png, or webp) into that folder (or a folder within that folder).

For example, add /images/bobcgallery/cg1.png and /images/bobcgallery/cgs/cg2.jpg

When images are auto-imported this way, their name is the filename not including the extension. For example, cg2.jpg has the name cg2
(Image names will become important when you actually unlock and show images.)

This auto-import functionality will only work with physical image files, and you cannot include layeredimage or other Ren'Py-code-defined images (such as Composite images) in this way. However, you can include them manually...

If you do not wish to auto-import any images, it is recommended that you update the BOBCGALLERY_AUTOIMPORT variable to False instead of True.

The framework will only import jpg, png, and webp images in the bobcgallery folder. Any other files in the bobcgallery folder will be reported as lint errors.

(Optional) Manually Add Images To The Framework

If you have images (layeredimage, Composite, etc) that cannot be auto-imported as files, or if you simply don't want to auto-import, you can manually add images to the framework.

Update the BOBCGALLERY_MANUAL_CGS tuple in code with additional values for each image you wish to add, in the form (name, image)

For example, you can add the image /images/cgs/my_cg1.png either with
("cg1", "my_cg1"),
or
("cg1", "images/cgs/my_cg1.png"),

For example, you can add a layeredimage bob_cg with an attribute happy with
("bob cg", "bob_cg happy"),

For example, you can add an image defined as image eileen_coffee = Composite(...) with
("eileen coffee", "eileen_coffee"),

With all of the above examples added, your code should look something like:

define BOBCGALLERY_MANUAL_CGS = (
    ("cg1", "images/cgs/my_cg1.png"),
    ("bob cg", "bob_cg happy"),
    ("eileen coffee", "eileen_coffee"),
    )

(The first value is the name you'll use to refer to the image, and you can name images anything you'd like, although I recommend alphanumeric values. Image names will become important when you actually unlock and show images)

The framework should raise fairly descriptive errors during game launch if you configure something improperly in here. Start your game often as you're adding achievements if you're worried about the formatting.

(If you're pretty sure you haven't made a formatting error or typoed an image name, but you're getting startup problems anyway, set BOBCGALLERY_VALIDATE_MANUAL_CGS to False and let me know about the problem in the discussion board below.)

Note: Manually adding images is optional if you auto-import, and auto-import is optional if you're manually adding images. But you must do one or the other, or the framework will crash your game on startup with an error that no images have been added to the framework.

(Optional) Manually Add Images With Variants To The Framework

The framework also supports CGs with variants! Variant CGs must be manually defined (rather than autoimported). For example, for a CG of Eileen drinking coffee with three variants, you could define it like this:

define BOBCGALLERY_MANUAL_CGS = (
    ("eileen coffee", "eileen_coffee1", "eileen_coffee2", "eileen_coffee3"),
    )

Once defined, you can reference the entire set of CGs (with variants) by the defined name (eileen coffee, in this case).

(Optional) Handle Non-Screen-Size Images

If all of your images are the full size of the screen, or at least are proportional to the screen (16:9), you can set

BOBCGALLERY_USE_NON_SCREEN_IMGS = False
to simplify thumbnail generation and rendering. This will reduce the impact of the framework on your game's rendering and generally improve performance.

Setting this to False when you have non-proportional images will cause them to be stretched in their thumbnail views (although they should still display properly when viewed from the gallery).

Add The Gallery Link To The Menu

Open your screens.rpy file and search for screen navigation():

On that screen, add a new text button for the gallery so the code looks like this:

        textbutton _("Preferences") action ShowMenu("preferences")
        textbutton _("Gallery") action ShowMenu("bobcgallery")

This is the only code change that you must make.

You can optionally customize the gallery screen or the screen that actually shows CGs, but this is entirely optional.

Show (Or Unlock) Images During Gameplay

Now that you have a gallery set up, with a bunch of named images, you can show them during gameplay, or simply unlock them without displaying them (in case you wanted to show the image manually some other way, such as as a sprite).

To show an image and unlock it at the same time, use the gallery command. For example, for an image named cg0, you can show (and unlock it in the gallery) with:

label start:
    scene bg room
    show eileen happy
    e "You've created a new Ren'py game."
    gallery cg0
    e "Once you add a story, pictures, and music, you can release it to the world!"
    return

(If you're doing more complicated things with Python code, you can also directly show and unlock the image via a function call as bobcgallery_unlockshow("cg0"))

Note: When you show a CG with variants using the gallery command, it will immediately show all variants, one after the other. You must instead manually show each image if you do not want this behavior.

If you only want to unlock an image without showing it at that point, you can use the galleryunlock command. For example, for an image named eileen happy, you can unlock it in the gallery with:

label start:
    scene bg room
    show eileen happy
    e "You've created a new Ren'py game."
    galleryunlock eileen happy
    e "Once you add a story, pictures, and music, you can release it to the world!"
    return

(If you're doing more complicated things with Python code, you can also directly unlock the image via a function call as bobcgallery_unlockonly("eileen happy"))

Remember that the names of images you use with the gallery and galleryunlock commands must have been added to the framework, either by auto-importing or by manually adding them to the BOBCGALLERY_MANUAL_CGS list.

---

Frequently Asked Questions

(For some definition of "Frequently Asked")

Shouldn't I type $ gallery cg0?

No! Starting a line with $ in Ren'Py tells the engine to interpret that line as Python code.

In this case, we have defined a creator-defined statement (CDS) for achievements instead, which allows you grant achievements more directly in your game's script. We use this instead of a python function invocation to grant achievements.

The benefits of CDSes are many, but in particular, CDSes can be validated as part of the lint process (as the achieve command here is!) while Python code cannot be, and will instead fail at runtime.

(If you aren't already, you should be in the habit of regularly running lint on your game via the Ren'Py launcher, as it will help detect many problems that would either crash your game, or cause unintended behavior.)

What does "Flatten" do?

Basically, Ren'Py will normally apply a transform separately to each part of a composite image, whether it's a Composite or a layeredimage. Because of this, alpha transforms can result in strange opacities where layers overlap each other.

This effect is normally not very noticeable, but with larger thumbnails, lower alpha settings, or images with many layers, the effect can be distracting.

Ren'Py offers a Flatten displayable that forces transforms to treat the entire composite as a single image, but it is an expensive operation to perform. For that reason, we do not default the flatten functionality on for the gallery framework.