GodotPckTool packs and unpacks Godot .pck files with path control down to the file

A standalone packer, plus a library for C# callers

GodotPckTool is a standalone executable for unpacking and packing Godot .pck files, and the README says you can view the tool help by running godotpcktool -h. The executable is what most people need, and it is available from the releases page. There is a second thing in the repository that is easy to miss, which is a C# code library that can be used from C# code to interact with .pck files. That matters more than it sounds. The command line tool is for people assembling a build, while the library is for a tool that has to manipulate packs as part of a larger pipeline, for example a content pipeline that repacks after each asset import. The repository layout reflects that split, with a src/ directory for the C++ side, GodotPckTool.CSharp/ and GodotPckTool.CSharp.Tests/ for the managed side, a GodotPckTool.sln, and a StyleCop.ruleset with stylecop.json for the C# code style.

Short flags and long forms for the same three operations

The command line has three operations and each has a short and a long form. Listing the files inside a pck file is the first:

godotpcktool Thrive.pck

and the long form of the same thing is:

godotpcktool --pack Thrive.pck --action list

Extraction is the second, and here the short form names the action and the output directory:

godotpcktool Thrive.pck -a e -o extracted

while the long form spells it out as --action extract and --output extracted. Adding content is the third, and it can also create a new pck where there is none. There is a small platform wrinkle the README mentions, that if you do not install the tool on Linux you need either the full path or a folder and to run it as ./godotpcktool, the same as on Windows. Everything else about the interface is deliberately conventional, a single positional pack file, short actions, and long options for scripts that want to be readable.

Adding files strips the source prefix and adds res:// for you

The add operation takes the paths to add on the command line, with the prefix removed, and there is a flag that names the Godot version a newly created pck claims to be packed with, set-godot-version. The example shows the shape:

godotpcktool Thrive.pck -a a extracted --remove-prefix extracted

The rule it applies is worth remembering because it changes where files land. If a file was called extracted/example.png and another extracted/subfolder/file.txt, after the operation they are inside the pack as res://example.png and res://subfolder/file.txt. If you do not want the res:// prefix added at all, the --no-res-prefix flag prevents it, and the example of that is a new pack with a single file:

godotpcktool NewPack.pck -a a some_file.txt --no-res-prefix

Two behaviours are documented that will save you a confusing diff later. When a new file matches exactly the path name inside the pck, it will replace that file, and after adding files the recommendation is to run the listing command to view the resulting data and verify the expected actions happened. The version stamp has its own limit, since the approach does not override the engine version number in existing .pck files and currently only applies to new ones.

Filters are regular expressions and size limits, and they compose in a fixed order

Filters restrict which files an operation touches, either inside the pck or on the filesystem. The size filters are numeric, with a minimum size under which files are excluded and a maximum size above which they are excluded, and the README warns about a trap when using them together. If you use max size to complement min size extraction, you should subtract one from the size, otherwise you will operate on the same files twice, and if you want to work on exactly some size files you can specify the same size twice, for example:

godotpcktool --min-size-filter 1 --max-size-filter 1

The name filters are regular expressions, and the include option takes a list of them, selecting only files that match at least one:

godotpcktool -i '\.po'

Multiple expressions can be separated by a comma or given by repeating the option, so both of these are valid, and the README notes that different shells need different escaping. Filtering is case-sensitive, and if no include filter is specified then all files pass through it. Exclusions work the same way with the exclude option, and when both are given the include filter is applied first, after which the exclude filter removes files that passed the first one:

godotpcktool -i '\.po' -e 'zh'

There is also an override for the other direction, --include-override-filter, which makes any file matching those expressions be included in the operation even if another filter would have excluded it, which is how you set a size limit and then carve out a specific file type.

The JSON bulk API is how you control the exact path of every file

For finer control over the resulting paths, the tool offers a JSON operation API, and the format is a list of file and target pairs:

[
    {
        "file": "/path/to/file",
        "target": "overridden/path/file"
    },
    {
        "file": "LICENSE",
        "target": "example/path/LICENSE"
    }
]

The command file is passed with --command-file, and it can always be specified when the add operation is used:

godotpcktool Thrive.pck -a a --command-file commands.json

Reading it in full, the tool reads the source file, which can be an absolute or a relative path, and saves it in the pack at the target path with the res:// prefix added, so /path/to/file becomes res://overridden/path/file and LICENSE becomes res://example/path/LICENSE. There is one sharp edge, and the README is explicit about it. The full path without the res:// prefix has to be in the target property, and this mode does not support specifying just a folder, so multiple files with a target of pck/folder will overwrite each other rather than being placed inside pck/folder. Always specify full paths like pck/folder/README.txt. For scripting, the same API works without a temporary file, by passing - as the file to add and writing the JSON to the tool's standard input.

The build is CMake, with cross compilation and a container path

The Makefile at the repository root wraps CMake, and the targets show how the project expects to be built. A plain build is cmake into a build directory, a debug variant sets the build type, compile builds it, and install-local installs into a prefix. The test target is present and marked not implemented yet, which tells you something about the state of the automated testing. Cross compilation to Windows is handled with a separate build directory and a MinGW cmake, and the Makefile even detects Arch at build time to pick between x86_64-w64-mingw32-cmake and mingw32-cmake. There is also a podman path, with a build-podman target, a podman-build-image target that builds the image tagged godotpcktool-builder, and a compile-podman target that runs the build inside the container. The Dockerfile for that path starts from ubuntu:22.04 and installs make, cmake, build-essential, g++ and coreutils in a builder stage, and there is an in_container_build.sh script beside it. The topics also name thrive, which is the project that this tool was built for in the first place.

Editorial conclusion

Adopt GodotPckTool if you build Godot projects whose .pck files have to be assembled from a directory rather than exported by the editor, since it understands the container format, the res:// path convention and the Godot version stamp, and it also gives you a C# library if that is your language. Do not adopt it as a general purpose archive tool, because the point of it is the Godot specific structure rather than compression. Before you rely on it, remember the two boundaries in the documentation, the engine version flag applies only to new archives, and the JSON target property must be a full path rather than a folder, or files will overwrite each other.

Frequently asked questions

Official sources

1. hhyyrylainen/GodotPckTool on GitHub
2. Issues
3. License: MIT
4. README
5. Releases