IServerPluginCallbacks

From Valve Developer Community
Jump to: navigation, search

IServerPluginCallbacks is the interface used by server plugins to hook game events. It is typically used in conjunction with IGameEventListener2.

See Server Plugins#Coding for implementation details.

Functions

Plugin state

bool Load(CreateInterfaceFn interfaceFactory, CreateInterfaceFn gameServerFactory)
Called when the plugin is loaded by the engine. This can happen either on initialization or when being re-loaded after being unloaded. The two parameters provide the interface factories that the plugin needs to operate. Returns false on error.
void UnLoad()
Called when a plugin is unloaded, use this to disable any asynchronous tasks and remove any callbacks you have registered with the engine (for example a game events listener). Additionally, this function will be called if false is returned by Load().
void Pause()
Called when the operation of the plugin is paused (i.e it will stop receiving callbacks but should not be unloaded).
void UnPause()
Called when a plugin is brought out of the paused state. You should re-enable any asynchronous events your plugin uses in this call
const char *GetPluginDescription()
This function should return a friendly string describing your plugin. Typically this would be its name and the author.

Server events

void LevelInit(char const *pMapName)
Called on level (map) startup, it is the first function called as a server enters a new level.
void ServerActivate(edict_t *pEdictList, int edictCount, int clientMax)
This is called when the server successfully enters a new level, this will happen after the LevelInit call. This call provides pointers to the list of edicts created on the server and the maxplayer count of the server.
void GameFrame(bool simulating)
Called once per server frame. Server performance is very sensitive to the execution time of this function so keep anything you do in this function to a minimum.
void LevelShutdown()
Called when a server is changing to a new level or is being shutdown. Remove any map specific allocations in this call. This can be called multiple times during a map change.
void OnQueryCvarValueFinished( QueryCvarCookie_t iCookie, edict_t *pPlayerEntity, EQueryCvarValueStatus eStatus, char *pCvarName, char *pCvarValue )
Called when a query from IServerPluginHelpers::StartQueryCvarValue() finishes. iCookie is the value requested.
void OnEdictAllocated(edict_t *edict)
void OnEdictAllocated(const edict_t *edict)

Clients

PLUGIN_RESULT ClientConnect(bool *bAllowConnect, edict_t *pEntity, const char *pszName, const char *pszAddress, char *reject, int maxrejectlen)
Called when a client initially connects to a server. Set bAllowConnect to false to stop this user from connecting.
void ClientPutInServer(edict_t *pEntity, char const *playername)
Called when a client spawns into a server. This is called before the server spawn function.
void ClientActive(edict_t *pEntity)
Called after a client is fully spawned and configured by the Mod. Use this call to change any player specific settings.
void ClientDisconnect(edict_t *pEntity)
Called when a client disconnects from the server.
Bug: If a client disconnects very quickly after connecting, this function will not be called.
void SetCommandClient(int index)
Called by the ConVar code to let you keep track of which client is entering a ConCommand. Use this index in ConCommands if you want to see who is running the command. As ConVar commands don't have an edict associated with them when they run you can use this index to look up the entity that is running the command. The index is one less than the entity index.
void ClientSettingsChanged(edict_t *pEdict)
Called when player specific cvars about a player change (for example the users name). Use this function to control what operations a user is allowed to perform to their settings (for example limiting usernames).
PLUGIN_RESULT ClientCommand(edict_t *pEntity, const CCommand &args)
Called when a remote client enters a command into the console. This should be used to provide commands to clients (and ConCommand used to implement server side only commands).
PLUGIN_RESULT NetworkIDValidated(const char *pszUserName, const char *pszNetworkID)
Called when the server retrieves a clients network ID (i.e Steam ID). Note that a clients network ID is not set on connect, you must wait for this callback before a users network ID is valid. The client name is passed into this function, you need to search the currently connected players to find the associated edict pointer. Note that the clients name can change between connect and id validation, you should use the entity index to track specific players. Note also that this function is NOT called for the local user when running a listen/non-dedicated server.

Related constructs

PLUGIN_RESULT
One of:
PLUGIN_CONTINUE
Keep going; no change
PLUGIN_OVERRIDE
Run the game's function, but use our return value instead (Note: This is in reference to arguments passed by reference, such as ClientConnect's bool *bAllowConnect)
PLUGIN_STOP
Don't run the game's function at all
QueryCvarCookie_t
CreateInterfaceFn
EQueryCvarValueStatus

IServerPluginHelpers

CreateMessage()

void CreateMessage( edict_t *pEntity, DIALOG_TYPE type, KeyValues *data, IServerPluginCallbacks *plugin )

This function displays the in-game messages you are probably used to seeing on servers. It can create either simple announcements, or menus from which a choice must be made with one of the number keys.

Bug: Weapon selection commands count as numbers even if the player has re-assigned them to totally different keys. Be aware that popping up a menu can cause great frustration both through confusion and the blocking of input.

The function's arguments are:

edict_t *pEntity
Player to send message to
DIALOG_TYPE type
One of:
DIALOG_MSG
A plain and simple message
DIALOG_MENU
An options menu. If you use this, add sub keys (To do: Called what?) to data containing:
string command
Client command to run if this item is selected
string msg
Option text
DIALOG_TEXT
A rich text message (To do: What format? HTML?)
DIALOG_ENTRY
An entry box (To do: What does this look like?)
DIALOG_ASKCONNECT
Ask the client to connect to a specified IP address. Only the "time" and "title" keys are used.
KeyValues *data
Raw data to send to the client. Can contain the following keys:
string title
The title text to display at the top of the message
string msg
The body of the message
color color
The color to display the message in; white by default
int level
The priority of the message, where 0 is highest (only one message can be displayed at any one time)
int time
Number of seconds the message should stay active. Min 10, max 200.
IServerPluginCallbacks *plugin
Confirm:The plugin you are calling from

StartQueryCvarValue()

QueryCvarCookie_t StartQueryCvarValue( edict_t *pEntity, const char *pName )

Call this to find out the value of a cvar on the client.

It is an asynchronous query, and it will call IServerPluginCallbacks::OnQueryCvarValueFinished when the value comes in from the client.

Store the return value if you want to match this specific query to the OnQueryCvarValueFinished call.

Returns InvalidQueryCvarCookie if the entity if invalid.

The function's arguments are:

edict_t *pEntity
Player to send message to
const char *pName
Cvar name

Other functions

void ClientCommand( edict_t *pEntity, const char *cmd )
Attempt to run a command on the client. In some games, only Commands marked FCVAR_SERVER_CAN_EXECUTE can be executed this way.

See also