How To: Exporting a PCK with compiled Python for distribution

[codewithmichael]

There have been a lot of questions the last couple years floating around misc forums about how to package a Godot-Python (PythonScripts) project for distribution, and I rarely see much in the way of answers.

Since there's no Wiki, I thought I'd drop a quick primer on how I've been accomplishing the task in hopes of helping a few lost souls -- but feel free to migrate this elsewhere!

In the end you should end up with the following files/directories:

• Game binary (e.g. HelloWorld.x86_64 or HelloWorld.exe)
• Game PCK (e.g. HelloWorld.pck)
• An "addons" directory (contains your game's python installation)
• A "Scripts" directory (contains compiled .pyc python bytecode files)

The steps should be about the same on any OS.
I'll attempt to describe them in full detail below.

Here's a quick gist I wrote up to automate the whole task for Linux.
Anyone's welcome to clean it up, update it for macOS, or translate it to a Windows .bat file to suit their needs.
If so, share and share alike :)

Required Tools

• Godot Game Engine - I tested using the latest 3.5.1 (obligatory link)
• Godot-Python - Install "PythonScript" from the "AssetLib" tab to your project (or build from source here and install)
• GodotPckTool - Tested with the Linux 1.7 binary from the GitHub project page

For our purposes here, I will assume Godot and GodotPckTool are installed and available on your system PATH -- respectively named godot and godotpcktool. If you're on Windows, you'll probably need to tack on a .exe extension to associated calls.

Step 1 - Configure the Project for Export

Open your project and make sure ALL of your Python scripts are in a project-root-level directory called "Scripts".
If they're not already, you should be able to safely move them. Godot will pick up the change.

Then go to the Project > Export... menu. If you don't already have an export template installed, click Add at the top of the new window and select (or download) an appropriate template for your target operating system.

Once you have a template installed/selected, ensure Embed PCK is NOT checked and then you can cancel out.

At this point, assuming your project already runs correctly, you don't even really need to keep Godot open anymore if you want to do everything from the command line. If you prefer a graphical user interface, leave Godot open (for running exports) and open your favorite file explorer.

Step 2 - Ensure Python Won't Be Added to the PCK

Python won't run from inside the PCK archive, nor will it run any scripts within said archive -- we'll hack around the scripts in a minute, but first we want to make sure Python won't be added to the PCK file.

Navigate to your project directory, then addons/pythonscript. Ensure there's a file called .gdignore in there. It doesn't need any content. It just tells Godot to ignore the directory when looking at project files.

Step 3 - Export Your Project

If you're doing this from Godot, return to the Project > Export... menu and click the Export Project... button at the bottom.
Make sure to export to another directory. For example, if your project directory is named "HelloWorld", make another directory outside of it called "HelloWorldExport", and then export your game files there.

If you prefer to do it on the command line, your export command should look something like this:

godot --path "/path/to/HelloWorld" --export "Linux/X11" "/path/to/HelloWorldExport"

• Note 1: "Linux/X11" there is the name of the export template. It should match whatever your export template shows up as in the export window (not including the (Runnable) trailing bit).
• Note 2: Use --export-debug instead of --export to export a debug build

You should end up with 3 files:

• The game executable
• The PCK file
• An extra libpythonscript library file you probably don't need (I always delete it on Linux)

Step 4 - Bring in your Portable Python Installation

In your export directory, along side the game binary, create a new directory called addons.
Inside the new directory, create another directory called pythonscript.

In a new window, navigate to the addons/pythonscript directory in your project, and copy the LICENSE.txt file and the appropriate platform directory matching your distribution OS (in my case, x11-64 for Linux) over to the addons/pythonscript in your export directory.

Step 5 - Repack the PCK - Trick Godot ;)

The important thing to note here is that Godot never actually looks at the content of resource files when it starts up. It checks to make sure all the files referenced by the project are present, but it doesn't actually read them until they're requested. You're going to take advantage of that and give it a bunch of empty dummy files to act as script placeholders in the PCK.

Python will read the -real- script files later when the addon starts up -- we'll get to those in the next step.

Create a Scripts directory in your export directory along side the game binary.
To be honest, this part's kind of annoying if you're not automating it with a script -- but we do what we must.

Inside the new Scripts directory, create a new empty file for each *.py Python script in your project's Scripts directory, and name them exactly the same. These empty dummy files are going to replace the scripts currently in the PCK.

Once you're sure you have a precisely named empty dummy file for each of your Python scripts, open a terminal, cd to your export directory, and run the following command to replace the Python scripts in the PCK with your dummy copies -- Note, I'm going to call it HelloWorld.pck here -- replace it with your actual PCK file's name.

godotpcktool "HelloWorld.pck" -a r -e "/Scripts/.*.py" -a a "Scripts/"

If you're curious (and you should be), in long form, that's:

• --action repack
• --exclude-regex-filter "/Scripts/*.py"
• --action add "Scripts/"

If you'd like to verify the PCK file at this point, you can do so by extracting it using the following command. Just remember to delete the extracted directory when you're done.

godotpcktool "HelloWorld.pck" -a e -o extracted

Step 6 - Bring In the Real Python Scripts

Now that you've tricked Godot's PCK loader and eliminated that wasted space, time to take advantage of Python's better nature :)

When the Godot-Python addon fires up Python, it knows nothing of the PCK file.
It wants to see those scripts where it expects them (and where it can compile them), in an actual Scripts directory.

Assuming everything went well in Step 5 (you did verify the PCK file, right? ;) then you can go ahead and delete those dummy files in the export Scripts directory you created earlier.

Copy in all of the real *.py files from your project's Scripts directory to the export's Scripts directory.

Step 7 - Compile Your Scripts and... BE DONE!

When Python loads a *.py file, it compiles it to bytecode before running it the first time. On subsequent runs, it looks to see if it has a bytecode file that isn't older than the *.py file itself, and, if so, just goes ahead and runs it. As a matter of fact, so long as you name the bytecode file correctly, it doesn't even care if there's a *.py file at all!

Regardless of your distribution intentions, you don't want players to have a slow first start (and bad first impression), so you should precompile the bytecode for them.

Note: This must be done separately for each release on each operating system -- they don't share the same bytecode.

In a terminal, cd into the export's Scripts directory and run one of the following:
(Note: the first argument to python is a hyphen followed by two capital letter 'o' -- this enables the optimizer)

Linux:

chmod 755 ../addons/pythonscript/x11-64/bin/python3.8
../addons/pythonscript/x11-64/bin/python3.8 -OO -m py_compile *.py

macOS:

chmod 755 ../addons/pythonscript/osx-64/bin/python3.8
../addons/pythonscript/osx-64/bin/python3.8 -OO -m py_compile *.py

Windows:

../addons/pythonscript/windows-64/python.exe -OO -m py_compile *.py

You should now see an extra __pycache__ directory containing the compiled *.pyc bytecode files inside your Scripts directory.

Now, if you're releasing your game open source, and intentionally trying to keep your scripts available to make it easier to mod, then you can stop here -- you're all done and you can skip the rest :)

But if not... if you want to obfuscate your code, get rid of all those comments and docstrings, and make it significantly more difficult for players to mod your scripts (but not impossible!), there's just one more thing to do.

Delete all of the *.py files from your export's Script's directory, and then copy all of the compiled *.pyc bytecode files from the new __pycache__ directory down into the Scripts directory, and delete __pycache__.

The files should look something like Hello.cpython-38.pyc -- the middle string may vary slightly from system to system, but it just designates the compiler used to generate the file. Rename all of the *.pyc files, removing the compiler string from the middle.
Example Hello.cpython-38.pyc -> Hello.pyc.

That's it. You're done. 2 Files, 2 Folders.
Run the game binary and make sure everything's working as planned.

If so, your dist version is all set to go :)

[codewithmichael]

Extra note

If you want to save a little more space, you can also remove the bin and include dirs from the addon in your distributable -- e.g.:

• addons/pythonscript/x11-64/bin
• addons/pythonscript/x11-64/include

Everything's already built and run through the libpythonscript dynamic lib bindings, so your distributable doesn't need the executable binaries and headers.

You can also remove any unnecessary modules from the lib/site-packages directory.
For example, there's no need to distribute the pip module with your project just because you used it to install other modules.

These things should be decided on a per-project basis, depending on whether you're distributing your project and/or scripts open-source, so they're not reflected in the gist above, but just know the options are there :)

[gnuchanos]

i hope this is be easy in the future
project looking dead now

./Godot_v3.5.3-stable_x11.64 --path pythonTest/ --export "Linux/X11" /home/archkubi/Godot/newexport/
Godot Engine v3.5.3.stable.official.6c814135b - https://godotengine.org
OpenGL ES 3.0 Renderer: Mesa Intel(R) HD Graphics 3000 (SNB GT2)
Async. shader compilation: OFF

Pythonscript 0.50.0 (CPython 3.8.5.final.0)
ERROR: Failed to open /home/archkubi/Godot/newexport/
at: copy (core/os/dir_access.cpp:297)
ERROR: Prepare Template: Failed to copy export template.

at: add_message (editor/editor_export.h:254)
ERROR: Project export for preset "Linux/X11" failed.
at: _fs_changed (editor/editor_node.cpp:822)

[Lance-Starkie]

Me too this is driving me nuts right now. It refused to recognize the .dll as existing I'm so lost

[gnuchanos]

2023-10-16.23-10-04.mp4

normal export works like this but i just do just press button print world i don't know how switch scene or do different and give up there is no doc for this

[Lance-Starkie]

Fair yeah it's definitely driving me nuts so far. The .zip export works fine so I'm gonna try just loading stuff in from an external .pck from an extra loader project so I can still keep stuff packed up.

Still a pain with AutoLoad issues and weird load order stuff but it seems like there's a light at the end of the tunnel for this approach!

Wish me luck 😂

[gnuchanos]

good luck bro