PCK/ZIP: add-ons, patches and loading order

What a pack mounts

A PCK or ZIP adds files to the virtual asset:// filesystem. Use it for additional levels, assets and content updates. Mounting does not start a level, add Entity instances or automatically update objects already in memory.

A resource pack is not an installer for a new executable. Changes to C# code, native extensions or the engine need a separate, coordinated build and delivery process. Placing a DLL inside a PCK does not by itself load it into .NET.

For an ordinary image or sound outside a pack, use external file loading.

Prepare the pack

1. Add the content to a project and wait for import. Use the same Reckfell version and an export preset suitable for the target platform.
2. Give an add-on its own paths, such as asset://Mods/Island/. Include the level and all its dependencies. Internal paths must match the paths requested by the game.
3. In the export window, select the preset and Export PCK/ZIP…. The output extension selects the format. Save outside the project directory.
4. Test in the target game build: a successful mount does not prove that every texture or imported file is present or that code is compatible.

Project export covers preset preparation. For automation, the editor supports --export-pack <preset> <path>; see the command line for launch syntax. Simply archiving source models does not replace exporting their imported resources.

Mount before loading the level

This example expects a pack containing asset://Mods/Island/Main.rscene without additional C# assemblies. Save the class as PackLevelExample.cs:

using Reckfell;

public static class PackLevelExample
{
    public static bool TryLoadLevel(string packFile, string levelPath,
        out PackedEntity? level, bool replaceFiles = false)
    {
        level = null;
        if (!FileAccess.FileExists(packFile))
            return false;
        if (!ProjectSettings.LoadResourcePack(packFile, replaceFiles))
            return false;
        level = ResourceLoader.Load<PackedEntity>(levelPath);
        return level is not null;
    }
}

Pass the physical PCK/ZIP path and the logical level path. When the function returns true, level contains a PackedEntity: loading is complete, but there is no instance in the tree yet. Call Instantiate() and add the instance to the appropriate parent with AddChild(), or pass the resource to EntityTree.ChangeSceneToPacked() to change levels.

A false result means the file is absent, mounting failed or level loading returned no resource. Check the log for format and dependency errors too. If mounting succeeds but loading the level fails, mounted paths remain: this function does not roll back the mount.

Mount in an explicit loading stage before the first access to add-on resources. Moving the call into an arbitrary object's _Ready() does not guarantee this order: other objects may already have loaded the resource. _init() and _ready() are not C# method overrides.

Path collisions and the cache

Thus replaceFiles: false controls ordinary file collisions; it does not isolate a mod. A PCK removal entry applies even with false: this flag does not protect registered paths from patch removals. Use a dedicated path prefix for an independent add-on. For patches, mount the base and then updates in the prescribed order with replacement enabled.

To diagnose, compare FileAccess.GetFileAsString() on a text file with a fresh ResourceLoader.Load<Resource>(path, "", ResourceLoader.CacheMode.Ignore). The former reads current bytes; the latter bypasses the cache for the requested resource itself. Ignore does not deeply bypass dependency caches or update old references, materials or Entity instances. For releases, applying patches before loading game resources is simpler; hot updates need separate resource-lifetime management.

Ordinary patches and deltas

The export preset's Patching section specifies base packs. Patch export compares current content against these and writes changes. Automation supports --export-patch <preset> <path> and --patches <paths> with a comma-separated list of bases.

Retain the base and patches that were actually shipped. Delta encoding requires the original file bytes and correct chain: on the player's machine, mount the same base packs in the same order used to build the patch. A delta stores differences within files; an ordinary patch can store changed files in full. Measure size and loading time on your content—a smaller patch does not guarantee faster loading.

Diagnose an add-on failure

Mods containing executable code do not become sandboxed by being packed into PCK/ZIP. Accept them from trusted sources. For your updates, verify authenticity before mounting; file presence and successful LoadResourcePack do not establish authorship. The pack format also does not by itself restrict copying paid content.