WCSafeResourceFormat

A set of Godot ResourceFormatLoader/ResourceFormatSaver based file formats designed as a "safe" drop-in replacement for .tres/.res files by simply changing the file extension.

Unlike other "parser-based filters" for actual .tres/.res files, the code doing the checking is the same code doing the loading/instantiating, thus making it more likely to "fail safe".

Just like them however, this does not define or rely on a new Resource-derived base class, instead serializing any Resource.

TLDR/Getting Started

• assuming as a starting point a .tres based save/load system
• install and enable the plugin
• rename .tres to .wcsb (or .wcsj for debugging purposes)
• add the following snippet to the involved resource classes and enable @tool for their scripts:

static func _static_init()->void:
  if Engine.is_editor_hint():
    WCSafeResourceFormatPlugin.allow()
    #<add>

• also add (where marked above) calls to WCSafeResourceFormatPlugin.allow_class(...) for any internal classes required
• same with WCSafeResourceFormatPlugin.allow_resource(...) for any external non-wcsb resources. both of those can use wildcards
• you might need some editor restarting afterwards for it to process all that. check the Addons->WCSafeResourceFormatPlugin page in the ProjectSettings to see the resulting configuration

for example a resource that references png files from the user://images folder might:

static func _static_init()->void:
    if Engine.is_editor_hint():
        WCSafeResourceFormatPlugin.allow()
        WCSafeResourceFormatPlugin.allow_class("Image")
        WCSafeResourceFormatPlugin.allow_resource("user://images/*.png")

(note this isn't actually how runtime image loading works, but i needed some example)

File formats

• .wcsj: JSON-encoded data, human readable, helpful for debugging
• .wcsb: compressed binary-encoded data, smaller/faster

API

• WCSafeResourceFormatPlugin: plugin main class, contains whitelists for builtin classes, script paths and external resource paths, as well as helper functions, described in Docstring.
• WCSafeResourceFormatSaverJSON: the saver for .wcsj files
  • String store_indentation: can be set to a string like "\t" to output formatted indented JSON
• WCSafeResourceFormatSaverBinary: the saver for .wcsb files
  • FileAccess.CompressionMode compress_mode: which compression to use: FastLZ (default), zstd, gzip, deflate
• WCSafeResourceFormatLoaderJSON: the loader for .wcsj files
• WCSafeResourceFormatLoaderBinary: the loader for .wcsb files
• WCSafeResourceFormatDictEncoding: the actual Object<->Dictionary serialization logic (contains all of the safety logic too; you can use this directly to implement other saver/loader classes or e.g. send data through a network connection or similar)

Project Settings

• Page: addons/wc_safe_resource_format
  • allowed_classes, allowed_scripts, allowed_resources: see WCSafeResourceFormatPlugin properties.
  • json_store_indentation: WCSafeResourceFormatSaverJSON.store_indentation
  • bin_compress_mode: WCSafeResourceFormatSaverBinary.compress_mode

Encryption?

Wont be officially supported because I disagree it's helpful for most tasks this plugin is intended for, and for the few it is a project-specific solution will be better than the assumptions my code can make.

You can however easily just copy the Saver+Loader pair you're interested in, change the file extension in _get_recognized_extensions and edit _load or _save to do whatever you want.