From 62bb039d25fc08084cfdc1fcfb9720bd72868b38 Mon Sep 17 00:00:00 2001 From: Nicolai Cornelis Date: Tue, 5 Jul 2022 22:17:22 +0200 Subject: [PATCH] Format docs (way too long lines) --- documentation/docs/commands.md | 34 +++++++---- documentation/docs/developer_api.md | 42 +++++++++----- documentation/docs/event_logs.md | 49 ++++++++++------ documentation/docs/get5_configuration.md | 64 +++++++++++++++------ documentation/docs/index.md | 6 +- documentation/docs/installation.md | 44 ++++++++++++--- documentation/docs/match_configuration.md | 69 ++++++++++++++++++----- documentation/docs/match_schema.md | 62 +++++++++++++++----- documentation/docs/stats_system.md | 46 +++++++++++---- 9 files changed, 310 insertions(+), 106 deletions(-) diff --git a/documentation/docs/commands.md b/documentation/docs/commands.md index 17522c8bf..8e553939a 100644 --- a/documentation/docs/commands.md +++ b/documentation/docs/commands.md @@ -1,9 +1,14 @@ # Commands -Generally admin commands will have a `get5_` prefix and must be used in console. Commands intended for general player usage are created with `sm_` prefixes, which means sourcemod automtically registers a `!` chat version of the command. (For example: sm_ready in console is equivalent to !ready in chat) -Some client commands are available also for admin usage. For example, `sm_pause` and `sm_unpause` will force pauses if executed by the server (e.g., through `rcon`). +Generally admin commands will have a `get5_` prefix and must be used in console. Commands intended for general player +usage are created with `sm_` prefixes, which means SourceMod automatically registers a `!` chat version of the +command. (For example: `sm_ready` in console is equivalent to `!ready` in chat). + +Some client commands are available also for admin usage. For example, `sm_pause` and `sm_unpause` will force pauses if +executed by the server (e.g., through `rcon`). + +## Client Commands -## Client Commands Please note that these can be typed by *all players* in chat. - `!ready`: Marks a client's team as ready to begin. @@ -17,18 +22,25 @@ Please note that these can be typed by *all players* in chat. - `!switch`: Same as `!swap`. - `!stop`: Asks to reload the last match backup file, requires other team to confirm. - `!forceready`: Force readies your team, letting your team start regardless of player numbers/whether they are ready. -- `!get5`: Opens a menu that wraps some common commands. It's mostly intended for people using scrim settings, and has menu buttons for starting a scrim, force-starting, force-ending, adding a ringer, and loading the most recent backup file. +- `!get5`: Opens a menu that wraps some common commands. It's mostly intended for people using scrim settings, and has + menu buttons for starting a scrim, force-starting, force-ending, adding a ringer, and loading the most recent backup + file. + +## Server/Admin Commands -## Server/Admin Commands Please note that these are meant to be used by *admins* in console. - `get5_loadmatch `: Loads a match config file (JSON or KeyValue) relative from the `csgo` directory. - `get5_loadbackup `: Loads a get5 backup file relative from the `csgo` directory. -- `get5_loadteam `: Loads a team section from a file into a team relative from the `csgo` directory. -- `get5_loadmatch_url `: Loads a remote (JSON formatted) match config by sending a HTTP(S) GET to the given url, this requires the [Steamworks](https://forums.alliedmods.net/showthread.php?t=229556) extension. When specifying an URL with http:// or https:// in front, you have to put it in quotation (`""`) marks. +- `get5_loadteam `: Loads a team section from a file into a team relative from the `csgo` + directory. +- `get5_loadmatch_url `: Loads a remote (JSON formatted) match config by sending a HTTP(S) GET to the given url, + this requires the [Steamworks](https://forums.alliedmods.net/showthread.php?t=229556) extension. When specifying an + URL with http:// or https:// in front, you have to put it in quotation (`""`) marks. - `get5_endmatch`: Force ends the current match. - `get5_creatematch`: Creates a BO1 match with the current players on the server on the current map. -- `get5_scrim`: Creates a BO1 match with the using settings from `addons/sourcemod/configs/get5/scrim_template.cfg`, relative from the `csgo` directory. +- `get5_scrim`: Creates a BO1 match with the using settings from `addons/sourcemod/configs/get5/scrim_template.cfg`, + relative from the `csgo` directory. - `get5_addplayer [name]`: Adds a Steam ID to a team (can be any format for the Steam ID). - `get5_removeplayer `: Removes a steamid from all teams (can be any format for the Steam ID). - `get5_addkickedplayer [name]`: Adds the last kicked Steam ID to a team @@ -40,5 +52,7 @@ Please note that these are meant to be used by *admins* in console. - `get5_listbackups `: Lists backup files for the current matchid or a given matchid if not provided. - `get5_ringer `: Adds/removes a ringer to/from the home scrim team. - `sm_ringer `: Same as `get5_ringer`. -- `get5_debuginfo `: Dumps debug info to a file (addons/sourcemod/logs/get5_debuginfo.txt by default, if no file provided). -- `get5_test`: Runs get5 tests. **This should not be used on a live match server since it will reload a match config to test**. +- `get5_debuginfo `: Dumps debug info to a file (`addons/sourcemod/logs/get5_debuginfo.txt` by default, if no file + provided). +- `get5_test`: Runs get5 tests. **This should not be used on a live match server since it will reload a match config to + test**. diff --git a/documentation/docs/developer_api.md b/documentation/docs/developer_api.md index 8f2f8611a..ab49360a6 100644 --- a/documentation/docs/developer_api.md +++ b/documentation/docs/developer_api.md @@ -1,18 +1,31 @@ # API for developers + Get5 can be interacted with in several ways. At a glance: -1) You can write another sourcemod plugin that uses the [Get5 natives and forwards](https://github.com/splewis/get5/blob/master/scripting/include/get5.inc). This is exactly what the [get5_apistats](https://github.com/splewis/get5/blob/master/scripting/get5_apistats.sp) and [get5_mysqlstats](https://github.com/splewis/get5/blob/master/get5_mysqlstats.sp) plugins do. Please use these as a general guide/starting point, don't fork this repository to make changes to these plugins alone, but use these as a template and create a new repository for your plugin! +1) You can write another SourceMod plugin that uses + the [Get5 natives and forwards](https://github.com/splewis/get5/blob/master/scripting/include/get5.inc). This is + exactly what the [get5_apistats](https://github.com/splewis/get5/blob/master/scripting/get5_apistats.sp) + and [get5_mysqlstats](https://github.com/splewis/get5/blob/master/get5_mysqlstats.sp) plugins do. Please use these as + a general guide/starting point, don't fork this repository to make changes to these plugins alone, but use these as a + template and create a new repository for your plugin! -2) You can read [event logs](./event_logs.md) from a file on disk (set by [`get5_event_log_format`](./get5_configuration.md#file-name-formatting)), through a RCON connection to the server console since they are output there, or through another sourcemod plugin (see #1). +2) You can read [event logs](./event_logs.md) from a file on disk (set + by [`get5_event_log_format`](./get5_configuration.md#file-name-formatting)), through a RCON connection to the server + console since they are output there, or through another SourceMod plugin (see #1). -3) You can read the [stats](./stats_system.md) get5 collects from a file on disk (set by [`get5_stats_path_format`](./get5_configuration.md#file-name-formatting)), or through another sourcemod plugin (see #1). +3) You can read the [stats](./stats_system.md) get5 collects from a file on disk (set + by [`get5_stats_path_format`](./get5_configuration.md#file-name-formatting)), or through another SourceMod plugin ( + see #1). -4) You can execute the `get5_loadmatch` command or `get5_loadmatch_url` commands via another plugin or via a RCON connection to begin matches. Of course, you could execute any get5 command you want as well. +4) You can execute the `get5_loadmatch` command or `get5_loadmatch_url` commands via another plugin or via a RCON + connection to begin matches. Of course, you could execute any get5 command you want as well. ## Status Schema + The following is the `get_status` response's schema. ### Static + - `plugin_version`: Get5's version number. - `commit`: Only here if `COMMIT_STRING` is defined (probably not your case). - `gamestate`: A number representing the game's state. @@ -38,21 +51,24 @@ The following is the `get_status` response's schema. - `"postgame"` #### Additional Parts + *If the current game state is not "none"*: - `matchid`: The current match's id. You can set it in match configs, with the property which has the same name. -- `loaded_config_file`: The name of the loaded config file. If you used `get5_loadmatch `, it's this file's name. If you used `get5_loadmatch_url`, the pattern of the file is `remote_config%d.json`, where `%d` is the server's id, which you can set with `get5_server_id`. +- `loaded_config_file`: The name of the loaded config file. If you used `get5_loadmatch `, it's this file's name. + If you used `get5_loadmatch_url`, the pattern of the file is `remote_config%d.json`, where `%d` is the server's id, + which you can set with `get5_server_id`. - `map_number`: The current map number in the series. - `team1` and `team2`: Two JSON objects which share the same properties. - - `name`: Name of the team. - - `series_score`: The score in the series. - - `ready`: Boolean indicating if the team is ready. - - `side`: The side on which the team is. Can be `"CT"`, `"T"`, or `"none"`. - - `connected_clients`: The number of human clients connected on the team. - - `current_map_score`: The team's score on the current map. + - `name`: Name of the team. + - `series_score`: The score in the series. + - `ready`: Boolean indicating if the team is ready. + - `side`: The side on which the team is. Can be `"CT"`, `"T"`, or `"none"`. + - `connected_clients`: The number of human clients connected on the team. + - `current_map_score`: The team's score on the current map. *If the current game state is past the veto stage* - `maps`: A JSON Object which contains one property per map. - - Key: `"map%d"` where `%d` is the map index in the array. - - Value: The name of the map (taken from the [match config](./match_configuration.md)). \ No newline at end of file + - Key: `"map%d"` where `%d` is the map index in the array. + - Value: The name of the map (taken from the [match config](./match_configuration.md)). diff --git a/documentation/docs/event_logs.md b/documentation/docs/event_logs.md index 9daf60358..2e29fa839 100644 --- a/documentation/docs/event_logs.md +++ b/documentation/docs/event_logs.md @@ -1,25 +1,36 @@ # Event Logs -Get5 contains an event-logging system that logs many client actions and what is happening in the game. These supplement the logs CS:GO does on its own, but adds additional information about the ongoing match. + +Get5 contains an event-logging system that logs many client actions and what is happening in the game. These supplement +the logs CS:GO does on its own, but adds additional information about the ongoing match. An `event` is a json object that looks something like this: + ```json { - "matchid": "1", - "event": "series_start", - "params": { - "team1_name": "EnvyUs", - "team2_name": "Fnatic" - } + "matchid": "1", + "event": "series_start", + "params": { + "team1_name": "EnvyUs", + "team2_name": "Fnatic" + } } ``` -Events will have variable parameters depending on what type of event it is. In the example, we see the event name is "series_start". All events include the "matchid" field and have a name under `event`. +Events will have variable parameters depending on what type of event it is. In the example, we see the event name is " +series_start". All events include the "matchid" field and have a name under `event`. ## Interfacing With Events -From a plugin, you can use the `void Get5_OnEvent(const char[] eventJson)` forward to do anything you like with Get5 events. -You can also use the builtin server `logaddress_add` command to add a server `ip:port` that is listening to the game server log and reading events (it could also read plain CS:GO server log lines - this is what [eBot](https://github.com/deStrO/eBot-CSGO) does). -Finally, event can be logged to a file by settting the [`get5_event_log_format`](./get5_configuration.md#file-name-formatting) cvar. The file will look something like this: +From a plugin, you can use the `void Get5_OnEvent(const char[] eventJson)` forward to do anything you like with Get5 +events. +You can also use the builtin server `logaddress_add` command to add a server `ip:port` that is listening to the game +server log and reading events (it could also read plain CS:GO server log lines - this is +what [eBot](https://github.com/deStrO/eBot-CSGO) does). + +Finally, event can be logged to a file by settting +the [`get5_event_log_format`](./get5_configuration.md#file-name-formatting) cvar. The file will look something like +this: + ```log L 11/26/2016 - 02:58:39: { "matchid": "example_match", @@ -30,19 +41,23 @@ L 11/26/2016 - 02:58:39: { } } ``` -You'd have to do some processing to handle parsing the logging timestamp before each json event, but it isn't very hard (a simple regex replacement would be fine). + +You'd have to do some processing to handle parsing the logging timestamp before each json event, but it isn't very +hard (a simple regex replacement would be fine). ## List of Events and Their Params + Some rules are followed in these settings: 1. `Winner` is a match team, i.e. `team1` or `team2` 2. `team` is a match team, i.e. `team1` or `team2` 3. `side` is a CS team, i.e. `CT` or `T` 4. `map_number` is 0-indexed -5. `client` fields (`client`, `attacker`, `victim`, etc.) will use `%L` sourcemod formatting +5. `client` fields (`client`, `attacker`, `victim`, etc.) will use `%L` SourceMod formatting 6. `site` is `"A"` or `"B"` ### Series Flow + *The events listed below are rather self-documenting in a sense as to when they will be called.*. - `series_start`: @@ -88,7 +103,8 @@ Some rules are followed in these settings: - `winner`: Either `"team1"`, `"team2"`. - `team1_score`: The current score for `team1`. - `team2_score`: The current score for `team2`. - - `reason`: The number that represents the [CSRoundEndReason](https://sm.alliedmods.net/new-api/cstrike/CSRoundEndReason) + - `reason`: The number that represents + the [CSRoundEndReason](https://sm.alliedmods.net/new-api/cstrike/CSRoundEndReason) - `side_swap`: - `map_name`: The name of the map being vetoed. - `map_number`: The current map number. @@ -113,6 +129,7 @@ Some rules are followed in these settings: - `map_number`: The current map number. ### Client Actions + - `player_death`: - `map_name`: The name of the map being vetoed. - `map_number`: The current map number. @@ -157,7 +174,7 @@ Some rules are followed in these settings: - `match_config_load_fail`: - `reason`: Reason as to why the match configuration failed to load. - `backup_loaded`: - `file`: Location of the backup. + `file`: Location of the backup. - `team_ready` - `team`: Either `"team1"`, `"team2"`, or `"spec"` if spectators are required to ready. - - `stage`: one of `"veto"`, `"backup_restore"`, `"knife"`, or `"start"` \ No newline at end of file + - `stage`: one of `"veto"`, `"backup_restore"`, `"knife"`, or `"start"` diff --git a/documentation/docs/get5_configuration.md b/documentation/docs/get5_configuration.md index 550eb47c1..051a7af13 100644 --- a/documentation/docs/get5_configuration.md +++ b/documentation/docs/get5_configuration.md @@ -1,26 +1,37 @@ # Get5 Configuration -This config is auto-generated on first plugin run, then auto-executed on each plugin start. The file is located at `cfg/sourcemod/get5.cfg`. You can either set these in the aforementioned file, or in the `cvars` section of a match config. As mentioned in the [match schema](../match_schema#optional-values), that section will override all other settings. This section will be broken up into various sub-sections which explains each configuration value. + +This config is auto-generated on first plugin run, then auto-executed on each plugin start. The file is located +at `cfg/sourcemod/get5.cfg`. You can either set these in the aforementioned file, or in the `cvars` section of a match +config. As mentioned in the [match schema](../match_schema#optional-values), that section will override all other +settings. This section will be broken up into various sub-sections which explains each configuration value. ## Pausing + - `get5_max_pauses`: Maximum number of pauses a team can use, 0=unlimited. - `get5_max_pause_time`: Maximum number of time the game can spend paused by a team, 0=unlimited. - `get5_reset_pauses_each_half`: Whether pause limits are reset each halftime period (default 1). -- `get5_fixed_pause_time`: If non-zero, the fixed length all pauses will be. Adjusting this to non-zero this will use the in-game timeout counter. +- `get5_fixed_pause_time`: If non-zero, the fixed length all pauses will be. Adjusting this to non-zero this will use + the in-game timeout counter. - `get5_pausing_enabled`: Whether the `!pause` command is enabled to clients or not. - `get5_allow_technical_pause`: Whether technical pauses (`!tech` command) are enabled (default 1). - `get5_max_tech_pauses`: Number of technical pauses a team is allowed to have, 0=unlimited. -- `get5_tech_pause_time`: If non-zero, number of seconds before any team can call unpause without confirmation. 0=unlimited and both teams must confirm. +- `get5_tech_pause_time`: If non-zero, number of seconds before any team can call unpause without confirmation. + 0=unlimited and both teams must confirm. - `get5_pause_on_veto`: Pauses/Freezes players during the veto phase. ## File Name Formatting + *Note: for these, setting the cvar to an empty string ("") will disable the file writing entirely.* -- `get5_time_format`: Time format string (default `%Y-%m-%d_%H`), only affects if a {TIME} tag is used in other file-name formatting cvars. +- `get5_time_format`: Time format string (default `%Y-%m-%d_%H`), only affects if a {TIME} tag is used in other + file-name formatting cvars. - `get5_demo_name_format`: Format to name demo files in (default `{MATCHID}_map{MAPNUMBER}_{MAPNAME}`). - `get5_event_log_format`: Format to write get5 event logs to (default `logs/get5_match{MATCHID}.log`). -- `get5_stats_path_format`: Path where stats are output at each map end if it is set. Default `get5_matchstats_{MATCHID}.cfg` +- `get5_stats_path_format`: Path where stats are output at each map end if it is set. + Default `get5_matchstats_{MATCHID}.cfg` ### Substitution Variables + Valid substitutions into the above file name formatting cvars (when surrounded by {}): - `TIME` @@ -32,6 +43,7 @@ Valid substitutions into the above file name formatting cvars (when surrounded b - `MATCHTITLE` #### Colour Substitution Variables + This project also includes substitution variables for colour in text chat (when surrounded by {}): - `{NORMAL}` @@ -48,40 +60,58 @@ This project also includes substitution variables for colour in text chat (when - `{PURPLE}` ## Match Management Timers + - `get5_time_to_start`: Time (in seconds) teams have to ready up before forfeiting the match, 0=unlimited. -- `get5_time_to_make_knife_decision`: Time (in seconds) a team has to make a !stay/!swap decision after winning knife round, 0=unlimited. +- `get5_time_to_make_knife_decision`: Time (in seconds) a team has to make a !stay/!swap decision after winning knife + round, 0=unlimited. - `get5_veto_countdown`: Time (in seconds) to countdown before veto process commences, default 5 seconds. -- `get5_end_match_on_empty_server`: Whether the match is ended with no winner if all players leave (note: this will happen even if all players disconnect even in warmup with the intention to reconnect!). -- `get5_veto_confirmation_time`: Time (in seconds) from presenting a veto menu to a selection being made, during which a confirmation will be required, 0 to disable, default 2.0 seconds. +- `get5_end_match_on_empty_server`: Whether the match is ended with no winner if all players leave (note: this will + happen even if all players disconnect even in warmup with the intention to reconnect!). +- `get5_veto_confirmation_time`: Time (in seconds) from presenting a veto menu to a selection being made, during which a + confirmation will be required, 0 to disable, default 2.0 seconds. ## Backup System + - `get5_backup_system_enabled`: Whether the get5 backup system is enabled, default is 1. -- `get5_last_backup_file`: Last match backup file get5 wrote in the current series, this is automatically updated by get5 each time a backup file is written. -- `get5_max_backup_age`: Number of seconds before a get5 backup file is automatically deleted, 0 to disable, default is 160000 seconds. +- `get5_last_backup_file`: Last match backup file get5 wrote in the current series, this is automatically updated by + get5 each time a backup file is written. +- `get5_max_backup_age`: Number of seconds before a get5 backup file is automatically deleted, 0 to disable, default is + 160000 seconds. ## Miscellaneous + ### Configs + - `get5_live_cfg`: Config file executed when the game goes live, default is `get5/live.cfg`. -- `get5_autoload_config`: A config file to autoload on map starts if no match is loaded, directory is relative to the `csgo/` directory. +- `get5_autoload_config`: A config file to autoload on map starts if no match is loaded, directory is relative to + the `csgo/` directory. - `get5_warmup_cfg`: Config file executed in warmup periods, default is `get5/warmup.cfg`. ### Server Setup -*These options will generally not be directly presented to clients, but will modify how Get5 interacts on the game server.* + +*These options will generally not be directly presented to clients, but will modify how Get5 interacts on the game +server.* - `get5_server_id`: Integer that identifies your server. This is used in temp files to prevent collisions. Default is 0. -- `get5_kick_immunity`: Whether or not admins with the changemap flag will be immune to kicks from `get5_kick_when_no_match_loaded`. Set to 0 to disable, default is 1. +- `get5_kick_immunity`: Whether or not admins with the changemap flag will be immune to kicks + from `get5_kick_when_no_match_loaded`. Set to 0 to disable, default is 1. - `get5_stop_command_enabled`: Whether the `!stop` command is enabled, default is 1. - `get5_kick_when_no_match_loaded`: Whether to kick all clients if no match is loaded. Default 0. - `get5_display_gotv_veto`: Whether to wait for map vetos to be printed to GOTV before changing map, default is 0. -- `get5_check_auths`: Whether the steamids from a "players" section are used to force players onto teams, and will kick users if they are not in the auth list (default 1). +- `get5_check_auths`: Whether the steamids from a "players" section are used to force players onto teams, and will kick + users if they are not in the auth list (default 1). ### Match Setup + *These options will generally be represented by changes to the clients.* -- `get5_ready_team_tag`: Adds `[READY] [NOT READY]` Tags before Team Names, and removes clan tags from users. 0 to disable it, default is 1. +- `get5_ready_team_tag`: Adds `[READY] [NOT READY]` Tags before Team Names, and removes clan tags from users. 0 to + disable it, default is 1. - `get5_live_countdown_time`: Number of seconds used to count down when a match is going live, default 10 seconds. -- `get5_auto_ready_active_players`: Whether to automatically mark players as ready if they kill anyone in the warmup or veto phase. Default is 0. +- `get5_auto_ready_active_players`: Whether to automatically mark players as ready if they kill anyone in the warmup or + veto phase. Default is 0. - `get5_set_client_clan_tags`: Whether to set client clan tags to player ready status. Default is 1. - `get5_print_damage`: Whether to print damage reports on round ends, default is 0. -- `get5_damageprint_format`: Formatting of damage reports in the text chat. defaults to `- [{KILL_TO}] ({DMG_TO} in {HITS_TO}) to [{KILL_FROM}] ({DMG_FROM} in {HITS_FROM}) from {NAME} ({HEALTH} HP)`. +- `get5_damageprint_format`: Formatting of damage reports in the text chat. defaults + to `- [{KILL_TO}] ({DMG_TO} in {HITS_TO}) to [{KILL_FROM}] ({DMG_FROM} in {HITS_FROM}) from {NAME} ({HEALTH} HP)`. - `get5_message_prefix`: The tag applied before plugin messages, default is `Get5`. diff --git a/documentation/docs/index.md b/documentation/docs/index.md index db5eb7112..8d1f7817d 100644 --- a/documentation/docs/index.md +++ b/documentation/docs/index.md @@ -1,3 +1,7 @@ # Welcome to Get5 Documentation -The aim for this documentation is to provide a full overview of what is included in the Get5 plugin. Originally based off of [pugsetup](https://github.com/splewis/csgo-pug-setup) and inspired by [eBot](https://github.com/deStrO/eBot-CSGO), it intends to be as non-invasive and builds most of its functionality on top of the CS:GO server operations. It is meant to be an easy-to-use solution for tournament and LANs. Use the sidebar to navigate around the documentation. If you are installing this on your game server, head over to the [Installation](./installation.md) instructions. +The aim for this documentation is to provide a full overview of what is included in the Get5 plugin. Originally based +off of [pugsetup](https://github.com/splewis/csgo-pug-setup) and inspired by [eBot](https://github.com/deStrO/eBot-CSGO) +, it intends to be as non-invasive and builds most of its functionality on top of the CS:GO server operations. It is +meant to be an easy-to-use solution for tournament and LANs. Use the sidebar to navigate around the documentation. If +you are installing this on your game server, head over to the [Installation](./installation.md) instructions. diff --git a/documentation/docs/installation.md b/documentation/docs/installation.md index 9bc189b13..c33fd236d 100644 --- a/documentation/docs/installation.md +++ b/documentation/docs/installation.md @@ -1,18 +1,46 @@ # Download and Installation -You must have [Sourcemod](https://www.sourcemod.net/) downloaded and installed on your server. Please note that get5 only supports Sourcemod version 1.9 and above. Instructions of how to install Sourcemod and Metamod (requirement of Sourcemod) can be found on their website. + +## SourceMod & MetaMod + +You must have [SourceMod](https://www.sourcemod.net/) downloaded and installed on your server. Please note that Get5 +requires SourceMod version 1.09 or higher. Instructions of how to install SourceMod and MetaMod (requirement of +SourceMod) can be found on their website. ## Download Get5 -Releases of Get5 can be found in the [Tags](https://github.com/splewis/get5/tags) section of the repo. These versions are known to be stable, but may be lacking features that are currently in development. If you would like to test new features, or be on the "bleeding edge", you can also download through the Jenkins instance found [here](https://ci.splewis.net/job/get5/), or the build artifacts found under each run in GitHub actions [here](https://github.com/splewis/get5/actions). + +Releases of Get5 can be found in the [Tags](https://github.com/splewis/get5/tags) section of the repo. These versions +are known to be stable, but may be lacking features that are currently in development. If you would like to test new +features, or be on the "bleeding edge", you can also download through the Jenkins instance +found [here](https://ci.splewis.net/job/get5/), or the build artifacts found under each run in GitHub +actions [here](https://github.com/splewis/get5/actions). ## Installation -Once you have downloaded the zip file, extract it into your `csgo/` directory in your game server. If all goes well, you should have the compiled plugin located at `addons/sourcemod/plugins/get5.smx`. Once the plugin first loads on the server, you can edit general get5 cvars in the autogenerated `cfg/sourcemod/get5.cfg`. You should also have 3 config files: `cfg/get5/warmupcfg`, `cfg/get5/knife.cfg`, cfg/get5/live.cfg. These can be edited, but I recommend not blindly pasting another config in (e.g. ESL, CEVO). Configs that execute warmup commands (mp_warmup_end, for example) **will** cause problems. -### Installing Steamworks (Optional) -SteamWorks is not required for Get5 to work on your game server, however it is required if you wish to load match configs remotely. You can download the latest binaries for SteamWorks [here](https://github.com/KyleSanderson/SteamWorks/releases/). If you require a Windows build of the extension, that can also be found [here](https://github.com/hexa-core-eu/SteamWorks/releases) instead. After downloading, unzip the file and merge the `addons` directory to the one in your CS:GO server installation. +Once you have downloaded the zip file, extract it into your `csgo/` directory in your game server. If all goes well, you +should have the compiled plugin located at `addons/sourcemod/plugins/get5.smx`. Once the plugin first loads on the +server, you can edit general get5 cvars in the autogenerated `cfg/sourcemod/get5.cfg`. You should also have 3 config +files: `cfg/get5/warmupcfg`, `cfg/get5/knife.cfg` and `cfg/get5/live.cfg`. These can be edited, but we recommend not +blindly pasting another config in (e.g. ESL, CEVO). Configs that execute warmup commands (`mp_warmup_end`, for +example) **will** cause problems. + +### Installing SteamWorks (Optional) + +SteamWorks is not required for Get5 to work on your game server, however it is required if you wish to load match +configs remotely. You can download the latest binaries for +SteamWorks [here](https://github.com/KyleSanderson/SteamWorks/releases/). If you require a Windows build of the +extension, that can also be found [here](https://github.com/hexa-core-eu/SteamWorks/releases) instead. After +downloading, unzip the file and merge the `addons` directory to the one in your CS:GO server installation. ### Installing get5_apistats (Optional) -If you want to use the [get5 web panel](https://github.com/splewis/get5-web) (however, this is unsupported, and there are other tools/webpanels available) to manage matches and display stats, then you should install the get5_apistats plugin in addition to the get5 plugin. In addition to get5.smx in `addons/sourcemod/plugins`, you should have copied get5_apistats.smx into that directory as well. Both plugins are included in releases/builds, and the apistats plugin will be in the `disabled` folder. -Note: this requires that you installed the SteamWorks extension from the above step. The command get5_web_avaliable will tell you if this plugin was successfully installed. If not, it will reply with "unknown command". +If you want to use the [get5 web panel](https://github.com/splewis/get5-web) (however, this is unsupported, and there +are other tools/webpanels available) to manage matches and display stats, then you should install the `get5_apistats` +plugin in addition to the get5 plugin. In addition to get5.smx in `addons/sourcemod/plugins`, you should have copied +get5_apistats.smx into that directory as well. Both plugins are included in releases/builds, and the apistats plugin +will be in the `disabled` folder. + +Note: this requires that you installed the SteamWorks extension from the above step. The command `get5_web_available` +will tell you if this plugin was successfully installed. If not, it will reply with "unknown command". -Congratulations, get5 is now installed on your server, and you can continue to [Configuration](./match_configuration.md). \ No newline at end of file +Congratulations, Get5 is now installed on your server, and you can continue to [Configuration](./match_configuration.md) +. diff --git a/documentation/docs/match_configuration.md b/documentation/docs/match_configuration.md index c9d86d10f..12deea89a 100644 --- a/documentation/docs/match_configuration.md +++ b/documentation/docs/match_configuration.md @@ -1,45 +1,84 @@ # Configuration ## Quick Start -If you want to create a match quickly without modifying anything, you will just need to change two cvars, `get5_check_auths 0` and `get5_kick_when_no_match_loaded 0`, so users will be able to join the server. Once these are set, and all players are connected to the server and correct teams, just call `get5_creatematch`. There is also a simple menu that you can call this command by using `!get5` in the game chat. + +If you want to create a match quickly without modifying anything, you will just need to change two +cvars, `get5_check_auths 0` and `get5_kick_when_no_match_loaded 0`, so users will be able to join the server. Once these +are set, and all players are connected to the server and correct teams, just call `get5_creatematch`. There is also a +simple menu that you can call this command by using `!get5` in the game chat. ## Scrim Configuration + If you are using get5 for scrims, please follow these steps. -While get5 is intended for matches (league matches, lan matches, cups, etc.), it can be used for everyday scrims/gathers/whatever as well. If that is your use case, you should do a few things differently. +While get5 is intended for matches (league matches, lan matches, cups, etc.), it can be used for everyday +scrims/gathers/whatever as well. If that is your use case, you should do a few things differently. *Note*: these features are new to the 0.5.0+ versions. ### Cvars -By default, get5 kicks all players from the server if no match is loaded. You should disable this for a practice server. To do so, edit `cfg/sourcemod/get5.cfg` and change the following cvar: + +By default, get5 kicks all players from the server if no match is loaded. You should disable this for a practice server. +To do so, edit `cfg/sourcemod/get5.cfg` and change the following cvar: `get5_kick_when_no_match_loaded 0` - this will enable players to join before starting ### Adding Your Team's Steam IDs -You **must** edit the [scrim template](https://github.com/splewis/get5/blob/master/configs/get5/scrim_template.cfg) located at `addons/sourcemod/configs/get5/scrim_template.cfg` and add in *your* team's players to the `team1` section by their Steam IDs (any format works). After doing this, any user who does not belong in `team1` will implicitly be set to `team2`. -You can list however many players you want. Add all your coaches, analysts, ringers, and such. If someone on your list ends up being on the other team in a scrim, you can use the !ringer command to temporarily swap them (similarly, you can use !ringer to put someone not in the list, on your team temporarily). +You **must** edit the [scrim template](https://github.com/splewis/get5/blob/master/configs/get5/scrim_template.cfg) +located at `addons/sourcemod/configs/get5/scrim_template.cfg` and add in *your* team's players to the `team1` section by +their Steam IDs (any format works). After doing this, any user who does not belong in `team1` will implicitly be set +to `team2`. + +You can list however many players you want. Add all your coaches, analysts, ringers, and such. If someone on your list +ends up being on the other team in a scrim, you can use the !ringer command to temporarily swap them (similarly, you can +use !ringer to put someone not in the list, on your team temporarily). ### Starting the Match -Rather than creating a [match config](https://github.com/splewis/get5#match-schema), you should use the `get5_scrim` when the server is on the correct map. You can use this via rcon (`rcon get5_scrim`, be sure your `rcon_password` is set!) or as a regular console command if you have the sourcemod changemap admin flag. You could also type `!scrim` in chat. -This command takes optional arguments: `get5_scrim [other team name] [map name] [matchid]`. For example, if you're playing *fnatic* on *dust2* you might run `get5_scrim fnatic de_dust2`. The other team name defaults to "away" and the map name defaults to the current map. `matchid` defaults to "scrim". +Rather than creating a [match config](https://github.com/splewis/get5#match-schema), you should use the `get5_scrim` +when the server is on the correct map. You can use this via rcon (`rcon get5_scrim`, be sure your `rcon_password` is +set!) or as a regular console command if you have the SourceMod changemap admin flag. You could also type `!scrim` in +chat. + +This command takes optional arguments: `get5_scrim [other team name] [map name] [matchid]`. For example, if you're +playing *fnatic* on *dust2* you might run `get5_scrim fnatic de_dust2`. The other team name defaults to "away" and the +map name defaults to the current map. `matchid` defaults to "scrim". Once you've done this, all that has to happen is teams to ready up to start the match. #### Extra Commands -- You can use `get5_ringer` in console with a steamid to add a player to the "home" team as of 0.6.0, or `!ringer` in chat. + +- You can use `get5_ringer` in console with a steamid to add a player to the "home" team as of 0.6.0, or `!ringer` in + chat. - You can do `!swap` in chat to swap sides during the warmup phase if you want to start on a different side. -- If you forget commands, use `!get5` in chat, and you will get a user friendly menu to do all the above (new in 0.6.0+). -- If you have [practicemode](https://github.com/splewis/csgo-practice-mode) on your server as well, you may wish to add `sm_practicemode_can_be_started 0` in your [live config](https://github.com/splewis/get5/blob/master/cfg/get5/live.cfg) at `cfg/get5/live.cfg`. +- If you forget commands, use `!get5` in chat, and you will get a user friendly menu to do all the above (new in 0.6.0+) + . +- If you have [practicemode](https://github.com/splewis/csgo-practice-mode) on your server as well, you may wish to + add `sm_practicemode_can_be_started 0` in + your [live config](https://github.com/splewis/get5/blob/master/cfg/get5/live.cfg) at `cfg/get5/live.cfg`. ### Changing Scrim Settings -You can (and should) edit the [scrim template](https://github.com/splewis/get5/blob/master/configs/get5/scrim_template.cfg) at `addons/sourcemod/configs/get5/scrim_template.cfg`. In this you can set any scrim-specific cvars in the cvars section. -The default settings will playout all 30 rounds and shorten up the halftime break. You also may want to lower `tv_delay` (and maybe `tv_enable` so you can record your scrims) and other settings in your [live config](https://github.com/splewis/get5/blob/master/cfg/get5/live.cfg) at `cfg/get5/live.cfg`. + +You can (and should) edit +the [scrim template](https://github.com/splewis/get5/blob/master/configs/get5/scrim_template.cfg) +at `addons/sourcemod/configs/get5/scrim_template.cfg`. In this you can set any scrim-specific cvars in the cvars +section. +The default settings will playout all 30 rounds and shorten up the halftime break. You also may want to +lower `tv_delay` (and maybe `tv_enable` so you can record your scrims) and other settings in +your [live config](https://github.com/splewis/get5/blob/master/cfg/get5/live.cfg) at `cfg/get5/live.cfg`. ## Match Configuration + **Note**: If you are using get5 just for scrims, do not proceed here, just follow the instructions above! - You can either load a match config from a Key Value file (a good [example](https://github.com/splewis/get5/blob/master/configs/get5/example_match.cfg) and starting point is located at `addons/sourcemod/configs/get5/example_match.cfg`). There are many *optional* fields there, and they can be explained in the [Match Schema](./match_schema.md) section of the docs. The only **required** portions of the config are `team1` and `team2`. - Once you have your file created, you can place it anywhere in your server directory. For example, if you create the file under `csgo/match.cfg`, you would call `get5_loadmatch match.cfg`. - If you place it anywhere else, for example `csgo/addons/sourcemod/configs/get5/match.cfg`, you would call `get5_loadmatch addons/sourcemod/configs/get5/match.cfg` and Get5 will load your match according to the values in that file. \ No newline at end of file +You can either load a match config from a Key Value file (a +good [example](https://github.com/splewis/get5/blob/master/configs/get5/example_match.cfg) and starting point is located +at `addons/sourcemod/configs/get5/example_match.cfg`). There are many *optional* fields there, and they can be explained +in the [Match Schema](./match_schema.md) section of the docs. The only **required** portions of the config are `team1` +and `team2`. +Once you have your file created, you can place it anywhere in your server directory. For example, if you create the file +under `csgo/match.cfg`, you would call `get5_loadmatch match.cfg`. +If you place it anywhere else, for example `csgo/addons/sourcemod/configs/get5/match.cfg`, you would +call `get5_loadmatch addons/sourcemod/configs/get5/match.cfg` and Get5 will load your match according to the values in +that file. diff --git a/documentation/docs/match_schema.md b/documentation/docs/match_schema.md index 817ee28af..408a2628d 100644 --- a/documentation/docs/match_schema.md +++ b/documentation/docs/match_schema.md @@ -1,41 +1,72 @@ # Match Schema -Inside this repo are two files that give a general idea of what can be included in a match config. A Valve KeyValue format can be found [here](https://github.com/splewis/get5/blob/master/configs/get5/example_match.cfg), and a JSON format can be found [here](https://github.com/splewis/get5/blob/master/configs/get5/example_match.json). In this documentation, we'll go through what each value means, but do note that **only the values** `team1` and `team2` are required to start a match, which can be seen in the next section. Reasonable defaults are used for entries (bo3 series, 5v5, empty strings for team names, etc.). + +Inside this repo are two files that give a general idea of what can be included in a match config. A Valve KeyValue +format can be found [here](https://github.com/splewis/get5/blob/master/configs/get5/example_match.cfg), and a JSON +format can be found [here](https://github.com/splewis/get5/blob/master/configs/get5/example_match.json). In this +documentation, we'll go through what each value means, but do note that **only the values** `team1` and `team2` are +required to start a match, which can be seen in the next section. Reasonable defaults are used for entries (bo3 series, +5v5, empty strings for team names, etc.). ## Required Values (The Team Schema) -There are quite a few values that are also optional within the team schema, but we will outline what they are all intended for. Realisitcally, if you want to setup a quick match, only the `name` and `players` are required to set up a match. + +There are quite a few values that are also optional within the team schema, but we will outline what they are all +intended for. Realisitcally, if you want to setup a quick match, only the `name` and `players` are required to set up a +match. - `name`: The team name (wraps `mp_teamname_1` and is displayed often in chat messages). - `tag`: The team tag (or short name), this replaces client "clan tags". -- `flag`: The team flag (2 letter country code, wraps `mp_teamflag_1`), list of country codes for CS:GO can be found [here](https://steamcommunity.com/sharedfiles/filedetails/?id=719079703). -- `logo`: The team logo (wraps `mp_teamlogo_1`), which requires to be on a FastDL in order for clients to see, or users may download another [sourcemod plugin](https://forums.alliedmods.net/showthread.php?t=258206). -- `players`: A list of Steam ID's for users on the team (not used if `get5_check_auths` is set to `0`). You can also force player names in here; in JSON you may use either an array of steamids or a dictionary of Steam IDs to names. Both ways are shown in the above example. -- `series_score`: The current score in the series, this can be used to give a team a map advantage or used as a manual backup method, defaults to `0`. -- `matchtext`: Wraps `mp_teammatchstat_1`, you probably don't want to set this, in BoX series `mp_teamscore` cvars are automatically set and take the place of the `mp_teammatchstat` cvars. +- `flag`: The team flag (2 letter country code, wraps `mp_teamflag_1`), list of country codes for CS:GO can be + found [here](https://steamcommunity.com/sharedfiles/filedetails/?id=719079703). +- `logo`: The team logo (wraps `mp_teamlogo_1`), which requires to be on a FastDL in order for clients to see, or users + may download another [SourceMod plugin](https://forums.alliedmods.net/showthread.php?t=258206). +- `players`: A list of Steam ID's for users on the team (not used if `get5_check_auths` is set to `0`). You can also + force player names in here; in JSON you may use either an array of steamids or a dictionary of Steam IDs to names. + Both ways are shown in the above example. +- `series_score`: The current score in the series, this can be used to give a team a map advantage or used as a manual + backup method, defaults to `0`. +- `matchtext`: Wraps `mp_teammatchstat_1`, you probably don't want to set this, in BoX series `mp_teamscore` cvars are + automatically set and take the place of the `mp_teammatchstat` cvars. ## Optional Values + - `matchid`: A string matchid used to identify the match. - `num_maps`: Number of maps in the series. This must be an odd number or 2. -- `maplist`: List of the maps in use (an array of strings in JSON, mapnames as keys for KeyValues), you should always use an odd-sized maplist +- `maplist`: List of the maps in use (an array of strings in JSON, mapnames as keys for KeyValues), you should always + use an odd-sized maplist - `skip_veto`: Whether the veto will be skipped and the maps will come from the maplist (in the order given). - `veto_first`: Either "random", "team1", or "team2". If not set, or set to any other value, "team1" will veto first. -- `side_type`: Either "standard", "never_knife", or "always_knife"; "standard" means the team that doesn't pick a map gets the side choice, "never_knife" means "team1" is always on CT first, and "always_knife" means there is always a knife round. +- `side_type`: Either "standard", "never_knife", or "always_knife"; "standard" means the team that doesn't pick a map + gets the side choice, "never_knife" means "team1" is always on CT first, and "always_knife" means there is always a + knife round. - `players_per_team`: Maximum players per team (doesn't include a coach spot, default: 5). - `min_players_to_ready`: Minimum players a team needs to be able to ready up (default: 1). - `favored_percentage_team1`: Wrapper for the servers `mp_teamprediction_pct`. - `favored_percentage_text` Wrapper for the servers `mp_teamprediction_txt`. -- `cvars`: Cvars to be set during the match warmup/knife round/live state. **These will override all other settings** (standard CS:GO cvars are also supported). -- `match_title`: Wrapper on the servers `mp_teammatchstat_txt` cvar, but can use {MAPNUMBER} and {MAXMAPS} as variables that get replaced with their integer values. In a BoX series, you probably don't want to set this since Get5 automatically sets `mp_teamscore` cvars for the current series score, and take the place of the `mp_teammatchstat` cvars. +- `cvars`: Cvars to be set during the match warmup/knife round/live state. **These will override all other settings** ( + standard CS:GO cvars are also supported). +- `match_title`: Wrapper on the servers `mp_teammatchstat_txt` cvar, but can use {MAPNUMBER} and {MAXMAPS} as variables + that get replaced with their integer values. In a BoX series, you probably don't want to set this since Get5 + automatically sets `mp_teamscore` cvars for the current series score, and take the place of the `mp_teammatchstat` + cvars. ## Managing Match Configs + ### Going *laissez faire* -The cvar `get5_check_auths` (which you should set in `cfg/sourcemod/get5.cfg`, or the match config cvars section) can be set to `0`, which will stop the plugin from forcing players onto the correct team. This means the players section will not be used, and can be omitted if you don't want to set everyone's Steam ID. -This is **generally not recommended**, as there are great advantages to letting the plugin handle forcing players onto the correct teams and kicking people that shouldn't be in the server. +The cvar `get5_check_auths` (which you should set in `cfg/sourcemod/get5.cfg`, or the match config cvars section) can be +set to `0`, which will stop the plugin from forcing players onto the correct team. This means the players section will +not be used, and can be omitted if you don't want to set everyone's Steam ID. + +This is **generally not recommended**, as there are great advantages to letting the plugin handle forcing players onto +the correct teams and kicking people that shouldn't be in the server. ### Managing Team Data From Separate Files -One strategy for storing all the team data is to create a config for each team, then you can use the `fromfile` field when creating match configs. + +One strategy for storing all the team data is to create a config for each team, then you can use the `fromfile` field +when creating match configs. By using this strategy, you would: + - Create a team config file for every team in your tournament/league/etc. - When a match is played, update the server's match config `team1:fromfile` and `team2:fromfile` fields. @@ -80,6 +111,7 @@ Here is an example `match.cfg` that includes `fromfile`: ``` Inside the `team_nip.cfg` would be the following: + ```cfg "team" { @@ -95,6 +127,7 @@ Inside the `team_nip.cfg` would be the following: ``` And inside `team_nv.cfg` would be the following: + ```cfg "team" { @@ -108,4 +141,5 @@ And inside `team_nv.cfg` would be the following: } } ``` + Please note that this works for both KeyValue and JSON formatted configs. diff --git a/documentation/docs/stats_system.md b/documentation/docs/stats_system.md index 46eb80e01..8920d1040 100644 --- a/documentation/docs/stats_system.md +++ b/documentation/docs/stats_system.md @@ -1,18 +1,29 @@ # Stats System -When a get5 match is live, the plugin will automatically record match stats for each player, across each map in the match. These are recorded in an internal KeyValues structure, and are available at any time during the match (including the postgame waiting period) via the `Get5_GetMatchStats` native and the [`get5_dumpstats`](./commands.md#serveradmin-commands) command. -Note: the stats collection is not going to be reliable if using [`get5_check_auths 0`](./get5_configuration.md#server-setup). +When a get5 match is live, the plugin will automatically record match stats for each player, across each map in the +match. These are recorded in an internal KeyValues structure, and are available at any time during the match (including +the postgame waiting period) via the `Get5_GetMatchStats` native and +the [`get5_dumpstats`](./commands.md#serveradmin-commands) command. + +Note: the stats collection is not going to be reliable if +using [`get5_check_auths 0`](./get5_configuration.md#server-setup). ## Stats KeyValues structure -The root level of the KV contains data for the full series: the series winner (if one exists yet) and the series type (bo1, bo2..., etc). -Under that root level, there is a level for each map ("map1", "map2"), which contains the map winner (if one exists yet), the mapname, and the demo file recording. +The root level of the KV contains data for the full series: the series winner (if one exists yet) and the series type ( +bo1, bo2..., etc). + +Under that root level, there is a level for each map ("map1", "map2"), which contains the map winner (if one exists yet) +, the mapname, and the demo file recording. -Under the map level, there is a section for each team ("team1" and "team2) which contains the current team score (on that map) and the team name. +Under the map level, there is a section for each team ("team1" and "team2) which contains the current team score (on +that map) and the team name. -Each player has a section under the team level under the section name of their steam64id. It contains all the personal level stats: name, kills, deaths, assists, etc. +Each player has a section under the team level under the section name of their steam64id. It contains all the personal +level stats: name, kills, deaths, assists, etc. Partial Example: + ``` "Stats" { @@ -40,14 +51,25 @@ Partial Example: ``` ## What Stats Are Collected -See the [get5 include](https://github.com/splewis/get5/blob/master/scripting/include/get5.inc#L168) for what stats will be recorded and what their key in the keyvalues structure is. + +See the [get5 include](https://github.com/splewis/get5/blob/master/scripting/include/get5.inc#L168) for what stats will +be recorded and what their key in the keyvalues structure is. ## MySQL Statistics -Get5 ships with a (disabled by default) plugin called `get5_mysqlstats` that will save many of the stats to a MySQL database. To use this: -- Create the tables using this [schema](https://github.com/splewis/get5/blob/master/misc/import_stats.sql), raw text link can be found [here](https://raw.githubusercontent.com/splewis/get5/master/misc/import_stats.sql). + +Get5 ships with a (disabled by default) plugin called `get5_mysqlstats` that will save many of the stats to a MySQL +database. To use this: + +- Create the tables using this [schema](https://github.com/splewis/get5/blob/master/misc/import_stats.sql), raw text + link can be found [here](https://raw.githubusercontent.com/splewis/get5/master/misc/import_stats.sql). - Configure a `"get5"` database section in `addons/sourcemod/configs/databases.cfg `. -- Make sure the `get5_mysqlstats` plugin is enabled (moved up a directory from `addons/sourcemod/plugins/disabled` directory) and reload with `sm plugins reload get5_mysqlstats`. +- Make sure the `get5_mysqlstats` plugin is enabled (moved up a directory from `addons/sourcemod/plugins/disabled` + directory) and reload with `sm plugins reload get5_mysqlstats`. -**Note** that if you use this module, you can force the matchid used by the stats system by setting the `get5_mysql_force_matchid` convar in your matchconfig (the [cvars](./match_configuration.md#cvars) section). If you don't do this, then the get5 matchid will be set to the next matchid returned by inserting into the `get5_stats_matches` table. +**Note** that if you use this module, you can force the matchid used by the stats system by setting +the `get5_mysql_force_matchid` convar in your matchconfig (the [cvars](./match_configuration.md#cvars) section). If you +don't do this, then the get5 matchid will be set to the next matchid returned by inserting into the `get5_stats_matches` +table. -If you are using an external web panel, **this plugin is not needed** as most external applications record to their own match tables. \ No newline at end of file +If you are using an external web panel, **this plugin is not needed** as most external applications record to their own +match tables.