From 39a8611910c4b12e8131e7be4eefd492762c3cb7 Mon Sep 17 00:00:00 2001
From: HEIHUAa <112499486+HEIHUAa@users.noreply.github.com>
Date: Sat, 22 Aug 2026 12:21:32 +0800
Subject: [PATCH 1/2] Flags.CLEAR_ASSET_CACHE_ON_STATE_SWITCH

---
 source/funkin/backend/system/Flags.hx         |  8 ++++
 .../backend/system/modules/FunkinCache.hx     | 47 +++++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/source/funkin/backend/system/Flags.hx b/source/funkin/backend/system/Flags.hx
index 9003cf21a9..2d1a7eb26b 100644
--- a/source/funkin/backend/system/Flags.hx
+++ b/source/funkin/backend/system/Flags.hx
@@ -227,6 +227,14 @@ class Flags {
 	public static var DISABLE_LANGUAGES:Bool = false;
 	public static var DISABLE_AUTOUPDATER:Bool = false;
 
+	/**
+	 * DEBUG ONLY — REMEMBER TO REMOVE THIS BEFORE SHIPPING YOUR MOD!
+	 * When enabled, every asset cache (textures, sounds, fonts, shaders)
+	 * is cleared on every state switch/reload, forcing a re-fetch from disk as if the game just started.
+	 * This flag exists purely for debugging stale asset issues and must be deleted from release builds.
+	 */
+	public static var CLEAR_ASSET_CACHE_ON_STATE_SWITCH:Bool = false;
+
 	@:also(funkin.backend.MusicBeatTransition.script)
 	public static var DEFAULT_TRANSITION_SCRIPT:String = "";
 	@:also(funkin.menus.PauseSubState.script)
diff --git a/source/funkin/backend/system/modules/FunkinCache.hx b/source/funkin/backend/system/modules/FunkinCache.hx
index e1d8283497..8f650b5543 100644
--- a/source/funkin/backend/system/modules/FunkinCache.hx
+++ b/source/funkin/backend/system/modules/FunkinCache.hx
@@ -42,6 +42,35 @@ class FunkinCache extends AssetCache {
 		FlxG.signals.postStateSwitch.add(function() {
 			instance.clearSecondLayer();
 		});
+
+		FlxG.signals.preStateCreate.add(function(_) {
+			if (Flags.CLEAR_ASSET_CACHE_ON_STATE_SWITCH)
+				clearAllCaches();
+		});
+	}
+
+	/**
+		Clears every asset cache (textures, sounds, fonts, shader programs) so everything is re-fetched from disk, as if the game just started.
+	**/
+	public static function clearAllCaches() {
+		@:privateAccess
+		for (key in [for (k in FlxG.bitmap._cache.keys()) k]) {
+			var graphic = FlxG.bitmap._cache.get(key);
+			if (graphic != null && graphic.assetsKey != null)
+				FlxG.bitmap.removeByKey(key);
+		}
+		if (instance != null)
+			instance.clearAll();
+		clearShaderProgramCache();
+	}
+
+	/**
+		Clears openfl's compiled shader program cache, so edited shaders get recompiled on next use.
+	**/
+	public static function clearShaderProgramCache() {
+		@:privateAccess
+		if (FlxG.stage != null && FlxG.stage.context3D != null && FlxG.stage.context3D.__programs != null)
+			FlxG.stage.context3D.__programs.clear();
 	}
 
 	public function moveToSecondLayer() {
@@ -53,6 +82,24 @@ class FunkinCache extends AssetCache {
 		sound = [];
 	}
 
+	/**
+		Completely clears both cache layers (including lime's own asset cache),
+	**/
+	public function clearAll() {
+		for (k in [for (k in bitmapData.keys()) k])
+			removeBitmapData(k);
+		for (k in [for (k in bitmapData2.keys()) k])
+			removeBitmapData(k);
+		for (k in [for (k in font.keys()) k])
+			removeFont(k);
+		for (k in [for (k in font2.keys()) k])
+			removeFont(k);
+		for (k in [for (k in sound.keys()) k])
+			removeSound(k);
+		for (k in [for (k in sound2.keys()) k])
+			removeSound(k);
+	}
+
 	public function clearSecondLayer() {
 		for(k=>b in bitmapData2) {
 			FlxG.bitmap.removeByKey(k);

From 4b942e7f63225af2499f9c7542897e59946e99cd Mon Sep 17 00:00:00 2001
From: HEIHUAa <112499486+HEIHUAa@users.noreply.github.com>
Date: Mon, 24 Aug 2026 14:53:05 +0800
Subject: [PATCH 2/2] graphic.key

---
 source/funkin/backend/system/modules/FunkinCache.hx | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/source/funkin/backend/system/modules/FunkinCache.hx b/source/funkin/backend/system/modules/FunkinCache.hx
index 8f650b5543..19cbe22fc9 100644
--- a/source/funkin/backend/system/modules/FunkinCache.hx
+++ b/source/funkin/backend/system/modules/FunkinCache.hx
@@ -54,10 +54,9 @@ class FunkinCache extends AssetCache {
 	**/
 	public static function clearAllCaches() {
 		@:privateAccess
-		for (key in [for (k in FlxG.bitmap._cache.keys()) k]) {
-			var graphic = FlxG.bitmap._cache.get(key);
+		for (graphic in [for (g in FlxG.bitmap._cache) g]) {
 			if (graphic != null && graphic.assetsKey != null)
-				FlxG.bitmap.removeByKey(key);
+				FlxG.bitmap.removeByKey(graphic.key);
 		}
 		if (instance != null)
 			instance.clearAll();