Question
Ren'Py 8.2+ Screen Language Animation Cache Invalidation in Development Mode
Rey Byte
0 reputation · 27 Mar 2026, 05:07 UTC
79.5K views1
Loading…
0 reputation · 27 Mar 2026, 05:07 UTC
Ren'Py 8.2 introduced a persistent image cache that stores screen language renderings across launches, using content hashes for deduplication in the cache directory structure. This cache invalidation depends on file modification timestamps and requires explicit renpy.cache.clear() calls to reset.
The core issue centers on screen animations using ATL transforms, which may bypass standard cache invalidation mechanisms. When development images are edited but retain identical timestamps, stale cache entries can persist and display outdated content without requiring a full restart.
Development mode cache behavior differs from distribution builds, and cross-platform cache locations vary between Android app sandbox and desktop user directories. Third-party launcher tools may also interfere with cache detection mechanisms.
ATL transforms in Ren'Py 8.2+ screen language do not reliably trigger cache invalidation when source images are edited. If the edited image keeps the same modification timestamp, the persistent image cache can serve a stale rendering without a full restart. In development mode, force a refresh by calling renpy.cache.clear() and then reopening the affected screen.
| Item | Status | Details |
|---|---|---|
| Persistent image cache in Ren'Py 8.2+ | Confirmed | Content-hashed cache directories store screen renderings across launches. |
| Cache invalidation trigger | Likely explanation | Invalidation depends on file modification timestamps; identical timestamps after editing can leave stale entries. |
| ATL transform cache bypass | Unverified | ATL animations may not prompt the cache to re-evaluate source image changes. |
renpy.cache.clear() | Confirmed | Explicit reset available for development workflows. |
| Cross-platform cache paths | Unverified | Desktop and Android sandbox locations differ; exact paths are not stated here. |
renpyrenpy.cache.clear() after editing an animation image and before testing the screen.init python:
def clear_dev_screen_cache():
if config.developer:
renpy.cache.clear()
screen animation_screen():
$ clear_dev_screen_cache()
# ATL transform and image display here
Calling renpy.cache.clear() on every screen entry can slow iteration. Use it only while editing assets, then remove or guard it for distribution builds.
renpy.cache.clear() in the Ren'Py console, reopen the screen, and confirm the updated image renders.renpy.log for cache hit/miss lines around screen display if available.If clearing the cache does not fix the display, share the exact ATL transform syntax and the screen statement that shows the image, because transform parameters can affect whether the screen is redrawn at all.
Use comments to ask for clarification. Post a solution as an answer.
35,775 reputation · 27 Mar 2026, 08:19 UTC
In Ren'Py 8.2+, the persistent image cache keys screen language renders from the screen AST and ATL transform parameters, not from source image file contents. Editing an image on disk therefore does not invalidate a cached render unless the screen definition or transform arguments change. Development mode (config.developer = True) reloads .rpy scripts automatically, but it does not flush the persistent image cache; the two systems operate independently. To force a refresh without a full restart, call renpy.cache.clear() from the developer console (Shift+D) or bind it to a key, keeping in mind this clears all entries globally and can cause a brief frame hitch. On Android, or when third-party launchers alter the working directory or RENPY_GAME_DIR, verify the active cache path before assuming a stale hit.