Wiimms SZS Tools/How To

This is a How To for Wiimms SZS Tools. The scripts in this How To are bash Scripts. bash is one of the most popular scripting shells in the Unix world including Mac. Together with the standard Unix tools like grep, sort, awk, sed, tac and many more it is very powerful scripting host.

bash and all Linux tools are also available for Windows: Just install Cygwin. To install on Mac, but only if the install.sh did not work, drag all the files in the downloaded bin folder to /usr/bin. To find it, click Go, then Go to Folder. Enter /usr/bin, and paste the files there.

Extracting All

It's very easy to extract a SZS or BRRES archive completely and recursively:

wszst extract --all my.szs
# or shorter
wszst x -a my.szs

A directory named "my.d" is created. it contains all extracted files and also some control file:

Known archives like SZS, U8, BRRES, BREFF and BREFT are extracted recursively.
BMG file are decoded and stored as BMG-Text files.
Images of TPL, TEX0 and BREFT subfiles files are stored as PNG files.
For recreating the archives a text file names 'wszst-setup.txt' is created. You can edit it to change the behavior.

You can add, remove and/or modify files in the extracted tree:

wszst create my.d

This command tries to create a new my.szs, but it won't overwrite it. Add --overwrite to overwrite or --dest=new.szs to give it another filename.

Extracting all files

With Linux or Mac and also with Windows if using the Cygwin environment, it is very easy to extract all SZS files with one command:

find -name '*.szs' | wszst extract --all --overwrite @-

The "@" means: Read the filename from a fie.
The "-" behind the "@" means: Use stdin (standard input) as file.

Replace Track Names

The following steps describes how to replace the track names of all message files of all supported languages of Mario Kart Wii without destroying any other message. The user must only provide one text file with the new track names, all other is done fully automatically by a single command.

Track Name File

First prepare a text file with the following content:

#BMG

 #--- standard track names

 T11 = Track name for slot 1.1 (cup 1 track 1)
 T12 = Name of track 1.2
 T13
 T14 = Name of track 1.4
 T21 = Name of track 2.1
 ...
 T84 = Name of last track

 #--- arena track names

 U11 = Track name for first arena (cup 1 arena 1)
 ...
 U15
 U21
 ...
 U25 = Name of last arena

 #--- Online Chat (24 pages with 4 message)

 M01 = First chat message
 ...
 M96 = Last chat message

 #--- mode messages by hex id

 12ab = Message
 ...

Some syntax rules

The encoding is UTF-8.
The very first 4 characters of the file must be »#BMG« (without quotes)!
Lines may be in Unix (LF) or Windows (CR+LF) style.
Empty lines and lines starting with an hash ('#') are ignored.
Indention by spaces and tabs is allowed.
"Tnn" is only an other notation for message IDs. You can use any message id (MID, in hex notation) to set a message. "Tnn" will set both track related messages.
"Unn" is like "Tnn", but for arenas. (The letter 'A' cant be used because conflicting with a hex number.)
"Mnn" is an alternative name for the message codes 1194..11f3.
Leave (or comment) out unmodified track and arena names.
The message order is irrelevant.
If a MID is defined twice, the second will override the first one.

Command

The following command patches all BMG files included into all SZS of directory ./Scene/UI:

wszst patch --quiet path/to/Scene/UI/*_?.szs --patch-bmg "replace=PATCH_FILE.txt"

Transform KMP Values

If a course model is scaled, the position, size and perhaps rotation values of the KMP must be scaled too. There may be 1000 or more single values. Since v0.24a, Wiimms SZS Tools are able to shift, scale and rotate horizontally all KMP values. The following description is based on v0.25a of the tools.

What is possible?

If a transformation is set and a KMP file (binary or text) was read, the tools wszst and wkmpt transform the KMP values (positions, scales and rotations). Different values can be entered for the 3 axis (X, Y and Z) and the transformation is done in three steps for the 3 axis in this order:

First positions and sizes (=scale vectors) are scaled, if option --scale is set. For positions, the distance to the origin is scaled, sizes don't need the origin. Negative scale values force a mirroring of the positions.
In a second step, all positions are shifted, if option --shift is set. The entered values are added to the position values.
In the last step a horizontal counterclockwise rotation is done, if option --hrot is set. Only position and rotation values are transformed and vertical positions (Y values) are never changed.

Determine the transformation values

Select points to determine the transformation

If the users know the scale and shift values, they can enter them directly with the options --scale and --shift. But there are also the alternative options --xss (x-scale-shift), --yss, and --zss. If using these options, the user enters the old and new coordinates of 2 points and the scale and shift vectors are calculated automatically. This section describes how to find good points for these options.

First the user must select 2 good points for the operations. Good points are far away for each axis. The example on the picture contains several good pairs. First they can select a point in the top left and the other in the bottom right (red points). They can also use points from the other diagonal (magenta points). Alternatively, they can use separate points for each axis, e.g. the blue points for the X-axis and the green points for the Z-axis. The height (Y-axis) can' be determined by the minimap model.

To determine the positions of the selected points, open the old and the new SZS file with a graphic viewer like the KMP editor of the SZS Modifier. Zoom in as max as possible and place any points (perhaps from any route section) at prominent positions. Then note (copy+paste) the coordinates from the old and the new model. Repeat this until you have found pairs for each axis.

Then select a command (see next section) and add:

--xss x1old,x1new,x2old,x2new
--yss y1old,y1new,y2old,y2new
--zss z1old,z1new,z2old,z2new

It is important, that each number use a point ('.') as decimal point, never a comma (','): 123.45 is a correct floating point number, but 123,45 are 2 numbers (123 and 45) separated by a comma.

Tools, commands and options

Nearly all copy commands of the tools wszst and wkmpt accept the transformation options and transform the KMP file on the fly. Examples:

# Copy a SZS file and transform:
wszst compress source.szs --dest dest.szs  --transform-options

# Normalize a SZS file and transform:
wszst norm source.szs --dest dest.szs  --transform-options

# Copy a KMP file and transform
wkmpt encode source.kmp --dest dest.kmp  --transform-options

# Compile a KMP text file and transform
wkmpt encode source.kmp.txt --dest dest.kmp  --transform-options

# Decode a KMP text file and transform
wkmpt decode source.kmp --dest dest.kmp.txt  --transform-options

This is a summary of all transform options, it is a copy of the built in help:

--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.

--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').

--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.

--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.

And again: It is important, that each number use a point ('.') as decimal point, never a comma (','): 123.45 is a correct floating point number, but 123,45 are 2 numbers (123 and 45) separated by a comma.

Links