commonlib.package

NPL package system

Title	NPL package system
Author(s)	LiXizhi
Date	2008.5.11
File	script/ide/package/package.lua

Description

This class is part of commonlib

What is a package?

A package is a redistributable zip file containing asset files and may optionally having an installer script or an start up script. A zip package file is first downloaded or manually copied to the "packages/" directory. And should be named as [MyPackageName]-[version].zip When a package is loaded, the files in side the zip package files will be available via the NPL file io.

There are four kinds of packages: startup, lib, installer, redist

startup packages

package files under "packages/startup/" are assumed to be start up packages. They are loaded early when ParaEngine start up. It is suitable to distribute core applications, common assets, etc as startup packages. The package start up script is called when a package is loaded this way. the startup script file must be named "[MyPackageName]-[version].zip.startup.lua", and it will search for this file in the "packages/" directory as well as all its first level sub directories. HINT: one can put the start up script inside the zip package itself.

lib packages

package files under "packages/" are assumed to be lib packages. They are loaded On Demand when a client applications calls commonlib.package.use("MyPackageName"). It is suitable to distribute extensions to applications, such as world specific assets, extension games, shared art pack, etc as lib packages. The package start up script is called when a package is loaded this way. the startup script file must be named "[MyPackageName]-[version].zip.startup.lua", and it will search for this file in the "packages/" directory as well as all its first level sub directories.

installer packages

package files under "packages/installer" are assumed to be installer packages. When the main interface is loaded, the ParaWorld platform will popup a dialog for each installer package, asking for user to install or skip the package. It is suitable to distribute application patches, updates or very important big applications as installer packages. The package installer script is called when a package is loaded this way. the installer script file must be named "[MyPackageName]-[version].zip.startup.lua", and it will search for this file in the "packages/" directory as well as all its first level sub directories.

redist packages

This is actually not a specific package type. Developers can create new packages in this directory, since contents in this folder are not processed in the package system. When it is ready, they can copy or move the packages to other folders accroding to package type. The AssetsApp contains a PackageMaker application that helps developers to make redistributable packages.

Package Versioning

At run time, multiple versions of a packages can be loaded at the same time, however whether it can work properly is up to the package author. An author is encourage to write and use version aware application codes. Basically if one uses a package without specifying its version, the latest version is automatically located and used.

Package Format

There are two supported package file format: zip or pkg. Zip is the widely supported zip format; where pkg is an encrpted zip format defined by ParaEngine and solely used by official applications. if there is a zip and pkg file with the same name and version number under a directory, the zip file is used. Zip file only falls back to pkg file.

Sample Code

NPL.load("(gl)script/ide/package/package.lua");

-- at any time, call following to ensure package is loaded on demand. 
commonlib.package.require("MyPackageName", "1.0")
commonlib.package.require("MyPackageName")

-- when ParaEngine starts up, call following function only once to start startup script. Usually at one of the beginning lines of the game interface script.
commonlib.package.Startup();

Member Functions

package.require

---

public methods:

---

use a package, this function will ensure that the package is loaded

• param packageName : string name of the package without version number. e.g. suppose your package file is called packages/mypackage-101.zip. then the package name should be "mypackage"
• param packageVersion : the version can be nil, a number or a string containing a number. If nil, the latest version will be used. Otherwise it will try to find an available version.
• return __ : true if loaded, otherwise nil.

syntax

function package.require(packageName, packageVersion)

parameters

| packageName | string name of the package without version number. e.g. suppose your package file is called packages/mypackage-101.zip. then the package name should be "mypackage" |

packageVersion
return	true if loaded, otherwise nil.

package.Startup

refresh package info in "packages/" and its sub directories, and load the latest version of all packages in the packages/startup folder

• return __ : the number of packages are returned.

syntax

function package.Startup()

parameters

return	the number of packages are returned.

PackageInfo:new

-------------------------------------
 package info
-------------------------------------
local PackageInfo = {
   -- nil: lib package, 1: startup package, 2: installer package, 3 is other (redist) package. 
   type = nil,
   -- whether the package is loaded or not. 
   IsLoaded = nil,
   -- package major name
   name = nil,
   -- package minor version. currently only the first minor number is used. 
   version = 0,
   -- startup script: nil means not searched. "" means does not have this script, or it should be an valid string path. 
   StartupScript = nil,
   -- full package file path string. 
   filepath = nil,
   -- file extension, zip or pkg.
   ext = nil,
}

syntax

function PackageInfo:new (o)

parameters

o

PackageInfo:Load

Load this package if not loaded before. it will cause the startup or installer script to be called.

• return __ : true if loaded succesfully.

syntax

function PackageInfo:Load()

parameters

return	true if loaded succesfully.

PackageInfo.CreateFromPath

-------------------------------------
 private functions: 
-------------------------------------

 a mapping from path to package type
local packageTypePath = {
   ["packages"] = nil,
   ["packages/startup"] = 1,
   ["packages/installer"] = 2,
   ["packages/redist"] = 3,
}

; Create a new package from file path. It just derives package information from

• param filepath : such as packages/startup/test-1.0.zip
• return nil : or a new PackageInfo is returned.

syntax

function PackageInfo.CreateFromPath(filepath)

parameters

filepath	such as packages/startup/test-1.0.zip

package.BuildPackageInfoInFolder

build package info of all packages in a given folder

• param folderPath : where the packages are located. such as "packages/startup/", "packages/installer/" , "packages/" , "packages/redist/"
• param nSubFolderLevel : how many levels of sub folders to search for. if nil, it defaults to 0 which is the current folder.

syntax

function package.BuildPackageInfoInFolder(folderPath, nSubFolderLevel)

parameters

folderPath	where the packages are located. such as "packages/startup/", "packages/installer/" , "packages/" , "packages/redist/"
nSubFolderLevel

package.InsertPackageInfo

insert a new package info to the current pool.

syntax

function package.InsertPackageInfo(pkgInfo)

parameters

pkgInfo