Description

Changelog

Reviews (0)

godot-cbor

A CBOR decoder and encoder for Godot 4.6 and above, written in GDScript.

CBOR (Concise Binary Object Representation) is a binary data interchange format loosely inspired by JSON. Like JSON, it can encode a set of commonly used data types. Unlike JSON, it is compact and therefore better-suited to real-time networking or small save files.

Installing

Download the asset and merge the addons/ folder with your project's.

A new class, CBOR will become available. See the in-editor documentation for more details.

Encoding

The encoder supports encoding the following Godot types into CBOR major types:

Godot type	Encodes into
`float`	7 (simple/float)
`int`	0 (positive integer) or 1 (negative integer)
`PackedByteArray`	2 (fixed length byte string)
`String`, `StringName`	3 (fixed length text string)
`Array`	4 (fixed length array)
`Dictionary`	5 (fixed length map)
`bool`	7 (simple, either true or false)
`null` and invalid object references	7 (simple, null)

float numbers are always stored as double-precision. int numbers, on the other hand, are stored in the smallest number of bytes that can fit.

Any other types that are not covered by this table get stored as type 3 (fixed length string), the value being the result of str(value).

Example

func _ready():
    var data = {
        "hello": "world",
        -42: 33.5,
        ["nested", "structures"]: {
            "are supported": true
        }
    }
    var bytes = CBOR.encode(data)
    print(bytes.hex_encode()) # a36568656c6c6f65776f726c643829fb4040c0000000000082666e65737465646a73747275637475726573a16d61726520737570706f72746564f5

Decoding

The decoder supports all major types defined for CBOR:

Major type	Decodes into
0 (positive integer)	`int`
1 (negative integer)	`int`
2 (byte string)	`PackedByteArray`
3 (text string)	`String`
4 (array)	`Array`
5 (map)	`Dictionary`
6 (tag)	`{"type": N, "value": M}` where N is the tag type and M is the payload
7 (simple/float)	`false`/`true`/`null` or `float` or `{"simple": N}` where N is the simple value

Due to Godot's int type being signed and 64-bit wide, it can not represent values above 9223372036854775807 and below -9223372036854775808. When decoding, the value is preserved bitwise but may be interpreted in a different way than intended.

Only fixed-length sequences are supported. a value of 31 for the additional data (the lower 5 bits of a data item's header) will push an error.

No extended/tag types are supported at this time, but their data is preserved in the returned Dictionary.

Example

func _ready():
    var incoming_data = "8c020305070b0d111317181d181f1825"
    var cbor = CBOR.decode(incoming_data.hex_decode())
    if cbor.error == OK:
        print(cbor.data) # [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37]
    else:
        printerr(error_string(cbor.error))

Roadmap

ability to register custom tags for both serializing and deserializing
support for deserializing certain tag types (specifically, tags 0, 1, and 24; see spec) into native types