What does FLAG_BUNDLE_RESOURCES do?

Embeds external Resource references inline rather than referencing them by path. Useful when saving a self-contained Resource (e.g. a save game). Misused, it can embed unintended assets and bloat or break the save.

Why does my save file no longer load after enabling the flag?

Bundled resources lose their original UID/path. On load, references that previously pointed to res://path/to/asset.tres may resolve to the embedded copy instead, which has a different identity. Plan whether you want self-contained or path-linked saves.

Should I use binary or text format for save files?

.tres for human-readable + version-controllable; .res for binary + smaller. For player save files (untouched by humans), .res is faster. For developer-edited config, .tres.

Fix: Godot 4 ResourceSaver BundleResources Flag Corrupts Saves

Quick answer: Use FLAG_BUNDLE_RESOURCES only when you want a self-contained Resource. For save games that reference shared assets, omit the flag — references stay as paths. Bundling embeds copies that may resolve to wrong identities on load.

You save a player save Resource that references a CharacterClass resource. With FLAG_BUNDLE_RESOURCES, the save embeds a snapshot of the class. Reloading produces a separate copy that doesn’t match the live one elsewhere.

The Symptom

Save and reload appear to work, but loaded references don’t match the original Resources. save.character_class == ClassDB.get_class() returns false. Comparing IDs differs.

What Causes This

FLAG_BUNDLE_RESOURCES embeds external resources inline. The save file becomes self-contained but every embedded Resource gets a fresh path/identity. Two save files referencing the same shared CharacterClass each carry their own copy.

The Fix

# Self-contained: bundle
ResourceSaver.save(save_data, "user://slot1.res", ResourceSaver.FLAG_BUNDLE_RESOURCES)

# Path-linked: don't bundle
ResourceSaver.save(save_data, "user://slot1.res")

Choose based on intent. For player saves that should reference shared res:// content, omit the flag. The save file holds paths; load resolves them to the live shared Resources.

FLAG_CHANGE_PATH

Sets the resource_path of the saved object to the new path. Useful when saving a duplicated Resource you want to track as a separate asset. Don’t use for player saves — you don’t want to claim user://slot1.res as the canonical path of the in-memory data.

Verifying

Save, load. Compare references via == against the original asset. Without bundling, equal. With bundling, false (separate instance).

“Bundle for self-contained. Don’t bundle for shared. Pick based on save semantics.”

Related Issues

For UID collisions, see UID collision. For resource not found, see resource load.

Bundle by intent. Saves preserve identity.