PickleGD

PickleGD is a Godot asset for safely serializing arbitrary godot data structures, including custom classes, over multiplayer and to disk.

Tested with: Godot Engine v4.4.stable.official.4c311cbee

This is a system for "pickling" GDScript objects to byte arrays, using native var_to_bytes plus some code inspection magic. It's meant to make it easy for you to send complex data structures (such as large custom classes) over the network to multiplayer peers, or to create your own save system. PickleGD is designed to prevent arbitrary code execution in the serialization and deserialization process.

Note: this asset is not compatible with Python's pickle format.

Quick Start example

To get started pickling your data, first create a pickler.

var pickler = Pickler.new()

If you have custom classes you want to register, register them at scene load time:

pickler.register_custom_class(CustomClassOne)
pickler.register_custom_class(CustomClassTwo)

If you want to register godot engine native classes, you must use the class name as a string:

pickler.register_native_class("Node2D")

Now you are ready to pickle your data! On the sender's side, just pass your data to picker.pickle(), send the resulting PackedByteArray, then at the receiver's side pass the PackedByteArray to pickler.unpickle().

var data = {
        "one": CustomClassOne.new(),
        "things": ["str", 42, {"foo":"bar"}, [1,2,3], true, false, null],
        "node": Node2D.new(),
    }
var pba: PackedByteArray = pickler.pickle(data)

# "unpickled" should be the same as "data"
var unpickled = pickler.unpickle(pba)

Compressing a pickle

You can create smaller pickles by setting Pickler.serialize_defaults to false, which removes default values from pickled Objects.

You can create compressed binary pickles using Pickler.pickle_compressed().

Customizing a pickle

You can also have direct control over which properties are serialized/deserialized by adding __getnewargs__(), __getstate__() and __setstate__() methods to your custom class. The Pickler will first call __getnewargs__() to get the arguments for the object's constructor, then will call __getstate__() to retrieve an Object's properties during serialization, and later will call __setstate__() to set an Object's properties during deserialization. You may also use these methods to perform input validation on an Object's properties.

__getnewargs__() takes no arguments, and must return an Array.

__getstate__() takes no arguments, and must return a Dictionary.

__setstate__() takes one argument, the state Dictionary, and has no return value.

For example:

extends Resource
class_name CustomClassNewargs

var foo: String = "bluh"
var baz: float = 4.0
var qux: String = "x"

func _init(new_foo: String):
    foo = new_foo

func __getnewargs__() -> Array:
    return [foo]

func __getstate__() -> Dictionary:
    return {"1": baz, "2": qux}

func __setstate__(state: Dictionary):
    baz = state["1"]
    qux = state["2"]

The PicklableClass for an Object type that is created at registration time also has __getnewargs__(), __getstate__() and __setstate__() functions you can override.