Zip-file Script Packages

This Zip- file Script package file can be run like an ordinary .ms file. Any secondary files, needed by the tool, will be either automatically found in the package or they will be automatically extracted to specified locations prior to running the main tool scripts.

The file type for script packages is '.mzp' . These files are recognized as executable script files in the following situations:

• Auto-loading at MAX startup, in scripts\startups, stdplugs\stdscripts, etc. any .mzp file found is run.

• Choosing the Run Script menu item in the main MAXScript menu, or in the Listener menu, now shows .mzp files as one of the default kinds of executable files in the Open Script dialog and will run it if selected.

• Specifying a fileName: parameter when adding a callBack script.

• As executable files inside other .mzp archives, you can nest them if want.

• When using the fileIn fileName function, you can specify a .mzp package for fileIn.

The mzp Package

The package startup control file is 'mzp.run'. When a .mzp package is opened, it is scanned for an 'mzp.run' file and, if found, the package commands in it are executed in sequence.

If there is no mzp.run control file in the package, MAXScript will unzip all the files in it to a unique temporary directory in the system temp directory and run all the executable script files it finds, in unspecified order. The kinds of runnable script files in a .mzp package are .ms, .mse and nested .mzp files.

When the contents of the .mzp file is extracted to a destination folder, either the default temp folder or one defined in the mzp.run control file, MAXScript will build and replicate any folder structure that is present in the .mzp file.

When you cause a script file inside the package to be run, either through 'run' commands in the mzp.run file, or by the default running scheme described in the previous item, the package becomes a search context for files that the script may try to open while it is running such things as image .bmp files, include files, etc. Only files named by relative path names are searched for in the package, fully specified paths (with device names at the front) will be looked for at the specified location.

The names of files and directories in commands that take them now can be supplied WITHOUT surrounding double quotes if the name contains only the following kinds of characters:

alphanumeric, '_', '$', '*', '.', '-', '\\'

which covers most file names. Any file names with embedded spaces or punctuation not in the above list needs double-quotes.

EXAMPLE

name "test package"
version 3
treeCopy flobber to $scripts
copy *.ms to $scripts\flobber\dobber
move foo.max $scenes
drop $scenes\foo.max

The zip package is a text file that contains one or more of the following commands. All are optional.

name "<package_name>"   

Names the package.

description "<text>"   

Describes the package. Normally, a readme file in the package would give extended operating instructions, if they are provided.

version <number> 

Returns the version number of the package.

extract to "<directory>" 

Specifies the location in which to extract the contained files. This can be an absolute path name (starting with a drive letter or \) or a relative name. Relative names are taken as being relative to the default temp directory. The special prefix $max can be used to specify the main MAX executable directory

run "<script_file_name>" 

If the package is launched from a MAXScript run menu item or via a fileIn() function, run the named script file. There can be more than one run command and they are run in order. These are ignored if the package is launched via a fileIn() call that is supplied with an explicit script file to run. During the execution of an mzp.run file, any 'run' commands are ignored. See mzp drop protocol for details.

drop "<dropScript_file_name>" 

If the package is launched by drag-and-drop into MAX, run the named dropScript file. There can only be one of these per msp.startup file.

copy "<files>" to "<directory>" 

Copies the named file or files (if the <files> string contains wild-cards) to the given directory. The special $max prefix can be used here.

clear temp 

Cause the temporarily-extracted files to be deleted once all the nominated scripts are run or dropped.

clear temp on MAX exit 

Cause the temporarily-extracted files to be deleted when the currently running MAX session exits.

clear temp on reset 

Cause the temporarily-extracted files to be deleted when a file open or reset is performed.

keep temp 

Prevents any deletion of the extracted files.

open <max_file_name> 

Opens the named MAX scene file.

merge <max_file_name> 

Merges the named MAX scene file.

xref <max_file_name> 

Xrefs the named MAX scene file.

import <importable_file_name> 

Imports the named file.

Only one 'open' or 'import' command may be used per mzp.run file. Any number of 'merge' and 'xref' commands can be used.

File Searches:

The following functions will perform searches for files given as relative file names in the current package file:

fileIn

include

openBitmap

editScript <filename> 

loadMAXFile <filename> 
mergeMAXFile <filename> ... 
getMAXFileObjectNames <filename> 
importFile <filename> ... 
loadMaterialLibrary <filename> 

Bitmap Searches:

The following UI items will search for named bitmap .bmp files in the package:

bitmap <name> fileName:<filename> 
button <name> images:<image_spec_array> 
checkButton <name> images:<image_spec_array> 

Relative file names can contain path names, so

EXAMPLE

fileIn "libs/myFns.ms"

would search in the "libs" sub-folder in the extracted package for "myFns.ms". You can arrange the contents of the package in any kind of folder nesting desired and file names in running script or in the mzp.run control file are relative to the package directory structure.

Copy and Move:

copy "<from>" to "<to>" [noReplace] 
move "<from>" to "<to>" [noReplace] 
treeCopy "<from>" to "<to>" [noReplace] 
treeMove "<from>" to "<to>" [noReplace] 

These cause files from within the package to be copied or moved as specified. The treeCopy & treeMove variants move whole nested directories of files. By default, any existing files in the destination location are replaced with the newly extracted ones, add the 'noReplace' keyword to prevent this.

The <to> spec must always be a directory. Any treeCopy/Move replicates the source sub-directories into the <to> directory, making new directories as needed. The <from> spec for copy & move may be any relative or fully specified file name or wild-card pattern. Relatively named files are looked for in that relative position in the package. Fully specified names are looked for in the main file-system.

The <from> spec for treeCopy/Move may be just a directory path, in which case the whole directory and its subdirectories are copied/moved, or it can be a wild-card path name in which case just the matching files or directory trees are copied/moved.

The file path names you can specify in the various commands (extract to, run, copy, move, etc.) can have a starting path that is one of several special names beginning with $. These name useful locations in the currently running MAX installation.

For a list of recognized $ names, see Symbolic Pathnames.

These directories reflect any customization the user has set up in the various preference dialogs.

EXAMPLE

If you had set up a package with several scenes, plug-ins & map files in several directories in the package, you could install them with some move commands in the mzp.run file, something like this:

move "plug-ins\*.*" to "$plugins"
move "*.max" to "$scenes"
move "texmaps\*.bmp" to "$maps"

As an added feature, if the scripts run from within a package define any functions, macroScripts, plug-ins, rollouts, or any major MAXScript value or construct that might live longer that the running script, then the package is 'associated' with that defined value or construct and will again become the initial search location whenever the functions or handlers in the rollouts/plug-ins/macroScripts/etc. are later run.

Winzip:

You can initially create a .mzp with a zip utility such as WinZip. You can then associate that utility with the .mzp type, so simple double-clicking a .mzp file will open it in that editor. You only need to set up this association once, and you can do this in the Windows Explorer by selecting a .mzp file, shift-right-clicking on the selected file and choosing "Open with..." in the popup menu that appears. Scroll the application list that appears to find you desired zip utility and check the "Always use this program ..." checkbox at the bottom of the dialog.

msZip Interface:

The MAXScript zip package interface has exposed 2 MAXScript-callable functions:

msZip.fileInPackage <mzpFilename> &<exractDirVar>       

The 'fileInPackage' function is essentially the equivalent of:

fileIn <mzpFileName>    

and will return true if success or false if there is a failure, or a missing or invalid .mzp file, and it will also return the directory that the package file were extracted to in the pass-by-reference <extractDirVar> argument.

EXAMPLE

local extractDir = ""
if msZip.fileInPackage "foo.mzp" &extractDir then 
( 
-- extractDir contains the extracted-to directory name ... 
) 
msZip.unloadPackage <mzpFilename> &<exractDirVar> &<dropFileVar>     

The 'unloadPackage' function performs an extract and executes all the file copying and moving commands in any enclosed mzp.run file, but will not execute any scripts in the package. The extractTo directory and any 'drop' command file found will be returned in the pass-by-reference arguments.

EXAMPLE

local extractDir = "", dropFile = ""
if msZip.unloadPackage "foo.mzp" &extractDir &dropFile then
(
-- extractDir contains the extracted-to directory name
-- dropFile contains any found drop file name (the path to extracted location )
...
)