Godot Reverse Engineering: How to Decompile and Recover Godot Games

Are you looking to reverse engineer a Godot game? Do you need to recover a lost project? Godot RE Tools (gdsdecomp) is a powerful suite designed to help you decompile, extract, and recover Godot Engine projects. This guide will walk you through everything you need to know about using these tools effectively, including Godot project recovery and GDScript decompilation.

What is GDRETools/gdsdecomp?

GDRETools/gdsdecomp is an open-source project that provides tools for reverse engineering Godot games. It allows you to extract assets, decompile GDScript code, and recover entire Godot projects from compiled games. This is invaluable for those who have lost project files or are interested in understanding how a Godot game was built. Perfect for ethical reverse engineering!

Why Use Godot Reverse Engineering Tools?

• Project Recovery: Recover lost or corrupted Godot projects, including scripts and assets.
• GDScript Decompilation: Extract and examine GDScript code to understand game logic.
• Asset Extraction: Retrieve textures, models, and other resources from compiled games.
• Learning and Modding: Analyze existing games to learn new techniques or create mods.

Key Features of GDRETools

• Full Project Recovery: Extracts all resources from PCK, APK, or EXE files.
• GDScript Batch Decompiler: Converts compiled GDScript back into readable code.
• Resource Conversion: Transforms binary resources back to their original text formats.

How to Get Started with Godot Project Recovery

1. Download the Latest Release

Grab the latest release of GDRETools from the official GitHub releases page. Choose the version that corresponds to your operating system.

2. Using the GUI for Project Recovery

• Open the Tool: Launch the GDRETools application.
• Select "Recover project...": Find this option in the "RE Tools" menu.
• Drag and Drop: Alternatively, drag the PCK/EXE file directly onto the application window.

3. Command-Line Interface for Advanced Users

For more control, use the command-line interface:

gdre_tools --headless [options]

Here's how to use some key commands:

• --recover=: Fully recover a project from a PCK, APK, EXE, or extracted project directory.
• --extract=: Extract the contents of a PCK, APK, or EXE file.
• --decompile=: Decompile GDScript files to text scripts with this command (requires --bytecode).

4. Important Command-Line Options

• --key=: Use this option if the project is encrypted, providing the 64-character hex key.
• --output=: Specify the output directory for recovered files. If omitted, it defaults to the project directory.
• --scripts-only: Only extract scripts, which can save time and space.

Example Usage:

To recover a project named "mygame.pck" to an output directory called "recovered_project", use the following command:

gdre_tools --headless --recover=mygame.pck --output=recovered_project

Decompiling GDScript Effectively

GDRETools shines when it comes to decompiling GDScript. Whether you're analyzing game logic or recovering lost code, follow these steps:

Using the GUI:

The GUI provides a straightforward way to decompile scripts as part of the project recovery process. Simply initiate a project recovery as described above, and GDScript files will be automatically decompiled.

Command-Line Decompilation:

For batch decompilation, use the --decompile option:

gdre_tools --headless --decompile="path/to/your/script.gdc" --bytecode=[version]

Replace [version] with the Godot Engine version used to compile the script (e.g., '4.3.0').

Understanding Include and Exclude Globs

When recovering projects, you can use glob patterns to include or exclude specific files. This is particularly useful for large projects where you only need certain assets or scripts.

• res://**/*.gdc matches all .gdc files recursively within the res:// directory.
• res://*.gdc matches only .gdc files in the root of the res:// directory.

Addressing Common Limitations

Keep in mind the following limitations of GDRETools:

• Model Support: Limited support for older 3D model formats (.dae, .fbx, .glb).
• Font Support: Partial support for bitmap and image fonts. However, recovering 4.x TTF/OTF font files is supported
• GDNative/GDExtension: No support for decompiling GDNative or GDExtension scripts.

For reverse engineering C# code in GDMono, consider using tools like Ilspy or dotPeek.

Compiling GDRETools from Source

If you need the latest features or want to contribute to the project, you can compile GDRETools from source:

1. Clone the repository into Godot's modules subfolder as gdsdecomp.
2. Rebuild the Godot engine as described in the Godot documentation.

Mastering Godot Reverse Engineering

By understanding and utilizing GDRETools effectively, you can unlock the secrets of Godot games, recover lost projects, and enhance your game development skills. Happy decompiling!