prevnext   » SZS: Wiimms SZS Toolset » wszst: Wiimms SZS Tool

wszst: Wiimms SZS Tool

Wiimms SZS Tool : List, compare, (de-)compress, extract and create SZS, U8, PACK, BRRES, BREFF, BREFT and RARC archives. It is also a wrapper to all other tools.

Contents

1.   Syntax

wszst [option]... command [option|parameter|@file]...

2.   Features of wszst

Read »Features« for features of the whole toolset.

3.   Commands

VERSION Print program name and version and exit.
HELP H Print help for commands and options.
ARGTEST This debug command accepts all kinds of parameters and prints one line for each parameter.
TEST This debugging command accepts all options and parameters and prints a list of the internal option values. The command is designed to test the option parameters. The non option parameters are completly ignored.
COLORS Ignore all parameters and print clored text for testing.
ERROR ERR Translate an exit code to a message name. If no exit code is entered, print a table with all error messages.
FILETYPE FT Scan the header of the entered files and print file type and path for each file as list.
FILEATTRIB FA Print a table with attributes for all known file types. If at least one keyword is entered, only matching file types are printed. A keyword is either a file type (like 'BRRES' or 'BMG') or one of the printed keywords (like 'ARCHIVE' or 'EXTRACT').
SYMBOLS Print predefined symbols of text parser to standard output.
FUNCTIONS Print a list with all parser functions. If one key ore more key entered, then only functions that match at least one key are printed.
CALCULATE Calculate each expression and print the result to standard output.
MATRIX Use the transformation options as base and calculate and print the related vectors and the transformation matrices. Then do a forward and backward transformation for each vector parameter using the matrices and print the results.
FLOAT This commands helps to convert hex value into floating point numbers. For each non empty parameter, a line with 4 bytes hex and a float, 8 bytes hex and a double float, and the parameter itself is printed. If a parameter begins with 'x' or '0x', it is a hex string. Otherwise it is a floating point number. All conversions are done using big endian.
AUTOADD Manage the auto-add library. Primarily add files to the main auto-add archive for future use of option --auto-add or to convert WU8 files. If SOURCE is a directory, all standard track and arena file names are searched for the missed auto-add files. Without source files, the status of the auto-add archive is printed.

Try »wszst AUTOADD ./path_to/Race/Course/« to add all supported files.

TRACKS Print a list of all known track SZS files of Mario Kart internal directory './Race/Course'. These files are 32 standard track files and 10 arena files. The first column shows an unique ID of exact 3 upper case characters or digits. For '_d' files, a 'd' is appended.
LIST LS List all sub files of SZS, U8, PACK, BRRES, BREFF, BREFT and RARC archives. If listing a directory, then a virtual SZS file is created (like CREATE does it) and listed.
LIST-L LL List all sub files with size. 'LIST-L' and 'LL' are short cuts for »LIST --long«.
LIST-LL LLL List all sub files with offset and size. 'LIST-LL' and 'LLL' are short cuts for »LIST --long --long«.
LIST-LLL LLLL List all sub files with offset and size in debugging mode. 'LIST-LLL' and 'LLLL' are short cuts for »LIST --long --long --long«.
LIST-A LA List recursive all sub files with size. 'LIST-A' and 'LA' are short cuts for »LIST --long --all --all«.
LIST-LA LLA List recursive all sub files with offset and size. 'LIST-LA' and 'LLA' are short cuts for »LIST --long --long --all --all«.
ILIST IL List the images files of all sub files of SZS, U8, PACK, BRRES, BREFF, BREFT and RARC archives; non image files are ignored. If listing a directory, then a virtual SZS file is created (like CREATE does it) and listed.
ILIST-L ILL List all image files with geometry data. 'ILIST-L' and 'ILL' are short cuts for »ILIST --long«.
ILIST-LL ILLL List all sub files with advanced geometry data. 'ILIST-LL' and 'ILLL' are short cuts for »ILIST --long --long«.
ILIST-A ILA List recursive all image files. 'ILIST-A' and 'ILA' are short cuts for »ILIST --all«.
ILIST-LA ILLA List recursive all image files with geometry data. 'ILIST-LA' and 'ILLA' are short cuts for »ILIST --long --all«.
MEMORY MEM Dump a memory map of each source file. Virtual images (extracted directories) are also supported.
MEMORY-A MEMA Dump recursive a memory map of each source file. 'MEMORY-A' and 'MEMA' are short cuts for »MEMORY --all --all«.
DUMP Dump the internal structure of a BRRES files, compressed or not. Other archives are ignored. The main goal is to verify string relocation. Virtual images (extracted directories) are also supported.
SHA1 Print a SHA1 checksum for each source. The checksum is calculated using the uncompressed data.
DIFF CMP Compare two or more sources (each SZS, U8, PACK, BRRES, BREFF, BREFT, RARC or directory) on file level and report mismatches for each sub file. If option --dest is set, than each source file is compared with a file in the destination.
CHECK Make a validity check for track files: Try to read KCL and KMP (and check both) and find unknown, modified, needed and unneeded files. Also analyse cannons and make slot proposals. This command uses an internal object and file database. The source can be a SZS, U8, WU8 or WBZ file, or an U8 like directory.
SLOTS Try to find out the slots, that will run a track. Each source can be a SZS, U8, WU8 or WBZ file, or an U8 like directory. For each source one status line is printed. The status line contains either a positive or a negative slot list, whatever is shorter.
STGI Find the first KMP/STGI of each file and print an analysis of it as single line statistic. Additional the number of lap counter check points ('LC') is printed. Track and KMP (binary and text) files are accepted as input.
NORMALIZE NORM Normalize an U8 archive, compressed or not: The files are sorted in `Nintendo like' order and unused data holes are removed. If directory '.' is available it becomes the root directory for all others. Compressed sources are compressed again with maximum compression (level 9). The destination is only written if any data changed.

»wszst NORMALIZE« is the same as »wszst PATCH --norm«.

PATCH Patch an U8 archive, compressed or not: Load the archive, apply all patching and transforming options and store the file again. Compressed sources are compressed again. The destination is only written if any data changed.
COPY CP COPY is an alternative command for copying and pathing files. It uses the same internal procedure as command PATCH, but has another command line syntax.

The command copies all source files to the destination. If more than 1 source is defined, the destination must be either a directory or a destination filename with escapes. Patching is also possible and option --overwrite is set implicitly.

MINIMAP Print minimap data (more exact: the visual field of the minimap) of a SZS, U8, BRRES or MDL file. If patching options are used, modify the data and write back the file using its original file format. Only the 'translation' vector is modified and new translation and inverse matrices are calculated.
COMPRESS COM Compress and create a SZS archives. If the source is already compressed, then decompress and compress it again. The default destination is '%P/%N.szs'.
DECOMPRESS DEC Decompress SZS files. The default destination is '%P/%N.u8'.
ENCODE E Create and/or encode sub files if necessary. It works like command CREATE, but without creating a new first level archive file.
CREATE C Create SZS, U8, PACK, BRRES, BREFF, BREFT or RARC archives by adding all not hidden files of the directory structure. Create and/or encode sub files if necessary. The default destination is '%P/%N%T'.
UPDATE U Update an existing SZS, U8, PACK, BRRES, BREFF, BREFT and RARCarchive. This is done in similar way as the EXTRACT command, but instead of extracting, source files are searched in a prior extracted archive. Only files with the same size are updated. The secondary source is used to find the source sub files. The default secondary source is '%P/%N.d/'.
EXTRACT X Extract all sub files of SZS, U8, PACK, BRRES, BREFF, BREFT and RARC archives. The default destination is '%P/%N.d/'.
XDECODE XD Command XDECODE is a short cut for »EXTRACT --decode«. It extract all sub files of SZS, U8, PACK, BRRES, BREFF, BREFT and RARC archives and decodes all supported files. The default destination is '%P/%N.d/'.
XEXPORT XX Command XEXPORT is a short cut for »EXTRACT --decode --export«. It extract all sub files of SZS, U8, PACK, BRRES, BREFF, BREFT and RARC archives and decodes all supported files with enabled export modus. The default destination is '%P/%N.d/'.
XALL XA Command XALL is a short cut for »EXTRACT --all«. It extract all sub files of SZS, U8, PACK, BRRES, BREFF, BREFT and RARC archives recursively and decodes all supported files. The default destination is '%P/%N.d/'.
CAT Extract one or more sub files of SZS, U8, PACK, BRRES, BREFF, BREFT and RARC archives. The output of all source files is concatenated and written to stdout.
BMG For each archive all BMG sub files are searched and, if found, decoded and printed as combined BMG text file. The command works exactly like »wbmgt MIX«.
KCL For each archive the KCL sub file course.kcl is searched and, if found, decoded and printed (copied to stdout).

Automated dropping of bad KCL triangles is enabled if no other drop option is specified by option --kcl.

KMP For each archive the KMP sub file course.kmp is searched and, if found, decoded and printed (copied to stdout).
INFO For each archive a file named info.txt and, if not found, credits.txt is searched, ignoring case. The first found file of each archive is printed (copied to stdout).
YAZDUMP YD Analyse YAZ compression print a dump to stdout. Ignore files without YAZ comporession.

4.   Options in alphabetic order

Options
Option Param Description
--align size Define an align value for the sub files in all archives. This is a short cut for »--align-u8=size --align-pack=size --align-brres=size --align-breff=size --align-breft=size«.
--align-breff size Define an align value for the sub files in BREFF archives. The value must be a power of 2 and the default value is 4 This value is only relevant if creating or normalizing BREFF archives.
--align-breft size Define an align value for the sub files in BREFT archives. The value must be a power of 2 and the default value is 0x20 This value is only relevant if creating or normalizing BREFT archives.
--align-brres size Define an align value for the sub files in BRRES archives. The value must be a power of 2 and the default value is 4 This value is only relevant if creating or normalizing BRRES archives.
--align-pack size Define an align value for the sub files in PACK archives. The value must be a power of 2 and the default value is 32 (0x20) This value is only relevant if creating or normalizing OACK archives.
--align-u8 size Define an align value for the sub files in U8 archives. The value must be a power of 2 and the default value is 32 (0x20) This value is only relevant if creating or normalizing U8 archives.
-a --all Extract and decode all known and supported files recursively. This is a short cut for »--recurse --decode --mipmaps«. If entered twice, option --cut is included too.
--allow-all Usually commands accept only options with impact to the command. All other options fire a syntax error. But if --allow-all is set, all commands accept all options.

This makes changing the command of a long command line without removing useless options easier. It also helps to override wrong option permissions.

-A --arenas arenas Define a new arena order. A comma separated list in the format [a=]b or a:=b is expected. 'a' and 'b' are arena names or slot numbers. 'a' is the destination slot and 'b' the assigned arena. If 'a' is omitted, the next slot is used; this means [a=]b,c,d is possible.

Arenas will only be exchanged so that always all arenas are assigned. But if using ':=' the new slots are assigned without exchanging and the old values are lost.

--arot degree[@pos1]@pos2 Transform the data and do an axis rotation: Close the current transformation step like --next and rotate the data by 'degree' around the axis defined by the 2 points. If 'pos1' is not set, use 0,0,0 instead. Store the resulting matrix as single transformation step and open a new one.

This kind of transformation is EXPERIMENTAL!

--array Use an array on script output if possible. If arrays are not supported, then append a '_#' suffix with an zero based index to the variable name defined by »--var name«. In this case, only one output file is created.
--ascale factor@dir Transform the data and do an axis scale: Close the current transformation step like --next and scale the data by 'factor' into the direction given by the vector 'dir'. Store the resulting matrix as single transformation step and open a new one.

This kind of transformation is EXPERIMENTAL!

--auto Calculate the minimap translations automatically by using the minimum and maximum vertex coordinates. The 'scale' and 'rotation' fields are reset. This is done as first action before the SET, CENTER and the other transformations.
--auto-add Analyze the KMP (if exist) and add missing BRRES, BREFF, BREFT, BRASD and KCL files automatically, if the tool can find the files in any sub directory named 'auto-add'. This sub directory is searched in all directories of 'SEARCH_PATH'; use command »wszst AUTOADD« to view them. Command »wszst AUTOADD« may also create an auto-add database. --aadd is a short cut.
--autoadd-path directory Define an alternative directory as autoadd library. The default is, that the sub-directory called './auto-add/' of all search pathes are used. Use »wszst test -vvvv« for tests.
--avar varname Shortcut for: »--array --var name«
--base64 Encode the the checksum string as BASE64 instead of hex. If --id is also set, use the alternative charset with '-.*' instead of '+/='.
--bash Dump infos using BASH syntax. Use »--var name« as prefix.
--bmg-colors Force output of '\c{color}' escape sequences with names, even for foreign (not MKWii) BMG files.
--bmg-inf-size size Defines the 'INF0' size of new BMG files between 4 and 1000. The first 4 bytes of a INF0 record is a pointer to the string and the remaining bytes the string attributes. However, maximal 20 attribute bytes are supported and additional bytes are assumed to be NULL. All BMG files of MKW have a size of 8.
--bmg-inline [DEPRECATED] Print BMG values between message name and the equal sign using the format '[...]'. The output for the standard value (usually 0x01000000) is always suppressed. Since v1.44, the inline mode is the default. It can be disabled by option --no-bmg-inline to be compatible with versions until v1.39.
--breff Create a BREFF archive.
--breft Create a BREFT archive.
-B --brief Suppress information lines in decoded text files. This includes syntax information (--no-header). If set twice, the output of unneeded sections is also suppressed.
--brres Create a BRRES archive.
--bz If creating a compressed file, force BZ compression (a BZIP2 variant).
--cache file Use the file as cache file. If the parameter is a directory, find a file with the file name of the destination file. If the file is valid (same content), then use it as compressed version of the file and link (or copy if link failed) it to the destination.

If the cache file is not found or the content differ, the file is (re-)created and exit status 2=differ is returned.

--center Center the minimap in all 3 directions. This is a short cut for »--xcenter --ycenter --zcenter«.
--chdir dir Set a new working directory for all following options, for all parameters and for the command execution. This option can be used multiple times, but for parameter parsing and for command execution only the last usage is relevant. Nevertheless, '@param' values are scanned while reading the command line.
--color Force colorized text. This is the default, if an output file is a terminal. But colorized text is only supported for a few messages.

If a command is prefixed by 'C-', then this option is set automatically.

--compatible vers The option expects a version number (format '#.##' or 'v#.##') or a revision number (format 'r#') as parameter. If set, the tools try to create BMG and KMP text files, that are compatible to the entered version of the tools. This may override other legacy options.
-C --compr level Define a compression level between 0..9: 0 (or NOCHUNKS) disables finding chunks, 1 (or FAST) for the fastest standard compression and 9 (or BEST) for the best (=default) compression. 10 (or ULTRA) and 100-150 are a special time-consuming compression modes. They are dedicated to competitions with size limitations. The special value UNCOMPRESSED acts like option --no-compress.

Because of many repeated data, the best bz-compression mode varies. Therefor the levels TRY2..TRY5 (or short T2..T5) are defined to find the best compression mode with testing the first N modes of 9, 1, 8, 2, 5. TRY2 is used for normalizing. For non bz-compression, TRY* are the same as BEST.

Option --norm takes precedence over --compr and sets the compression level to TRY2 (BEST).

For more modes and details type »wszst -C list«. To force colorized output type »wszst -C clist«.

-c --const list Define constant values, that are used by the internal encoders and by the numeric options as predefined global variables. This option allows a conditional encoding of text files. It can be used multiple times for multiple definitions.

The Parameter is a comma separated list of terms and a term is 'name=expression'. The expression is calculated by the text parser.

--ct-code Enable the CT-CODE modus.
--cut Cut different non archive files into smaller peaces (logical units like headers, groups, sections) or list these peaces as single sub files for a more detailed analysis. Supported file types are BMG, BREFT-IMG, KMP, PAT, TEX, TPL, BRRES sub files and more.
--de Use german track and arena names.
--decode If a extracted file is known and can be decoded, do it. --dec is a short cut.
--def-attrib attrib Define the default attributes for BMG files. If not set, the default attributes are estimated. On text output, strings with default attributes are printed without attribute vector. The usual default attribute for MKW is [1].
-d --dest path Define a destination path (directory/file). The destination - means: write to standard output.

The path may contain escape sequences: %Q is replaced by the fully qualified source name. %P and %F are replaced by the source path or by the filename. %N and %E are replaced by source filename without extension or by the source extension. Finally, %T is replaced by the default extension of the destination format.

A '?' direct behind '%' in %E and %T conversions avoid that the same extension is used twice in row.

-D --DEST path Like --dest, but create the directory path automatically.
--encode-all Encode all files. Normally a file is only encoded, if the source is younger than the destination or the destination is missing. Only files in the [encode] section of the file 'wszst-setup.txt' are candidates for encoding. --eall is a short cut. Option --no-encode takes precedence over --encode-all.
--encode-img Encode all image files. Normally a image file is only encoded, if the source is younger than the destination or the destination is missing. Only files in the [encode] section of the file 'wszst-setup.txt' are candidates for encoding. --eimg is a short cut. If set, option --no-encode is ignored for images.
-E --esc char Define an alternative escape character for destination files. The default is '%'. For Windows batch files it is a good choice to set '-E$'.
-X --export Enable the export modus and create small and machine readable text files for easy post processing. The option works similar like -HBB for KMP and like -HBl1 for BMG text files.
-e --ext For BRRES archives only: If a file is extracted, add a handy file extension like '.mdl' to the file name. If set twice and a textual file magic is available, use the file magic in lower case instead like '.mdl0'.
--fast Short cut for --compr=fast: Set the fastest real compression. It also overrides compression rates set by --norm or --compr.
--flag-file filename Define a flag file if scanning an OBJ file (KCL processing). The file name may contain %-escapes. Set it to an empty string to disable flag files at all.

The tool search the flag file in the following order until found: File defined by --flag-file; OBJ file name with replaced extension ('a.obj' becomes 'a.flag'); OBJ file name with appended extension ('a.obj' becomes 'a.obj.flag').

--force The tools analyse input files and reject files with invalid data structures. If --force is set, little repairable issues are ignored and a warning is printed.

Option »--kmp force« does the same, but only for KMP files.

>>> THE RESULT MAY BE INVALID OUTPUT FILES! <<<

--force-attrib attrib Forces, that all attributes are set to this vector.
-h --help Stop parsing the command line, print a help message and exit.
--id Print an ID with 8 characters instead of a SHA-1 sum with 40 characters. The SHA-1 sum is used to calculate the ID. The ID consists of '0'-'9' and 'a'-'w' (32 characters).
-i --ignore Ignore non existing source files without warning.
--ignore-setup Ignore hidden setup file 'wszst-setup.txt'. This file is used to determine some default settings and to find out sub archives and files to encode. Use this option only if you know what you do.
--kcl list Set global options for KCL processing. Parameter 'list' is a comma separated list of keywords. A minus sign before a keyword disables a setting. Each occurrence of the option will only change entered settings and all other settings are untouched.

Keyword DEFAULT resets the default settings and CLEAR disables all. Keywords SMALL, MEDIUM and CHARY select the default parameters for the octree creation. The other allowed keywords are: FAST, NEW, CENTER, ROUND, NORMALS, MTL, WIIMM, TRIANGLES, OUT-SWAP, G, USEMTL, CLIP, IN-SWAP, AUTO, HEX4, HEX23, HEX, DROP-UNUSED, DROP-FIXED, DROP-INVALID, DROP, RM-FACEDOWN, RM-FACEUP, FIX-ALL, CONV-FACEUP, WEAK-WALLS, SORT, INPLACE, SILENT and LOG.

--kcl-flag joblist Modify the KCL flag of KCL files. A comma separated job list in the format 'srclist=dest' is expected. 'srclist' is a plus sign separated list with single values like <val>, T<type> and <val>/<mask> or ranges like <val>:<val>, T<type>:<type> and <val>:<val>/<mask>. '<val>' is a complete KCL flag in the range of 0..0xffff. '<type>' are only the base types in the range of 0..0x1f. If <mask> is present, it marks the relevant bits. For the T<type> variant, the mask is set to 0x1f.

All KCL flags of the source list are assigned to the new value 'dest', but only the set bits of '<mask>' are modified. A later definition overrides the previous one.

--kcl-script script After reading a KCL source file and executing all transformations, the text file 'script' is executed by the internal text parser. The script should use the parser functions tri$*() to read and modify the triangle positions and flags, or to add or remove complete triangles.

If this option is used multiple times, each script is executed in the entered order.

--kmp list Set global options for KMP processing. Parameter 'list' is a comma separated list of keywords. A minus sign before a keyword disables a setting. Each occurrence of the option will only change entered settings and all other settings are untouched.

Keyword DEFAULT resets the default settings and CLEAR disables all. The other allowed keywords are: FORCE, NEW, RM-SPCITEM, LEFT, RIGHT, WIDE, NARROW, FIX-CKPH, FIX-ENPH, FIX-ITPH, FIX-PH, FIX-CKNEXT, FIX-CKJGPT, FIX-CK, FIX-ALL, 1LAP, 2LAPS ... 9LAPS, MAX-LAPS, RM-EMPTY, INPLACE, SILENT and LOG.

--load-kcl file Load a KCL or OBJ file for reference issues.
-L --logging This debug option enables the logging of internal lists and maps.
-l --long Print in long format. Multiple usage possible.
--makedoc Dump infos using MakeDoc syntax. Use »--var name« as variable name of the resulting map.
-M --max-file-size size This security option defines the maximum file size for input files; larger files are ignored with a warning. The default unit is MiB and the default size is 100 MiB; that should be enough for standard usage.
--mdl list Set global options for MDL processing. To enable MDL patching, use option --patch-file to select BRRES files for patching.

Parameter 'list' is a comma separated list of keywords. A minus sign before a keyword disables a setting. Each occurrence of the option will only change entered settings and all other settings are untouched.

A MDL transformation (controlled by the transformation options) is only done, if at least one of the keywords VECTOR or VERTEX is set.

Keyword DEFAULT resets the default settings (VERTEX) and CLEAR disables all. The other allowed keywords are: VECTOR, MATRIX, VERTEX, PARENT, CHILD and LOG.

--minimap Fix the minimap position in the same way as »wszst MINIMAP --auto«. All other minimap related options are ignored for the minimap processing.
--mipmap-size num Define the minimal width and minimal height of a generated mipmap. The default is 16. Tools before v1.49 used 1 as not alterable value. --mm-size is a short cut.
--mipmaps If reading a source, scan for mipmaps and load them too. For PNG files, files named NAME.mm#.EXT with #=1.. are searched. This is the default.
--msg list If this option is set, the BMG messages are filtered by this list. Only enabled messages are exported to the ouput BMG file (binary or text).

The parameter is a list of message ids (short MID, 'Txx' or 'Uxx' or Mxx' or hex number) or message ranges (MID:MID) or one of the keywords NONE, PARAM, CUPS, TRACKS, ARENAS, CHAT, CTCODE, CTTRACKS or ALL. If an element is preceeded by a minus sign, it is removed from the filter list (disabled).

--n-mipmaps num Force the number of mipmaps. Values between 0 and 20 are allowed. Value AUTO (default) enabless automatic detection. The creation of mipmaps stops if the witdh or the height of the mipmap becomes 0. --n-mm is a short cut.
--next Close the current transformation step with all scaling, shifting, rotation and translation options and open a new step with cleared options. On transformation each step is logical done one by one. In real, one total transformation matrix is calculated and used for fast transformations.

If option --next is used, the ability for modifying the scale and rotation vectors (not the positions) of different KMP sections is nearly always lost. A warning is printed if this occurs.

--no-attrib Suppress the output of any BMG attributes at text BMG files.
--no-bmg-colors If set, suppress the output of '\c{color}' escape sequences for colors definitions in BMG text output to be compatible with old versions of the tools.
--no-bmg-inline Print BMG values as separate line before the message definition to be compatible with versions until v1.39. The output for the standard value 0x01000000 is always suppressed. This was the default until v1.43. Since v1.44, --bmg-inline is the default.
-N --no-check Do not make plausibility checks for KCL and KMP files.
--no-color Deactive colorized text. This is the default, if an output file is not a terminal.
--no-compress Create an uncompressed file instead of a compressed SZS file. The default destination changes to '%P/%N%T'. --noc is a short cut.
--no-echo Suppress output of @ECHO commands while scanning text files.
--no-encode Do not encode files before creating an archive. --noenc is a short cut. Option --no-encode takes precedence over --encode-all, but --encode-img takes precedence for images.
-H --no-header Suppress printing of header and footer.
--no-mipmaps If reading a source, ignore mipmaps. This disables not the creation of mipmaps (see -n-mipmaps). --no-mm is a short cut.
-P --no-param Disable parameter support in decoded KMP text files.
--no-recurse Do not create archives recursively. Normally files in the [create] section of the file 'wszst-setup.txt' are created first. --norec is a short cut.
-n --norm The uncompressed data will be normalized. See command NORMALIZE for more details.
--null Create a neutral transformation without affecting the coordinates. The only influence is, that the dependent values (like maximum) are re-calculated as if a transformation has taken place.
--number If a file already exist, append a number directly before the file extension to make the filename unique. If other numbered files already exist (ignoring case), use the maximum existing index+1. --num is a short cut.
--old-escapes To be compatible with v1.43 and earlier, print 1A escape sequences with total size of >12 bytes as single words using \x{}. Also don't use \x{} and \u{} with parameter lists.
-o --overwrite Overwrite already existing files without warning and ignore option --number.
--pack Create a PACK archive.
--pat list Set global options for PAT processing. Parameter 'list' is a comma separated list of keywords. A minus sign before a keyword disables a setting. Each occurrence of the option will only change entered settings and all other settings are untouched.

Keyword DEFAULT resets the default settings and CLEAR disables all. The other allowed keywords are: AUTO, SIMPLE, COMPLEX, BOTH, SILENT and LOG.

--patch-bmg mode[=param] This option specifies a BMG patch mode. Some of the modes need a parameter or a file name of a BMG patch file (raw or text BMG), both separated by an equal sign. Modes with required file names are PRINT, REPLACE, INSERT, OVERWRITE, DELETE, MASK, EQUAL and NOTEQUAL. A mode with text parameter is FORMAT. Standalone modes are ID, ID-ALL, UNICODE, RM-ESCAPES, RM-CUPS, CT-COPY, CT-FORCE-COPY and CT-FILL. Unique abbreviations are allowed.

If this option is used multiple times, all patch files will be processed in the entered order.

--patch-file list Define, which kind of KMP, KCL and BRRES/MDL files are objects for patching. --pfile is a short cut.

Parameter 'list' is a comma separated list of keywords. A minus sign before a keyword disables a setting. Each occurrence of the option will only change entered settings and all other settings are untouched.

Keyword DEFAULT resets the default settings (TRACK,LOG) and CLEAR disables all. The other allowed keywords are: KMP, KCL, OTHER-KCL, ALL-KCL, MODEL, MAP, VRCORN, OTHER-BRRES, ALL-BRRES, TRACK (=KMP,KCL,MODEL,MAP,VRCORN), ALL, LOG and LOG-ALL.

--php Dump infos using PHP syntax. Use »--var name« as variable name of the resulting object.
-p --preserve Preserve file times (atime+mtime) while converting or copying files.
--pt-dir [=mode] Set one of the `point directory' modes REMOVE (=0), FORCE (=1) or AUTO (default). If --pt-dir is used without parameter, then FORCE is assumed.

This option is only relevant if creating an U8 archive. It decides, if a special directory with name '.' will be added as base for all other files.

-q --quiet Be quiet and print only error messages. Multiple usage is possible. The impact is command dependent.
--raw Extract BRRES sub file in raw mode and do not adjust string pointers and other offsets.
-R --recurse [=level] If a extracted file is a known and supported archive, than extract it recursively until the entered level is reached. Level 0 (=NONE) deactivates this. If --recurse is used without parameter, then UNLIMITED is assumed.

-R does'nt accept a parameter and is a short cut for --recurse=unlimited.

-r --remove-dest Remove already existing files before creating it. If set, --overwrite is ignored. --rm-dest is a short cut.
--remove-src Remove the source file after successful operation. --rm-src is a short cut.
--rm-aiparam Remove the directory AIParam and all files from the archive. This option has only impact, if creating a new archive or normalizing an existing archive. --rmai is a short cut.
--rm-gobj objlist Remove objects from the KMP section GOBJ. Therefor a comma separated object list with single values like 'a' or ranges like 'a:b' is expected. 'a' and 'b' are numbers, object names (prefixed by 'o$') or any other parser expressions.
--rot degree[@origin] Transform the data: Rotate all coordinates and rotation values by the angle 'degree' (is a vecotr) around the 3 axes. All 3 axes goes through the point 'origin'. If the origin is not set, 0,0,0 is used instead.

Each parameter is either a vector expression or a comma separated expression list of coordinates ('x,y,z').

Option --rot is an alternative for --xrot, --yrot and --zrot to define all 3 rotations in one step. Transformations are calculated in the order SCALE, SHIFT, X-ROTATE, Y-ROTATE, Z-ROTATE, TRANSLATE.

--scale vector[@origin] Transform the data: Scale all coordinates and size values by 'vector' relative to the point 'origin'. If the origin is not set, 0,0,0 is used instead.

Negative values mirror the coordinates. Each parameter is either a vector expression or a comma separated expression list of coordinates ('x,z' or 'x,y,z').

Transformations are calculated in the order SCALE, SHIFT, ROTATE, TRANSLATE.

--sections Print in machine readable sections and parameter lines.
--set-flags flag Define the flag values (default 0x31f) of the minimap.
--set-rot vector Define the rotation values (default 0.0) of the minimap. The parameter is either a vector expression or a comma separated list of coordinates ('x,z' or 'x,y,z').
--set-scale vector Define the scale values (default 1.0) of the minimap. The parameter is either a vector expression or a comma separated list of coordinates ('x,z' or 'x,y,z').
--set-x v1[,v2] Define 2 values and sort them to define the minimum and maximum x-coordinates of the minimap. If 'v2' is not entered, '-v1' is used as second value.
--set-y v1[,v2] Define 2 values and sort them to define the minimum and maximum y-coordinates of the minimap. If 'v2' is not entered, '-v1' is used as second value.
--set-z v1[,v2] Define 2 values and sort them to define the minimum and maximum z-coordinates of the minimap. If 'v2' is not entered, '-v1' is used as second value.
--sh Dump infos using SH syntax. Use »--var name« as prefix.
--shift vector Transform the data: Add 'vector' to all coordinates. Is's simlar to --translate, but the addition is done before rotation. The parameter is either a vector expression or a comma separated expression list of coordinates ('x,z' or 'x,y,z').

Transformations are calculated in the order SCALE, SHIFT, ROTATE, TRANSLATE.

-1 --single-line If set, don't print continuation lines for BMG text output. If set twice, print only single text lines and suppress attributes like option --no-attrib does it.
--slot keyword Patch a track file to run at the specified slot. KMP and KCL may be modified. BRRES files may be added to or removed from SZS. The main keywords are DAISY, DESERT, SHERBET, SHYGUY, STANDARD and MOST. Slot numbers (except '42' and '4.2') and different other track names are also accepted. For some conversions, the auto-add library is needed.
--smart If resizing an image, use the new smart resize function. The new function is much slower (factor 2-4) than the old function, but creates much better resized images. This is only relevant for creating mipmaps with odd width or height.
-S --sort mode Define a sort mode. Allowed keywords are: NONE (default), NAME, OFFSET, U8, PACK, BRRES, BREFT and AUTO
-s --src path Define a secondary source path (directory/file).

The path may contain escape sequences: %Q is replaced by the fully qualified primary source name. %P and %F are replaced by the primary source path or by the filename. %N and %E are replaced by primary source filename without extension or by the source extension. Finally, %T is replaced by the default extension of a virtual destination format.

A '?' direct behind '%' in %E and %T conversions avoid that the same extension is used twice in row.

--speed-mod factor The speed modifier is a user extensions to change the basic speed of all vehicles. The speed factor itself is stored into KMP/STGI section of a track.

If --speed-mod is set to a value >0.0, then the last 2 bytes of the STGI section are patched. The value 0.0 reset these 2 bytes and deactivates the speed modifier.

--szs Short cut for »--u8 --yaz0«: Create an U8 archive, if possible, and set the compression method to Yaz0.
-t --test Run in test mode, modify nothing.

>>> USE THIS OPTION IF UNSURE! <<<

--tform-kmp list Select KMP sections and objects for a transformation. --tkmp is a short cut. The option expects a comma separated list of keywords. Non ambiguous of keywords are allowed and minus signs within keywords are optional (e.g. GOBJS). A minus sign before a keyword disables transformation of the related section or object.

Sections are selected by the KMP section names AREA, CAME, CKPT, CNPT, ENPT, GOBJ, ITPT, JGPT, KTPT, MSPT and POTI.

Objects are selected by the keywords AREA-POSITION, AREA-ROTATE, AREA-SCALE, CAME-POSITION, CKPT-POSITION, CNPT-POSITION, CNPT-ROTATE, ENPT-POSITION, ENPT-SCALE, GOBJ-POSITION, GOBJ-ROTATE, GOBJ-SCALE, ITPT-POSITION, ITPT-SCALE, JGPT-POSITION, JGPT-ROTATE, KTPT-POSITION, KTPT-ROTATE, MSPT-POSITION, MSPT-ROTATE and POTI-POSITION.

The keywords NONE and ALL (default) complete the field.

--tform-script script Load the script and execute it by the text parser.

Then for each coordinate (2D and 3D), call the macro TRANSFORM after all other transformations. Call it without parameters and set variable $I with a zero based index of all vertices, variable $D to the dimension (2 or 3) and the variable $P to the vector of the current vertex. If the macro returns a vector, it is the new position.

For each file, macro BEGIN is called at the beginning and END after proccessing all points, but only, if the macros are defined. For END, variable $I is set to the number of proccessed vertices in the current file.

Before each macro call, the private and local variables are cleared and only global parameters are permanent. The zero based index is cleared for each new source. The parameters of the macro calls are defined in the local name space.

--tiny mode Set tiny mode to a level between 0 and 7.
--touch Mark the minimap as modified to force a new calculation of the translation and inverse matrices.
-T --tracks tracks Define a new track order. A comma separated list in the format [a=]b or a:=b is expected. 'a' and 'b' are track names or slot numbers. 'a' is the destination slot and 'b' the assigned track. If 'a' is omitted, the next slot is used; this means [a=]b,c,d is possible.

Tracks will only be exchanged so that always all tracks are assigned. But if using ':=' the new slots are assigned without exchanging and the old values are lost.

-x --transform list Convert image formats when reading. A comma separated list with terms is expected. A term have the syntax '[SRC=]DEST'. It means: convert SRC format into DEST format. If SRC= is not set, the destination format is used for all source formats. This makes only sense as last rule. If DEST is empty no transformation is done for the source. Examples: 'TPL' or 'GRAY' or 'BTI.IA8' or 'TPL.I4+I8=IA8,TEX=,CMPR'

SRC and DEST are tupel of file, image and palette formats and of 2 more attributes. All parts are optional and separated by points, the order is irrelevant.

Allowed file formats are: TPL, TEX, BTI, BREFT-IMG (=BTIMG), PNG (import). Allowed image formats are: I4, I8, IA4, IA8, RGB565 (=R565), RGB5A3 (=R3), RGBA32 (=R32), C4, C8, C14X2, CMPR. Allowed palette formats are: P-IA8 (=P8), P-RGB565 (=P565), P-RGB5A3 (=P3). Attributtes are PALETTE, NO-PALETTE, GRAY, COLOR, ALPHA and NO-ALPHA.

All terms are managed as list. For each graphic the list is iterated until the first SRC tupel of a term matches the graphic. Then the destination tupel is used for the transformation.

The command »wimgt TEST« prints a clearly arranged readable table as result of this option.

--translate vector Transform the data: Add 'vector' to all coordinates. Is's simlar to --shift, but the addition is done after rotation. The parameter is either a vector expression or a comma separated expression list of coordinates ('x,z' or 'x,y,z'). --trans is a short cut.

Transformations are calculated in the order SCALE, SHIFT, ROTATE, TRANSLATE.

--u8 Create an U8 archive, if possible. If the source is a WU8 archive, convert it to an U8 archive. This is the default if the setup file 'wszst-setup.txt' has no other definition. The default compression mode is set to Yaz0 (see --yaz0).
-u --update Create only files that do not exist. Already existing files are ignored without warning. If set, --overwrite and --remove-dest are ignored.
--var varname Use VARNAME as variable name or prefix on script output. The default variabe name is 'res'.
-v --verbose Be verbose and print more progress information. Multiple usage is possible. The impact is command dependent.
--verify Calculate the checksum and compare the filename and return exit status (0=valid, 2=differ). The result is valid, if the checksum is found with a leading and a following point or minus sign. If --quiet is set, error messages are suppressed.
-V --version Stop parsing the command line, print a version info and exit.
--wbz Short cut for »--wu8 --bz«: Create a WU8 archive, if possible, and set the compression method to BZ.
--width width Define the width (number of columns) for help and some other messages and disable the automatic detection of the terminal width.
--wu8 Create a WU8 archive, if possible. If the source is an U8 archive, convert it to a WU8 archive.
--x-escapes Use \x{} escapes instead of \z{} escapes.
--xcenter Center the minimap in x-direction. This is done after AUTO and SET, but before SCALE and SHIFT.
--xhelp Stop parsing the command line and print a help message with all commands included. Exit after printing.
--xrot degree[@origin] Transform the data: Rotate all coordinates and rotation values by the angle 'degree' around the x-axis, that goes through the point 'origin'. If the origin is not set, 0,0,0 is used instead.

Each parameter is either a vector expression or a comma separated expression list of coordinates ('y,z' or 'x,y,z').

Transformations are calculated in the order SCALE, SHIFT, X-ROTATE, Y-ROTATE, Z-ROTATE, TRANSLATE.

--xss x1old,x1new,x2old,x2new --xss (x-scale-shift) calculates the X values of --scale and --shift, so that the old values are transformed to the new values. The parameters are numbers or expression.
--xyz If creating a compressed file, force XYZ compression (an experimental Yaz0 variant).
--yaz0 If creating a compressed file, force Yaz0 compression. Yaz0 compression is the default, if no compression method is defined by option or setup file.
--yaz1 If creating a compressed file, force Yaz1 compression. The difference to Yaz0 is only the magic, which is set to 'Yaz1'.
--ycenter Center the minimap in y-direction. This is done after AUTO and SET, but before SCALE and SHIFT.
--ypos pos This option defines an Y position for KMP/CKPT transformations. It has only impact to X and Z rotations (Options --xrot and --zrot). If not set, the mean y of the active rotation origins are used.
--yrot degree[@origin] Transform the data: Rotate all coordinates and rotation values by the angle 'degree' around the x-axis, that goes through the point 'origin'. If the origin is not set, 0,0,0 is used instead. This is a horizontal counterclockwise rotation and the old option name --hrot can also used.

Each parameter is either a vector expression or a comma separated expression list of coordinates ('x,z' or 'x,y,z').

Transformations are calculated in the order SCALE, SHIFT, X-ROTATE, Y-ROTATE, Z-ROTATE, TRANSLATE.

--yss y1old,y1new,y2old,y2new --yss (y-scale-shift) calculates the Y values of --scale and --shift, so that the old values are transformed to the new values. The parameters are numbers or expression.
--zcenter Center the minimap in z-direction. This is done after AUTO and SET, but before SCALE and SHIFT.
--zrot degree[@origin] Transform the data: Rotate all coordinates and rotation values by the angle 'degree' around the z-axis, that goes through the point 'origin'. If the origin is not set, 0,0,0 is used instead.

Each parameter is either a vector expression or a comma separated expression list of coordinates ('x,y' or 'x,y,z').

Transformations are calculated in the order SCALE, SHIFT, X-ROTATE, Y-ROTATE, Z-ROTATE, TRANSLATE.

--zss z1old,z1new,z2old,z2new --zss (z-scale-shift) calculates the Z values of --scale and --shift, so that the old values are transformed to the new values. The parameters are numbers or expression.

5.   Wrapper

From the beginning wszst was able to decode and encode BMG, KMP, images and more file types. It is simply a part of the SZS extraction and creation process. So it contains the complete functionality of all tools.

With version 1.38 the tool wszst is also a wrapper to all other tools with their interfaces. So technically only one image (wszst) is needed to have the functionality of all tools. The size of wszst growed about 300-400k.

The advantage is, that only one tool is needed. And this merged tool needs much less disk space then all tools together.

The wrapper itself is implemented on a way that it is not noticeable in normal operation and without knowledge of it. It is noticeable only active when it is addressed with special keywords as very first parameter.

5.1   Tool activation

The different built-in tools can be activated by a parameter, by renaming the main application (standard name wszst), or by linking (soft and hard) to the main application.

If the main application (generally wszst) is started, it enters wrapper mode and tries to find outthe tool to start:

  1. If the very first parameter (before any option or other parameters) is 'wrapper' (exact 7 characters, case ignored), then the special wrapper mode is activated and a help is printed or a wrapper subcommand is executed.

    Example:   wszst wrapper help

    See »wrapper commands« for more details.

  2. If the very first parameter is one of the tools name (exact 5 characters, case ignored), then the parameter is removed from the command line and the named tool is started as usual.

    Example:

      $ wszst wbmgt version
      wbmgt: Wiimms BMG Tool v1.38a r6056 x86_64 - Dirk Clemens - 2015-02-27
    

    This mechanism can also be used to create wrapper shell scripts. A not so simple bash example for wkmpt:

      #!/usr/bin/env bash
      "$(dirname "$BASH_SOURCE")/wszst" wkmpt "$@"
    
  3. If both steps above failed, then the file name of the tool is analyzed. Again case is ignored. If the first letter is 'w', then it is skipped. Then the next 3 characters are analyzed. If they equal to the middle 3 characters of the tool names (szs, bmg, img, kmp, ...), then the related tool is started.

    This methods works for renamed files and for hard and soft links pointing to the main application.

    Examples for creating links:

      ln -s wszst wkmpt  # softlink for the KMP tool (wkmpt)
      ln -s wszst kmp    # softlink for the KMP tool, but with shorter name
      ln wszst wkclt     # hardlink to the KCL tool (wkclt)
      ln wszst ctcode    # hardlink to the CTC tool (wctct) with other name
    
    The wrapper commands can create the links for you.
  4. Otherwise automatic detection failed and the wrapper starts wszst. This is transparent to the old behavior: If calling wszst with the usual options and parameters, it works like ever.

5.2   Wrapper commands

If the very first parameter 'wrapper' (exact 7 characters, case ignored, before any other parameter or option), then and only then the wrapper support mode with own commands is activated.

The wrapper support mode has a very easy interface. Without parameters or with at least 1 unknown parameter or with an invalid combination of parameters a simple help page is printed.

Read the help page for more information:


Wrapper commands:

   WRAPPER HELP
   WRAPPER CREATE    [QUIET] HARDLINKS|SOFTLINKS|BESTLINKS|CYGWIN|SHELL|BASH
   WRAPPER OVERWRITE [QUIET] HARDLINKS|SOFTLINKS|BESTLINKS|CYGWIN|SHELL|BASH

   H[ELP]      : Print this help and exit.
   CRE[ATE]    : Create links or scripts, but don't overwrite.
   OVER[WRITE] : Create links or scripts and remove existing files before.
   HARD[LINKS] : Create hard links to the main program.
   SOFT[LINKS] : Create soft links to the main program.
   BEST[LINKS] : For Cygwin same as HARDLINKS, for all other same as SOFTLINKS.
   CYG[WIN]    : Create softlinks for Cygwin (plain files with special content).
   SH[ELL]     : Create simple `sh| scripts assuming the main program is in PATH.
   BASH        : Create `bash| scripts with run time path detection.
   Q[UIET]     : Option to suppress creation messages.

A SHELL script for wbmgt looks like this:
#!/bin/sh
wszst wbmgt "$@"
The same as BASH script:
#!/usr/bin/env bash
"$(dirname "$BASH_SOURCE")/wszst" wbmgt "$@"