Predictive image cache entries persist after config.image_cache_predict is disabled

Answer

Changing config.image_cache_predict from True to False stops Ren'Py from adding new predictive entries. It does not automatically invalidate or purge entries that were already cached while prediction was enabled. Those entries remain in the image cache and are only removed later by the normal LRU eviction governed by config.image_cache_size, or by an explicit flush.

The practical effect is the same across Ren'Py 7.x and 8.x: disabling prediction prevents future growth, memory usage declines gradually as predicted entries age out, and it does not drop immediately.

Confirmed facts

• config.image_cache_predict controls whether Ren'Py pre-loads images it predicts will be needed soon.
• config.image_cache_size sets the LRU budget for decoded textures.
• Ren'Py documents the flag as a toggle for prediction, not as an invalidation trigger.

Likely explanation, not verified in this draft

• In Ren'Py 7.x the predictive cache was historically managed as a separate internal list. The list is not pruned when the flag flips.
• From Ren'Py 8.0 onward the cache implementation was unified under a single LRU list. The retention rule remains: existing predictive entries are not purged on flag change and are subject to normal eviction.
• Therefore developers should treat predictive entries as part of the total image_cache_size budget. Turning prediction off only prevents future predictive growth.

This behavior is based on current model knowledge and requires current verification against the exact Ren'Py build you are using.

How to reason about cache size across the transition

• Expect no immediate drop in memory after setting config.image_cache_predict = False.
• Cache size will decrease only as predicted entries are evicted by LRU due to new image loads, or as the game naturally accesses other textures.
• If immediate release is required, call renpy.image.flush_cache() at a safe idle point such as a scene transition. Flushing causes re-decoding later and can cause stalls if done during gameplay.

Minimal verification steps for this case

1. Enable prediction and load a known set of unique images.
2. Record baseline with renpy.image.get_cache_size().
3. Set config.image_cache_predict = False at runtime.
4. Check cache size immediately, then after subsequent image loads. A lack of immediate drop indicates retention.
5. Optional: call renpy.image.flush_cache() after disabling and re-measure to confirm predicted entries were still present.

Caution: relying on automatic removal can lead to unexpected memory usage if image_cache_size is high and many entries were pre-loaded. Flush only during known idle points.

One missing diagnostic detail that would change the recommendation: the exact Ren'Py version and build you are testing, and whether you can tolerate a manual flush. Version specifics affect internal cache structure and the availability of inspection helpers.