PCK encryption: key, templates and filters

PCK encryption

PCK encryption hides selected file contents from simple archive reading. It does not turn a client game into secret storage: the decryption key is present in the executable build. External DLLs and other files outside the PCK are not encrypted by this method.

You need the same 32-byte key for packing and the matching export template, plus the correct template and filters. Represent the key as 64 hexadecimal digits without 0x, spaces or a newline. An arbitrary prebuilt template will not acquire your key from an environment variable at game startup.

Prepare the key

PowerShell 7 example: the key is generated in memory, not printed, and passed to current build/export processes. Use a separate shell prepared for Windows builds.

$pckKey = [Convert]::ToHexString([Security.Cryptography.RandomNumberGenerator]::GetBytes(32)).ToLowerInvariant()
if ($pckKey -notmatch '^[0-9a-f]{64}$') { throw "Invalid key format" }
$env:SCRIPT_AES256_ENCRYPTION_KEY = $pckKey
$env:RECKFELL_SCRIPT_ENCRYPTION_KEY = $pckKey

For repeat builds retain the original key in your protected storage and load it into the build process environment. Do not generate a new key for each export while keeping an old template. Do not send the key to an online generator or put it in a published example.

An empty first variable is not the same as an absent one: do not leave it empty expecting the fallback. Setting both variables to the same value avoids this ambiguity. Launch the editor or CLI exporter from the shell carrying the environment: an already open editor does not inherit the new environment.

Build and select templates

Build the required variants from the Source root. For a native Windows x64 project, for example:

scons platform=windows target=template_debug arch=x86_64
scons platform=windows target=template_release arch=x86_64

C# also requires module_mono_enabled=yes and the matching managed assemblies: see .NET builds. Do not substitute a native-only template for a C#-capable one.

In the Windows preset assign the produced files to custom_template/debug and custom_template/release. Key, architecture, precision and required modules must match. Release export selects the release template; debug export selects the debug template. A build message acknowledging the key proves the variable was read, not that the future game launches successfully.

When changing the key rebuild every template you use and re-export the PCK. Do not replace the working installed Runtime with an experimental build.

Configure the export preset

Open encryption settings for the selected export preset:

Filters match exported paths case-insensitively, with or without asset://. They do not determine export contents: including a resource in the PCK and selecting it for encryption are different operations. An imported texture may be exported under an internal path, so a filter matching only source *.png files does not prove its imported data was encrypted.

Export uses a nonempty RECKFELL_SCRIPT_ENCRYPTION_KEY, otherwise the preset key. The current editor saves the preset key to .reckfell/export_credentials.cfg and ordinary settings to export_presets.cfg. Do not publish the credentials file. For CI supply the key through the environment before starting the export process.

With manual PckPacker packing, controls are independent: PckStart(..., encryptDirectory: true) encrypts the directory, whereas AddFile(..., encrypt: true) or AddFileFromBuffer(..., encrypt: true) encrypts a particular file's data. Neither flag replaces the other. Check results from PckStart, file additions and Flush.

Verify the result

1. Export using the intended preset and matching template.
2. Run the exported game, not the project in the editor. Open a level and load encrypted textures, audio and other resources.
3. Repeat for each debug/release variant you actually ship. Do not generalize from one architecture or platform to another.
4. Check that selected data is absent as plaintext in the PCK and that selected paths are not visible when directory encryption is enabled. Such a search alone does not validate cryptographic protection; it helps detect a disabled flag or empty filter.

For this article the installed SDK was checked with four combinations of file/directory encryption, independent AES decoding of the produced data and integrity-check rejection using a wrong test key. New templates with a custom key were not built; complete exported-game startup is not confirmed here.

Diagnose export or loading failures

• Data remains visible: check encrypt_pck, include filters and exclusions. Directory encryption does not automatically encrypt files.
• Can't open encrypted pack directory: directory decryption failed. Check the selected template, key and PCK integrity.
• MD5 sum of the decrypted file does not match: the key may be wrong or the file damaged. The message does not prove only one cause.
• Editor reads it, game does not: a tool reading with an explicitly supplied key does not prove that key is embedded in the export template.
• Only debug works: check the separate release template and its build environment.

After working, clear the separate shell environment. This does not remove the key from an already built binary or saved preset:

Remove-Item Env:SCRIPT_AES256_ENCRYPTION_KEY -ErrorAction SilentlyContinue
Remove-Item Env:RECKFELL_SCRIPT_ENCRYPTION_KEY -ErrorAction SilentlyContinue
Remove-Variable pckKey -ErrorAction SilentlyContinue