gdsdecomp: recovering Godot projects from PCK, APK and EXE files

What gdsdecomp recovers, and who needs it

A shipped Godot game is not a folder of .gd and .tscn files. The exporter packs resources into a PCK archive, converts imported assets into engine-specific formats, and compiles scripts to bytecode. If the source tree is lost, the build is the only copy left. gdsdecomp exists for that situation. The README lists its scope plainly: full project recovery, a PCK archive extractor and creator, a GDScript batch decompiler, and a resource text/binary batch converter.

The full recovery path is the ambitious one. According to the README it loads resources from an APK, PCK or embedded EXE, decompiles all GDScript, recovers the original project file, converts imported resources back to their original import formats, converts auto-converted binary resources back to text, and recreates plugin configuration files. That is a pipeline, not a single command, and each stage can fail on its own.

Who is this for? Developers who shipped a build and then lost or corrupted the repository. Studios doing a code audit of a contracted Godot deliverable. People studying how a particular Godot game is structured. The tool supports Godot 4.x, 3.x and 2.x projects, which matters because bytecode formats changed across those lines.

How the recovery pipeline actually works

The repository layout tells you the architecture. There are separate top-level directories for bytecode, crypto, exporters, plugin_manager, standalone and gui, plus a bytecode_generator.py and a prepop_cache.py at the root. The bytecode directory is the interesting one: GDScript bytecode is not stable across engine releases, so the tool needs a definition for each revision it supports.

That is what the --bytecode option is for. It takes either a commit hash of the bytecode revision, such as 'f3f05dc', or an engine version such as '4.3.0'. There is also --list-bytecode-versions to enumerate what is available, --dump-bytecode-versions to write the definitions to a directory as JSON, and --load-custom-bytecode to feed in your own JSON definition. The presence of a generator script and a cache suggests the definitions are produced from engine sources rather than hand-written.

The crypto directory covers encrypted PCKs. The --key option takes a 64-character hex string, and the README gives an example key of '000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F'. Without the key, an encrypted archive is not going to open.

C# projects get a separate path: --csharp-assembly takes an optional path to the C# assembly, and the README says it is auto-detected from the PCK path if not specified. There is also a godot-mono-decomp directory in the repository. The README does not describe what that component does in detail.

Installing gdsdecomp and running a first recovery

The README points to the releases page on GitHub as the place to get binaries. On Windows there is a Scoop route, which the README gives as two commands: add the games bucket, then install the package.

scoop bucket add games
scoop install gdsdecomp

After that, gdsdecomp is on your PATH. The README does not document a Linux package, a macOS package, or a build-from-source procedure, so if you are not on Windows you are downloading a release artifact and running it directly.

The GUI path is the shortest: open the application, pick "Recover project..." from the "RE Tools" menu, or drag a PCK or EXE onto the window. For anything scriptable, use headless mode. The README's usage line is:

gdre_tools --headless <main_command> [options]

A first real use is to look before you extract. Listing the archive is cheap and tells you whether the file you have is the one you think it is:

gdre_tools --headless --list-files=<GAME_PCK/EXE/APK>

The README says --list-files lists all files in the specified PCK, APK or EXE and exits, and that it can be repeated. Once the listing looks right, run the full recovery:

gdre_tools --headless --recover=<GAME_PCK/EXE/APK/DIR> --output=<DIR>

The README states that --output defaults to <NAME_extracted>, or to the project directory if one is specified. If the archive is encrypted, add --key with the 64-character hex string. If you only want the scripts, --scripts-only narrows the run, and --include and --exclude take glob patterns to filter what gets written.

Where gdsdecomp runs into trouble

Bytecode version mismatch is the failure mode to plan for. If the tool cannot identify the bytecode revision of a compiled script, decompilation of that script does not happen, and the README's answer is to force it with --force-bytecode-version, which accepts a commit hash or a version string. Forcing a version that does not match the file is not going to produce correct output, so treat it as a way to pin a known revision, not a fix for an unknown one.

Integrity checks are the second obstacle. The README provides --ignore-checksum-errors and --skip-checksum-check as separate options. That two-option design is worth noting: ignoring an MD5 error and skipping the check entirely are different behaviours, and the README does not explain the distinction in the excerpt available. If a recovery fails partway, try the narrower option first.

C# projects are a third boundary. The README says the assembly path is auto-detected from the PCK path if not specified, which implies recovery depends on having that assembly. A C# Godot project without the accompanying assembly is not a case the documentation addresses.

Finally, translation recovery has its own surface: --translation-hint accepts .csv, .txt, .po or .mo files, and --skip-loading-resource-strings changes how strings are gathered. The README notes that --patch-translations can be combined with --pck-patch, and that --pck can be omitted when it is. This is a lot of interacting flags, and the README is a reference, not a tutorial. There is no documented rollback if a patched PCK turns out wrong, so keep the original archive.

gdsdecomp against a plain PCK extractor

The obvious alternative is a bare PCK extractor: a small tool that unpacks the archive and stops there. The difference is what you get at the end. An extractor leaves you with the packed forms of the resources and the compiled .gdc scripts. gdsdecomp's recovery path is designed to go further, converting imported resources back to their original import formats and auto-converted binary resources back to text, then recreating the project file and plugin configuration files.

That is a real difference in output, and it comes with a cost in surface area. The command line has separate option groups for recovery and extraction, decompiling and compiling, creating a PCK, patching a PCK, and patching translations. Each group has its own --output semantics. If all you need is a file listing or a raw dump, a minimal extractor is easier to reason about. If you need a project directory that Godot can open, the conversion stages are the whole point.

The other comparison is to the engine itself. The README exposes --godot-version and --godot-help, which print the version and help message of the embedded Godot engine and exit. That tells you gdsdecomp embeds an engine build rather than reimplementing resource handling from scratch, which is why resource conversion tracks engine behaviour.

Licence, maintenance and what an upgrade costs you

The repository is MIT licensed, with a LICENSE file at the root. For most users that means you can use, modify and redistribute the tool, including in commercial work, provided the licence text and copyright notice travel with it. That is the general shape of MIT; it is not legal advice, and if you are redistributing gdsdecomp inside a product you should read the LICENSE file yourself rather than take a summary.

Maintenance is visible in the release history. The most recent push to the repository was on 2026-08-16, and the same date carries the v2.7.0-beta.2 release. Before that came v2.7.0-beta.1 on 2026-08-15 and v2.6.4 on 2026-08-12. The current line is a beta, with a stable 2.6.4 sitting just behind it. That is a normal pattern for a tool that has to track engine changes, but it means the newest bytecode support arrives in beta builds first.

The upgrade cost is the part to think about before you depend on this. Bytecode definitions are versioned against engine revisions, so a new Godot release can require a new gdsdecomp release before your target decompiles. The --load-custom-bytecode and --dump-bytecode-versions options exist precisely because that gap is real: you can dump the definitions you have, inspect them as JSON, and supply your own. If your workflow assumes a specific Godot version, pin the gdsdecomp release alongside it rather than tracking the latest beta.

Building a patched PCK and translating an existing release

Recovery is only half the tool. The README documents --pck-create, which requires --pck-version and --pck-engine-version, and --pck-patch, which takes --patch-file entries in the form <SRC_FILE>=<DEST_FILE>, for example "/path/to/file.gd=res://file.gd". Both accept --embed to place the result inside an executable, and both accept --key to encrypt the output.

The patch path is the one that gets used in practice for small fixes: you take the original PCK, replace a script or resource, and write a new archive. --include and --exclude globs let you carry over only part of the original file set. Note that --patch-file is repeatable, so multiple replacements go in one invocation.

Translation patching is a separate command with its own options. --patch-translations takes a CSV file and a source path, and the README's example is "/path/to/translation.csv=res://translations/translation.csv". It supports --locales as a comma-separated list, and the README says the default is only newly-added locales. When combined with --pck-patch, --pck can be omitted and --output becomes optional. The README does not state what happens to existing translations in a locale that is both present and patched, so test on a copy before touching a release build.

Editorial conclusion

Use gdsdecomp when you need to read your own shipped build, audit a Godot title you have permission to inspect, or recover a project whose source is gone. Do not use it as a way to lift assets from someone else's game, and do not expect it to produce a build-ready tree: bytecode recovery depends on the engine version, and the README does not promise that a recovered project compiles unchanged. Before trusting a recovery, run --list-files on the archive to confirm the file set, then check the recovered project.godot against the engine version you intend to open it with.

Frequently asked questions

Official sources

1. GDRETools/gdsdecomp on GitHub
2. Issues
3. License: MIT
4. README
5. Releases