Track Transformation

Overview

This article describes how to transform a complete track including the KMP, KCL, course model, minimap, and skybox (vrcorn) files. Transformation is any combination of scaling in three dimensions, rotating around three axes and translation (shifting into any direction).

The main idea of a track transformation is to scale a track (mostly down, sometimes up) because a track can either be too large or too small. Another reason is to change the height of the track over the ground, as a track can be too low to the ground or too far away. A third reason is to make a horizontal rotation to find a optimal start position or an optimal minimap placement.

For a complete track transformation, you must at least transformate the positions (vertices) of the KMP (routes, positions, sizes, and more), the KCL (collision file), the course model (visible stuff), and the minimap. Additionally, the skybox and other BRRES and KCL files can be transformed. The easiest way is to manipulate the vertex lists of the files and KMP positions.

Since v1.17, Wiimms SZS Tools allow scaling and shifting of whole tracks. The tools also allow scaling with different factors for the three dimensions and rotating around all three axes. Last but not least, they allow mirroring by using negative scale factors, but this may have different issues because of the changed culling.

After a transformation, you must verify the track – especially the KMP because it needs user edits. In general, the KMP transformations work fine, but they must be verified:

• The KMP section CKPT only has two dimensional points. If rotating vertically by --xrot or --zrot, the placement of the checkpoints are nearly always wrong. One way is to define a good Y-value as a rotation base by using option --ypos.
• Enemy and item routes are usually fine. Narrow turns may be problematic if scaling down.
• Cameras and moving objects seem to be too fast if scaling down. Therefore, speed factors in CAME, GOBJ and POTI must be changed.
• Objects are scaled by the scaling factors. If scaling with different factors for each dimension, objects are deformed too. Some objects, like item boxes, cannot be scaled.
• Verify the start position and respawn points. Using the option --tform-kmp, the user can select KMP options and objects for the transformation.

Example

Let us start with a video example. In this example, you see six transformed Nintendo tracks. Some tracks are only scaled and some tracks are deformed using different scaling factors for the three axes. The KMP, KCL, course model, minimap, and skybox are transformed in the same way, but the tracks are still playable.

The video shows only fully automated transformations without any user edits:

Six Transformed Nintendo Tracks

Transformed Tracks

Time	Slot	Track Name	Scaling	Options
0:00	1.1	Luigi Circuit	60%	--scale 0.6 --yrot 45
0:44	1.1	Luigi Circuit	100%, 200%, 50%	--scale 1,2,0.5 --yrot 45
1:46	1.2	Moo Moo Meadows	70%	--scale 0.7
2:31	2.3	DK Summit	70%, 150% vertical	--scale 0.7,1.5,0.7
3:46	2.4	Wario's Gold Mine	70%, 200% vertical	--scale 0.7,2,0.7
4:57	4.2	Moonview Highway	60%	--scale 0.6

All tracks have been scaled by:

wszst patch TRACK.szs --minimap MOREOPTIONS --tform-kmp -gobj

wszst

Tool to call.

patch

patch command of tool wszst.

TRACK.szs

The track file to patch.

Option --minimap

Adjust the minimap view area after transformation.

Option --tform-kmp -gobj

Select KMP sections and objects for a transformation. Here, all sections, except GOBJ, are transformed.

MOREOPTIONS

Track specific options; see table above.

The default transformation is to only patch the main KCL, KMP, course_model.brres, and map_model.brres files. The option --patch-file keywords allows to select which kind of files are patched.

Using Wiimms SZS Tools

First, Wiimms SZS Tools are command line tools. Be sure to understand that concept before using the tools and asking for support.

Basic Transformation

The transformation is done for complete tracks files in the formats SZS, U8, WU8, or WBZ. Decompression, compression (SZS and WBZ), decoding, and encoding (WU8 and WBZ) are done automatically and transparently. The command to use is wszst patch.

If you have a track file named CIRCUIT.szs and want to scale it down to 85%, use the command:

wszst patch --scale 0.85 CIRCUIT.szs

That is all. If you enter three different scaling values in a comma-separated list, you define different scaling factors for each axis. The following example scales the track horizontally to 90%, but vertically to 100% (unmodified):

Three axes of the coordinate system

wszst patch --scale 0.9,1,0.9 CIRCUIT.szs

You can, for example, also raise the track a little bit. Use the --shift or --translate options. Both options are similar: --shift is executed before any rotation and --translate is behind the rotation. Again, enter one value for all three axes or three values for different parameters:

wszst patch --scale 0.85 --shift 0,1000,0 CIRCUIT.szs

If you want to rotate the track, add one or more of the options --xrot, --yrot or --zrot. Use the picture on the right to identify the axes. For a horizontal counterclockwise rotation of 45°, add --yrot 45:

wszst patch --scale 0.85 --shift 0,1000,0 --yrot 45 CIRCUIT.szs

Execution Order

The transformation options are executed in the following logical order.

1. Scaling set by options --scale, --xss, --yss, or --zss.
2. Shifting set by options --shift, --xss, --yss, or --zss.
3. Rotation around the X-axis set by options --xrot or --rot.
4. Rotation around the Y-axis set by options --yrot or --rot.
5. Rotation around the Z-axis set by options --zrot or --rot.
6. Translation set by option --translate.

Shift and translate are very similar operations and the only difference is the execution before or after the rotation. The rotation itself is done as a right-handed rotation with Euler angles and X-Y-Z convention. MDL0 files and global objects do not know the shift operation, but the other operations (scaling, rotation, translation) are done in exactly the same manner and order.

Multiple Transformation Steps

The current transformation model is hard to manage if you want to do several independent transformation steps, since you must mathematically combine them to the input model of the options. Some things are impossible to specify. For example, scaling: if you want to scale only in one direction, it is only possible for the three axes, but it is impossible for other directions.

Option --next allows and separates up to 10 independent transformation steps. The option closes the current transformation step with all scaling, shifting, rotation, and translation options and opens a new step with cleared options. On transformation, each step is logically done one by one. In real time, one final transformation matrix is calculated by multiplying the single step matrices and used for fast transformations.

Back to our scaling example above. If you want to scale your track horizontally by factor 2 into the direction between the X and Z-axis (Z-axis rotated 45° around the Y-axis), use the following options:

--yrot 45 --step --scale 2,1,1 --step --yrot -45

It rotates the axis that should be scaled, shows 45° into the X-direction, scales the X-axis, and rotates back. The second --step is not really necessary because scaling is done before rotation.

There are some problems using multiple transformation steps:

Some KMP sections (AREA, CAME and GOBJ) have scaling and rotation vectors. If using a simple transformation, these vectors are modified by multiplying the entered scale or adding the entered rotation. But, if using a complex transformation with multiple steps, these operations cannot be done and the scale and rotation vectors are unchanged. A warning message is printed if this occurs. Position vectors are handled correctly in any circumstance.

A similar problem exists for MDL0 transformations. For complex transformations, it is impossible to modify the vectors of MDL bones. If the user decided so, the transformation mode is switched back to the default (VERTEX mode) for a full transformation support. A warning message is printed if this occurs.

Transformation of Other Files

By default, only the main KCL, KMP, course model, minimap, and skybox files are transformed. However, the patch command is able to transform other BRRES and KCL files.

Therefore, the option --patch-file=list is implemented. Just enter a list of file types you want to patch. The default is:

--patch-file track,log

where track is a shortcut for kcl,kmp,model,map and log enables extended logging. If you want to disable vrcorn and enable additional KCL files, use:

--patch-file -vrcorn,other-kcl

The minus sign means to use the previous setting (normally the default) and change some other file types (in this case, vrcorn and other KCL files) of the transformation list.

Minimap

Another good option is --minimap to automatically adjust the minimap position:

wszst patch --scale 0.85 --shift 0,1000,0 --yrot 45 --minimap CIRCUIT.szs

More Details

All transformation options and more details are described here:

• Wiimms SZS Tools, Command PATCH, Transformation Options

Known Issues

KMP object sunDS forces a freeze if scaling the Y-direction by factor 3 (other factors are untested). It is unsure if the problem is the height, the scaling of the sun, its route, or a combination of all three.

Web Links

Wiiki

• Rotation
• KCL (File Format)
• KMP (File Format)
• MDL0 (File Format)

Videos

• First demonstration video
• Second demonstration video (the one of the example above)

Discussion

• wii-homebrew.com Forums: Transformation ganzer Strecken (German)

Software

• Wiimms SZS Tools (Homepage & Download)

References

Custom Track Tutorials

Main Tutorials
Introduction – Textures – Scale – Modeling ⇒ Using Blender – BRRES: CTools
BRRES: BrawlBox – BRRES: RiiStudio – Minimap – Solidity – KCL: Wiimms Tools – KMP Editing
Object Editing – Cameras – Cannons – Post-effects – Videos

Battle Arenas
Battle Arenas – Enemy routes in battle arenas ⇒ Using Wiimm's Tools – Coins

Misc. Tutorials
Getting Files – BrawlBox Tricks – Animations – Shadows – Mipmaps
Custom Effects – Moving Terrain – Music – Ports – Paint Remakes – Tutorial Archive
Extended presence flags: Track Tutorial – LE-CODE Track FAQ

Testing and Reviewing
Testing a Track – Visual Review – Track Transformation – Fixing Errors

Software
3D Tools – BrawlBox – CTools Pack – KMP3D – KMP Cloud – KMP Modifier
Lorenzi's KMP Editor – MagicY – Material Tool – Post-Effect Editor – Wiimms SZS Tools – Wiimm's Tool Manager

Other
KMP Objects – Custom Objects – Model Database – Tutorial Archive