From 7ea3300d024c9b88d7470f4b88a53e3966296ad4 Mon Sep 17 00:00:00 2001 From: PhlexPlexico Date: Sun, 26 Jun 2022 16:27:35 -0600 Subject: [PATCH] Create Github Pages Documentation (#752) * Include basic mkdocs installation. Update build to use one run instead of multiple. TODO: Update build job to build and host files with GH Pages. * Documentation conversion. Start with essentials. Include build job for github pages. Update example match json for new map pool. * Update mkdocs and github action. * Update published directory. * Try once more. * Change to a different build process. * Another build change? * Include space for commands for proper formatting. * Remove redunant text in README and point to docs site. * Swap URL. * Branch update. * Include colours from the utils class. --- .github/workflows/build.yml | 30 ++-- .github/workflows/generate_docs.yml | 21 +++ README.md | 191 +--------------------- configs/get5/example_match.json | 4 +- documentation/docs/commands.md | 44 +++++ documentation/docs/developer_api.md | 58 +++++++ documentation/docs/event_logs.md | 163 ++++++++++++++++++ documentation/docs/get5_configuration.md | 87 ++++++++++ documentation/docs/index.md | 3 + documentation/docs/installation.md | 18 ++ documentation/docs/match_configuration.md | 45 +++++ documentation/docs/match_schema.md | 111 +++++++++++++ documentation/docs/stats_system.md | 53 ++++++ documentation/mkdocs.yml | 17 ++ 14 files changed, 638 insertions(+), 207 deletions(-) create mode 100644 .github/workflows/generate_docs.yml create mode 100644 documentation/docs/commands.md create mode 100644 documentation/docs/developer_api.md create mode 100644 documentation/docs/event_logs.md create mode 100644 documentation/docs/get5_configuration.md create mode 100644 documentation/docs/index.md create mode 100644 documentation/docs/installation.md create mode 100644 documentation/docs/match_configuration.md create mode 100644 documentation/docs/match_schema.md create mode 100644 documentation/docs/stats_system.md create mode 100644 documentation/mkdocs.yml diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 40962bd19..070f1413c 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -20,22 +20,22 @@ jobs: with: version: '1.10.x' - - run: wget $STEAMWORKS_URL -P steamworks + - run: | + wget $STEAMWORKS_URL -P steamworks + mkdir -p $OUTPUT_SM_PATH/plugins/disabled + cp -R get5/cfg $OUTPUT_PATH + cp -R get5/translations $OUTPUT_SM_PATH + cp -R get5/configs $OUTPUT_SM_PATH + cp -R get5/scripting $OUTPUT_SM_PATH + cp get5/README.md $OUTPUT_PATH + cp get5/LICENSE $OUTPUT_PATH + spcomp get5/scripting/get5.sp -i steamworks -i $SM_JSON_INC_PATH -o $OUTPUT_SM_PATH/plugins/get5.smx + spcomp get5/scripting/get5_apistats.sp -i steamworks -i $SM_JSON_INC_PATH -o $OUTPUT_SM_PATH/plugins/disabled/get5_apistats.smx + spcomp get5/scripting/get5_mysqlstats.sp -i steamworks -i $SM_JSON_INC_PATH -o $OUTPUT_SM_PATH/plugins/disabled/get5_mysqlstats.smx - - run: mkdir -p $OUTPUT_SM_PATH/plugins/disabled - - run: cp -R get5/cfg $OUTPUT_PATH - - run: cp -R get5/translations $OUTPUT_SM_PATH - - run: cp -R get5/configs $OUTPUT_SM_PATH - - run: cp -R get5/scripting $OUTPUT_SM_PATH - - run: cp get5/README.md $OUTPUT_PATH - - run: cp get5/LICENSE $OUTPUT_PATH - - run: spcomp get5/scripting/get5.sp -i steamworks -i $SM_JSON_INC_PATH -o $OUTPUT_SM_PATH/plugins/get5.smx - - run: spcomp get5/scripting/get5_apistats.sp -i steamworks -i $SM_JSON_INC_PATH -o $OUTPUT_SM_PATH/plugins/disabled/get5_apistats.smx - - run: spcomp get5/scripting/get5_mysqlstats.sp -i steamworks -i $SM_JSON_INC_PATH -o $OUTPUT_SM_PATH/plugins/disabled/get5_mysqlstats.smx - - - run: mkdir -p artifacts - - run: tar -zcvf artifacts/get5.tar.gz $OUTPUT_PATH/ - - run: zip -r artifacts/get5.zip $OUTPUT_PATH/ + mkdir -p artifacts + tar -zcvf artifacts/get5.tar.gz $OUTPUT_PATH/ + zip -r artifacts/get5.zip $OUTPUT_PATH/ - uses: actions/upload-artifact@v2 with: diff --git a/.github/workflows/generate_docs.yml b/.github/workflows/generate_docs.yml new file mode 100644 index 000000000..9bb6773ae --- /dev/null +++ b/.github/workflows/generate_docs.yml @@ -0,0 +1,21 @@ +name: Publish MKDocs to GH Pages +on: + push: + branches: + - master + +jobs: + build: + name: Deploy docs + runs-on: ubuntu-latest + steps: + - name: Checkout main + uses: actions/checkout@v2 + + - name: Deploy docs + uses: mhausenblas/mkdocs-deploy-gh-pages@master + # Or use mhausenblas/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + CONFIG_FILE: documentation/mkdocs.yml + EXTRA_PACKAGES: build-base \ No newline at end of file diff --git a/README.md b/README.md index 9d4bea17f..1265ff6b0 100644 --- a/README.md +++ b/README.md @@ -32,196 +32,7 @@ Features of this include: Get5 also aims to make it easy to build automation for it. Commands are added so that a remote server can manage get5, collect stats, etc. The [get5 web panel](https://github.com/splewis/get5-web) is an (functional) proof-of-concept for this. ## Download and Installation - -#### Requirements -You must have sourcemod installed on the game server. You can download it at http://www.sourcemod.net/downloads.php. Note that sourcemod also requires MetaMod:Source to be on the server. You can download it at http://www.metamodsource.net/downloads.php. You must have a 1.9+ build of sourcemod. - -#### Download -Download a release package from the [releases section](https://github.com/splewis/get5/releases) or [the latest development build](https://github.com/splewis/get5/actions/workflows/build.yml?query=branch%3Amaster++) (click the latest successful build from `branch:master` and download the artifact called `build`). - -Release and development builds are currently compiled against sourcemod 1.10 and should work on sourcemod 1.10 or later. - -#### Installation -Extract the download archive into the csgo/ directory on the server. 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. - -If you need more help, see the [step-by-step guide in the wiki](https://github.com/splewis/get5/wiki/Step-by-step-installation-guide). - -#### Optional steps/plugins - -The get5 releases contain 2 additional plugins, disabled by default. They are in ``addons/sourcemod/plugins/disabled``. To enable one, move it up a directory to ``addons/sourcemod/plugins``. - -##### get5_apistats - -``get5_apistats`` is for integration with the [get5 web panel](https://github.com/splewis/get5-web). You don't need it unless you're using the web panel. Note you need the [Steamworks](https://forums.alliedmods.net/showthread.php?t=229556) extension for this plugin. - -**NOTE**: The HTTP API requests this plugin sends are **not** part of a public API. They are the communication between this plugin and the [get5-web](https://github.com/splewis/get5-web) project; you should not rely on the API being stable. If you're a developer writing your own server listening to get5_apistats, consider forking the get5_apistats plugin and renaming it to something else. - -##### get5_mysqlstats - -``get5_mysqlstats``: is an optional plugin for recording match stats. To use it, create a "get5" section in your ``addons/sourcemod/configs/databases.cfg`` file and use [these MySQL commands](misc/import_stats.sql) to create the tables. You can also set ``get5_mysql_force_matchid`` to a matchid to make get5 ignore the matchid in match configs, and use the one in the cvar. Otherwise, the matchid will be set based on matchid returned by MySQL from the SQL ``insert`` statement. - - -## Quickstart - -To use get5, you generally create a [match config](https://github.com/splewis/get5#match-schema). In this file, you'll set up the match - what players, what map(s), etc. - - -Once you create the match config anywhere under the server's ``csgo`` directory, run ``get5_loadmatch `` in the server console. Everything will happen automatically after that. - -If you don't want to create a match config, you can set ``get5_check_auths 0`` in ``cfg/sourcemod/get5.cfg`` and then run the ``get5_creatematch`` command once all players are in the server. - -Alternatively, you can also up your server for [scrims](https://github.com/splewis/get5/wiki/Using-get5-for-scrims) by creating a scrim template specifying your team and run ``get5_scrim`` in console. - -The ``!get5`` command in-game will let you run the ``get5_creatematch`` and ``get5_scrim`` via a simple menu. - - -## 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). - -#### Client Commands (these can be typed by all players in chat) -- ``!ready``: marks a client's team as ready to begin -- ``!unready``: marks a client's team as not-ready -- ``!pause``: requests a freezetime pause -- ``!unpause``: requests an unpause, requires the other team to confirm -- ``!tech``: requests a technical pause (technical pauses have no time limit or max number of uses) -- ``!coach``: moves a client to coach for their team -- ``!stay``: elects to stay after a knife round win -- ``!swap`` or ``!switch``: elects to swap team side after a knife round win -- ``!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 - -#### Server/Admin Commands (meant to be used by admins in console) -- ``get5_loadmatch``: loads a match config file (JSON or keyvalues) relative from the ``csgo`` directory -- ``get5_loadbackup``: loads a get5 backup file -- ``get5_loadteam``: loads a team section from a file into a team -- ``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 ``configs/get5/scrim_template.cfg`` -- ``get5_addplayer``: adds a steamid to a team (any format for steamid) -- ``get5_removeplayer``: removes a steamid from all teams (any format for steamid) -- ``get5_addkickedplayer``: adds the last kicked steamid to a team -- ``get5_removekickedplayer``: removes the last kicked steamid from all teams -- ``get5_forceready``: marks all teams as ready -- ``get5_dumpstats``: dumps current match stats to a file -- ``get5_status``: replies with JSON formatted match state (available to all clients) -- ``get5_listbackups``: lists backup files for the current matchid or a given matchid - -#### Other commands - -- ``!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. - -## Match Schema - -See the example config in [Valve KeyValues format](configs/get5/example_match.cfg) or [JSON format](configs/get5/example_match.json) to learn how to format the configs. Both example files contain equivalent match data. - -Of the below fields, only the ``team1`` and ``team2`` fields are actually required. Reasonable defaults are used for entires (bo3 series, 5v5, empty strings for team names, etc.) - -- ``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 -- ``skip_veto``: whether the veto will be skipped and the maps will come from the maplist (in the order given) -- ``veto_first``: either "team1", or "team2". If not set, or set to any other value, team 1 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 -- ``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 ``mp_teamprediction_pct`` -- ``favored_percentage_text`` wrapper for ``mp_teamprediction_txt`` -- ``cvars``: cvars to be set during the match warmup/knife round/live state -- ``spectators``: see the team schema below (only the ``players`` and ``name`` sections are used for spectators) -- ``team1``: see the team schema below -- ``team2``: see the team schema below - -Fields you may use, you aren't generally needed to: -- ``match_title``: wrapper on the ``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. - -#### Team Schema -Only ``name`` and ``players`` are required. - -- ``name``: team name (wraps ``mp_teamname_1`` and is displayed often in chat messages) -- ``tag``: team tag (or short name), this replaces client "clan tags" -- ``flag``: team flag (2 letter country code, wraps ``mp_teamflag_1``) -- ``logo`` team logo (wraps ``mp_teamlogo_1``) -- ``players``: 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 steamids to names. -- ``series_score``: 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 - -There is advice on handling these match configs in [the wiki](https://github.com/splewis/get5/wiki/Managing-match-configs). - -Instead of the above fields, you can also use "fromfile" and a filename, where that file contains the other above fields. This is available for both json and keyvalue format.s - -## ConVars -These are auto-executed on plugin start by the auto-generated (the 1st time the plugin starts) file ``cfg/sourcemod/get5.cfg``. - -Please see [the wiki](https://github.com/splewis/get5/wiki/Full-list-of-get5-cvars) for a full list of cvars. You may also just look at the ``cfg/sourcemod/get5.cfg`` file directly on your server and see the cvar descriptions and values in the autogenerated file. - -You should either set these in the above file, or in the match config's ``cvars`` section. - -Note: cvars set in the ``cvars`` section will override other settings (standard CS:GO cvars are also supported). - -## 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](scripting/include/get5.inc). This is exactly what the [get5_apistats](scripting/get5_apistats.sp) and [get5_mysqlstats](scripting/get5_mysqlstats.sp) plugins do. Consider starting from those plugins and making any changes you want (forking the get5 plugin itself is strongly discouraged; but just making another plugin using the get5 plugin api like get5_apistats does is encouraged). - -1. You can read [event logs](https://github.com/splewis/get5/wiki/Event-logs) from a file on disk (set by ``get5_event_log_format``), through a RCON -connection to the server console since they are output there, or through another sourcemod plugin (see #1). - -1. You can read the [stats](https://github.com/splewis/get5/wiki/Stats-system) get5 collects from a file on disk (set by ``get5_stats_path_format``), or through another sourcemod plugin (see #1). - -1. 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 part -- `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. - - **0** - No setup has taken place. - - **1** - Warmup, waiting for the veto. - - **2** - Warmup, doing the veto. - - **3** - Setup done, waiting for players to ready up. - - **4** - In the knife round. - - **5** - Waiting for a !stay or !swap command after the knife. - - **6** - In the lo3 process. - - **7** - The match is live. - - **8** - Postgame screen + waiting for GOTV to finish broadcast. -- `paused`: Is the match paused? -- `gamestate_string`: A human-readable gamestate which is a translation of `gamestate`. - - `"none"` - - `"waiting for map veto"` - - `"map veto"` - - `"warmup"` - - `"knife round"` - - `"waiting for knife round decision"` - - `"going live"` - - `"live"` - - `"postgame"` - -#### Additional parts - -**If current game state isn't "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`. -- `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 in the team. - - `current_map_score`: The team's score on the current map. - -**If current game state is past the veto** -- `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). +To see how to download and use Get5 on your game server, please visit the [documentation website](https://splewis.github.io/get5). ## Other things diff --git a/configs/get5/example_match.json b/configs/get5/example_match.json index f6484d154..869a07348 100644 --- a/configs/get5/example_match.json +++ b/configs/get5/example_match.json @@ -19,13 +19,13 @@ "maplist": [ - "de_cache", "de_dust2", "de_inferno", "de_mirage", "de_nuke", "de_overpass", - "de_train" + "de_train", + "de_vertigo" ], "favored_percentage_team1": 65, diff --git a/documentation/docs/commands.md b/documentation/docs/commands.md new file mode 100644 index 000000000..17522c8bf --- /dev/null +++ b/documentation/docs/commands.md @@ -0,0 +1,44 @@ +# 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`). + +## Client Commands +Please note that these can be typed by *all players* in chat. + +- `!ready`: Marks a client's team as ready to begin. +- `!unready`: Marks a client's team as not-ready. +- `!pause`: Requests a freeze time pause. Pauses can be modified in the Get5 config. +- `!unpause`: Requests an unpause, requires the other team to confirm if pauses are not timed. +- `!tech`: Requests a technical pause. These can be modified in the Get5 config. +- `!coach`: Moves a client to coach for their team. +- `!stay`: Elects to stay after a knife round win. +- `!swap`: Elects to swap team side after a knife round win. +- `!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. + +## 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_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_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 +- `get5_removekickedplayer`: Removes the last kicked steamid from all teams, cannot be used in scrim mode. +- `get5_forceready`: Marks all teams as ready. +- `get5_forcestart`: Same as `get5_forceready`. +- `get5_dumpstats`: Dumps current match stats to a file. +- `get5_status`: Replies with JSON formatted match state (available to all clients). +- `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**. diff --git a/documentation/docs/developer_api.md b/documentation/docs/developer_api.md new file mode 100644 index 000000000..8f2f8611a --- /dev/null +++ b/documentation/docs/developer_api.md @@ -0,0 +1,58 @@ +# 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! + +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). + +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. + - **0**: No setup has taken place. + - **1**: Warmup, waiting for the veto. + - **2**: Warmup, doing the veto. + - **3**: Setup done, waiting for players to ready up. + - **4**: In the knife round. + - **5**: Waiting for a !stay or !swap command after the knife. + - **6**: In the lo3 process. + - **7**: The match is live. + - **8**: Postgame screen + waiting for GOTV to finish broadcast. +- `paused`: Is the match paused? +- `gamestate_string`: human-readable gamestate which is a translation of `gamestate`. + - `"none"` + - `"waiting for map veto"` + - `"map veto"` + - `"warmup"` + - `"knife round"` + - `"waiting for knife round decision"` + - `"going live"` + - `"live"` + - `"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`. +- `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. + +*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 diff --git a/documentation/docs/event_logs.md b/documentation/docs/event_logs.md new file mode 100644 index 000000000..9daf60358 --- /dev/null +++ b/documentation/docs/event_logs.md @@ -0,0 +1,163 @@ +# 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. + +An `event` is a json object that looks something like this: +```json +{ + "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`. + +## 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: +```log +L 11/26/2016 - 02:58:39: { + "matchid": "example_match", + "event": "series_start", + "params": { + "team1_name": "EnvyUs", + "team2_name": "Fnatic" + } +} +``` +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 +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`: + - `team1_name`: The formatted team name for `team1` + - `team2_name`: The formatted team name for `team2` +- `series_end`: + - `team1_series_score`: The score of the series for `team1` (how many maps won). + - `team2_series_score`: The score of the series for `team2` (how many maps won). + - `winner`: Either `"team1"`, `"team2"`, or `"none"`. +- `series_cancel`: Called if a series is cancelled. + - `team1_series_score`: The score of the series for `team1` (how many maps won). + - `team2_series_score`: The score of the series for `team2` (how many maps won). +- `map_veto`: + - `team`: Either `"team1"`, `"team2"` or `"none"` if it is a decider. + - `map_name`: The name of the map being vetoed. +- `map_pick`: + - `team`: Either `"team1"`, `"team2"` or `"none"` if it is a decider. + - `map_name`: The name of the map being vetoed. + - `map_number`: The map number of which it will be played in the series. +- `side_picked`: + - `team`: Either `"team1"`, `"team2"` or `"none"` if it is a decider. + - `map_name`: The name of the map being vetoed. + - `map_number`: The map number of which it will be played in the series. + - `side`: The enum for the side selected. Either `CS_TEAM_CT` or `CS_TEAM_T`. + +### Map Flow + +- `knife_start` + - `map_name`: The name of the map being vetoed. + - `map_number`: The current map number. +- `knife_won`: + - `map_name`: The name of the map being vetoed. + - `map_number`: The current map number. + - `winner`: Either `"team1"`, `"team2"`, or `"none"`. + - `selected_side`: The enum for the side selected. Either `CS_TEAM_CT` or `CS_TEAM_T`. +- `going_live`: + - `map_name`: The name of the map being vetoed. + - `map_number`: The current map number. +- `round_end`: + - `map_name`: The name of the map being vetoed. + - `map_number`: The current map number. + - `winner_side`: String value of which team won. Either `"T"` or `"CT"`. + - `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) +- `side_swap`: + - `map_name`: The name of the map being vetoed. + - `map_number`: The current map number. + - `team1_side`: String value of which team is on which side. Either `"T"` or `"CT"`. + - `team2_side`: String value of which team is on which side. Either `"T"` or `"CT"`. + - `team1_score`: The current score for `team1`. + - `team2_score`: The current score for `team2`. +- `map_end`: + - `map_name`: The name of the map being vetoed. + - `map_number`: The current map number. + - `winner`: Either `"team1"`, `"team2"`. + - `team1_score`: The current score for `team1`. + - `team2_score`: The current score for `team2`. +- `pause_command`: Called when a team calls any type of pause. + - `request_team`: Either `"team1"`, `"team2"` or `"none"`. + - `pause_reason`: Either `"technical"` or `"tactical"`. + - `map_name`: The name of the map being vetoed. + - `map_number`: The current map number. +- `unpause_command`: Called when a team calls unpause. + - `request_team`: Either `"team1"`, `"team2"` or `"none"`. + - `map_name`: The name of the map being vetoed. + - `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. + - `attacker`: The name plus steam ID of the attacker. + - `victim`: The name plus steam ID of the victim. + - `headshot`: Boolean value if the death was from a headshot. + - `weapon`: String value of the weapon used. + - `assister`: The name plus steam ID of an optional assister. + - `flash_assister`: The name plus steam ID of an optional flashbang assister. +- `bomb_planted`: + - `map_name`: The name of the map being vetoed. + - `map_number`: The current map number. + - `client`: The name plus steam ID of the client who planted the bomb. + - `site`: Either `"A"` or `"B"`. +- `bomb_defused`: + - `map_name`: The name of the map being vetoed. + - `map_number`: The current map number. + - `client`: The name plus steam ID of the client who defused the bomb. + - `site`: Either `"A"` or `"B"`. +- `bomb_exploded`: + - `map_name`: The name of the map being vetoed. + - `map_number`: The current map number. + - `client`: The name plus steam ID of the client who planted the bomb. + - `site`: Either `"A"` or `"B"`. +- `client_say`: Whenever a client says something in text chat, either team or all chat. + - `map_name`: The name of the map being vetoed. + - `map_number`: The current map number. + - `client`: The name plus steam ID of the client who sent a message. + - `message`: The message that the client had said. +- `player_connect`: + - `map_name`: The name of the map being vetoed. + - `map_number`: The current map number. + - `client`: The name plus steam ID of the client who connected. + - `ip`: String value of the client's IP address. +- `player_disconnect`: + - `map_name`: The name of the map being vetoed. + - `map_number`: The current map number. + - `client`: The name plus steam ID of the client who disconnected. + +### Miscellaneous + +- `match_config_load_fail`: + - `reason`: Reason as to why the match configuration failed to load. +- `backup_loaded`: + `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 diff --git a/documentation/docs/get5_configuration.md b/documentation/docs/get5_configuration.md new file mode 100644 index 000000000..550eb47c1 --- /dev/null +++ b/documentation/docs/get5_configuration.md @@ -0,0 +1,87 @@ +# 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. + +## 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_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_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_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` + +### Substitution Variables +Valid substitutions into the above file name formatting cvars (when surrounded by {}): + +- `TIME` +- `MAPNAME` +- `MAPNUMBER` +- `MATCHID` +- `TEAM1` +- `TEAM2` +- `MATCHTITLE` + +#### Colour Substitution Variables +This project also includes substitution variables for colour in text chat (when surrounded by {}): + +- `{NORMAL}` +- `{DARK_RED}` +- `{PINK}` +- `{GREEN}` +- `{YELLOW}` +- `{LIGHT_GREEN}` +- `{LIGHT_RED}` +- `{GRAY}` +- `{ORANGE}` +- `{LIGHT_BLUE}` +- `{DARK_BLUE}` +- `{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_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. + +## 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. + +## 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_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.* + +- `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_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). + +### 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_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_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_message_prefix`: The tag applied before plugin messages, default is `Get5`. diff --git a/documentation/docs/index.md b/documentation/docs/index.md new file mode 100644 index 000000000..db5eb7112 --- /dev/null +++ b/documentation/docs/index.md @@ -0,0 +1,3 @@ +# 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. diff --git a/documentation/docs/installation.md b/documentation/docs/installation.md new file mode 100644 index 000000000..9bc189b13 --- /dev/null +++ b/documentation/docs/installation.md @@ -0,0 +1,18 @@ +# 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. + +## 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). + +## 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. + +### 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". + +Congratulations, get5 is now installed on your server, and you can continue to [Configuration](./match_configuration.md). \ No newline at end of file diff --git a/documentation/docs/match_configuration.md b/documentation/docs/match_configuration.md new file mode 100644 index 000000000..c9d86d10f --- /dev/null +++ b/documentation/docs/match_configuration.md @@ -0,0 +1,45 @@ +# 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. + +## 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. + +*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: + +`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). + +### 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". + +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 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`. + +### 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`. + +## 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 diff --git a/documentation/docs/match_schema.md b/documentation/docs/match_schema.md new file mode 100644 index 000000000..bd4c2df7e --- /dev/null +++ b/documentation/docs/match_schema.md @@ -0,0 +1,111 @@ +# 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.). + +## 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. + +- `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. + +## 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 +- `skip_veto`: Whether the veto will be skipped and the maps will come from the maplist (in the order given). +- `veto_first`: Either "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. +- `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. + +## 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. + +### 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. + +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. + +Here is an example `match.cfg` that includes `fromfile`: + +```cfg +"Match" +{ + + "maps_to_win" "1" + "skip_veto" "0" + "side_type" "standard" + + "maplist" + { + "de_cache" "" + "de_cbble" "" + "de_dust2" "" + "de_mirage" "" + "de_nuke" "" + "de_overpass" "" + "de_train" "" + } + + "players_per_team" "5" + + "team1" + { + "fromfile" "addons/sourcemod/configs/get5/team_nip.cfg" + } + + "team2" + { + "fromfile" "addons/sourcemod/configs/get5/team_nv.cfg" + } + + "cvars" + { + "hostname" "Match server #1" + } +} +``` + +Inside the `team_nip.cfg` would be the following: +```cfg +"team" +{ + "name" "NiP" + "flag" "SE" + "logo" "nip" + "matchtext" "" + "players" + { + "STEAM_1:1:52245092" "" + } +} +``` + +And inside `team_nv.cfg` would be the following: +```cfg +"team" +{ + "name" "EnvyUs" + "flag" "FR" + "logo" "nv" + "matchtext" "" + "players" + { + "STEAM_1:0:78189799" "" + } +} +``` +Please note that this works for both KeyValue and JSON formatted configs. \ No newline at end of file diff --git a/documentation/docs/stats_system.md b/documentation/docs/stats_system.md new file mode 100644 index 000000000..46eb80e01 --- /dev/null +++ b/documentation/docs/stats_system.md @@ -0,0 +1,53 @@ +# 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). + +## 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. + +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. + +Partial Example: +``` +"Stats" +{ + "series_type" "bo1" + "team1_name" "EnvyUs" + "team2_name" "Fnatic" + "map0" + { + "mapname" "de_mirage" + "winner" "team1" + "team1" + { + "score" "5" + "73613643164646" + { + "name" "xyz" + "kills" "0" + "deaths" "1" + "assists" "5" + "damage" "352" + } + } + } +} +``` + +## 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. + +## 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). +- 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`. + +**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 diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml new file mode 100644 index 000000000..1f9c66df5 --- /dev/null +++ b/documentation/mkdocs.yml @@ -0,0 +1,17 @@ +site_name: Get5 Documentation +site_url: https://splewis.github.io/get5 +repo_url: https://github.com/splewis/get5 +repo_name: get5 +theme: + name: readthedocs + +nav: + - Home: index.md + - Commands: commands.md + - Developer API: developer_api.md + - Event Logs: event_logs.md + - Get5 Configuration: get5_configuration.md + - Installation: installation.md + - Match Configuration: match_configuration.md + - Match Schema: match_schema.md + - Player Stats System: stats_system.md