Skip to content

Mapping API

Jump to bottom
zer0.k edited this page Oct 27, 2024 · 17 revisions

The Mapping API was designed with using the Mapping API FGD in mind. Some features are available without the FGD, like a basic start and end zone (can only have 1 course without the FGD), course start position, jumpstat area location,

Features that don't use the Mapping API FGD:

Timer zones

  • Time starts when the player leaves the zone.
  • Time ends when the player enters the zone.

To implement timer zones, the following are required:

  • Create a trigger_multiple entity.
  • Name the entity as either:
    • timer_startzone for the start of the course.
    • timer_endzone for the end of the course.

Things to keep in mind:

  • When using the Mapping API FGD, this method does not work.
  • Only one course can be created without the Mapping API FGD.
  • Entering a start timer zone will stop the player's current timer.
  • Start zones can be left midair as long as a perfect bunnyhop is not hit.
  • I recommend that you use triggers that are 4 units thick and on the ground for more consistent timing.

Course starts

Course starts mark where players will be teleported when using the !restart/!r commands. The priority is ordered as below:

  • !r <course name> command to teleport to the mapper defined start position of the course.
  • !r without arguments will prefer your custom start position (!ssp), or the mapper defined start position of the current active course, or the mapper defined start position of the only course of the map (if there is only one course).

To implement course starts, the following are required:

  • Create an info_teleport_destination entity.
  • Set the entity's Name (aka targetname) to timer_start.
  • Set Pitch Yaw Roll (Y Z X) to the angles you wish to teleport the player into.

For mappers using the FGD:

You should create a course start for every course you've made.

  • Put the targetname of your course descriptor entity in KZ | Course Descriptor.

Jumpstat Area Location

There can only be one of these in a map. This works with or without the FGD.

To implement the jumpstat area location, the following are required:

  • Create an info_teleport_destination entity.
  • Set the entity's Name (aka targetname) to timer_jumpstat_area.
  • Set Pitch Yaw Roll (Y Z X) to the angles you wish to teleport the player into.

Features using the Mapping API FGD

For the following features you will need the Mapping API FGD (csgo_internal.fgd) file.

After opening the above link for the .fgd, right click on the page and click Save As and save it to somewhere safe. Make sure to change the file extension to .fgd if it's .fgd.txt or something else, otherwise hammer won't be able to open it.

Put csgo_internal.fgd in the /steamapps/common/Counter-Strike Global Offensive/game/csgo_core/ folder.

NOTE: If you previously weren't using the Mapping API FGD, you will have to remake your course's start and end zone. See below for how to make start and end zone triggers with the FGD.

Updating

When the fgd changes with a Mapping API update you'll need to repeat the steps above. When that's done, check what the new Mapping API version is: it's in the first line in the kz_mapping_api.fgd file, something like this:

// KZ Mapping API Version 2

After that you'll have to change the KZ | Mapping API Version parameter in Map Properties on every map you've used it on to the new version!

Course descriptors

In CS2 KZ there is no "main" course or track on a map. A map can have multiple equally "important" courses. A course descriptor defines attributes of a course, currently only the name.

TODO: Implement course-wide disable checkpoints (doesn't work yet) + add more features (laps maybe :O ).

To make a course descriptor:

  1. Create an info_target_server_only entity.
  2. Enable the KZ | Is Course Descriptor checkbox.
  3. Give the entity a Name aka targetname, which is how other entities will find it, for example binguscourse.
  4. Give the course a nice Course Name under the KZ | Course Descriptor tree, for example Best Bingus Bever. This will be shown in-game to players, so pick a good one! If your map has only one course you should name it Main, people will usually refer to the only course with the map's name.
  5. If you're creating multiple courses, make sure the Course Numbers are unique
  6. Enable or disable any attributes you want.
  7. Done!

image

Next you will need to make start and end zones.

Start and end zones

  • Time starts when the player leaves the start zone.
  • Time ends when the player enters the end zone and has touched every stage and checkpoint zone assigned to the course (we'll get to that).

First you need to create a trigger_multiple entity.

  • For a start zone - select Start Zone from the KZ | Trigger Type dropdown.
  • For an end zone - select End Zone from the KZ | Trigger Type dropdown.
  • Next, expand the KZ | Zone tree and put the targetname of your course descriptor entity in Course Descriptor, for example binguscourse.
  • You're done!

image

Things to keep in mind:

  • UNFINISHED: Timer zones can act as Course starts

    • Entering a start timer zone will stop the player's current timer.
    • Entering a start timer zone will set the player's start position to the zone.

  • Start zones can be left midair as long as a perfect bunnyhop is not hit.

  • Multiple start timer zones should not be possible to be activated at once to avoid usability issues.

Stage, split and checkpoint zones

  • Split zones are the simplest ones. The player doesn't need to touch any of these zones for them to finish the map, nor do they have to touch them in numerical order, split zones are purely for comparing times from run to run as the name implies.
  • Checkpoint zones are the same as split zones, except the player has to touch every single checkpoint zone that's assigned to the course. The order the player has to touch checkpoint zones doesn't matter.
  • Stage zones are the same as checkpoint zones, except the player has to touch every single stage zone in order from 1 to however many stage zones there are.

Once again, first you need to create a trigger_multiple entity.

  • For a split zone - select Split Zone from the KZ | Trigger Type dropdown.
  • For a checkpoint zone - select Checkpoint Zone from the KZ | Trigger Type dropdown.
  • For a stage zone - select Stage Zone from the KZ | Trigger Type dropdown.
  • Like with start and end zones: next, expand the KZ | Zone tree and put the targetname of your course descriptor entity in Course Descriptor, for example binguscourse.
  • Then, if this isn't the first split/checkpoint/stage zone you're making - increment the Split/Checkpoint/Stage Number by 1.
  • IMPORTANT: Split/Stage/Checkpoint Numbers must be consecutive and start from 1! For example: if you have 4 stage zones and 3 checkpoint zones on your course, then all 4 stage zones' Stage Numbers must be 1, 2, 3 and 4. Same with the 3 checkpoint zones: Checkpoint Number on all 3 checkpoint zones, must be 1, 2 and 3, not 1, 2, 4 or 1, 4, 10! The same applies to split zones.

Teleport Triggers

  • Create a trigger_multiple entity.
  • Select General Teleport from the KZ | Trigger Type dropdown.
  • Set Destination in the KZ | Teleport section to the entity you want to teleport the player to.
  • Optionally change Delay - This makes it so the player gets teleported to the destination only after they've been in the trigger this long.
  • Optionally change Use Destination Angles from the default Yes if you don't want players to get their angles changed to the destination entity's.
  • Optionally change Reset Speed from the default Yes if you want players to keep their speed when you get teleported.
  • Optionally change Reorient Player - When teleported, it rotates the player's velocity and yaw by the teleport destination's yaw angle. The pitch angle will remain unchanged. This overrides the value of 'Use Destination Angles'.
  • Optionally change Relative To Trigger Origin - Gets the offset of the player to this trigger, then teleports the player to the destination with that offset added. If Reorient Player is enabled, then the offset is rotated by the destination entity's yaw. Changing the destination yaw will cause visible lag when moving your mouse.

All the parameters are also well explained inside hammer.

image

Bhop triggers

Bhop triggers share a similar setup with teleport triggers just above, with a few extra steps.

To implement bhop triggers, the following are required:

  • Change the KZ | Trigger Type parameter to one of the following:
    • Multi Bhop
    • Single Bhop
    • Sequential Bhop
  • Change KZ | Teleport | Delay - IMPORTANT: The teleport delay for bhops starts when you touch the ground inside the trigger, instead of when you touch the trigger. 0.1 is a very common value. The minimum delay is 0.1 for bhop triggers. Read more below:

Important information

  • The reason that the minimum delay is so high is that a very small delay will greatly increase the chances of getting a false bhop hack ban.
  • For single bhops, you get teleported if you bhop on the same single bhop trigger twice.
  • For sequential bhops, you get teleported if you bhop on any of the sequential bhop triggers that you've already bhopped on.
  • Single and sequential bhops get automatically reset if you touch the ground or a ladder without touching any single/sequential bhop triggers (touching multibhop triggers will automatically reset as well).
  • Single bhops also get reset when you touch a bhop trigger that isn't a single bhop.

If you need to reset bhop triggers manually, you can use the Single bhop reset trigger type.

IMPORTANT: You will almost never need to use Single bhop reset because resetting happens automatically.

Other triggers

KZ | Trigger Type: Reset Checkpoints

Resets the player's checkpoints when they enter this trigger.

Note: This does not work when the timer is not running.

KZ | Trigger Type: Modifiers

Activates multiple different modifiers for the player.

  • Disable Pausing: Disables pausing while inside this trigger.
  • Disable Checkpoints: Disables creating checkpoints inside this trigger.
  • Disable Teleports: Disables teleporting to checkpoints inside this trigger.
  • Disable Jumpstats: Disables registering jumpstats inside this trigger.
  • Enable Slide: Makes every surface surfable, even floors.
  • Player Gravity: Change the player's gravity while inside the trigger. Can be negative (TODO: check what happens if it's 0). Multiple gravity modifier triggers can be inside each other, the one most recently entered takes priority.

KZ | Trigger Type: Anti Bhop

  • Optionally change Time in the KZ | Anti Bhop section - A delay of 0 means that jumping is always disabled in this trigger. The delay timer starts when you're on the ground inside the trigger.

  • Disables jumping while on the ground and in the trigger.

  • WARNING! This trigger can be bypassed by a jumpbug and lag. You have to make this trigger at least 16 units thick to prevent that.

  • WARNING! It can also be bypassed by jumping into a teleport trigger and bhopping when you get TP'd (also called triggerhopping). This happens if the teleport destination is inside an antibhop trigger and the destination is 2 units or less above the ground. To fix this, make sure that the teleport destination is 4 units or more above the ground!

image

Clone this wiki locally