Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:GDScript binary tokens

From ReverseEngineering.wiki
Format
Versions tokenizer version 3-13 (Godot 1-3), 100-101 (Godot 4.3+)
Magic 47 44 53 43 ("GDSC")
Extensions .gdc, .gde (encrypted)
Endianness little endian
On this wiki Facts · Code · Notes · Topics

The compiled form of GDScript (.gdc, or .gde when encrypted): magic GDSC, a bytecode version (12-13 for Godot 3, 100-101 for Godot 4.3 and later) and a tokenizer dump of identifiers, constants and tokens. It is not VM bytecode: scripts are decompiled by re-printing the tokens.

Overview

Godot can export scripts as binary token streams: GDScriptTokenizerBuffer in modules/gdscript/gdscript_tokenizer_buffer.cpp (godotengine/godot, MIT, commit 81ab961f91) in Godot 4, and the equivalent in Godot 3. A script is just the tokenizer's output, so the original source (without comments and mostly formatting) can be rebuilt by a decompiler such as gdsdecomp (MIT). Godot 4.0 to 4.2 have no compiled mode, according to the gdsdecomp table; token buffers appear again from 4.3.

Godot 4 layout (version 101 at the read commit)

Offset Field
0 GDSC
4 uint32 tokenizer version; the engine refuses any other than its own (101)
8 uint32 decompressed size; 0 means the rest is stored uncompressed, otherwise the rest is one Zstd frame
12 content: uint32 identifier count, constant count, token line count, token count

Then identifiers: per identifier a uint32 length in characters followed by that many UTF-32 code units (4 bytes each) with every byte XORed with 0xB6; constants as Variant binary encodings (Format:Godot variant binary encoding); the token line map and token column map (pairs of uint32 token index and line or column); and the tokens. A token is 1 byte of type (value below 0x80) plus uint32 start line, or, when bit 0x80 of the first byte is set, a uint32 whose low 7 bits are the token type and whose upper 24 bits (value >> 8) index the identifier or constant table, plus the uint32 start line.

Godot 3 layout

From gdsdecomp bytecode/bytecode_base.cpp (get_ids_consts_tokens, MIT): GDSC, uint32 bytecode version (12 for 3.0, 13 for 3.1 to 3.5), then at offsets 8, 12, 16, 20 the identifier, constant, line and token counts; data starts at byte 24. Identifiers: uint32 length (counting the NUL) and bytes XORed with 0xB6. Constants: Variant encoding. Lines: 8-byte pairs. Tokens: 1 byte, or 4 bytes with bit 0x80 set in the first byte.

Telling versions apart

Read the uint32 at offset 4. The numbers map to releases through gdsdecomp's BYTECODE_HISTORY.md: 3 (Godot 1.0), 4 (1.1), 10 (2.0 to 2.1), 11-12 (3.0 development and 3.0.x), 13 (3.1 to 3.5), 100 (4.3), 101 (4.5). The token numbering changed with almost every added keyword or built-in function, so a decompiler must be built for the exact bytecode revision; a wrong one yields garbage identifiers, not an error.

Encrypted scripts

Encrypted .gde files use Godot's FileAccessEncrypted wrapper (see Format:Godot PCK), not a different token format; decrypt first, then parse GDSC.

Code & repositories

  • https://github.com/godotengine/godot @ 81ab961f91066a63bcbf3ec340962bb1a1ada558 · license: MIT
    Godot engine source (MIT). Useful without building: core/io/file_access_pack.cpp (PCK reader), core/io/resource_format_binary.cpp (RSRC), core/io/file_access_compressed.cpp (RSCC), core/io/file_access_encrypted.cpp, scene/resources/compressed_texture.cpp (GST2/GSTL), modules/gdscript/gdscript_tokenizer_buffer.cpp (GDSC).
    Tested on: source read, not run: source read, not run · checked 2026-10-18; last activity 2026-10-18; Note: the latest release ships binaries; the wiki links only the source, never the binaries

Pitfalls

  • Unverified: the exact meaning of the first-byte check token_type & TOKEN_MASK in the Godot 4 writer; follow the reader (_binary_to_token) when parsing.
  • Version 100 (4.3) has a different content header size than 101: gdsdecomp switches between a 16-byte and a 12-byte header at its CONTENT_HEADER_SIZE_CHANGED version; Unverified which of 100 or 101 is which.