---++!! !commonlib.package %TOC{title="Contents:"}% %STARTINCLUDE% ---++ 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. %T% __Sample Code__ <verbatim> 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(); </verbatim> ---+++ 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__ <verbatim>function package.require(packageName, packageVersion)</verbatim> __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__ <verbatim>function package.Startup()</verbatim> __parameters__ | *return* | the number of packages are returned. | ---++++ !PackageInfo:new <verbatim>------------------------------------- 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, }</verbatim> __syntax__ <verbatim>function PackageInfo:new (o)</verbatim> __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__ <verbatim>function PackageInfo:Load()</verbatim> __parameters__ | *return* | true if loaded succesfully. | ---++++ !PackageInfo.CreateFromPath <verbatim>------------------------------------- private functions: ------------------------------------- a mapping from path to package type local packageTypePath = { ["packages"] = nil, ["packages/startup"] = 1, ["packages/installer"] = 2, ["packages/redist"] = 3, }</verbatim>; 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__ <verbatim>function PackageInfo.CreateFromPath(filepath)</verbatim> __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__ <verbatim>function package.BuildPackageInfoInFolder(folderPath, nSubFolderLevel)</verbatim> __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__ <verbatim>function package.InsertPackageInfo(pkgInfo)</verbatim> __parameters__ | *pkgInfo* | | %STOPINCLUDE%
E
dit
|
A
ttach
|
P
rint version
|
H
istory
: r1
|
B
acklinks
|
V
iew topic
|
Ra
w
edit
|
M
ore topic actions
Topic revision: r1 - 2008-02-29
-
LiXizhi
Home
Site map
CCWeb web
HaqiTeen web
Main web
ParaEngine web
TWiki web
Main Web
Users
Groups
Index
Search
Changes
Notifications
RSS Feed
Statistics
导航页WebTopMenu
Preferences
开发指南
Getting Started
ParacraftSDK
NPL
MCML
NPL Reference Manual
美术Mod
Account
Log In
English
简体中文
簡體中文
E
dit
A
ttach
Copyright © 2008-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki?
Send feedback