KCL flag

From Custom Mario Kart
Jump to navigation Jump to search

Overview

In Mario Kart Wii, collision data is stored as a list of triangles in a KCL file. Each triangle in the file is associated with a 16-bit KCL flag, which determines the effect that the triangle has on players or items that collide with it. A KCL flag consists of 5 components, each corresponding to a bit group:

Kcl-flag-bit-groups.png

Base Type:
Ranges in value from 0x00 to 0x1F. This component represents the main effect that the triangle will have, e.g. road, offroad, fall boundary, etc.. Descriptions of each value's effect can be found below.

Variant:
Ranges in value from 0 to 7. This component determines the variant of the base type. The possible variants of each base type are described below.

BLIGHT Index:
Ranges in value from 0 to 7. This component is the index of posteffect.blight that the triangle should use. For drivable surfaces, this refers to the lighting that is applied to any character, vehicle or item that is touching it. For most non-drivable surfaces such as walls, it appears to have no effect. Some variants of 0x10 and 0x1A repurpose this component to index into the KMP.

Wheel Depth:
Ranges in value from 0 to 3. For drivable surfaces, a higher value will cause the player's wheels to "sink" further into the road. This is used by Nintendo on surfaces such as snow or sand. This likely has other subtle effects on wheel physics; exact details are unknown.

Collision effect:
This component consists of 3 bits that each have a different effect when set:

Bit Effect
0 Affects drivable surfaces. If set to 1, the surface becomes trickable. NOTE: For base types that
are trickable by default, e.g. boost ramps, this bit should remain as 0 to avoid inconsistent trick types.
1 Affects drivable surfaces. If set to 1, the surface becomes reject road, which forces a player to
change direction when attempting to drive on it.
2 Affects walls. If set to 1, the wall becomes a soft wall, also referred to as "barrel roll" collision. This
is used by Nintendo on walls below ledges to prevent players from hanging on them.

Example

To manually calculate the KCL flag for grass offroad (base type = 0x03, variant = 4) that is trickable (collision effect bit 0 = 1) and uses BLIGHT index 3: First insert the components into the correct bit groups, then convert the resulting binary number to hexadecimal.

Kcl-flags-ex.png

Cheat Sheet

This image sums up the base types and variants for finding them more quickly (although it is a bit outdated).

KCL Cheat Sheet.png



Base Types & Variants

Road (0x00)

Default road. The variant controls the terrain type, i.e. the sound effects (SFX) and particles (GFX) generated by driving on it.

Variant Effect
0 Normal road
1 Dirt, GFX on slots 7.3 and 8.3
2 Dirt, no GFX
3 Smooth
4 Wood
5 Snow with GFX
6 Metal grate
7 Road, but the sound cuts off and returns immediately when triggered

Slippery Road 1 (0x01)

A type of road that is slippery, but does not slow you down.

Variant Effect
0 White sand
1 Dirt[1]
2 Water (unused)
3 Snow (unused)
4 Grass (unused)
5 Yellow sand
6 Sand, no GFX (unused)
7 Dirt, no GFX (unused)
  1. GFX is a lighter color on slot 8.2.

Weak Off-road (0x02)

A type of road that slows the player down a small amount.

Variant Effect
0 Orange Sand
1 Dirt[1]
2 Water
3 Grass, darker GFX
4 Sand, lighter GFX
5 Carpet
6 Gravel[2][3]
7 Gravel, different impact SFX[2][3]
  1. GFX is red on slot 3.4.
  2. 2.0 2.1 GFX is orange on slot 3.1.
  3. 3.0 3.1 GFX does not include the rock particles on slot 3.4.

Off-road (0x03)

A type of road that slows the player down a moderate amount.

Variant Effect
0 Sand[1]
1 Dirt
2 Mud[1]
3 Water, no GFX (unused)
4 Grass[1]
5 Sand, lighter GFX
6 Gravel, different impact SFX
7 Carpet
  1. 1.0 1.1 1.2 GFX can be a different color on different slots.

Heavy Off-road (0x04)

A type of road that slows the player down a large amount.

Variant Effect
0 Sand
1 Dirt
2 Mud
3 Flowers
4 Grass
5 Snow
6 Sand
7 Dirt, no GFX

Slippery Road 2 (0x05)

A type of road that is slippery and slightly slows you down.

Variant Effect
0 Ice
1 Mud, no GFX (unused)
2-5 Water, no GFX (unused)
6-7 Normal road, different sound (unused)

Boost (0x06) [DASH]

(Boost Panel) Applies a boost when you drive over it.

Variant Effect
0 Default
1 If used in course.kcl and casino_roulette is present, this surface will rotate around it counterclockwise. Used in Chain Chomp Wheel.
2-7 Unknown. Unused

Boost Ramp (0x07) [DASHJ]

Applies a boost and is trickable by default. The variant controls the trick animation, and by extension the duration of the trick boost you get upon landing. The duration is listed in frames for karts/bikes. Generally, more flips mean longer airtime and more landing boost time. Note that you should not use the collision effect "trickable" with this KCL flag, otherwise the trick type will be semi random. Additionally, if used in course.kcl and casino_roulette is present, this surface will rotate around it counterclockwise.

Variant Effect Trick Boost (Karts) Trick Boost (Bikes)
0 Double flip trick 85 frames 95 frames
1 Single flip trick 70 frames 80 frames
2-7 Stunt trick, unused 40 frames 45 frames

Jump Pad (0x08)

Bounces the player into the air, and is trickable by default. The variant controls the characteristics of the bounce. Since there is no real pattern, a higher "stage" generally means longer air time and more distance.

Variant Effect
0 Stage 2, used in GBA Bowser Castle 3
1 Stage 3, used in SNES Ghost Valley 2
2 Stage 1, used in GBA Shy Guy Beach
3 Stage 4, used in Mushroom Gorge[1]
4 Stage 5, Bouncy mushroom[2]
5 Stage 4, used in Chain Chomp Wheel
6 Stage 2, used in DS Yoshi Falls and Funky Stadium
7 Stage 4, unused
  1. This flag causes the Off-Road Glitch.
  2. SFX always work on the kinoko_bend object, but requires slot 1.3 for the course model KCL.

Item Road (0x09)

A type of road that is solid for items only. Items that land on it will despawn after 3 seconds (180 frames). The purpose of the variant is unknown.

Variant Effect
0 Unknown
1 Unknown
2 Used on metal grates
3 Unknown. Used on wooden paths/grass/mushrooms
4 Unknown. Unused
5 Unknown. Used on grass/bushes
6-7 Unknown. Unused

Solid Fall (0x0A)

A solid surface that counts the player out of bounds. The variant controls the terrain type.

Variant Effect
0 Sand
1 Sand/Underwater
2 Unknown
3 Ice
4 Dirt
5 Grass
6 Wood
7 Dark sand with GFX

Moving Water (0x0B)

A type of road that moves the player along a route, used in Koopa Cape and DS Yoshi Falls. It is only active while inside an AREA type 0x3. The exact functionality depends on the variant. For more information, see: Moving Terrain

Variant Effect
0 Moving water that follows a route, pulling the player downwards.
1 Moving water that follows a route and strongly pulls the player downwards, making it hard to drive.
2 Moving water that follows a route from the start of the path to the end of it.

Uses 2 AREA settings:

  • Setting 1: Acceleration modifier.
  • Setting 2: Moving speed.[1]
3 Moving water that follows a route from the start of the path to the end of it and disables player's acceleration.

Uses 2 AREA settings:

  • Setting 1: Current player's speed modifier.
    eg. value of 100 will keep current player's speed. Values below 100 will slow down player until full stop.
  • Setting 2: Moving speed.[1]
4 Moving asphalt, unused. Functions the same as variant 0.
5 Moving asphalt, unused. Functions the same as variant 0.
6 Moving road, unused. Functions the same as variant 0.
7 Moving road, unused. Functions the same as variant 0.
  1. 1.0 1.1 Always overrides route's moving speed setting.

Route Settings:

Setting Description
1 Moving speed.
2 Value of 1 changes moving water direction 90 degrees to the right.
Value of 2 changes moving water direction 90 degrees to the left.

Wall (0x0C)

Default wall, solid for both players and items. The variant controls the sound played when colliding with it.

Variant Effect
0 Normal
1 Rock
2 Metal
3 Wood
4 Ice
5 Bush (with GFX)
6 Rope
7 Rubber

Invisible Wall (0x0D)

A type of wall that is solid for players only, and is typically invisible in-game.

Variant Effect
0 No spark and no character wall hit voice
1-2 Spark and character wall hit voice (unused)
3-7 Unknown. Same as 0? (unused)

Item Wall (0x0E)

A type of wall that is solid for items only. Items that land on it will despawn instantly. The purpose of the variant is unknown.

Variant Effect
0 Unknown
1 Unknown. Used on rock walls
2 Unknown. Used on metal walls
3 Unknown
4 Unknown. Unused
5 Unknown. Used on grass/bushes
6-7 Unknown. Unused

Wall 2 (0x0F)

Solid for players and items. The difference between this and Wall (0x0C) is unknown.

Variant Effect
0 Normal
1 Rock
2 Metal
3 Wood
4 Ice
5 Bush (no GFX, unused)
6 Rope
7 Rubber

Fall Boundary (0x10)

A non-solid barrier that counts the player out of bounds. The variant controls the animation and sounds to play when it is triggered. For variants 1-3, the BLIGHT index is instead used to reference a pocha object in the KMP, which is used to determine the height of the splash effect. The BLIGHT index should match Setting 1 of the corresponding pocha object.

Variant Effect
0 Air fall
1 Water
2 Lava
3 Icy water, (ice on respawn)[1]
4 Lava, no GFX
5 Burning air fall
6 Quicksand (used in object quicksand)[2]
7 Short fall
  1. Requires slot 6.1.
  2. In rare cases with complex KCL geometry, this variant can activate, but not cause the player to respawn, resulting in intangibility and no control of the character. If this occurs somewhere on your track, an additional fall boundary may be needed to "catch" the victim and make them respawn.

Cannon Trigger (0x11)

Used to implement cannons. Upon contact, the player will be launched to a destination cannon point. The variant determines the KMP index of the cannon point to launch to. Subsequently, a track cannot have more than 8 distinct cannons.

Variant Effect
0 To point 0
1 To point 1
2 To point 2
3 To point 3 (unused)
4 To point 4 (unused)
5 To point 5 (unused)
6 To point 6 (unused)
7 To point 7 (unused)

Force Recalculation (0x12)

A trigger that forces an enemy/item route recalculation when a player or CPU passes through it. This is typically used in areas where players or CPUs can fall to a different route. It is only active while inside an AREA type 0x4. Variants are never used and likely have no effect.

Variant Effect
0 Default
1-7 Unknown. Unused

Half-pipe Ramp (0x13)

A special type of ramp that functions like a half-pipe jump. Trickable by default. This type is best used in combination with Invisible Wall (0x0D), although this is not strictly necessary.

Variant Effect
0 Default
1 Applies a boost, used in Bowser's Castle
2-7 Unknown. Unused

Player-Only Wall (0x14)

Allows items to pass through it like Invisible Wall (0x0D), but produces sounds upon collision similar to Wall (0x0C). Used by Nintendo below open ledges to prevent players from hanging on to them.

Variant Effect
0 Normal (unused)
1 Rock (unused)
2 Metal (unused)
3 Wood
4 Ice (unused)
5 Bush (unused)
6 Rope (unused)
7 No SFX/GFX

Moving Road (0x15)

A type of road that moves players in a specified direction, used in Toad's Factory and Coconut Mall. Unlike moving water, moving road is not controlled by routes in the KMP, but rather by specific objects. For more information, see: Moving Terrain

Variant Effect
0 Moves west with BeltCrossing and escalator. The latter only works with escalator.kcl
1 Moves east with BeltCrossing and west with escalator. The latter only works with escalator.kcl
2 Moves east with BeltEasy
3 Moves west with BeltEasy
4 Rotates around BeltCurveA clockwise
5 Rotates around BeltCurveA counterclockwise
6-7 Unknown. Unused

Sticky Road (0x16) [ATTACH]

A type of road that attaches players to the road if they are within 200 units of the road with a correction of up to 200 units/frame. Moving water shares this code internally. The game logic does not care if player is also colliding with a different surface; as long as the player within 200 units of a surface with this attribute, the player's position will be corrected. This effect does not stack; layering on moving water will not make it more intense. The variant controls the terrain type.

Variant Effect
0 Wood.
1 Gravel, different impact SFX.
2 Carpet.
3 Dirt, no GFX.
4 Sand, different impact and drift SFX, no GFX.
5 Normal road, SFX on slot 4.4.
6 Normal road.
7 Mud with GFX.

Road 2 (0x17)

An alternative to Road (0x00) with different variants.

Variant Effect
0 Normal road, different sound
1 Carpet
2 Grass, GFX on 8.3
3 Normal road, used on green mushrooms
4 Grass
5 Glass road with SFX
6 Dirt (unused)
7 Normal road, SFX on slot 4.4

Sound Trigger (0x18)

A trigger that activates/deactivates sound effects or music channels when the player passes through it. The effects of each variant are different for every track slot and are described below.
Show text


Weak Wall (0x19)

Nintendo uses this type in Wario's Gold Mine and Rainbow Road. It acts as a wall that pushes players away when driving at low speed, but it can easily be trespassed when accelerating. They seem to be originally used below flat road to prevent players from hanging on the edges. Variants are never used and likely have no effect.

Variant Effect
0 Default
1-7 Unknown. Unused

Effect Trigger (0x1A)

A trigger that activates when the player passes through it; it can have several different functions depending on the variant.

Variant Effect
0 Change BLIGHT to specified index. Useful when a lighting change is needed in mid-air.
1 Change BLIGHT to specified index. (Different from 0?)
2 Trigger a water splash (pocha) without respawning the player.[1][2] The BLIGHT index references a pocha object in the KMP, which is used to determine the height of the splash effect. The BLIGHT index should match Setting 1 of the corresponding pocha object.
3 Activate starGate object. Used in tournaments only.
4 Half-pipe cancellation; forces the player out of half-pipe state.
5 Coin despawner; despawns any coins that touch it. Used in battle mode only.
6 Unknown. Used on top of the chimneys in Delfino Pier. Possibly related to truckChimSmkW?
7 Unknown. Unused
  1. Reusable only if a fall boundary is triggered.
  2. On slots T4.2 and B2.5, index 5 is hardcoded to spawn a pochaLeaf or pochaLeafY (pochaMori) respectively. In all other cases, a pocha is used, even if the linked object is of a different type.

Item State Modifier (0x1B)

Nintendo uses this type only in Toad's Factory. It stops stationary items once leaving the curved conveyor belts. Variants are never used and likely have no effect.

Variant Effect
0 Default
1-7 Unknown. Unused

Half-Pipe Invisible Wall (0x1C)

An invisible wall that is only solid for players in the air after a half-pipe jump, used in Bowser's Castle and Funky Stadium. Variants are never used and likely have no effect.

Variant Effect
0 Default
1-7 Unknown. Unused

Rotating Road (0x1D)

If casino_roulette is present, this road slowly rotates around it counterclockwise. Without casino_roulette, it acts like ordinary road. For more information, see: Moving Terrain

Variant Effect
0 Carpet, different impact SFX
1 Normal road, different sound, different impact SFX (unused)
2 Normal road
3 Glass road
4 Carpet
5 No sound, star crash impact SFX (requires starGate for SFX) (unused)
6 Sand (unused)
7 Dirt (unused)

Special Wall (0x1E)

Variants consist of wall types that have special functionality and/or are used in very specific situations.

Variant Effect
0 Cactus. Touching this will cause the player to spin out. Used in Dry Dry Ruins and Thwomp Desert.
1 No SFX/GFX. Used behind the lavafalls in Grumble Volcano.
2 Bouncy wall (unused). Driving into it at slow speed will cause the player to be pushed backwards.
3 No SFX/GFX. Used for the finish line banners on Wario's Gold Mine and Koopa Cape.
4 Rainbow Road railings. SFX only work on slot 4.4.
5 The sides and stalk of mushroom pads, used on Mushroom Gorge.
6 Metal SFX. Used for the statue in Luigi Circuit and the top of the underwater section in Koopa Cape.
7 The sides of the gates from competitions. Requires starGate object for SFX.

Invisible Wall 2 (0x1F)

Solid for players only. The difference between this and Invisible Wall (0x0D) is unknown.

Variant Effect
0 No SFX/GFX
1-7 Unknown. Same as 0? (unused)

Additional Info

Wiimm has made a statistical analysis about the usage of flags in all 32 tracks: kcl-types.txt


Type What is it? Speed factor[1] Handling factor[1]
0x00 Road 1.0 0.7
0x01 Slippery Road 1 1.0 0.050 – 0.105
0x02 Weak Off-road 0.550 – 0.909 0.080 – 0.157
0x03 Off-road 0.325 – 0.712 0.050 – 0.105
0x04 Heavy Off-road 0.185 – 0.422 0.050 – 0.105
0x05 Slippery Road 2 0.881 – 0.999 0.030 – 0.074
0x06 Boost Panel 1.0 0.7
0x07 Boost Ramp 1.0 0.7
0x08 Jump Pad 1.0 0.7
0x09 Item Road 1.0 0.7
0x0A Solid Fall 0.1 0.7
0x0B Moving Water 1.0 0.7
0x0C Wall 1.0 0.7
0x0D Invisible Wall 1.0 0.7
0x0E Item Wall 1.0 0.7
0x0F Wall 2 1.0 0.7
0x10 Fall Boundary 1.0 0.7
0x11 Cannon Activator 1.0 0.7
0x12 Force Recalculation 1.0 0.7
0x13 Half-pipe Ramp 1.0 0.7
0x14 Player-Only Wall 1.0 0.7
0x15 Moving Road 1.0 0.7
0x16 Sticky/Gravity Road 1.0 0.7
0x17 Road 2 1.0 0.7
0x18 Sound Trigger 1.0 0.7
0x19 Weak Wall 1.0 0.7
0x1A Effect Trigger 1.0 0.7
0x1B Item State Modifier 1.0 0.7
0x1C Half-pipe Invisible Wall 1.0 0.7
0x1D Rotating Road 1.0 0.7
0x1E Special Walls 1.0 0.7
0x1F Invisible Wall 2 1.0 0.7
[1] : Notes for Speed factor
  • Each vehicle and driver combination has its own basic speed. The Speed factor is always ≤1.0 and defines the relative KCL type dependent speed.
  • The values are calculated after analyzing different Mario Kart Wii files. The ranges depends on the possible driver and vehicle combinations.
  • The different basic speed of the vehicles (75.00 – 85.07) and the driver modifications of the basic speed (add 0 – 0.53) are not part of these speed factor calculations.
  • Some values are senseless (e.g. walls, fall down, effects), but the values are available in the Mario Kart Wii tables.