prevnext   » SZS: Wiimms SZS Toolset » Guides » KMP Guide

KMP Guide

Contents

1.   Introduction

The tool wkmpt appeared in August 2011 (v0.15a). Since beginning it can read and binary KMP files (Nintedos file format) and text KMP files (ASCII files with special semantics). The main idea is to decode a binary KMP file to a text file, edit the text file, and encode it back to a binary KMP file.

The KMP decoder substitutes internal numeric links by unique names. The compiler accept these names. This allows for example, to insert, delete or rearange POTI routes without changing the numeric references of the other sections.

Since November 2011 (v0.22a) the KMP encoder becomes a 2 pass compiler. In the current version, the compiler supports macros, includes and conditional execution. This makes it very flexible.

You can find technical information about KMP files on this site and in the Custom Track Wiiki:

2.   Options

2.1   --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.
This options will remove KMP objects of the section GOBJ. The selection is done by the object IDs. The objects are really removed and the KMP becomes smaller.

2.2   --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, INPLACE, SILENT and LOG.
The option --kmp expects a comma separated list of keywords to define global settings for the KMP processing. If a keyword is preceded by a minus sign, it is disabled. Each occurrence of the option will only change the current settings. To reset all settings, use either CLEAR or DEFAULT.

The following table shows all user keyword (there are some more hidden keywords for development). The jobs are done after reading the source file; for text files this is after scanning and compiling.

Keywords for option --kmp
Keyword Description
CLEAR This keyword clears (disables) all other keywords.
DEFAULT This keyword resets all keywords to their default status. At the moment, it is the same as CLEAR.
FORCE The tools analyse input files and reject files with invalid data structures. If keyword FORCE is set, little repairable issues are ignored on reading KMP files. A warning is printed in this case.

THE RESULT MAY BE INVALID OUTPUT FILES!

This keyword works like the option --force, but only for KMP files.

NEW On reading, a KMP is converted into the internal format (data structures). Normally, a new binary KMP is only created, if the internal data was modified.

If NEW is set, the new binary KMP file is always created. This may help to remove data structure errors.

RM-SPCITEM
RMSPCITEM
Clear the special items for players setting of all item objects (6 object types: itembox, s_itembox, f_itembox, w_itembox, w_itemboxline and sin_itembox).
LEFT Modify all records (usually 1) of KMP section STGI and set the pole position (byte at offset 1) to 0 (left).
Modify all records (usually 1) of KMP section STGI and set the pole position (byte at offset 1) to 1 (right).
WIDE Modify all records (usually 1) of KMP section STGI and set the narrow mode (byte at offset 2) to 0 (wide).
NARROW Modify all records (usually 1) of KMP section STGI and set the narrow mode (byte at offset 2) to 1 (narrow).
1LAP
...
9LAPS
Modify all records (usually 1) of KMP section STGI and set the lap counter (byte at offset 0) to a value between 1..9. This has only impact, if running a special cheat code.
FIX-CKPH
FIXCKPH
FIX-ENPH
FIXENPH
FIX-ITPH
FIXITPH
This keywords will enable an automated repairing of the KMP sections CKPH, ENPH and/or ITPH:
  • Fix the 'first' and 'len' values of the PH section, so that all PT entries are covered in order, and remove overlays.
  • Remove groups with no PT entries with care for the moved 'next' links.
  • Remove invalid 'next' links.
  • Remove duplicate 'next' links (CKPH and ITPH only).
  • Move valid 'next' links to the top of the list.
  • If a group has no valid 'next' link, insert a link to the (cyclic) next group.
  • Calculate 'prev' links by analysing all 'next' links.
  • If a group has no valid 'prev' link, insert a link to the (cyclic) previous group.
FIX-PH
FIXPH
This is a short cut for FIX-CKPH,FIX-ENPH,FIX-ITPH (fix all PH sections).
FIX-CKNEXT
FIXCKNEXT
Fix the 'prev' and 'next' links of section CKPT:
  • Set all 'prev' values to 'index-1' (to previous entry) and all 'next' values to 'index+1' (to next entry).
  • Set very first 'prev' and very last 'next' entry to 0xff.
  • Analyse KMP section CKPH and set the first 'prev' and the last 'next' entry of each group to 0xff.
This fix is done after FIX-CKPH.
FIX-CKJGPT
FIXCKJGPT
Fix invalid 'respawn' links of section CKPT and replace them by the last used valid respawn link.
FIX-CK
FIXCK
This is a short cut for FIX-CKPH,FIX-CKNEXT,FIX-CKJGPT (fix all CKPH and CKPT issues).
FIX-ALL
FIXALL
This is a short cut for all FIX-* of above.
INPLACE If a KMP file within a SZS file is replaced by a new version, the SZS files is rearanged (sub files are moved) to give the new KMP optimal space.

If INPLACE is set, no other files are moved and the new KMP size must be smaller or equal as the old size. If the new file is smaller, the SZS file receives an usused hole. This is the old behaviour.

SILENT If set, the default logging of all KMP patching actions is suppressed. If LOG is set, SILENT is ignored.
LOG This is a debugging mode. If set, the tools create a trace log about the main KMP reading, modifying (patching) and writing steps.

2.3   --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.
The speed modifier is a user extensions to change the basic speed of all vehicles. This works only for custom track distributions, that support the speed hack. The speed factor itself is stored as a 16 bit value into the last 2 bytes of a KMP/STGI record. Nintendo set it always to 0x0000.

If the parameter of option --speed-mod is set to a value >0.0, then the last 2 bytes of each STGI record are modified and set to the most significant bytes of a floating point number representing the speed factor.

A value of 0.0 deactivates the speed modifier and reset the 16 bit value to 0x0000.

2.4   --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.
Select KMP sections and objects for a transformation. The option expects a comma separated list of keywords. A keyword is either a KMP section or a combination of a KMP section and one keyword of POSITION, ROTATION or SCALE. Additonally the keywords NONE and ALL are possible. The default is to patch all objects.

A minus sign before a keyword disables transformation of the related section or object. Otherwise the object is enabled.

Examples:

--tform-kmp POTI,GOBJ-POS
Transform only the POTI routes and the positions of all GOBJ objects.
--tform-kmp ALL,-GOBJ or --tform-kmp -GOBJ
Transform all sections, but not GOBJ.
--tform-kmp -GOBJ-SCALE
Transform all sections including GOBJ, but not the scale factors of GOBJ.

2.5   --shift, --scale, --xss, --yss, --zss, --hrot

The global transforming options --shift, --scale, --xss, --yss, --zss and --hrot are also available.

3.   Execution Order

Last not least the execution order. It's a logical explanation and some points are done is one step for optimization reasons.
  1. First the input file is loaded and analyzed. If it is a valid KMP file (binary or text), it is scanned and the data is transferred into the internal data structures.
  2. If at least one of the options --shift, --scale, --xss, --yss, --zss or --hrot is set, the transformation is done. Only sections and objects defined by option --tform-kmp are transformed.
  3. The option --rm-gobj is processed.
  4. The STGI section is patched. Relevant is the option --speed-mod and the following modes of option --kmp: LEFT, RIGHT, WIDE, NARROW and 1LAP..9LAPS.
  5. The following modes of option --kmp are processed in this order: RM-SPCITEM, FIX-CKPH, FIX-ENPH, FIX-ITPH, FIX-CKNEXT and FIX-CKJGPT.
  6. The check status is generated.
  7. The output is processed. This is creating either a binary or a textual KMP file as copy of the internal data structures.