diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 55e05d5..cd3fd11 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -15,23 +15,70 @@ export default defineConfig({ metaChunk: true, themeConfig: { - nav: nav(), + nav: [ + { + text: "Stats", + link: "https://cs2kz.org", + }, + { + text: "Dashboard", + link: "https://dashboard.cs2kz.org", + }, + { + text: "API", + link: "/api/", + }, + ], + sidebar: { - "/": sidebar(), - "/api/": [ + "/": [ + { + items: [ + { text: "Modes", link: "/modes" }, + { text: "Styles", link: "/styles" }, + { text: "Mapping", link: "/mapping" }, + { text: "Servers", link: "/servers" }, + { text: "Ranking", link: "/ranking" }, + ], + }, { - text: "Introduction", - link: "/api/", + text: "Mapping", + items: [ + { text: "API", link: "/mapping/api" }, + { text: "Approval Process", link: "/mapping/approval" }, + { text: "Discord", link: "https://discord.gg/R593VhE" }, + ], }, { - text: "Problems", - link: "/api/problems", + text: "Servers", + items: [ + { text: "Approval Process", link: "/servers/approval" }, + { text: "LAN Setup", link: "/servers/lan" }, + ], }, { - text: "Explorer", - link: "/api/explorer", + text: "Resources", + items: [ + { text: "Differences from GOKZ", link: "/gokz" }, + { text: "GlobalAPI Documentation", link: "/api" }, + ], }, ], + "/mapping/": [ + { text: "Terminology", link: "/mapping/" }, + { text: "API", link: "/mapping/api" }, + { text: "Approval Process", link: "/mapping/approval" }, + { text: "Discord", link: "https://discord.gg/R593VhE" }, + ], + "/servers/": [ + { text: "Approval Process", link: "/servers/approval" }, + { text: "LAN Setup", link: "/servers/lan" }, + ], + "/api/": [ + { text: "Introduction", link: "/api/" }, + { text: "Explorer", link: "/api/explorer" }, + { text: "Problems", link: "/api/problems" }, + ], }, socialLinks: [ @@ -45,46 +92,3 @@ export default defineConfig({ }, }, }); - -function nav(): DefaultTheme.NavItem[] { - return [ - { - text: "API", - link: "/api/", - }, - { - text: "Dashboard", - link: "https://dashboard.cs2kz.org", - }, - { - text: "Stats", - link: "https://cs2kz.org", - }, - ]; -}; - -function sidebar(): DefaultTheme.SidebarItem[] { - return [ - { - text: "Systems", - items: [ - { text: "Modes", link: "/systems/modes" }, - { text: "Maps", link: "/systems/maps" }, - { text: "Points", link: "/systems/points" }, - { text: "Styles", link: "/systems/styles" }, - ], - }, - { - text: "Servers", - items: [ - { text: "LAN Server Setup", link: "/servers/lan" }, - ], - }, - { - text: "Creator resources", - items: [ - { text: "Map Approval Process", link: "/mapping/approval" }, - ], - }, - ]; -}; diff --git a/docs/gokz/index.md b/docs/gokz/index.md new file mode 100644 index 0000000..6205e23 --- /dev/null +++ b/docs/gokz/index.md @@ -0,0 +1,17 @@ +# Differences from GOKZ + +As CS2 has replaced CS:GO, CS2KZ is now supposed to (more or less) replace +[GOKZ](https://github.com/KZGlobalTeam/gokz). + +While CS:GO, and therefore GOKZ, is still playable, actually playing requires +work-arounds and it is unclear for how long this house of cards will hold up +going into the future. The people working on CS2KZ have spent a considerable +amount of time in the CS:GO KZ community both as players and developers, and as +such we are taking previous experiences into account when it comes to working +on CS2KZ. What it does **not** mean is that we intend to replicate GOKZ 1:1 in +CS2. A lot of things are *different*, and whether you like that is up to you. + +Below you can find a list of important differences that you might want to know +about if you are a CS:GO KZ player discovering CS2KZ: + +- TODO diff --git a/docs/index.md b/docs/index.md index daeaac9..dfb1cc8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,22 +1,49 @@ --- title: Home -description: Home page --- # Welcome to CS2KZ -CS2KZ is a skill-based mod for Counter-Strike 2 where players complete challenging obstacle courses that test their precision, speed, and movement skills. Compete against yourself or others, improve your abilities, and climb the ranks as you master each course. +CS2KZ is a skill-based mod for Counter-Strike 2 where players complete +challenging obstacle courses that test their precision, speed, and movement +skills. Compete against yourself or others, improve your abilities, and climb +the ranks as you master each course. -## Systems +## 2 Modes -- [Modes](/systems/modes) -- [Maps](/systems/maps) -- [Points](/systems/points) -- [Styles](/systems/styles) +CS2KZ features two different game modes: +[Vanilla](/modes#vanilla) and [Classic](/modes#classic) -## Servers +[Vanilla](/modes#vanilla) resembles the default movement experience you would +also get in regular matchmaking, while [Classic](/modes#classic) is closer to +what most people would expect when they think of KZ. -- [LAN Server Setup](/servers/lan) +## Styles + +Different [styles](/styles) allow you to customize gameplay independent of +modes. + +## The Global Map Pool + +An [official list of maps](https://cs2kz.org/maps) for you to play and +contribute to! + +See [the guidelines](/mapping/approval) for how to submit your own maps. + +## Global Servers -## Creator resources +An [offical list of servers](https://cs2kz.org/servers) for you to play on! +See [the guidelines](/servers/approval) for how to get your own server. + +## Player Ratings + +Competing will award you [points](ranking#points) on each leaderboard and +contributes to your overall [player rating](ranking#rating). + +## Resources + +- [LAN Server Setup](/servers/lan) +- [Server Approval Process](/servers/approval) - [Map Approval Process](/mapping/approval) +- [GlobalAPI Documentation](/api) +- [Differences from GOKZ](/gokz) diff --git a/docs/mapping/api.md b/docs/mapping/api.md new file mode 100644 index 0000000..b65e67b --- /dev/null +++ b/docs/mapping/api.md @@ -0,0 +1,281 @@ +# Mapping API + +The Mapping API was designed with using the [Mapping API FGD][fgd] in +mind. Some features are available without the FGD, like a basic start and end +zone (only 1 course without the FGD), course start position, and jumpstat area +location. + +## Features available without the FGD + +### Timer Zones + +The timer starts when the player leaves the start zone and ends when the player +enters the end zone. You can create these zones like so: + +1. Create a [`trigger_multiple`](https://developer.valvesoftware.com/wiki/Trigger_multiple) entity. +2. Set the start zone entity's `Name` (targetname) to `timer_startzone`. +3. Set the end zone entity's `Name` (targetname) to `timer_endzone`. + +It is recommended that you use triggers that are 4 units thick and on the +ground for more consistent timing. + +Some things to keep in mind: + +- When using the FGD this method will not work! +- You can only create this one course without the FGD. +- Start zones can be left mid-air as long as a perfect bunnyhop is not hit. + +### Course Starts + +Course starts mark where players will be teleported when using the `!restart` +/ `!r` commands. The priority is ordered as below: + +- `!r ` - teleport to the mapper defined start position of the + course. +- `!r` 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: + +1. Create an [`info_teleport_destination`](https://developer.valvesoftware.com/wiki/Info_teleport_destination) entity. +2. Set the entity's `Name` (targetname) to `timer_start`. +3. 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: + +1. Create an [`info_teleport_destination`](https://developer.valvesoftware.com/wiki/Info_teleport_destination) entity. +2. Set the entity's `Name` (targetname) to `timer_jumpstat_area`. +3. Set Pitch Yaw Roll (Y Z X) to the angles you wish to teleport the player + into. + +## Features available only with the FGD + +For the following features you will need the +[Mapping API FGD (`csgo_internal.fgd`) file][fgd]. + +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 CS2KZ [there is no "main" course or track on a map](/mapping#courses). A map +can have multiple equally "important" courses. A **course descriptor** defines +attributes of a course, currently only the name. + +To make a course descriptor: + +1. Create an `info_target_server_only` entity. +2. Enable the `KZ | Is Course Descriptor` checkbox. +3. Set the entity's `Name` (targetname) to something other entities can find + (e.g. `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. + +![course_descriptor](/public/images/course-descriptor.png) + +### Start and End zones + +The timer will start when the player leaves the start zone and end when the +player enters the end zone (and has touched every "stage" and "checkpoint" zone +assigned to the course). + +1. Create a [`trigger_multiple`](https://developer.valvesoftware.com/wiki/Trigger_multiple) entity. +2. For start zones, select `Start Zone` from the `KZ | Trigger Type` dropdown. +3. For end zones, select `End Zone` from the `KZ | Trigger Type` dropdown. +4. Expand the `KZ | Zone` tree and put the targetname of your course + descriptor entity in `Course Descriptor` (e.g. `binguscourse`). + +![zones](/public/images/zones.png) + +Some things to keep in mind: + +>[!WARNING] +> 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. + +### Split / Checkpoint / Stage zones + +#### Split zones + +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 + +These 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 + +These are the same as checkpoint zones, except the player has to touch every +single stage zone in order. + +#### Creating the zones + +1. Create a [`trigger_multiple`](https://developer.valvesoftware.com/wiki/Trigger_multiple) entity. +2. Select `Split Zone` / `Checkpoint Zone` / `Stage Zone` from the + `KZ | Trigger Type` dropdown. +3. Expand the `KZ | Zone` tree and put the targetname of your course + descriptor entity in `Course Descriptor` (e.g. `binguscourse`). +4. Then, if this isn't the first split / checkpoint / stage zone you're making, + increment the `Split/Checkpoint/Stage Number` by 1. + +>[!INFO] +> `Split/Stage/Checkpoint Number`s 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 Number`s 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 + +1. Create a [`trigger_multiple`](https://developer.valvesoftware.com/wiki/Trigger_multiple) entity. +2. Select `General Teleport` from the `KZ | Trigger Type` dropdown. +3. Set `Destination` in the `KZ | Teleport` section to the entity you want to + teleport the player to. +4. Optionally change `Delay`. This makes it so the player gets teleported to + the destination only after they've been in the trigger this long. +5. 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. +6. Optionally change `Reset Speed` from the default `Yes` if you want players + to keep their speed when you get teleported. +7. 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'. +8. 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. + +![teleport-triggers](/public/images/teleport-triggers.png) + +### Bhop triggers + +These share a similar setup with teleport triggers just above, with a few extra +steps. To implement bhop triggers, the following are required: + +1. Change the `KZ | Trigger Type` parameter to one of the following: + - `Multi Bhop` + - `Single Bhop` + - `Sequential Bhop` +2. Change `KZ | Teleport | Delay`. + +>[!WARNING] +> 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. + +>[!INFO] +> 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. + +>[!INFO] +> 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 teleported (also called "trigger hopping"). 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! + +![anti-bhop-trigger](/public/images/anti-bhop-trigger.png) + +[fgd]: https://github.com/KZGlobalTeam/cs2kz-metamod/blob/master/mapping_api/game/csgo_core/csgo_internal.fgd diff --git a/docs/mapping/approval.md b/docs/mapping/approval.md index 7b3f66b..51cf271 100644 --- a/docs/mapping/approval.md +++ b/docs/mapping/approval.md @@ -1,20 +1,128 @@ -# Map approval process +# Map Approval -The map approval process structure will closely resemble GOKZ, with a few key details still to be finalized: +If you want your own map to become part of +[the official map pool](https://cs2kz.org/maps), you need +[permission](#acquiring-permission) to do so, +[submit it for approval](#creating-a-map), and make sure it follows +[the rules](#rules). If you plan on porting a map, see -## 1. Submission +## Acquiring Permission -- **Uploading:** Mappers submit their maps via the [CS2 Steam Workshop](https://steamcommunity.com/app/730/workshop). -- **Course Requirements:** Each map must contain at least one course with a filter of tier 8 or lower, to be considered for ranking. +>[!NOTE] +> This step only has to be performed *once*; not for every map. -## 2. Review +Visit [the forum](https://forum.cs2kz.org) and create a new post in the "Map +Approval" category with the "Approval Permission" tag. The post should include +a link to your Steam profile and a short introduction about who you are, your +connection to KZ, and whether you have any existing maps (ideally on your +workshop). -- **Approval Team:** A group of experienced KZ community members will review the map. They are responsible for evaluating the course -difficulty, ranking potential, and adherence to community standards. -- **Objective Evaluation:** Maps will be assessed on objective metrics such as difficulty, design, and gameplay quality. -- **Subjective Evaluation:** The team will also consider whether the course is "reasonable to compete on," allowing for some flexibility and creative expression in map design. +>[!NOTE] +> This post will be private between you and the map approval team. -## 3. Publication +Once you have been accepted, you can log into +[the dashboard](https://dashboard.cs2kz.org) and submit maps. Please keep in +mind that this is a **privilege** and that if you break any rules or otherwise +abuse your power, it will be taken away from you. -- Once approved, the map is added to the global KZ pool. It will then be available for players to compete on in ranked or unranked settings, - depending on the course's filter. +## Creating a Map + +Once you have created a map (in Hammer), you may also create it on +[the dashboard](https://dashboard.cs2kz.org). Maps will transition between +[different states](#map-states) over time, and newly created maps start out in +the "WIP" state. + +### Map States + +Newly submitted maps will start out in the "WIP" state. In this state you can +gather player feedback, for example by making a forum post and/or joining +[the Mapping Discord](https://discord.gg/R593VhE). While players _can_ submit +records during this phase, leaderboards will be reset whenever the map is +updated. + +>[!NOTE] +> In order to update a map you have to update it both on the workshop and the +> dashboard. + +If a map remains without updates for ~2 months it will transition into the +"Graveyard" state where it will remain until you update it again. + +Once you are happy with your creation you may submit it for approval. You do +this by updating its state to "Submitted" on the dashboard and then creating +another forum post in the "Map Approval" category with the "Submission" tag. + +>[!NOTE] +> This post will be publicly visible, but only you and the map approval team +> will be able to comment on it. + +>[!WARNING] +> Once your map is in the "Submitted" state, you will no longer be able to +> update it. + +If your map is accepted it will transition into the "Approved" state where it +will remain frozen. + +If your map is rejected it will transition back into the "WIP" state and you +can choose to either continue your work on it and re-submit for approval, or +leave it as is. If you decide that your map is complete, and you don't want it +to disappear into the sea of "Graveyard" maps, you can update its state on the +dashboard to "Complete". This will, just like "Approved", freeze your map from +further updates, but it will be more visible to players searching for new maps +to play. + +## Rules + +Rules that apply to every map: + +- At least one course must be present on the map. +- At least one filter must have the goal of being ranked. +- A display of effort and quality + - fully textured + - good lighting and visibility + - performance optimizations + - reasonable file size +- A "jumpstats" area featuring LJ blocks from 210-280, in increments of 10 + - There must be a trigger that allows for teleporting to this area via + `!lj`. +- Discriminatory, obscene, or sexually explicit content are **strictly + prohibited**. +- Any course with filters intended to be ranked must be completed at least once + on said filter while the map is in the WIP state. + +Rules that apply to courses with ranked filters specifically: + +- Avoid using clips, non-solid blocks, triggers, or moving blocks in + unintuitive or exploitable ways. +- Avoid inconsistent mechanics like moving platforms or time-based events. +- Avoid "pre-run setups" like breakable objects or doors which do not open + automatically. +- There must be no way to skip from the start of a course straight to the end, + resulting in ridiculously short times. + +In addition, the *names* of your maps must start with `kz_`, can only contain +ASCII alphanumeric characters (and underscores), and must not exceed 27 +characters in length (including the `kz_` prefix). It should be easily +distinguishable from other maps. + +>[!NOTE] +> The 27 character limit exists because of how command parsing is implemented +> in the game engine. Any command must fit into 63 characters (the buffer is 64 +> characters, but the last character is a `\0` terminator). The two available +> commands to change map are `map` and `changelevel`. The argument to these +> commands is the path to the map file, which usually looks like this: +> `workshop/.bsp`, with `` being an unsigned 32-bit integer. Therefore, +> the longest possible command, without an actual map name, is `changelevel +> workshop/4294967295/.bsp`. This is 36 characters long, leaving 27 characters +> for the map name, to reach the limit of 63. + +Course names can only contain ASCII characters (including spaces, punctuation, +quotes, etc.) and must be unique across all courses **on your map**. + +## Porting + +Map "porting" refers to the process of taking an existing map, for example from +CS:GO, and updating it to CS2. If you plan on porting a map and submitting it, +and you are not the original mapper, you must get permission from the original +mapper to port their map. If the original mapper has been inactive for 2 years +or longer, and you have made honest (but unsuccessful) attempts to contact +them, you may submit your port anyway. diff --git a/docs/mapping/index.md b/docs/mapping/index.md new file mode 100644 index 0000000..b06e364 --- /dev/null +++ b/docs/mapping/index.md @@ -0,0 +1,50 @@ +# Mapping + +A KZ "map" refers to a CS2 map that contains one or more ["courses"](#courses). +Every map is uploaded to the +[Steam Workshop](https://steamcommunity.com/app/730/workshop) and registered to +the [GlobalAPI](/api/explorer#tag/maps). You can find the official map list on +[our website](https://cs2kz.org/maps). + +## Courses + +A "course" is a section of the map that has a start and end zone. For each +course there are two ["filters"](#course-filters) that determine its +difficulty. + +### Course Filters + +A "course filter" is a set of attributes that are applied to courses on +a per-mode basis. More specifically: + +- a [Tier](#tiers) +- whether it is ranked + - "unranked" means the filter is not ranked and never will be (e.g. because + the mapper requested so). + - "pending" means the filter is not currently ranked, for example because it + was determined too difficult for the given mode. It may however *become* + ranked later if a player manages to beat it. + - "ranked" means the filter is ranked and will award points for competing. + +### Tiers + +We judge the difficulty of a course in a given mode by placing it into one of +ten different **tiers**: + +1. "Very Easy" - an average CS2 player who has never touched KZ before is able + to complete the course +2. "Easy" - a new KZ player who has just learned movement basics like air + strafing and bunny hopping is able to complete the course +3. "Medium" - more difficult than T2 but without introducing new concepts +4. "Advanced" - more advanced concepts like surf and ladders but still on + a basic level +5. "Hard" - even more advanced concepts and more niche mechanics like box-tech, + tightly timed sections, wall strafing, prekeep, etc. +6. "Very Hard" - more difficult than T5 but without introducing new concepts +7. "Extreme" - features the most advanced mechanics +8. "Death" - T7 but harder +9. "Unfeasible" - special tier for courses that are *technically* possible, but + unlikely to be done by humans without TAS (Tool-Assisted Speedrun) tools +10. "Impossible" - special tier for courses that are *literally* impossible; + even with perfect inputs (generally reserved for VNL filters on courses + intended for CKZ) diff --git a/docs/modes/index.md b/docs/modes/index.md new file mode 100644 index 0000000..60aab20 --- /dev/null +++ b/docs/modes/index.md @@ -0,0 +1,84 @@ +# CS2KZ Modes + +CS2KZ features two *official* modes (you can make your own!). You can switch +your mode using the `!vnl` and `!ckz` commands. + +## Vanilla + +The "Vanilla" (or "VNL") mode is supposed to resemble the default CS2 gameplay, +as you would experience it in matchmaking. This means you can play VNL to +practice your movement on the side, even if you're not mainly a KZ player. Any +oddities or inconsistencies with this mode that are also found in the regular +game will **not** be "fixed" or removed; the intention is to be as close as +possible to the real™️ CS2 experience. + +## Classic + +The "Classic" (or "CKZ") mode is supposed to have heavily modified gameplay, +which means higher air acceleration, consistent bunny hopping, pre-strafing, +and more. If you've played a previous iteration of KZ, this is probably the +mode you want to play! + +A list of detailed changes can be found below: + +- Player movement is always processed at least twice per tick. +- View angles are interpolated to emulate 128 tick movement. +- Inputs are semi-desubticked server-side to the closest half tick for + increased consistency and synergy with the emulated 128 tick movement. +- Player eye level is consistent on slopes so players can better estimate block + heights. +- Default player running speed is `250` regardless of weapons. +- Ground acceleration (`sv_accelerate`) is increased to `6.5`. +- Acceleration speed does not depend on weapon speed. +- Air acceleration (`sv_airaccelerate`) is increased to `100`. +- Player jumps ever so slightly higher for more consistency on `57`/`66` unit + blocks (`+0.0025` height). +- Jump height quantization is disabled (Z coordinates and velocity will no + longer only be in intervals of `0.03125`). +- Ladder movement at view angles near perpendicular to the ladder will no + longer have clamped speed (no more 30 pre LAJs). +- Ladder movement speed is increased by ~28.2% (`sv_ladder_scale_speed 1`) +- Removed stamina system, player will not have reduced acceleration/movement + speed/jump height from jumping or landing. +- Penalty on repeated ducking is removed. +- **Rampbugfix**: Player will be pushed out of the collision spot to avoid + rampbugs if they collide with two surfaces at the same time. +- **Slopefix**: Landing on a downward slope will always give speed to the + player. +- **New prestrafe mechanics**: + - Accelerating in a different direction compared to the current movement + speed will increase player's speed cap, up to `276`. This means running + slightly into a wall will make the player run faster, similar to CSS or + CS 1.6 prestrafe mechanics. + - The difference in acceleration and velocity direction is computed as an + average over `0.02` seconds. + - The bigger the angle difference, the faster the gain speed will be. + - The maximum gain is achieved by keeping acceleration `16` or more degrees + away from the current velocity's direction. + - The minimum gain starts at `7` degrees. + - The maximum gain can be achived in `0.55` seconds. + - Prestrafe speed modifier depends on the player's current speed. + - Losing all speed on the ground means losing all prestrafe gain. + - Prestrafe speed modifier will start decreasing at `3x` the maximum gain + speed if the player stops prestrafing for over `0.2` seconds. + - However, there is a `0.25` second grace period after landing where + prestrafe gain will not be affected. This helps with prekeeping after + landing. + - Player must not be running on the ground if they want to preserve + prestrafe gain while changing direction. For example, player can + prestrafe to the right, then jump. After landing, the player can either + perform a left or right prestrafe while still preserving the gain. + - Prestrafe speed modifier persists in the air and will not decay, however + airstrafing will not benefit from the increased maximum speed (this is + relevant in high speed scenarios). + - Water movement speed is not increased by prestrafe. +- **Bunnyhop related changes**: + - The limit on scroll speed is lifted. + - Jump height is always the same as a normal jump. + - The window for a perfect bunnyhop window is increased to `0.02` seconds + (~2.5 ticks for 128 tick) instead of 0 to 1 tick (with subtick). + - The prespeed formula is + `MAX(250 + prestrafeGain, MIN(speed, (51.5 timeOnGround * 75) log(speed) - 13.4506445844))`. + In short, the bhop prespeed will be linear until the landing speed is + greater than the ground speed, after which the speed gain is + reduced. Typical bhops will have `286-296` prespeed. diff --git a/docs/public/images/anti-bhop-trigger.png b/docs/public/images/anti-bhop-trigger.png new file mode 100644 index 0000000..4e00894 Binary files /dev/null and b/docs/public/images/anti-bhop-trigger.png differ diff --git a/docs/public/images/course-descriptor.png b/docs/public/images/course-descriptor.png new file mode 100644 index 0000000..58db84c Binary files /dev/null and b/docs/public/images/course-descriptor.png differ diff --git a/docs/public/images/teleport-triggers.png b/docs/public/images/teleport-triggers.png new file mode 100644 index 0000000..1cc89f2 Binary files /dev/null and b/docs/public/images/teleport-triggers.png differ diff --git a/docs/public/images/zones.png b/docs/public/images/zones.png new file mode 100644 index 0000000..4b328b8 Binary files /dev/null and b/docs/public/images/zones.png differ diff --git a/docs/ranking/index.md b/docs/ranking/index.md new file mode 100644 index 0000000..bfbc3ab --- /dev/null +++ b/docs/ranking/index.md @@ -0,0 +1,43 @@ +# Ranking + +You can compare yourself to other players on two scales: per leaderboard and +overall + +Within each leaderboard every record is awarded an amount of [points](#points). +All points you gain from all ranked leaderboards will culminate in your [player +rating](#rating). + +## Points + +Every record on a ranked filter is awarded a value between `0` and `10,000`. +The fastest record will always be worth `10,000` points. Depending on the tier +of the filter, every record will also have a minimum amount of points. + +| Tier | Minimum Points (NUB) | Minimum Points (PRO) | +|------|----------------------|----------------------| +| 1 | 0 | 1,000 | +| 2 | 500 | 1,450 | +| 3 | 2,000 | 2,800 | +| 4 | 3,500 | 4,150 | +| 5 | 5,000 | 5,500 | +| 6 | 6,500 | 6,850 | +| 7 | 8,000 | 8,200 | +| 8 | 9,500 | 9,550 | + +The final value depends on how well you do compared to everyone else. + +## Rating + +All points you achieve on ranked filters are sorted and summed up with +a modifier applied to each value. + +The following python code illustrates the algorithm: + +```python +# `records` are sorted by points in descending order +def calculate_rating(records): + rating = 0 + for n, record in enumerate(records): + rating += record["points"] * (0.975 ** n) + return rating +``` diff --git a/docs/servers/approval.md b/docs/servers/approval.md new file mode 100644 index 0000000..adad4ed --- /dev/null +++ b/docs/servers/approval.md @@ -0,0 +1,38 @@ +# Server Approval + +You can create new servers on [the dashboard](https://dashboard.cs2kz.org). +Each user has a "server budget", or in other words: an amount of servers they +can create. + +Everyone starts out with a budget of 0, and the budget is managed +manually. This may change in the future, but for now, you have to explicitly +ask either on [the forum](https://forum.cs2kz.org) or +[our Discord server](https://discord.gg/csgokz) if you want your own CS2KZ +server. + +Once you have created a server, it will be assigned its own API Key. This key +can be placed into your server's configuration file to active the connection to +the GlobalAPI. + +## Rules + +If you are a server owner, there are certain rules you will have to follow. If +you fail to do so, servers may be taken away from you, and we will be more +critical when it comes to increasing your server budget. + +- Your server must run + [an official release](https://github.com/KZGlobalTeam/cs2kz-metamod/releases) + of [`cs2kz-metamod`](https://github.com/KZGlobalTeam/cs2kz-metamod). +- Your server must **not** run *any other* plugins that modify movement in + *any* way. +- You must **not** use your server's API Key for anything but that server. This + includes but is not limited to: + - using the key for multiple servers + - using the key for authenticating with the API manually + - sharing the key with someone else +- Your server must have consistent uptime. If your server is offline too much, + its API Key will be taken away. +- Your server must be accessible to the administration of CS2KZ at all times, + should manual inspection be necessary. +- Your server's name or branding must **not** include any discriminating, + obscene, or sexually explicit terms. diff --git a/docs/servers/index.md b/docs/servers/index.md new file mode 100644 index 0000000..76ef859 --- /dev/null +++ b/docs/servers/index.md @@ -0,0 +1,5 @@ +# Servers + +KZ servers are community servers running the +[`cs2kz-metamod`](https://github.com/KZGlobalTeam/cs2kz-metamod) plugin. There +is a list of approved servers on . diff --git a/docs/styles/index.md b/docs/styles/index.md new file mode 100644 index 0000000..57fe638 --- /dev/null +++ b/docs/styles/index.md @@ -0,0 +1,15 @@ +# Styles + +"styles" are modifications to gameplay that are applied on top of your +[mode](/modes). They are also additive, which means you can apply as many as +you want at the same time. Runs with styles do not award +[points](/ranking#points) or contribute to your +[player rating](/ranking#rating). Currently CS2KZ only features a single style, +but just like with modes, you can make your own! + +Below you can find a detailed list of all official styles. + +## AutoBhop + +The "AutoBhop" (or "ABH") style will allow you to hold your `+jump` key (the +space key by default) and get perfect bunny hops 100% of the time. diff --git a/docs/systems/maps.md b/docs/systems/maps.md deleted file mode 100644 index 762820a..0000000 --- a/docs/systems/maps.md +++ /dev/null @@ -1,81 +0,0 @@ -# Maps - -Maps and everything surrounding them will be quite different in CS2KZ compared -to GOKZ. The most important changes include: - -- Instead of the original 7 difficulty tiers we now have 10. -- Instead of a "main" course and 0 or more "bonus" courses we will just have "courses". -- Each course will have 4 "filters" applied to it. Each filter consists of a - [mode](/systems/modes), whether teleports are allowed, a tier, and "ranked" status. -- Every submitted record will be stored, independent of filters, but only - records that correspond to a "ranked" filter will contribute to a player's overall rank. - -## Tiers - -The new tiering system consists of 10 different tiers: - -> [!NOTE] -> These are best-effort descriptions, not hard rules. They are meant to illustrate the key ideas, -> not to be interpreted literally. - -1. Very Easy - for the average player who has never touched KZ before -2. Easy - you grasp the basics of CS2 movement, like airstrafing and bhopping -3. Medium - you have some KZ experience and are comfortable with the basics -4. Advanced - you are comfortable with strafing, bhopping, surfing, and ladder - movement -5. Hard - you have played quite a bit of KZ now and are comfortable combining - the above techniques -6. Very Hard - tier 5 but harder -7. Extreme - you can KZ in your sleep and are competing for World Records -8. Death - you have mastered KZ and can complete the most difficult of maps -9. Unfeasible - technically possible, but probably not by humans; reserved for - TAS runs -10. Impossible - literally and technically impossible, even with perfect inputs - -Unlike in GOKZ, tiers will not be applied to maps anymore, but rather to -[Filters](#filters). - -## Courses - -Each map in CS2KZ consists of one or more "courses." A course is a segment of gameplay - defined by a start and an end zone. Unlike GOKZ, CS2KZ eliminates the distinction between - "main" and "bonus" courses—there are simply courses. - -To have a [map approved](/mapping/approval), mappers must meet a minimum quality standard (not yet defined). To balance creativity with fair competition, CS2KZ introduces the concept - of "ranked" filters. This allows for diverse course types: - -- High-quality, high-effort courses (formerly "main" courses in GOKZ) designed for competitive play. -- Fun or experimental courses (previously "bonus" courses) that offer more creative gameplay. - -For a filter to be ranked, it must: - -- Be a tier of 8 or lower. -- Be "reasonable to compete on" (a subjective standard to be further clarified later in development). - -## Filters - -In CS2KZ, each course has a filter which represents a unique combination of mode, - teleport settings, difficulty tier, and "ranked" status. Filters create different variations of a course, providing players with distinct challenges and aligning the course with the appropriate difficulty level. - -### Key Components of a Filter - -1. **Mode** - This defines how the course is played (either [CKZ](/systems/modes#Classic) or [VNL](/systems/modes#Vanilla)) -2. **Teleport Settings** - Whether or not teleports are allowed in the course -3. **Tier** - Each Filter will have a [tier](#tiers), which indicates the difficulty level of the filter, determined - by the course’s complexity and challenge. Filters can range from Tier 1 (Very East) to Tier 10 (Impossible). -4. **Ranked Status** - This indicates whether the filter is ranked or unranked. - -#### Example Filter - -- **Map:** kz_example_map, course 3 -- **Mode:** CKZ -- **Teleport Setting:** No teleports -- **Tier:** 4 -- **Ranked Status:** Ranked - - -Filters will evolve over time as the skill ceiling of KZ grows and new boundaries are reached. We aim to create a system that allows the community to have input in making changes when needed, while ensuring **no data is lost.** -So go and play what you enjoy! - -> [!NOTE] -> Only records from ranked filters will contribute to a player's overall rank and award points. This ensures a fair competitive environment while giving mappers the freedom to create diverse courses. diff --git a/docs/systems/modes.md b/docs/systems/modes.md deleted file mode 100644 index 3939419..0000000 --- a/docs/systems/modes.md +++ /dev/null @@ -1,41 +0,0 @@ -# Modes - -Similar to [GOKZ](https://github.com/KZGlobalTeam/gokz) there are two modes you -can choose to play. - -## Vanilla - -The "Vanilla" (VNL) mode is the standard CS2 experience. - -The goal is to preserve as much of the default movement mechanics as possible -while only providing quality of life adjustments. - -This means no movement related settings are changed and the gameplay should feel -exactly like standard matchmaking. - -## Classic - -> [!NOTE] -> The name "Classic" is not final and is still under discussion, but it -> has gained popularity in the community and may become the official name. - -The "Classic" (CKZ) mode is the spiritual successor of SKZ. - -The goal is to make KZ more skill-based than RNG-based. - -- Bhopping is consistent with good scroll-timing. -- Bhop speed depends on landing speed. - -Players found that SKZ felt slow (~270 speed while bhopping), while consistently reaching -380u/s was difficult and annoying on most maps. CKZ addresses this with a **logarithmic speed formula**: - -- Higher initial speed gains compared to SKZ. -- Diminishing returns as speed increases, preventing absurd speeds but allowing fast-paced gameplay (~300 pre). -- No hard cap on speed, but building infinite speed isn’t possible. - -We also want to keep popular mechanics such as pre-keep and "WAD" / "our father tech" -in the new mode, which are not part of SKZ. - -KZT and SKZ were very similar, yet so different. We want to keep a single -heavily modified mode that everyone can enjoy and compete in. - diff --git a/docs/systems/points.md b/docs/systems/points.md deleted file mode 100644 index 52ac116..0000000 --- a/docs/systems/points.md +++ /dev/null @@ -1,44 +0,0 @@ -# Points & Rank - -In CS2KZ, players earn points by completing courses and achieving faster times across different modes and filters. -As players accumulate points, they advance through different ranks which reflect greater KZ skill. - -## Types of Points - -There are two types of points that are awarded in CS2KZ: - -### 1. Filter Points - -These points are tied to a specific [Filter](/systems/maps#filters) applied to a course and measure a player’s performance on that particular combination of map, mode, and settings. - -- **Max Points Per Filter:** The world record (WR) holder for a filter earns the maximum of 10,000 points. Players with slower times earn fewer points based on their performance -relative to the WR and the rest of the player base that has completed the filter - -- **Purpose:** Filter points indicate how skilled a player is at a specific map, mode, and filter combination. - -### 2. Player Points - -A player’s overall rating, or **Player Points**, is determined by a weighted sum of the points they’ve earned across **all** ranked filters. - -- **Rank Contributions:** Points from harder filters and better performances have more influence on the player’s rating, ensuring rankings reflect skill rather than sheer volume of completed maps. -- **Purpose:** Player points indicate general KZ proficiency and are used to determine rank tiers. - -## How Points are Calculated - -The amount of points rewarded after completing a map is based on the following: - -- **Course Difficulty:** More difficult courses yield higher point rewards. The difficulty of a course is tied to its filter's tier. -- **Performance:** Faster completion times and improved performance on a course will result in more points. -- **Filter Type:** Refers to the overall characteristics of the filter, such as teleport settings and other conditions. The more challenging the filter type, the more points are awarded. - -## Rank - -In CS2KZ, a player’s rank is determined by the total points accumulated through their performances in ranked filters. As players complete - courses and improve their times, they will earn points, which contribute to their overall rank. - -### Rank Tiers -Players progress through ranks based on their total points, with each rank representing a skill milestone. For example: - -- Noob: 0 - 999 Points -- Intermediate: 1,000 - 4,999 Points -- Pro: 5,000 - 14,999 Points \ No newline at end of file diff --git a/docs/systems/styles.md b/docs/systems/styles.md deleted file mode 100644 index 2a88568..0000000 --- a/docs/systems/styles.md +++ /dev/null @@ -1,16 +0,0 @@ -# Styles - -Styles in CS2KZ are optional modifiers that alter gameplay, offering creative and fun ways to explore maps beyond ranked competition. They don’t affect leaderboards or ranks but let players experiment, practice, or take on new challenges. - -## Examples of styles - -- Auto Bhop -- W/S-Only -- Low Gravity -- A/D-Only -- Ice - -
- -> [!NOTE] -> Currently only Auto Bhop is implemented, however, other styles are planned to be relesaed further in development \ No newline at end of file