Ren'Py Gallery pagination: bounding page contents and building navigation without a built-in widget

Direct Answer

Ren'Py's Gallery class has no pagination widget. The documented pattern is to call Gallery.get_page(page_name), which returns only the displayables for that page (already filtered by unlock/condition logic), and render that list in a screen driven by a normal variable holding the current page name. For several hundred entries, manual pagination — creating displayables only for the active page — is materially cheaper than a single vpgrid because vpgrid instantiates every child at screen-build time and does not virtualize. Page-switch state belongs in a normal (non-persistent) variable; persistent data is for cross-session unlocks, not UI navigation.

Rendering Only the Current Page

Define a screen that reads a variable (e.g., gallery_page) and builds its grid from gallery.get_page(gallery_page):

screen gallery_view():
    default gallery_page = gallery.get_pages()[0]
    $ page_buttons = gallery.get_page(gallery_page)
    grid 3 4:
        for btn in page_buttons:
            add btn
    # navigation buttons below
    hbox:
        textbutton "Previous" action SetScreenVariable("gallery_page", prev_page(gallery_page))
        textbutton "Next" action SetScreenVariable("gallery_page", next_page(gallery_page))

gallery.get_pages() returns the ordered list of page names, so prev_page/next_page can clamp to the first/last index. SetScreenVariable updates the variable and refreshes the screen without a full interaction restart.

Why Manual Pagination Beats vpgrid for Hundreds of Entries

vpgrid builds every child displayable when the screen is shown. With 300+ gallery buttons (each potentially wrapping a large image), screen-build time and texture memory spike noticeably. Manual pagination limits the live displayable count to one page (e.g., 12–20 items), keeping build time near-constant regardless of total gallery size. The trade-off is you must implement prev/next logic yourself, but the API surface is small: get_pages(), get_page(), and a variable update.

Where to Store the Current Page

• Normal variable (default in a screen or a default statement in python early block) — resets on game restart, which is usually the desired UX.
• Persistent only if you want the player to return to the last viewed page after quitting and reloading. Copy the variable into persistent on page change: action [SetScreenVariable("gallery_page", next_page), SetVariable("persistent.last_gallery_page", next_page)].

Do not store page index in persistent by default; unlock gating already lives in persistent, and mixing UI navigation state with progress data complicates save/load reasoning.

Practical Checks

1. Create a minimal gallery with 3 pages × 10 buttons, unlock a subset, and verify get_page() returns only unlocked buttons for the active page.
2. Profile screen-build time with renpy.profile_screen() comparing one vpgrid of all entries vs. manual pagination showing 12 entries.
3. Load a save, change page, save, quit, reload — confirm the page resets unless you explicitly wrote it to persistent.

One Diagnostic Detail

What is the typical number of entries per page and the approximate image dimensions? If pages hold 50+ items or thumbnails are full-resolution, texture memory may still pressure the GPU even with pagination, and you may need downsampled thumbnails (im.Data/im.Memory) regardless of the pagination strategy.