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