GDMaim

A plugin for the [Godot Engine] which obfuscates all GDScripts when exporting a project, resulting in increased difficulty of successful reverse engineering.

Table of contents

• Why does this exist?
  • Vulnerability of GDScripts
  • Obfuscation
  • Example
• Installation
• Configuration
• Usage
  • Source map viewer
  • Export template feature tags
  • Preprocessor hints
• Limitations and caveats
• Stability
• External Libraries
• Issues
• Troubleshooting
• Roadmap
• License

Why does this exist?

Vulnerability of GDScripts

GDScripts are stored as is when exporting a project, which makes it very easy for anyone to gain full access to the original source code, using tools like gdsdecomp. Godot does have built-in encryption, but that will only deter people who don't know about gdke, which extracts the encryption key from the executable.

Thus, it's very easy for people to get the entire GDScript source code of any exported project. This also means that writing cheats for multiplayer games becomes a lot easier, which includes finding and taking advantage of vulnerabilities in server-authoritative code.

Obfuscation

This plugin tries to make reverse engineering harder by obfuscating the source code of all exported scripts. Since only the exported 'pck' file gets processed, obfuscation is non-destructive to the project itself. It among other things, generates random names for identifiers, hardcodes enum and constant values and strips out comments and empty lines.

It does of course not make reverse engineering impossible, but will act as a way greater barrier than just encryption for example, which can be easily bypassed by just downloading a publicly available tool.

Example

Source code(left), obfuscated code(right)

<img src='docs/images/example1.png' width='800'>

Installation ↑

Note: Requires Godot 4.0+. Developed and tested on Godot 4.2-stable.

1. Download a release build or the latest main branch.
2. Extract the zip file and copy addons/gdmaim to the project's res://addons directory.
3. Go to Project -> Project Settings -> Plugins and enable GDMaim

Configuration ↑

To configure this plugin, open the GDMaim dock on the bottom left, right next to the file dock.

<img src='docs/images/configuration_window.png' width='330'>

Obfuscation

Enable Obfuscation: If enabled, obfuscate scripts. Does not affect post-processing.

Obfuscate Exports Vars: If enabled, obfuscate export vars.

Note: Requires all resources which modify export vars to be saved as '.tres' files.

Shuffle Top-Level Declarations: Shuffles the line positions of top-level declarations, such as variables, functions and classes.

Inline Statements: If enabled, aggressively compresses multiple lines of code into as little lines as possible.

Inline Constants: If enabled, accesses to constants will be replaced with hardcoded values. Declarations of constants get removed.

Inline enums: If enabled, accesses to enum keys will be replaced with hardcoded values. Declarations of enums get removed.

Preprocessor prefix: The prefix to use for preprocessor hints.

Post Processing

Strip Comments: If enabled, remove all comments.

Strip Empty Lines: If enabled, any line without code will be removed.

Strip Extraneous Spacing: If enabled, spaces and tabs that are not required, get removed.

Strip Editor Annotations: If enabled, annotations used exclusively by the editor will be removed.

Strip Lines Matching RegEx: If enabled, any lines matching the regular expression will be removed.

Process Feature Filters: If enabled, process automatic filtering of code, based on export template feature tags. For more information, see feature filters.

Export Mode: Defines the final format in which the scripts will be exported. This has the same function as the script export option from the editor, allowing to choose between plain text, binary tokens or compressed binary tokens.

Name Generator

Prefix: Sets the prefix to use for all generated names.

Character List: A list of characters the name generator is allowed to use.

Target Name Length: The length of names the generator will try to target. The length does not include the prefix.

Seed: The seed the name generator will use to generate names. A given seed will always produce the same name for every identifier.

Note: The set value will be ignored, if Use Dynamic Seed is enabled.

Use Dynamic Seed: If enabled, automatically generate a random seed every time the project is exported.

Warning: Dynamic seeds will produce unique scripts on each export, which might potentially 'break' delta updates, as used by Steam for example. It also makes debugging harder.

Source Mapping

Output Path: The path where source maps will automatically be saved to upon export.

Max Files: The maximum amount of saved source maps. When the limit has been reached, replace the oldest one.

Compress: If true, compress the source maps before export to take up less space.

Inject Name: If true, searches for the first enabled autoload during export and inserts a print statement into its _enter_tree method(or creates a new one if it does not exist). The print statement contains the filename of the associated source map that got generated during the export of that build.

Exclusion

Path : Files/Folders to prevent their obfuscation, the paths must be separated by ";"

Example: path/to/my_file_1;path/to/my_file_2;path/to/my_exclude_folder

Usage ↑

Please read limitations and caveats to make sure your project can export properly.

While enabled, GDMaim automatically obfuscates scripts and resources during export. As mentioned earlier, the obfuscation only affects the exported '.pck' file, but as always, make sure to use version control.

Source map viewer

During export, a source map for the current build will be generated and saved. By default Max Files is set to only keep the 10 latest files, so every time you actually release a build, make sure to copy the associated source map somewhere safe.

Debugging using source maps

<img src='docs/images/locate_source_map_viewer.png' width='200'>

Open the source map viewer by navigating to the GDMaim dock and selecting View Source Map. Next, open the source map you want to view.

On the left side you will find a file tree, containing all exported scripts. Double-clicking on one will open it.

Once a script has been opened, both the source and exported code will be shown. By selecting a line in either code, you can get the equivalent line in the other code.

<img src='docs/images/source_map_viewer.png' width='1000'>

Export template feature tags

<img src='docs/images/feature_tags.png' width='500'>

Feature tags allow configuration on per export template basis.

Using no_gdmaim as feature tag, will completely disable obfuscation for that specific export template.

Warning: Do not distribute builds made with no_gdmain export templates!

If Process Feature Filters is enabled, custom feature tags may be used to automatically filter code. See: feature filters.

Preprocessor hints

Obfuscation

##LOCK_SYMBOLS: Prevents obfuscation of identifiers declared in the current line.

var my_var : int ##LOCK_SYMBOLS
var my_var2 : int
my_var2 = 0 ##LOCK_SYMBOLS

=>

var my_var : int ##LOCK_SYMBOLS
var __6vjJ : int
__6vjJ = 0 ##LOCK_SYMBOLS

Note: Globally accessible names are shared with all scripts, which in the above example means that my_var declarations will not get obfuscated in any script.

##OBFUSCATE_STRINGS: Obfuscates all strings in the same line.

var my_var : int
set("my_var", 1) ##OBFUSCATE_STRINGS

=>

var __pQFC : int
set("__pQFC", 1) ##OBFUSCATE_STRINGS

##OBFUSCATE_STRING_PARAMETERS arg_name: Must be at the beginning of a line and before a function declaration. For all specified string parameters, obfuscate the arguments when the function is called.

##OBFUSCATE_STRING_PARAMETERS name
func custom_set(name : String, value) -> void:
	set(name, value)

var my_var : int
custom_set("my_var", 3)

=>

##OBFUSCATE_STRING_PARAMETERS name
func __U5iZ(name : String, value) -> void:
  set(name, value)

var __rEyW : int
__U5iZ("__rEyW", 3)

##EXCLUDE_FILE: Prevent obfuscation of the script file and it maintains match compatibility throughout the project for the scripts that can use it. put in wherever you want in your script, as a good practice, place it at the beginning of the file.

##EXCLUDE_FILE
class MyCustomClassNode extends Node

func _ready() -> void:
  print("Hello to a safer world")

# ...

Feature filters

Feature filters provide a way to dynamically strip out code based on the export template feature tags set. There is currently only one preprocessor hint.

##FEATURE_FUNC feature_tag: Must be at the