PKGFiles

Package Files

Package file is just an ordinary zip file. One can bundle scripts and assets in one or more package files, and load them at runtime. Each loaded package file is a virtual read-only file system. It provides a layered file interface on top of standard file system. Each package file is like a search path. The one that is opened last is searched first.

Generate package file

There are two kinds of package files: one is the standard *.zip file, the other is called *.pkg file.

One can use any external tools to generate zip file, or using the build-in NPL API, like below

-- testing creating zip files
local zipname = "temp/simple.zip";
local writer = ParaIO.CreateZip(zipname,"");
--writer:ZipAdd("lua.dll", "lua.dll");
writer:ZipAdd("aaa.txt", "deletefile.list");
--writer:ZipAddFolder("temp");
-- writer:AddDirectory("worlds/", "d:/temp/*.", 4);
writer:close();

One can create *.pkg file from a standard zip file with the NPL API like below. *.pkg use a simple encryption algorithm over the zip file.

ParaAsset.GeneratePkgFile("main.zip", "main.pkg");

Load package file

When application starts, NPL runtime will automatically load all main*.pkg and main*.zip files in the application's start directory into memory. The load order is based on file name, so that the a file in "main_patch2.pkg" will overwrite the same file in "main_patch1.pkg".

Please note that loading package file is very fast, it only copies the entire zip file into memory, individual script file or assets are only unzipped and parsed on first use.

A programmer can also programmatically load or unload any archive file using the NPL API like below.

NPL.load("pluginABC.pkg");
-- or using explicit calls
ParaAsset.OpenArchive("pluginABC.pkg", true);

Both functions will search pkg and zip file extensions if the other one is not found. Search paths, such as from npl_packages are honored when loading package files.

The second parameter of ParaAsset.OpenArchive is whether to use relative path in archive files. (i.e. file path in archive file are relative to the containing directory). If the second parameter is false (default value), all file paths in pkg file are relative to the application root directory. So one can regard pkg file as a way of mounting a virtual read-only file system at a specific application path.

ParaAsset.OpenArchive("pluginABC.pkg", false);

For example, if there is a file path in above pkg file called "script/app/abc.npl", then one can read the file with ParaIO.open("script/app/abc.npl").

One can explicitly specify the root directory, then all relative file path in zip files is regarded as relative to this directory.

local filename = "pluginABC.zip";
local zip_archive = ParaEngine.GetAttributeObject():GetChild("AssetManager"):GetChild("CFileManager"):GetChild(filename);
zip_archive:SetField("RootDirectory", "pluginABC/");

One can also set the base directory to be removed from the relative path of all files in the zip file.

local filename = "pluginABC.zip";
local zip_archive = ParaEngine.GetAttributeObject():GetChild("AssetManager"):GetChild("CFileManager"):GetChild(filename);
zip_archive:SetField("SetBaseDirectory", "pluginABC-master/Mod/pluginABC/");

Example of Packaging Paracraft

In real applications, one should use automation scripts to do the jobs.

Click https://github.com/lixizhi/paracraft to see how to package paracraft