prev

next

» SZS: Wiimms SZS Tools » wszst: Wiimms SZS Tool

Tools

wszst

wszst commands

decompress, dec

normalize, norm

wszst: Wiimms SZS Tool

Wiimms SZS Tool : List, compare, (de-)compress, extract and create SZS, U8, BRRES, BREFF, BREFT and RARC archives.

Contents

1. Syntax
2. Features of wszst
3. Commands
4. Options in alphabetic order

1. Syntax

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

2. Features of wszst

wszst supports compressed and uncompressed SZS files. Uncompressed files are good for analysis. Supported archive formats are U8, BRRES, BREFF, BREFT and RARC. The format of each source file is detected independent of the file name.
»wszst LIST« lists the content of a SZS, U8, BRRES, BREFF, BREFT and RARC archives and directories, if wanted recursive. It lists also extracted file systems to preview the creation process.
»wszst MEMORY« prints a memory dump of all known archives and file types, if wanted recursive. Normal files are cutted into section and peaces, if option --cut is set. This helps to find location of individual parts of the files.
»wszst NORMALIZE« read an U8 archive, compressed or not, and write it back in a normalized form:
- The files are sorted in a Nintendo like order.
- 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 COMPRESS« and »wszst DECOMPRESS« convert SZS files from and to compressed format.
»wszst EXTRACT« extract the directories and files to the local file system to make access very easy. Recursive extraction and automatic decoding of some file formats is also possible.
»wszst EXTRACT« can extract known archives reclusively and can decode BMG files and graphic images on the fly.
»wszst CREATE« creates SZS files from directory structures. All files are included, include and exlcude lists are supported. Recursive creation and automatic encoding of some file formats is also possible.
»wszst CAT« allow to access one or more sub files within SZS files. The output of all sources is concatenated and written to stdout.
Extrating a SZS file and creating again results in the same SZS file. Only the internal order of the files may be changed.
»wszst DIFF« compares 2 SZS files on file level. This comparing is independent of the compression and of file order.

Read »Features« for features of the whole toolset.

3. Commands

`VERSION`		Print program name and version and exit.
`HELP`	`H`	Print help and exit. If the first non option is a valid command name, then a help for the given command is printed.
`TEST`		Test options: All options are allowed, some are printed.
`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 pedefined symbols of text parser to standard output (stdout).
`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.
`AUTOADD`		Add files to the main auto-add archive for future use of option --auto-add. If a source is a directory, all standard track and arena file names are searched in it. Without any source files an archive status 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, 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, 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 build for the uncompressed data.
`DIFF`	`CMP`	Compare two or more sources (each SZS, U8, 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 KMP (and check it) and find unknown, modified, needed and unneeded files. This command uses an internal object and file database. The source can be a SZS or U8 file, or an U8 like directory.
`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.
`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'.
`CREATE`	`C`	Create SZS, U8, BRRES, BREFF, BREFT or RARC archives by adding all not hidden files of the directory structure. The default destination is '%P/%N.%T'.
`UPDATE`	`U`	Update an existing SZS, U8, BRRES, BREFF, BREFT and RARCarchive. This is done in simlar way as the EXTRACT command, but instead of extrating, 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, 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, BRRES, BREFF, BREFT and RARC archives and decodes all supported files. 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, 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, BRRES, BREFF, BREFT and RARC archives. The output of all source files is concatenated and written to stdout.
`KMP`		For each archive the KMP file named 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).

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-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-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.
`-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.
	`--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'; try »wszst AUTOADD« to view them. Command »wszst AUTOADD« may also create an auto-add database. --aadd is a short cut.
	`--breff`		Create an BREFF archive.
	`--breft`		Create an BREFT archive.
`-B`	`--brief`		Suppress information lines in decoded KMP text files. This includes syntax information (--no-header). If set twice, the output of unneeded sections is also suppressed.
	`--brres`		Create an BRRES archive.
	`--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.
`-C`	`--compr`	level	Define a compression level between 0..9: 0 (or NOCHUNKS) disables finding chunks, 1 (or FAST) set the fastest real compression and 9 (or BEST) set the best (=default) compression. The special value UNCOMPRESSED acts like option --no-compress. Option --norm takes precedence over --compr and sets the compression level to BEST.
`-c`	`--const`	list	Define a const value, that is used by the internal encoders as predefined global variable. This option allow conditional encodings of text files. It can be used multiple times to allow multiple definitions. Parameter list is a comma separated list of terms and a term is name=expression. The expression is calculated by the text parser.
	`--cut`		Cut different non archive files into smaller peaces (headers, groups, sections, ...) and list these peaces as single sub files for a more detailed analysis. Supported file types are: BMG, BREFT-IMG, KMP, TEX, TPL and BRRES sub files.
	`--decode`		If a extracted file is known and can be decoded, do it. --dec is a short cut.
`-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 imegae 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 (Cygwin) it is a good choice to set '-E$'.
`-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 instead like '.mdl0'.
	`--fast`		Short cut for --compr=fast: Set the fastest real compression. Ignored, if option --norm is set.
`-h`	`--help`		Stop parsing the command line, print a help message and exit.
	`--hrot`	degree[@origin]	Transform the data: Rotate all KMP coordinates and rotation values horizontal counterclockwise by the angle 'degree'. Each parameter is either a vector expression or a comma separated list of coordinates ('x,z' or 'x,y,z'). If the origin is not set, use 0,0,0 instead. Transformations are calculated in the order SCALE, SHIFT, ROTATE.
	`--id`		Print an ID with 8 characters instead of a SHA-1 sum with 40 charaters. 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.
`-L`	`--logging`		This debug option enables the logging of internal lists and maps.
`-l`	`--long`		Print in long format. Multiple usage possible.
`-M`	`--max-file-size`	size	This security options defines the maximum file size for uncompressed archives. The default unit is MiB and the default size is 20 MiB; that should be enough for standard usage.
	`--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.
	`--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.
`-N`	`--no-check`		Do not make plausibility check for KMP files.
	`--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 KMP 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.
`-o`	`--overwrite`		Overwrite already existing files without warning.
`-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.
	`--scale`	vector[@origin]	Transform the data: Scale all KMP coordinates and size values by 'vector'. Negative values mirror the coordinates. Each parameter is either a vector expression or a comma separated list of coordinates ('x,z' or 'x,y,z'). If the origin is not set, use 0,0,0 instead. Transformations are calculated in the order SCALE, SHIFT, ROTATE.
	`--shift`	vector	Transform the data: Add 'vector' to all KMP coordinates. 'vector' is either a vector expression or a comma separated list of coordinates ('x,z' or 'x,y,z'). Transformations are calculated in the order SCALE, SHIFT, ROTATE.
`-1`	`--single-line`		Don't use continuation lines for BMG text output.
`-S`	`--sort`	mode	Define a sort mode. Allowed keywords are: NONE (default), NAME, OFFSET, U8, BRRES, BREFT and AUTO
`-s`	`--source`	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.
`-t`	`--test`		Run in test mode, modify nothing. >>> USE THIS OPTION IF UNSURE! <<<
`-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. Example: TPL.I4+I8=IA8,TEX=,CMPR SRC and DEST are tupel of file, image and palette formats and 2 more attributes. All parts are optional and are 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. The 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.
	`--u8`		Create an U8 archive. This is the default if the setup file 'wszst-setup.txt' has no other definition.
`-u`	`--update`		Create only files that do not exist. Already existing files are ignored without warning. If set, --overwrite and --remove-dest are ignored.
`-v`	`--verbose`		Be verbose and print more progress information. Multiple usage is possible. The impact is command dependent.
`-V`	`--version`		Stop parsing the command line, print a version info and exit.
	`--width`	width	Define the width (number of columns) for help and some other messages and disable the automatic detection of the terminal width.
	`--xhelp`		Stop parsing the command line and print a help message with all commands included. Exit after printing.
	`--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.
	`--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.
	`--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.