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, MASK-PFLAGS, RM-LECODE, PURGE-GOBJ, FULL-DEFOBJ, DUMP-CLASS, DUMP-ONEWAY, DUMP-ALL, 1LAP .. 9LAPS, MAX-LAPS, RM-EMPTY, TINY-0 .. TINY-7, 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 ot to force RM-EMPTY.

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 to race, if running LE-CODE or a special cheat code.

Keywords *LAP (singular) and *LAPS (plural) are accepted for all numbers.

If MAX-LAPS is set too, the number of laps is never increased.

MAX-LAPS
MAXLAPS
MAX-LAPS has only impact, if one of 1LAP,...,9LAPS is set too. Then, the number of laps is only decreased to the specified number, but never increased.

Example MAX-LAPS,3LAPS: Reduce the number of laps to 3, but only if it is larger than 3 before patching. Lap counts of 1, 2 or 3 are not touched.

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 itself. Before v1.59a, a link to the (cyclic) next group was inserted.
  • Calculate 'prev' links by analysing all 'next' links.
  • If a group has no valid 'prev' link, insert a link to itself. Before v1.59a, a link to the (cyclic) previous group was inserted.
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.
MASK-PFLAGS
MASKPFLAGS
If set, the Presence Flag of all objects of section GOBJ will be masked (AND'ed) by value 0x3f. That means, that the bits 6 to 15 are cleared for objects. Be carefull with this option, because it clears settings used for »extended presence flags«.
RM-LECODE
RMLECODE
Remove all objects form section GOBJ, that are only relevant for LE-CODE. The result is a minimized section for standard code.
PURGE-GOBJ
PURGEGOBJ
Remove all objects form section GOBJ that are neither a valid object nor a definiton object for LE-CODE.
DUMP-CLASS
DUMPCLASS
Print reference lists of classes if creating a text KMP and if classes defined. The lists are printed at the end of sections ENPT and ITPT.
DUMP-ONEWAY
DUMPONEWAY
Print reference lists of oneway connections if creating a text KMP and if such connections defined. The lists are printed at the end of sections ENPT and ITPT.
DUMP-ALL
DUMPALL
This is a short cut for all DUMP-* of above.
RM-EMPTY
RMEMPTY
After creating a binary KMP file, all KMP empty sections are completely removed, if this option is set. The KMP header is also reduced. Combine this option with NEW to force a re-creation the binary KMP.

This option is dedicated to competitions with a strict size limit.

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   --ktpt2 vector

Insert or replace a second KTPT. Use VECTOR as new position. VECTOR is either X,Z or X,Y,Z or an expression. Set Y to 0 for an automatic defined height. If the first 4 characters of VECTOR are 'AUTO' (ignoring case), then the position is calculated automatically and set to the recommendation of command wkmpt KTPT. The tool looks for the nearest lap counter (CKPT with mode 0) and adjust the KTPT: The direction of the lap counter is copied and the KTPT is moved to the lap counter line using the new direction. LE-CODE uses the second KTPT to draw the finish line at another place away from the start position.
A second KTPT at index 1 with player-index -1 is inserted or replaced.

Parameter VECTOR is used as base position. Then the neareast lap counter (CKPT with mode 0) is searched. The direction of the check point is copied. Then the KTPT is moved orthogonal to the check point line to get a perfect position.

Use command wkmpt ktpt to find recommendations for VECTOR.

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

Camera types 0 (Goal) and 3 (KartFollow) are excluded from transformation and scaling since v1.59a.

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