Valve Admin Requirements

From Valve Developer Community
Jump to: navigation, search

Valve Admin Requirements Document


Overview

1.1 This document presents the framework for a set of requirements to build Valve Admin: A simple to use, elegant, and powerful administration tool that Server Administrators running Valve-created multiplayer (MP) first person shooter (FPS) games like Counter-Strike: Source and Day of Defeat: Source can use to administer their servers.

1.2 The backbone of a good fps gaming experience starts and ends with the combination of a good game and a good server run by competent server administrators. It's acknowledged that in addition to tools required to control regular administrative functions (like map changes, FF rules, player lists, etc) administrators also need simple tools to combat certain players who connect to servers just to perform unwanted and undesirable activities (team killers, cheating, voice spam, etc).

1.3 Current Valve server tools are inadequate. They are overly powerful and non-intuitive for the common server administrator. Many Source-game based servers suffer from a lack of oversight which creates animosity in the playing community that can have an adverse effect on the gaming experience and, eventually, sales. Much of this is attributable to a lack of quality administrative tools.

1.4 For reasons already noted, it is desirable to not overly-complicate this tool. Thus, scope will be limited to essential and high priority/need commands that have been identified from the player/admin community. Additionally, the Valve Admin (VA) tool should do no harm. It is not desirable to denigrate or otherwise abuse players. Thus, the VA shall not have any functions that are arbitrary or retributive in nature. Nor will it allow administrators the ability to do harm to the player's (client's) PC.

General Application Rules

2.1 A GUI shell menu will be created that is fully customizable so administrators can develop their own tree structure and tie each command to a menu choice. All commands will be available to the administrator to incorporate and execute from a GUI menu.

2.2 Every command will be executable from the command line.

2.3 All files, folders, etc… will be located within the …/cfg dir.

2.4 Syntax will be consistent. IE all commands starting 'va_'

2.5 Syntax will be intuitive, in terms of naming.

2.6 Whenever an admin action is taken in-game, a record must be written that includes:

2.6.1 Name of admin who took the action
2.6.2 Steam ID of admin who took the action
2.6.3 Name of player who was acted on
2.6.4 Steam ID of player who was acted on
2.6.5 Notation of the type of action
2.6.6 Date/Time stamp of when the action occurred

2.7 Since many servers are Linux, case-sensitivity must be treated in a consistent manner.

2.7.1 Syntax will be lower-case, always, unless noted.

2.8 All functions must be 'highlander' optional. Meaning that per security settings, a function will be disabled if a higher security level user is on.

2.9 All commands where a player name can be used, should use autocomplete/pattern matching. IE: To kick player 'mugsy', the admin can enter va_kick mugs and that will kick 'mugsy' so long as there is no other player with 'mugs' as a string in their name.

2.9.1 If there is another player so that the string is non-unique, return this message: "Player name is not unique"

2.10 All commands must give an appropriate console message indicating whether they completed correctly or not.

Glossary

Profile 
A security level that a name or steam_id can be assigned to for the purpose of granting them rights to specific functions.

Functional Requirements

Profiles

4.1.1 Different security levels (‘profiles’) can be defined in the admin.cfgs.

4.1.2 Access to functions granted per defined profile in the admin.cfgs.

4.1.3 The stock profile is "public" and does not have specified users. It applies to any Steam_ID not assigned to another existing profile.

4.1.4 Individual, unique Steam_IDs and/or names assigned can be assigned to all profiles.

4.1.4.1 Individuals are validated by Steam_ID, exact name, or both in conjunction with a password (‘PW’).
4.1.4.2 If name criteria are used, there will be a toggle to allow names that have the reserved name as part of their larger name on the server or not.
       IE: You have a protected name of 'Mugsy'.
           If the larger name is not allowed,
           then user 'MugsyWugsy' would not be
           allowed on the server unless there was
           a PW match.  If allowed then 'MugsyWugsy'
           would be allowed on the server.
4.1.4.2.1 Default value will be to not allow the larger name.
4.1.4.2.2 If the allowed larger name user later changed their name to the protected name, they would be kicked.

4.1.5 All Steam_ID’s trying to join the server will validate to see to which profile they belong.

4.1.6 Any Steam_ID that is kicked or not allowed on the server due to failing validation must be given the following message in the console: "Access to server denied due to security. Contact a server administrator."

Kicking

4.2.1 Admin may kick from the console or the GUI menu.

4.2.1.1 May kick by name from GUI or console
4.2.1.2 May kick by Steam_ID from the console

4.2.2 When an admin kicks a Steam_ID, display the following message in say_all: "[Name of removed Steam_ID] was kicked by [Name of admin who kicked]"

4.2.2.1 When a player is kicked from the server, the player will receive a message in their console: "You have been kicked by [Name of Admin]

4.2.3 When a recently admin-kicked Steam_ID returns, display the following message: "[Name of removed Steam_ID]/[Steam_ID] was recently kicked and has rejoined the server."

4.2.4 Write all kicks to a distinct file.

4.2.5 Regardless of how admin kicks, the system always logs kick by Steam_ID.

Banning

4.3.1 Admin may ban from the console or the GUI menu.

4.3.1.1 May ban by name from GUI or console
4.3.1.2 May ban by Steam_ID from the console

4.3.2 Admin may ban by defined time increments in the GUI:

4.3.2.1 Options for time increments must be defined in the admin.cfg.

4.3.3 When banning from the GUI, a reason will be required. This will be input via a pop-up box.

4.3.4 Admin may ban by any time if ban is entered from console. This includes permanent bans.

4.3.4.1 Suggested syntax: va_ban STEAM_ID Minutes "Reason"
       IE:  va_ban STEAM_0:0:11125 240 "ban for nading spawn"  would ban for 240 minutes.
            va_ban STEAM_0:0:11126 0 "ban for racist language" would be a permanent ban.
4.3.4.2 "Steam_ID" formatted so that an admin can cut/paste this from the status.

4.3.5 Regardless of how admin ban, the system logs bans by Steam_ID.

4.3.6 When an admin bans a Steam_ID, display the following message in say_all: "[Name of removed Steam_ID] was banned by [Name of admin who kicked]"

4.3.7 Write all bans to a distinct file.

4.3.8 Must be able to unban from console by Steam_ID. 

       IE:  va_unban STEAM_0:0:11126

4.3.9 When a player is banned from the server, the player will receive a message in their console. The message will be set in the va configuration.

4.3.9.1 When a banned player tries to join the server, they should be disconnected with this same message.

TK Management

Friendly-fire is a very popular and widely used option. Admins need a way to easily and efficiently deal with players who try to ruin gameplay by intentionally TKing.

4.4.1 When a TK occurs the player who was TK’d gets two options displayed on the screen:

"1. Forgive TK
2. Do not forgive"
4.4.1.1 These choices shall only appear for a number of seconds determined in the admin.cfg
4.4.1.2 A victim can forgive by typing "forgivetk" in team_say.
4.4.1.3 If the victim forgives, then a message will be displayed in say_team: "[VICTIM PLAYER] has forgiven [TKer]"

4.4.2 Kick a Steam_ID after X amount of unforgiven TKs.

4.4.2.1 X = number of unforgiven TKs before a Steam_ID is kicked from the server per time in 3.4.2.2.
4.4.2.1.1 If X = 0, then the functionality of kicking a player for TKs will be ignored and the ban logic will be used.
4.4.2.2 A variable in the .cfg will determine whether to reset counter at map change or continue to accrue unforgiven TKs.

4.4.3 Ban a Steam_ID after X amount of unforgiven TKs for Z amount of time.

4.4.3.1 X = number of unforgiven TKs before a Steam_ID is banned from the server per time in 3.1.2.2
4.4.3.2 A variable in the .cfg will determine whether to reset counter at map change or continue to accrue unforgiven TKs.
4.4.3.3 Z = the length of the ban.
4.4.3.4 As part of the act of banning the Steam_ID, it must also be kicked off the server.

4.4.4 When a Steam_ID is kicked or banned due to TKs, a message will be displayed in say_all: "[Name of removed Steam_ID] was removed due to unforgiven TKs."

4.4.5 Write all kick/bans due to TKs to a distinct log file.

4.4.6 VA will use the TK ban functionality on players who've already been kicked due to excessive TKS.

4.4.6.1 Exception would be if the TK kick functionality is "off" per 4.4.2.1.1.

4.4.7 From console, a command to forgive tks for any player on the server. IE: A steam_id has 3 tks. The admin wishes to forgive the player, so in console he types: va_forgivetk "playername". Each entry will forgive all TKs of the targeted player.

4.4.8 A config setting, va_attacker. If set to "1", then anytime a player hurts a friendly player, the following message displays: "[attacking player] injured teammate, [injured player]".

Messaging/Chat

4.5.1 Messaging between players ("chat")

4.5.1.1 Admin only chat. Who is admin is defined by profile.
4.5.1.2 Member (or secondary) chat. Who is member is defined by profile.
4.5.1.3 Private messaging between players.
4.5.1.4 Chat types will have colors that are unique, as well as distinct from the say_team and say_all colors.

4.5.2 Messaging to the server

4.5.2.1 Ability to send messages that will be read by the entire server.
4.5.2.2 Ability to have a default list of stock messages that can be defined in the configs that can be read by the entire server, available in GUI.
4.5.2.3 Ability to send messages from the GUI or the console.
4.5.2.4 Messages will default with the senders name appended to the front.
       IE:  (Shane) Watch the language please
4.5.2.5 Messages will be anonymous if there is an @ at the beginning.
4.5.2.6 Messages will either be centered or at the lower left of screen, above the chat display.
4.5.2.7 Default color will be green
4.5.2.8 Messages will have the following additional color choices: red, blue , orange, yellow, purple. Change the color simply by appending the message with your color choice.
       IE:  va_csay "red Watch the language please" would show as "(Shane) Watch the language please"
4.5.2.9 Message must be able to process anonymous and color option in the same message.
       IE:  va_csay "@ red Watch the language please" would show as "Watch the language please"
4.5.2.10 User can choose between 3 sizes for the messages: small, regular, large.
4.5.2.10.1 This is fixed for all messages on the server at the config level.

4.5.3 Recurring messages

4.5.3.1 Users will be able to set up recurring messages at the config level.
4.5.3.2 Messages will either be centered or at the lower left of screen, above the chat display.
4.5.3.3 Message will be displayed at a timed interval.
4.5.3.3.1 Interval will be per map cycle.
4.5.3.3.2 Will have a start value: At what time after map rotation is message sent
4.5.3.3.3 Will have an interval value: This is how often the message is again to be sent. "0" would mean the message is sent only once.

4.5.4 From console, allowed user can turn alltalk on/off.

Secure slots

4.6.1 Use of reserved slots must be turned on in the admin.cfgs.

4.6.2 There will be 3 types of slots: "Public," "Reserved," and "Private".

4.6.2.1 Public slots are open for anyone.
4.6.2.2 Reserved slots are open to those granted access by their profile.
4.6.2.3 Private slots are open to those granted access by their profile.

4.6.3 The quantity of each type of slot is determined in the admin.cfgs

4.6.3.1 Hierarchy of importance is: private, reserved, public

4.6.4 Slots are structured as follows. IE: A 22-man server with 16 public slots, 4 reserved, and 2 private. This means: *Slots 1-16 are open for anyone. *Slots 17-20 can only be taken by reserved slot holders. *Slots 21-22 can only be taken by private slot holders.

4.6.4.1 This is only considered when someone joins a server. Once on they cannot be kicked to free slots.

IE: From the above example, 15 people are on. Bob, who has a public slot joins, taking the server to 16. Next, Steve, a reserved slots joins, bringing the server to 17. Bob is not kicked. Nor will he be if the server goes all the way to 22 players. However, once above 16, Bob’s friend, Jerry, who has a public slots, cannot join.

4.6.5 In the server browser the user will see player limits per server based on his profile for each server.

4.6.5.1 So far as it is discernable, this will done in a way to make them not show on 3rd party browsers, or give those browsers and easy way to identify and remove private slots from view.

Maps / Map voting

4.7.1 A command that will switch to a different map from either the GUI or the console.

4.7.2 Mapvoting is optional, set at admin.cfg.

4.7.3 A command that will start a mapvote from either the GUI or the console.

4.7.3.1 Corresponding say_all message "Bob has started a mapvote"

4.7.4 A value for when mapvoting starts.

4.7.4.1 Corresponding say_all message "You may now nominate a map for voting" 1 minute prior to the start of the vote.
4.7.4.1.1 If map vote was initiated from the GUI or console, delay this message 30 seconds.

4.7.5 Players can nominate maps.

4.7.5.1 5 nominated maps will be put to vote
4.7.5.2 2 nominations max, per player
4.7.5.2.1 Corresponding say_all message "Bob has nominated dod_mapname"
4.7.5.3 Redundant nominations get the following say_all message: "dod_mapname has already been nominated by Bob"
4.7.5.4 After 5 nominations, no more are allowed.
4.7.5.4.1 The following message will be flashed after nominations are closed or if someone tries to nominate a map after nominations are closed: "Nominations are closed."

4.7.6 There will be a 6th voting option, "Extend current map for 15 minutes". If this wins, the map will be extended 15 minutes.

4.7.7 Voting will start 30 seconds after nominations close.

4.7.8 If not enough maps are selected, nominations filled from a file in admin.cfgs

4.7.9 Maps that are to be disallowed for nomination are listed in a file in the admin.cfgs

4.7.10 Map with the most votes will be the next map.

4.7.10.1 In case of a tie, use the map that was nominated first.

4.7.11 Value for Steam_IDs votes at map to be set in the profile.

4.7.11.1 Default value is "1".

4.7.12 Listmaps command from in-game or console shows the maps on the server. This should read the maps from the nominations admin.cfgs.

4.7.13 There will be a variable for the admin to set how many map rotations must pass until a map is eligible to be voted/played again.

Player Movement/Actions

4.8.1 Admin can force a player to take a screenshot from console or GUI. Generally this is done in trying determine if someone is cheating or not.

4.8.1.1 Player will see a colored, private message. The text of the message is setup in the .cfg by the admin.

4.8.2 Player can ask the following via "say_all" or "team_say":

4.8.2.1 "nextmap": display to them with message "next map is dod_nextmap"
4.8.2.2 "timeleft": display to them with message "Time left on current map: 0:00"
4.8.2.2 "listmaps": will generate a list of maps on the server in the console with message "check your console for a list of maps on this server"
4.8.2.4 "ff": will generate a response of "friendly fire is on" or "friendly fire is off" appropriate for the server settings.

Status

4.9.1 From console, admin can view status information plus profiles of players on the server.

4.9.2 From console, a player can type va_adminlist and see all the admins on the server.

Team-balancing

4.10.1 From console, allowed user can force players, based on last join, to balance teams. IE: There are 10 axis players and 6 allied players. va_teambalance would move the last to who joined axis to the allies.

4.10.1.1 In the case of uneven numbers, the system will round off in favor of moving fewer players.
IE: 10 axis and 7 allies, would result in 1 axis player moving to allies.

4.10.2 Admin can move a player to either team or spectator from console or menu.

"Just left"

This is something that is very useful for players who come in and disrupt the server then to quickly for the admin to react.

4.11.1 From console, allowed user can view the last 5 players who left the server with same info that is displayed by the status command.

Blacklist (Banned names/words)

4.12.1 A list of words that, if a user has as any part of their name, they cannot join the server.

4.12.1.1 Admin can define this message in config.

4.12.2 A list of words that, if used in game, will be replaced by an "X" per letter.

Unstick

Very often players become stuck on some element of a map. This command allows an admin to move a player up ever so slightly in the hope of dislodging them.

4.13.1 A console command, va_unstick "playername", that lifts the target a few units.

RCON

4.14.1 A console command, va_rcon <rcon command here>, that would allow the user to access rcon directly, without a password.

Reload

4.15.1 Reloads the specified config or file. va_reload <file/config name>

Changename

4.16.1 Can change the name of player.

Retrieved from "https://developer.valvesoftware.com/w/index.php?title=Valve_Admin_Requirements&oldid=146995"