prevnext   » SZS: Wiimms SZS Toolset » Guides » KMP: Syntax and Semantics of text files

KMP: Syntax and Semantics of text files

Contents

1.   Introduction

This article describes the syntax and semantics of KMP text files and each of his sections. For a general parser syntax read this article.

1.1   Magic

To identify the kind of the text file, the first 4 characters of a text file must be '#KMP', upper case is required. A byte order mark (BOM) as very first characters is detected and skipped.

File not beginning with this magic are not detected as KMP text files and ignored.

1.2   Sections

A KMP text file is devided into sections. Each section starts with »[NAME]« and ends at the beginning of the next section. If the same section exists two or more times, the later one overrides the previous definitions.

Any order of the section is allowed. Because of the 2 pass compiler, any section can access to all variables of all section independent from the order. The KMP decoder starts with the setup sections followed by the KMP sections in alphabetically order.

For more information about sections see »Parser Syntax / Sections«.

1.3   Import of SZS-Modifier text

You can paste text of SZS-Modifiers KMP Editor and copy it into the KMP text file.

Floats with comma (1,2) instead of a point (1.2) are always accepted. If you copy complete lines, tell the scanner to switch to the SZS-Modifier mode. '@SZS-MODIFIER = 1' enables the mode and '@SZS-MODIFIER = 0' disables it. Instead of writing '@szs-modifier = value' you can also write '@smod value'.

Example:

[ENPT]
  0   1.111  2.222  3.333  4.444  0x1234 0x5678

@szs-modifier = 1
  1   1,111  2,222  3,333  4,444  12345678
@szs-modifier = 0

  2   1.111  2.222  3.333  4.444  0x1234 0x5678

@smod 1
  3   1,111  2,222  3,333  4,444  12345678
@smod 0

  4   1.111  2.222  3.333  4.444  0x1234 0x5678

2.   Section [SETUP] (Basic Setup)

This is the general setup and info section. The setup section is divided into 2 parts:

2.1   System info

The first part of the setup section contains system information. It starts with parameters to identify the tool and version, that have written this file:
# Identify the tool and version, that have written this file:
TOOL     = wkmpt
SYSTEM   = x86_64
VERSION  = 0.32a
REVISION = 3617
DATE     = 2012-04-02
Some KMP tools support to add an info string at the end of the KMP file:
INFO = ""
The KMP file header has one unknown member at offset 0x0c and the value is always 0x9d8.
UNKNOWN-0x0c = 0x9d8
The info part contains also element counter for all sections.

2.2   User defined parameters

The user can define constants using the option --const to compile the same KMP text source on different ways. The second part of the setup section interact with predefined variable names to setup some usual variants. If option --no-param (-P) is set, this part is disabled.

The default setup define 7 different parameters with predefines meanings:

Name Description
slot Create a KMP for the entered slot. The default value 0 means: Design for almost all slots. Use it with an if..then..else structure to support special slots. The default code is completely slot independent, so the user have to implement slot dependencies.
d Create a KMP file for a _d variant of a track. Use it with an if..then..else structure to skip objects. The default code is completely slot independent, so the user have to implement slot dependencies.
test Enable test mode, if test>0. If test mode is disabled, all following modes are set to their default value. This helps to create a product version without resetting all other parameters.
ocam If ocam>0 and also test>0, then enable test of opening cameras. The opening camera with the entered index (1 based) is shown in an endless loop.

If ocam==0 and test>0, then all cameras are shown in an endless loop.

showrt If showrt>0 and test>0, points of different sections ar shown as item boxes and all standard item boxes are disabled showrt is a bit field. Set one or more of the following bits to show the points of the section: 1=ENPT, 2=ITPT, 4:JGPT, 8=CNPT, 16=MSPT and -1=all.
showck If showck>0 and also test>0, show check points as trees (or other user defined objects). See section CKPT for details.
laps This parameter controls the number of laps by changing the settings of the check point modes (section CKPT/@AUTO-MODE). Allowed values are:
  • 0: Make the race a short as possible.
  • 1: Finish the race after 1 lap
  • 3: Don't change the mode (default). This means generally: Finish the race after 3 laps.
  • 4: Never finish the race (unlimited).
Value 3 is used, if test mode is disabled.
The parameter part of the section is divided into 2 sub parts. First the parameters are set to their default values, if not defined by the command line.
  @def slot	?= 0	# Enable support for special slots
  @def d	?= 0	# Enable support for _d files
  @def test	?= 0	# Enable test mode
  @def ocam	?= 0	# Test opening cam, only relevant if test>0
  @def showrt   ?= 0    # Show item boxes for route points.
			# Only relevant if test>0. Set bit combination:
			#   1:ENPT, 2:ITPT, 4:JGPT, 8:CNPT, 0x10:MSPT (-1:all)
  @def showck   ?= 0    # Show objects a check point positions if test>0.
			#   0:off, 1:mandatory, 2:all, 3=left+right
  @def laps	?= 3	# Number of laps (0|1|3|4), only relevant if test>0

In a second step, global mode variables are defined and normalized following the rules of the above table. All conditions in a KMP text file should use these mode$ variables.

@gdef mode$slot     = slot > 0 ? slot : 0
@gdef mode$d	       = d    > 0

@gdef mode$test     = test > 0 ? test : 0
@gdef mode$ocam     = mode$test && ocam >= 1 ? ocam : 0
@gdef mode$laps     = mode$test && laps >= 0 ? laps : 3
@gdef mode$showrt   = mode$test ? showrt : 0
@gdef mode$showck   = mode$test ? showck : 0
@gdef mode$automode = select(mode$laps,AM$SHORT,AM$1LAP,AM$OFF,AM$OFF,AM$UNLIMIT)

Example:

  wszst --const test=12,ocam=2,laps=0 ...
Enable test mode 12, show opening camera 2 endless (until pressing A) and finish the race very fast to view the finish cameras very soon.

3.   Section [AREA] (Areas)

→ Custom Track Wiki: KMP/AREA

3.1   Parameter

Like all data sections, this section beginns with a revision number to define the input format. The input format of this section has changed with revision 2956 (Aug 2011). The previous input format is scanned correct if the revision number of the section is set right.
@REVISION = 1234

Parameter '@AREA-HEAD-VALUE' is stored into the section header at offset 0x06. It's meaning is unknown and it seems to be only a padding.

@AREA-HEAD-VALUE = 0

3.2   Input Table

Column 'idx' of the table may be a name or index number. A number will be ignored while scanning the file. A name is defined as global variable and set to the index of the current entry.

Each entry is split at least into 3 lines. The greater sign '>' as first non blank character of a line signals a continuation line.

4.   Section [CAME] (Cameras)

→ Custom Track Wiki: KMP/CAME

4.1   Parameter

Like all data sections, this section beginns with a revision number to define the input format. The input format of this section has changed with revision 2955 (Aug 2011). The previous input format is scanned correct if the revision number of the section is set right.
@REVISION = 1234
Parameters '@OPENING-INDEX' and '@SELECTION-INDEX' are byte values stored into the section header at offsets 0x06 and 0x07. They are used as index of the first camera for the opening pan around the track and the first camera for the videos on the track selection menu of the track. The second value is ignored by the Wii, as the videos have already been generated and stored.
@OPENING-INDEX   = c1
@SELECTION-INDEX = c2

4.2   Input Table

Column 'idx' may be a name or index number. A number will be ignored while scanning the file. A name is defined as global variable and set to the index of the current entry.

Column 'next' is either a camera name or index and points to the next camera. Column 'route' is either a route name or index and points into the POTI section. A value of -1 means "no link".

For each camera, 3 global variables are defined, if a name is specified as camera index (field 'idx'). 'NAME' is a placeholder for the entered name:

NAME.came.time
Camera duration, value of 'sec*60'.
NAME.zoom.len
Absolute value of the difference 'zoom_end-zoom_beg'.
NAME.viewpt.len
Distance between 'view point beg' and 'view point end'.

If zoom or view point speed is set to value -1, then the value is calculated so that the time coincides with the camera running time. If this calculation is not possible, value 1 will be used. The calculations are:

zoom_speed   := 100.0 * NAME.zoom.len   / NAME.came.time
viewpt_speed := 100.0 * NAME.viewpt.len / NAME.came.time

Each entry is split at least into 4 lines. The greater sign '>' as first non blank character of a line signals a continuation line.

5.   Section [CKPH] (Check point groups)

→ Custom Track Wiki: KMP/CKPH

This complete section is only informative and ignored on reading. The content is created while scanning the parameter '@CKPH-HEAD-VALUE' and the $GROUP and $SPLIT entries of section CKPT.

6.   Section [CKPT] (Check points)

→ Custom Track Wiki: KMP/CKPT

6.1   Parameter

Like all data sections, this section beginns with a revision number to define the input format.
@REVISION = 1234

The parameters '@*-HEAD-VALUE' are stored into the section headers of sections CKPT and CKPH at offset 0x06. The meaning is unknown and it seems to be only a padding.

@CKPT-HEAD-VALUE = 0
@CKPH-HEAD-VALUE = 0

The KMP compiler can override the 'mode' values by automatic calculated values, if parameter '@AUTO-MODE' is set to one of the following values:

AM$OFF
The auto mode is switched off. This is the default.
AM$NORM
All mode with values between 1 and 254 are normalized. All gaps are removed and the smallest mode becomes 1. All equal values are also equal after transformation.
AM$RENUMBER
All mode with values between 1 and 254 are renumbered beginning from 1.
AM$1LAP
Force a 1 lap race by setting the first 5 check points to 0,-1,0,-1,0 and all other check points to -1.
AM$SHORT
Force a short race by setting all modes cyclic to 0 and -1.
AM$UNLIMIT
Force an unlimited race by setting the first 4 modes to 3,0,1,2 and all other modes to -1. The fourth point (that one with mode=2) is placed far away from all others point to make it unreachable.
Usually, '@AUTO-MODE' is set to mode$automode, which is defined in the setup section based on the constant 'laps'.
@AUTO-MODE = mode$automode

If parameter '@AUTO-NEXT' is set to 1, then the 'prev' and 'next' columns are calculated automatically pointing to the previous and next points of the same group. The default setting of '@AUTO-NEXT' is set to 1, if this relation between index and 'prev' and 'next' is true for all entries. The parameter can be set anywhere and multiple times in this section to enable or disable the features for only some points.

@AUTO-NEXT = 0

If a KMP text file is encoded and printed as text file again, the scanned group names will be used for the output. If parameter '@AUTO-GROUP-NAME' is set to 1, then all groups will be renamed. The names are based on an analysis of the next links.

@AUTO-GROUP-NAME = 0

If '@ROUTE-OBJECT-MODE' is set, the entered objects are used to make the route points visible. Be sure to copy the needed files (BRRES and perhaps more) into the SZS file or to use the Auto Add data base. The following table shows the modes:

@ROUTE-OBJECT-MODE
ROUTE-
OBJECT-
MODE
lap counter
mode=0
mandatory
0<mode<255
all others
mode=255
0
1 object 2 object 1
2 object 2 object 2 object 1
3 left=object 1
right=object 2
left=object 1
right=object 2
left=object 1
right=object 2

Usually, '@ROUTE-OBJECT-MODE' is set to mode$showck, which is defined in the setup section based on the constant 'showrt'.

@ROUTE-OBJECT-MODE   = mode$showck
--- default settings:
@ROUTE-OBJECT1       = o$castletree1
@ROUTE-OBJECT2       = o$TownTreeDS
@ROUTE-OBJECT1-SCALE = v( 0.05, 12.00, 0.20 )
@ROUTE-OBJECT2-SCALE = v( 0.05, 12.00, 0.20 )
@ROUTE-OBJECT1-BASE  = -2000
@ROUTE-OBJECT2-BASE  = -2000
If tool wszst is active and a route object is defined, then option --auto-add is implicitly set.

6.2   Input Table

Column 'idx' is only informative and ignored when reading this file. Column 'respawn' is either a route name or a route index and points into the POTI section. Columns 'width of check point' and 'direction' are only comments as an additional info.

6.2.1   $GROUP and $SPLIT

Lines beginning with '$GROUP' followed by a group name mark the beginning of a new group of points. All groups are a mirror of the section CKPH. The values behind the ':' are the group link names to the next groups. A maximum of 6 links for each group are possible. If reading this file, section CKPH is ignored. The table of section CKPH is calculated by the '$GROUP' lines of this section.

The default GROUP names are the result of analyzing the pathes between the groups. For clearness, each '$GROUP' line is followed by a comment line with zero based section indices.

A '$SPLIT' command is followed by a group name and splits the current group into 2 peaces. It is an alternative way to create a group. The next elements of the previous group definition are moved to the new group. The only next-link in the previous groups points to the new group. Multiple '$SPLIT' commands can be used to split a group into more than 2 parts.

Syntax:

  '$GROUP' name: next1 ... next6
  '$SPLIT' name

6.2.2   $LINE, $BORDER and $BEZIER

The special commands '$LINE', '$BORDER' and '$BEZIER' insert N calculated points between 2 others; such commands before the first and behind the last point are ignored.

Syntax:

  '$LINE'    N
  '$BORDER'  N
  '$BEZIER'  N  [ P1x P1y ]  [ P2x P2y ]
Command '$LINE' set N points linear between the previous and the next point. The positions are calculated by the middle of the check points.

Command '$BORDER' set N points linear between the previous and the next point. The positions of the left and right borders are calculated separately.

Command '$BEZIER' creates a bézier curve. If only P1 is set, a quadratic bézier curve is used, else a cubic bézier curve. If no points are entered, the system calculates 2 help points with respect to the directions of both surrounding points.

7.   Section [CNPT] (Canon points)

→ Custom Track Wiki: KMP/CNPT

7.1   Parameter

Like all data sections, this section beginns with a revision number to define the input format.
@REVISION = 1234

Parameter '@CNPT-HEAD-VALUE' is stored into the section header at offset 0x06. It's meaning is unknown and it seems to be only a padding.

@CNPT-HEAD-VALUE = 0

If parameter '@AUTO-ID' is set to 1, then all 'id' values are set to the (new) index of the entry. All original Nintendo tracks use this setting. Value 0 disables it. The default setting is set to 1, if this relation between index and 'id' is true for all entries. This parameter can be set anywhere and multiple times in this section to enable or disable the feature for only some points.

@AUTO-ID = 1

All points can be adjusted using the KCL-FALL feature, if a reference KCL is loaded by option --load-kcl. This is done before the SNAP-TO-ENPT calculations.

If parameter '@SNAP-TO-ENPT' or '@SNAP2-TO-ENPT' is set to a numeric value, then all points will be moved to the nearest point of the section ENPT plus the entered value (y-scalar or vector). The horizontal direction (Y-rotation) is calculated to point to the next ENPT point, section linking is observed. X-rotation and Z-rotation are set to 0.0. '@SNAP2-TO-ENPT' has higher priority and additonally calculates the X-rotation. The value '$NONE' deactivates this function.

Parameter '@HSNAP-TO-ENPT' does the same as '@SNAP-TO-ENPT', but ignores the Y-value of ENPT and uses the Y-value of the entered point instead. '@HSNAP-TO-ENPT' is ignored if at least one of the other snap modes is active.

@HSNAP-TO-ENPT = $NONE  # horizontal snap without adjust, y-rotation
@SNAP-TO-ENPT  = $NONE  # 3D snap, y-rotation
@SNAP2-TO-ENPT = $NONE  # 3D snap, x- and y-rotation

If '@SHOW-ROUTE' (old name: '@ROUTE-ITEMBOX') is set to 1, all itemboxes of section GOBJ are disabled and an itembox (object id 0x65) is defined for each CNPT point. This helps to find and confirm the optimal positions. The default value 'mode$showrt' is defined in the setup section.

@SHOW-ROUTE = ( mode$showrt & 8 ) > 0

7.2   Input Table

Column 'idx' may be a name or index number. A number will be ignored while scanning the file. A name is defined as global variable and set to the index of the current entry.

8.   Section [ENPH] (Enemy route groups)

→ Custom Track Wiki: KMP/ENPH

This complete section is only informative and ignored on reading. The content is created while scanning the parameter '@ENPH-HEAD-VALUE' and the $GROUP and $SPLIT entries of section ENPT.

9.   Section [ENPT] (Enemy route points)

→ Custom Track Wiki: KMP/ENPT

9.1   Parameter

Like all data sections, this section beginns with a revision number to define the input format.
@REVISION = 1234

The parameters '@*-HEAD-VALUE' are stored into the section headers of sections ENPT and ENPH at offset 0x06. The meaning is unknown and it seems to be only a padding.

@ENPT-HEAD-VALUE = 0
@ENPH-HEAD-VALUE = 0

If parameter '@AUTO-FILL' is set to a value ≥1.0 and no $LINE or $BEZIER command is active, then the distance of the current and the previous point is calculated. If the distance is larger than the autofill value, then trunc(distance/autofill) additional points are inserted like the $LINE command does it.

@AUTO-FILL = 0.0

If a KMP text file is encoded and printed as text file again, the scanned group names will be used for the output. If parameter '@AUTO-GROUP-NAME' is set to 1, then all groups will be renamed. The names are based on an analysis of the next links.

@AUTO-GROUP-NAME = 0

If 'ROTATE-GROUP-LINKS' is set to a value>0, then the next links are rotated by the entered steps. If the first character behind '$GROUP' is a '-', then this group is not rotated. This allow easy testing of other main routes.

@ROTATE-GROUP-LINKS = 0

All points can be adjusted using the KCL-FALL feature, if a reference KCL is loaded by option --load-kcl.

If '@SHOW-ROUTE' (old name: '@ROUTE-ITEMBOX') is set to 1, all itemboxes of section GOBJ are disabled and an itembox (object id 0x65) is defined for each ENPT point. This helps to find and confirm the optimal positions. The default value 'mode$showrt' is defined in the setup section.

@SHOW-ROUTE = ( mode$showrt & 1 ) > 0

9.2   Input Table

Column 'idx' is only informative and ignored when reading this file. Columns 'distance to prev' and 'horizontal angle' are only comments as an additional info.

9.2.1   $GROUP and $SPLIT

Lines beginning with '$GROUP' followed by a group name mark the beginning of a new group of points. All groups are a mirror of the section ENPH. The values behind the ':' are the group link names to the next groups. A maximum of 6 links for each group are possible. If reading this file, section ENPH is ignored. The table of section ENPH is calculated by the '$GROUP' lines of this section.

To allow the same definition for ENPT and ITPT, a next name can be followed by '!E' or '!I'. Such marked next link is only used for ENPT or ITPT. To raise the chance that a specific route is used by an enemy, put it multiple times into the next list, or append a repeat factor of format '*N'.

The default GROUP names are the result of analyzing the pathes between the groups. For clearness, each '$GROUP' line is followed by a comment line with zero based section indices.

A '$SPLIT' command is followed by a group name and splits the current group into 2 peaces. It is an alternative way to create a group. The next elements of the previous group definition are moved to the new group. The only next-link in the previous groups points to the new group. Multiple '$SPLIT' commands can be used to split a group into more than 2 parts.

Syntax:

  '$GROUP' name: next1 ... next6
  '$SPLIT' name

9.2.2   $LINE and $BEZIER

The special commands '$LINE' and '$BEZIER' insert N calculated points betweeen 2 others; such commands before the first and behind the last point are ignored.

Syntax:

  '$LINE'    N
  '$BEZIER'  N  P1x P1y P1z  [ P2x P2y P2z ]

If P1 and P2 are not set, then the points are set linear between the previous and the next point. If P1 is set, then a quadratic bézier curve and if P1 and P2 are set, then a cubic bézier curve is calculated. The settings and the GROUP are copied from the point behind.

10.   Section [GOBJ] (Global objects)

→ Custom Track Wiki: KMP/GOBJ

10.1   Parameter

Like all data sections, this section beginns with a revision number to define the input format.
@REVISION = 1234

Parameter '@GOBJ-HEAD-VALUE' is stored into the section header at offset 0x06. It's meaning is unknown and it seems to be only a padding.

@GOBJ-HEAD-VALUE = 0

If parameter '@AUTO-ENEMY-ITEM' is set to a non null value, then setting #3 of some itembox objects are automatically set if entered with value 0. This will give the enemies special items for test purposes. The example value give them stars or mega mushrooms.

@AUTO-ENEMY-ITEM = 0 # mode$test ?  : 0

If a text file is encoded and printed as text file again, the scanned object names will be used for the output. If parameter '@AUTO-OBJECT-NAME' to 1, then all objects will be renamed.

@AUTO-OBJECT-NAME = 0

All points can be adjusted using the KCL-FALL feature, if a reference KCL is loaded by option --load-kcl.

It is possible to sort the global objects. If parameter '@SORT-OBJECTS' is set to mode 'SORT$GROUPING', then all objects are sorted into groups with same object ID. The sort order is the first appearance of an item type. Mode 'SORT$ANGLE' sorts additional the objects within each group by horizontal angle around the position v(0,0,0). Sorting implies '@AUTO-OBJECT-NAME=1'. Mode 'SORT$OFF' disables sorting.

@SORT-OBJECTS = SORT$OFF

10.2   Input Table

Column 'idx' may be a name or index number. A number will be ignored while scanning the file. A name is defined as global variable and set to the index of the current entry.

Column 'route' is either a route name or a route index and points into the POTI section. A value of -1 means "no link".

The additional info about the meaning and the parameters of the objects are copied from the Custom Track Wiki. Please edit the pages if you find more infos or errors.

Each entry is split at least into 3 lines. The greater sign '>' as first non blank character of a line signals a continuation line.

11.   Section [ITPH] (Item route groups)

→ Custom Track Wiki: KMP/ITPH

This complete section is only informative and ignored on reading. The content is created while scanning the parameter '@ITPH-HEAD-VALUE' and the $GROUP and $SPLIT entries of section ITPT.

12.   Section [ITPT] (Item route points)

→ Custom Track Wiki: KMP/ITPT

12.1   Parameter

Like all data sections, this section beginns with a revision number to define the input format.
@REVISION = 1234

The parameters '@*-HEAD-VALUE' are stored into the section headers of sections ITPT and ITPH at offset 0x06. The meaning is unknown and it seems to be only a padding.

@ITPT-HEAD-VALUE = 0
@ITPH-HEAD-VALUE = 0

If parameter '@AUTO-FILL' is set to a value ≥1.0 and no $LINE or $BEZIER command is active, then the distance of the current and the previous point is calculated. If the distance is larger than the autofill value, then trunc(distance/autofill) additional points are inserted like the $LINE command does it.

@AUTO-FILL = 0.0

If a KMP text file is encoded and printed as text file again, the scanned group names will be used for the output. If parameter '@AUTO-GROUP-NAME' is set to 1, then all groups will be renamed. The names are based on an analysis of the next links.

@AUTO-GROUP-NAME = 0

If 'ROTATE-GROUP-LINKS' is set to a value>0, then the next links are rotated by the entered steps. If the first character behind '$GROUP' is a '-', then this group is not rotated. This allow easy testing of other main routes.

@ROTATE-GROUP-LINKS = 0

All points can be adjusted using the KCL-FALL feature, if a reference KCL is loaded by option --load-kcl.

If '@SHOW-ROUTE' (old name: '@ROUTE-ITEMBOX') is set to 1, all itemboxes of section GOBJ are disabled and an itembox (object id 0x65) is defined for each ITPT point. This helps to find and confirm the optimal positions. The default value 'mode$showrt' is defined in the setup section.

@SHOW-ROUTE = ( mode$showrt & 2 ) > 0

12.2   Input Table

Column 'idx' is only informative and ignored when reading this file. Columns 'distance to prev' and 'horizontal angle' are only comments as an additional info.

12.2.1   $GROUP and $SPLIT

Lines beginning with '$GROUP' followed by a group name mark the beginning of a new group of points. All groups are a mirror of the section ITPH. The values behind the ':' are the group link names to the next groups. A maximum of 6 links for each group are possible. If reading this file, section ITPH is ignored. The table of section ITPH is calculated by the '$GROUP' lines of this section.

To allow the same definition for ENPT and ITPT, a next name can be followed by '!E' or '!I'. Such marked next link is only used for ENPT or ITPT.

The default GROUP names are the result of analyzing the pathes between the groups. For clearness, each '$GROUP' line is followed by a comment line with zero based section indices.

A '$SPLIT' command is followed by a group name and splits the current group into 2 peaces. It is an alternative way to create a group. The next elements of the previous group definition are moved to the new group. The only next-link in the previous groups points to the new group. Multiple '$SPLIT' commands can be used to split a group into more than 2 parts.

Syntax:

  '$GROUP' name: next1 ... next6
  '$SPLIT' name

12.2.2   $LINE and $BEZIER

The special commands '$LINE' and '$BEZIER' insert N calculated points betweeen 2 others; such commands before the first and behind the last point are ignored.

Syntax:

  '$LINE'    N
  '$BEZIER'  N  P1x P1y P1z  [ P2x P2y P2z ]

If P1 and P2 are not set, then the points are set linear between the previous and the next point. If P1 is set, then a quadratic bézier curve and if P1 and P2 are set, then a cubic bézier curve is calculated. The settings and the GROUP are copied from the point behind.

13.   Section [JGPT] (Respawn points)

→ Custom Track Wiki: KMP/JGPT

13.1   Parameter

Like all data sections, this section beginns with a revision number to define the input format.
@REVISION = 1234

Parameter '@JGPT-HEAD-VALUE' is stored into the section header at offset 0x06. It's meaning is unknown and it seems to be only a padding.

@JGPT-HEAD-VALUE = 0

If parameter '@AUTO-ID' is set to 1, then all 'id' values are set to the (new) index of the entry. All original Nintendo tracks use this setting. Value 0 disables it. The default setting is set to 1, if this relation between index and 'id' is true for all entries. This parameter can be set anywhere and multiple times in this section to enable or disable the feature for only some points.

@AUTO-ID = 1

All points can be adjusted using the KCL-FALL feature, if a reference KCL is loaded by option --load-kcl. This is done before the SNAP-TO-ENPT calculations.

If parameter '@SNAP-TO-ENPT' or '@SNAP2-TO-ENPT' is set to a numeric value, then all points will be moved to the nearest point of the section ENPT plus the entered value (y-scalar or vector). The horizontal direction (Y-rotation) is calculated to point to the next ENPT point, section linking is observed. X-rotation and Z-rotation are set to 0.0. '@SNAP2-TO-ENPT' has higher priority and additonally calculates the X-rotation. The value '$NONE' deactivates this function.

Parameter '@HSNAP-TO-ENPT' does the same as '@SNAP-TO-ENPT', but ignores the Y-value of ENPT and uses the Y-value of the entered point instead. '@HSNAP-TO-ENPT' is ignored if at least one of the other snap modes is active.

@HSNAP-TO-ENPT = $NONE  # horizontal snap without adjust, y-rotation
@SNAP-TO-ENPT  = $NONE  # 3D snap, y-rotation
@SNAP2-TO-ENPT = $NONE  # 3D snap, x- and y-rotation

If '@SHOW-ROUTE' (old name: '@ROUTE-ITEMBOX') is set to 1, all itemboxes of section GOBJ are disabled and an itembox (object id 0x65) is defined for each JGPT point. This helps to find and confirm the optimal positions. The default value 'mode$showrt' is defined in the setup section.

@SHOW-ROUTE = ( mode$showrt & 4 ) > 0

13.2   Input Table

Column 'idx' may be a name or index number. A number will be ignored while scanning the file. A name is defined as global variable and set to the index of the current entry.

14.   Section [KTPT] (Start positions)

→ Custom Track Wiki: KMP/KTPT

14.1   Parameter

Like all data sections, this section beginns with a revision number to define the input format.
@REVISION = 1234
Parameter '@KTPT-HEAD-VALUE' is stored into the section header at offset 0x06. It's meaning is unknown and it seems to be only a padding.
@KTPT-HEAD-VALUE = 0

All points can be adjusted using the KCL-FALL feature, if a reference KCL is loaded by option --load-kcl.

15.   Section [MSPT] (Battle positions)

→ Custom Track Wiki: KMP/MSPT

15.1   Parameter

Like all data sections, this section beginns with a revision number to define the input format.
@REVISION = 1234

Parameter '@MSPT-HEAD-VALUE' is stored into the section header at offset 0x06. It's meaning is unknown and it seems to be only a padding.

@MSPT-HEAD-VALUE = 0

If parameter '@AUTO-ID' is set to 1, then all 'id' values are set to the (new) index of the entry. All original Nintendo tracks use this setting. Value 0 disables it. The default setting is set to 1, if this relation between index and 'id' is true for all entries. This parameter can be set anywhere and multiple times in this section to enable or disable the feature for only some points.

@AUTO-ID = 1

All points can be adjusted using the KCL-FALL feature, if a reference KCL is loaded by option --load-kcl. This is done before the SNAP-TO-ENPT calculations.

If parameter '@SNAP-TO-ENPT' or '@SNAP2-TO-ENPT' is set to a numeric value, then all points will be moved to the nearest point of the section ENPT plus the entered value (y-scalar or vector). The horizontal direction (Y-rotation) is calculated to point to the next ENPT point, section linking is observed. X-rotation and Z-rotation are set to 0.0. '@SNAP2-TO-ENPT' has higher priority and additonally calculates the X-rotation. The value '$NONE' deactivates this function.

Parameter '@HSNAP-TO-ENPT' does the same as '@SNAP-TO-ENPT', but ignores the Y-value of ENPT and uses the Y-value of the entered point instead. '@HSNAP-TO-ENPT' is ignored if at least one of the other snap modes is active.

@HSNAP-TO-ENPT = $NONE  # horizontal snap without adjust, y-rotation
@SNAP-TO-ENPT  = $NONE  # 3D snap, y-rotation
@SNAP2-TO-ENPT = $NONE  # 3D snap, x- and y-rotation

If '@SHOW-ROUTE' (old name: '@ROUTE-ITEMBOX') is set to 1, all itemboxes of section GOBJ are disabled and an itembox (object id 0x65) is defined for each MSPT point. This helps to find and confirm the optimal positions. The default value 'mode$showrt' is defined in the setup section.

@SHOW-ROUTE = ( mode$showrt & 16 ) > 0

15.2   Input Table

Column 'idx' may be a name or index number. A number will be ignored while scanning the file. A name is defined as global variable and set to the index of the current entry.

16.   Section [POTI] (Routes)

→ Custom Track Wiki: KMP/POTI

16.1   Parameter

Like all data sections, this section beginns with a revision number to define the input format.
@REVISION = 1234

If a text file is encoded and printed as text file again, the scanned route names will be used for the output. If parameter '@AUTO-ROUTE-NAME' is set to 1, then all routes will be renamed using the generic name.

@AUTO-ROUTE-NAME = 0

16.2   Single Routes

Lines beginning with '$ROUTE' mark the beginning of a new route. The route headers and the related points are interleaved in the POTI binary data. The name behind '$ROUTE' will be defined as global variable and set to the route index for named references. Route references of other sections can use this name instead of an index to point to the route. This makes route list modifications (inserting, removing, reordering) much easier.

The generic route name is 'r#', where '#' is the zero based index of the route. The value(s) behind the first ':' is the route setting. A single value is interpreted as 16-bit number and 2 values as two 8-bit numbers (MSB first). The first value is 0 for "linear from point to point" or 1 for "smooth motion". The second value is 0 for "cyclic" or 1 for "forward and backward". See the Custom Track Wiki for more details.

The keyword '$CLOSE' closes a route. Routes are automatically closed at the end of the section or at the beginning of a new route.

If a route is closed, 3 global variables are defined for the route. 'NAME' is a placeholder for the route name (before renaming happens):

NAME.len
Total route distance over all points.
NAME.time
Total route time in 1/60 seconds calculated by the sum of all distances and the associated speed values.
NAME.time.set
Normally same value as 'NAME.time'. If parameter '@SET-ROUTE-TIME' is set, it is the new calculated sum (see below).

16.2.1   Parameter

There are 13 parameters devided into 2 groups. The impact of the first group is calculated directly after input. Because of thos you can enable or disable it for only a few points.
@KCL-FALL-WIDTH    = CUBE_WIDTH
@KCL-FALL-PRE-ADD  = HEIGHT_OR_VECTOR
@KCL-FALL-POST-ADD = HEIGHT_OR_VECTOR
@KCL-FALL-TYPES    = TYPEMASK

The next 9 parameters are computed after closing a route in this order:

@XSS               = X1OLD, X1NEW, X2OLD, X2NEW
@YSS               = Y1OLD, Y1NEW, Y2OLD, Y2NEW
@ZSS               = Z1OLD, Z1NEW, Z2OLD, Z2NEW
@SCALE             = FACTOR [ORIGIN]
@SHIFT             = DELTA
@HROTATE           = DEGREE [ORIGIN]
@REVERSE-ORDER     = 0|1
@SET-ROUTE-TIME    = SECONDS
@SHOW-ROUTE        = 0|1
Parameter descriptions:
@KCL-FALL-* ...
All points can be adjusted using the KCL-FALL feature, if a reference KCL is loaded by option --load-kcl.
@XSS = X1OLD, X1NEW, X2OLD, X2NEW
This parameter (X-Scale-Shift) calculates the X values of '@SCALE' and '@SHIFT', so that the old values are transformed to the new values. If at least one of the '@*SS' parameters is set, the parameters '@SCALE' and '@SHIFT' are ignored.
@YSS = X1OLD, Y1NEW, Y2OLD, Y2NEW
Same as '@XSS', but for the Y values.
@ZSS = Z1OLD, Z1NEW, Z2OLD, Z2NEW
Same as '@XSS', but for the Z values.
@SCALE = FACTOR [ORIGIN]
This parameter scales the coordinates by FACTOR. Negative values mirror the coordinates. If the ORIGIN is not set, vector v(0,0,0) is used instead.
@SHIFT = DELTA
This parameter adds the vector DELTA to all coordinates.
@HROTATE = DEGREE [ORIGIN]
This parameter rotates the coordinates horizontal counterclockwise by the float value DEGREE. If ORIGIN is not set, vector v(0,0,0) is used instead.
@REVERSE-ORDER = 0|1
If this parameter is set to 1 for a route, then the order of all points is reversed (last becomes last and vice versa).
@SET-ROUTE-TIME = SECONDS
If this parameter is set to a value >0.0, then the speed values are adjusted so that the total route time is nearly the entered number of 1/60 seconds. Set resulting time (not the wanted because of rounding issues) in 1/60 seconds is then assigned to the variable 'NAME.time.set' for further calculations.
@SHOW-ROUTE = 0|1
If this parameter is set to 1, all item boxes of section GOBJ are disabled and an item box (object id 0x65) is defined for each point of the current route. This helps to find and confirm the optimal route points.

16.3   Input Table

Column 'idx' may be a name or index number. A number will be ignored while scanning the file. A name is defined as global variable and set to the index of the current point within the route and can be used for links from objects.

Columns 'seconds+distance to next' and 'horizontal angle' are only comments as an additional info.

16.3.1   $LINE and $BEZIER

The special commands '$LINE' and '$BEZIER' insert N calculated points between 2 others; such commands before the first and behind the last point of each route are ignored.

Syntax:

  '$LINE'    N
  '$BEZIER'  N  P1x P1y P1z  [ P2x P2y P2z ]

If P1 and P2 are not set, then the points are set linear between the previous and the next point. If P1 is set, then a quadratic bézier curve and if P1 and P2 are set, then a cubic bézier curve is calculated. The settings are copied from the point behind.

16.3.2   $COPY

The special command '$COPY' copies route points from previous defined routes and also from the current route.

Syntax:

  '$COPY' ROUTE_ID [FIRST_POINT [LAST_POINT]]

'ROUTE_ID' is the name or ID of a source route. 'FIRST_POINT' is the index of the first point to be copied. If not set, all points are copied. 'LAST_POINT' is the index of the last point to be copied. If not set, all points beginning from 'FIRST_POINT' are copied.

17.   Section [STGI] (Stage info)

→ Custom Track Wiki: KMP/STGI

17.1   Parameter

Like all data sections, this section beginns with a revision number to define the input format. The input format of this section has changed with revision 3379 (Jan 2012). The previous input format is scanned correct if the revision number of the section is set right.
@REVISION = 1234
Parameter '@STGI-HEAD-VALUE' is stored into the section header at offset 0x06. It's meaning is unknown and it seems to be only a padding.
@STGI-HEAD-VALUE = 0

17.2   Input Table

Column 'idx' may be a name or index number. A number will be ignored while scanning the file. A name is defined as global variable and set to the index of the current entry.

18.   Special concepts

There are some concepts that can be used in different section, always with the same impact.

18.1   KCL-FALL

It is a hard job to place objects like itemboxes or enemy route points or other points directly over the road. Most this takes a lot of time for the loop fixing + creating + testing the track.

But we have a KCL, that knows where the roads are. Why not set an object to a position above the road. Then the computer can find a final position by simulating a free fall until a KCL border is found? This concept is implemented in Wiimms SZS Tools and called KCL-FALL.

For this calculation 4 parameters can be set.

@KCL-FALL-WIDTH    =  0  # set to a value >0 (e.g. 200) to enable KCL falling
@KCL-FALL-PRE-ADD  =  0  # add this height or vector before falling
@KCL-FALL-POST-ADD =  0  # add this height or vector after success
@KCL-FALL-TYPES    = -1  # bit field of recognized KCL types

For each point the following algorithm is used. The algorithm use always the current setting of the parameters. So it's allowed to change the parameters only for some points.

  1. KCL-FALL-WIDTH defines the length and width of the quadratic object, that falls down.

    If KCL-FALL-WIDTH <= 0, no transformation is done and the algorithm is aborted. 200 seems to be a good value for KCL-FALL-WIDTH.

  2. The vector KCL-FALL-PRE-ADD is added to the point. If KCL-FALL-PRE-ADD is a scalar, it is added to the height (y value) of the point.

    The main idea of this parameter is to raise the point before falling down. So the initial position can be estimated.

  3. A cube is created around the point. The point is horizontally in the middle and vertically at the bottom of the cube. The edge length of the cube is KCL-FALL-WIDTH. This cube is used to find the collisions.
  4. For all collision tests, the bit field KCL-FALL-TYPES defines, which KCL types (0..31) are recognized: If bit N is set, KCL type N will collide. The default (-1, all bits set) is to find collisions with all KCL types. A collison is found, if the cube overlaps at least one triangle of the entered KCL types.

    Use the predifined value KCL$BORDER for all KCL types except effect types. Use KCL$DRIVE for all drivable KCL types.

  5. A first collision test is done to see, if the cube is in a free area. Therefor the raised point (or better cube) is tested. If the cube collides in this steps, the algorithm is aborted and the original position is not changed.
  6. Now an iterative method is used to lower the point until a collision is found. The algorithm is aborted, if the y point is lower than 0.0, because it is definitley a fall boundary.
  7. Now at least one collision is found. The resulting height is an integral number above the colliding triangle; it is set as new y value of the position.
  8. The vector KCL-FALL-POST-ADD is added to the new position. If KCL-FALL-POST-ADD is a scalar, it is added to the height (y value) of the position.

    The main idea of this parameter to adjust the position by a user defined value, if and only if a collision was found.

  9. Now and only now, the resulting vector is stored as new 3D position for the object or route point.

If you want only to adjust a few points, define KCL_FALL-WIDTH before the first point to adjust and set set it to 0 behind the last point to adjust. It's also possible to change all other parameters.

Supported KMP sections: CNPT, ENPT, GOBJ, ITPT, JGPT, KTPT, MSPT and POTI. Additionally the parser function kcl$fall() and kcl$fallFlag() can be used in all sections.

18.1.1   Functions

KCL Fall Functions
File
Type
Return Value
& Function Name
& Parameters
Description
* vector
kcl$fall
(pt,​width​[,typemask])
If a reference KCL is defined, search the lowest point below 'pt', that can be reached without collision. The point is expanded to a cube with edge length 'width' for the collision tests. If 'typemask' is set, only KCL types with related bit number set are recognized. Use kcl$fallFlag() to get the corespondent KCL flag.
* int
kcl$fallFlag
()
This functions returns the corespondent KCL flag of the last call of kcl$fall(). The return value is the KCL flag of the colliding triangle, or -1 if no collision was found.

18.1.2   Examples

In the first example all enemy points are droped from their defined position until they hit anything in the KCL. It seems that the value 200 is a good width to find the colliding triangles:
[ENPT]
@KCL_FALL-WIDTH = 200
...

In the next example only some item boxes are first raised by 500 and then drop until they hit anything in the KCL:

[GOBJ]
....
 0 0x65 ...              # an itembox definition

@KCL-FALL-WIDTH   = 200  # enable adjusting
@KCL-FALL-PRE-ADD = 500  # raise the objects before dropping
 0 0x65 ...              # an itembox definition
 0 0x65 ...              # an itembox definition
@KCL-FALL-WIDTH   =   0  # disable adjusting
...

Use the command »wkclt FALL« to drop points in any KCL.

18.1.3   --load-kcl file

Load a KCL or OBJ file for reference issues.
The tools try to autoload a related KCL file, if the KCL-FALL feature is used. The filename for this auto loading is the filename of the KMP file with the replaced extension .kcl.

But if you use the option --load-kcl you can directly define a KCL file. It's also possible to disable this feature at all by using option --load-kcl with an empty string as parameter.

The KCL file is loaded into the memory on the first access.