Overview This reference documents all functions available in the CoD4 Unleashed Server Plugin API. All functions are exported from the server and can be called from within your plugin.
Header files are located in plugins/function_declarations.h and plugins/declarations.h.
Command Functions Handle server commands and arguments.
Plugin_Cmd_Argc Get the number of command arguments.
Returns: Number of arguments (including command name)Example: void MyCommand_f ( void ) { int argc = Plugin_Cmd_Argc (); Com_Printf ( "Command has %d arguments \n " , argc); }
Plugin_Cmd_Argv char * Plugin_Cmd_Argv ( int arg )
Get a command argument by index.
Argument index (0 = command name, 1 = first argument, etc.)
Returns: Argument stringExample: void MyCommand_f ( void ) { char * cmd = Plugin_Cmd_Argv ( 0 ); // Command name char * arg1 = Plugin_Cmd_Argv ( 1 ); // First argument Com_Printf ( " %s called with: %s \n " , cmd, arg1); }
Plugin_Cmd_Args char * Plugin_Cmd_Args ( char * buff , int bufsize )
Get all command arguments as a single string.
Buffer to store the arguments
Returns: Buffer containing all argumentsPlugin_Cmd_GetInvokerSlot int Plugin_Cmd_GetInvokerSlot ()
Get the client slot number of the player who invoked the command.
Returns: Client slot number, or -1 if invoked from server consoleExample: void TeleportCommand_f ( void ) { int slot = Plugin_Cmd_GetInvokerSlot (); if (slot < 0 ) { Com_Printf ( "Must be used by a player \n " ); return ; } // Teleport the player... }
Plugin_Cmd_GetInvokerUid int Plugin_Cmd_GetInvokerUid ()
Get the UID of the player who invoked the command.
Returns: Player UIDConsole Output Print messages to the server console, logs, and player chat.
Plugin_Printf void Plugin_Printf ( const char * fmt , ...)
Print a message to the console and logs. Works like printf().
Example: Plugin_Printf ( "Player %s connected \n " , playerName);
Plugin_PrintWarning void Plugin_PrintWarning ( const char * fmt , ...)
Print a warning message.
Plugin_PrintError void Plugin_PrintError ( const char * fmt , ...)
Print an error message.
Plugin_DPrintf void Plugin_DPrintf ( const char * fmt , ...)
Print a debug message (only shown when developer cvar is 1).
Example: Plugin_DPrintf ( "Debug: processing player %d \n " , clientNum);
Plugin_G_LogPrintf void Plugin_G_LogPrintf ( const char * fmt , ...)
Write to the game log file.
Plugin_ChatPrintf void Plugin_ChatPrintf ( int slot , const char * fmt , ...)
Send a chat message to a player (or all players).
Client slot number, or -1 to send to all players
Format string (supports color codes)
Example: // Message to one player Plugin_ChatPrintf (slot, "^2Welcome, %s !" , playerName); // Message to all players Plugin_ChatPrintf ( - 1 , "^1Server restart in 60 seconds!" );
Plugin_BoldPrintf void Plugin_BoldPrintf ( int slot , const char * fmt , ...)
Display a bold message on player’s screen.
Client slot number, or -1 for all players
Example: Plugin_BoldPrintf (slot, "^1HEADSHOT!" );
Player Management Functions for working with players.
Plugin_GetSlotCount int Plugin_GetSlotCount ()
Get the maximum number of player slots on the server.
Returns: Value of sv_maxclientsPlugin_GetPlayerName char * Plugin_GetPlayerName ( int slot )
Get a player’s name.
Returns: Player name (max 64 characters)Plugin_GetPlayerUid int Plugin_GetPlayerUid ( int slot )
Get a player’s UID (unique identifier).
Returns: Player UID, or 0 if not authenticatedPlugin_GetPlayerUID unsigned int Plugin_GetPlayerUID ( unsigned int clientslot )
Get player’s UID (alternative function).
Plugin_SetPlayerUID void Plugin_SetPlayerUID ( unsigned int clientslot , unsigned int uid )
Set a player’s UID.
Only use this if you’re implementing custom authentication.
Plugin_GetPlayerGUID const char * Plugin_GetPlayerGUID ( unsigned int clientslot )
Get player’s GUID (PunkBuster identifier).
Returns: 32-character GUID stringPlugin_SetPlayerGUID void Plugin_SetPlayerGUID ( unsigned int clientslot , const char * guid )
Set a player’s GUID.
Plugin_GetClientScoreboard clientScoreboard_t Plugin_GetClientScoreboard ( int clientNum )
Get a player’s scoreboard statistics.
Returns: Structure containing:
int score - Total scoreint deaths - Death countint kills - Kill countint assists - Assist count
Example: clientScoreboard_t stats = Plugin_GetClientScoreboard (clientNum); Plugin_ChatPrintf (clientNum, "K/D: %d / %d " , stats.kills, stats.deaths);
Plugin_DropClient void Plugin_DropClient ( unsigned int clientnum , const char * reason )
Kick a player from the server.
Kick reason (shown to player)
Example: Plugin_DropClient (slot, "Excessive teamkilling" );
Plugin_BanClient void Plugin_BanClient ( unsigned int clientnum , int duration , int invokerid , char * banreason )
Ban a player from the server.
Ban duration in minutes, or -1 for permanent ban
UID of the admin issuing the ban (0 for console)
Example: // Ban for 60 minutes Plugin_BanClient (slot, 60 , adminUID, "Cheating" ); // Permanent ban Plugin_BanClient (slot, - 1 , 0 , "Repeated offenses" );
Memory Management Always use these functions instead of standard malloc()/free().
Plugin_Malloc void * Plugin_Malloc ( size_t size )
Allocate memory for the plugin.
Number of bytes to allocate
Returns: Pointer to allocated memory, or NULL on failureExample: PlayerData_t * data = ( PlayerData_t * ) Plugin_Malloc ( sizeof ( PlayerData_t ) * 64 ); if (data == NULL ) { Plugin_Error (P_ERROR_DISABLE, "Out of memory" ); return - 1 ; }
Plugin_Free void Plugin_Free ( void * ptr )
Free previously allocated memory.
Pointer to memory to free
Example: Plugin_Free (data); data = NULL ;
Safe to call multiple times on the same pointer. Safe to call on NULL pointers.
Console Variables (CVars) Registering CVars Plugin_Cvar_RegisterString CONVAR_T * Plugin_Cvar_RegisterString ( const char * var_name , const char * var_value , int flags , const char * var_description )
Register a string console variable.
Example: cvar_t * my_name = Plugin_Cvar_RegisterString ( "myplugin_name" , "Default Name" , CVAR_ARCHIVE, "Player name setting" );
Plugin_Cvar_RegisterBool CONVAR_T * Plugin_Cvar_RegisterBool ( const char * var_name , qboolean var_value , int flags , const char * var_description )
Register a boolean console variable.
Example: cvar_t * enabled = Plugin_Cvar_RegisterBool ( "myplugin_enabled" , qtrue, CVAR_ARCHIVE, "Enable plugin features" );
Plugin_Cvar_RegisterInt CONVAR_T * Plugin_Cvar_RegisterInt ( const char * var_name , int var_value , int min_value , int max_value , int flags , const char * var_description )
Register an integer console variable with min/max bounds.
Example: cvar_t * max_players = Plugin_Cvar_RegisterInt ( "myplugin_maxplayers" , 32 , // Default 1 , // Min 64 , // Max CVAR_ARCHIVE, "Maximum players allowed" );
Plugin_Cvar_RegisterFloat CONVAR_T * Plugin_Cvar_RegisterFloat ( const char * var_name , float var_value , float min_value , float max_value , int flags , const char * var_description )
Register a floating-point console variable.
Example: cvar_t * multiplier = Plugin_Cvar_RegisterFloat ( "myplugin_multiplier" , 1.5 , // Default 0.0 , // Min 10.0 , // Max CVAR_ARCHIVE, "Damage multiplier" );
Reading CVars Plugin_Cvar_GetInteger int Plugin_Cvar_GetInteger (CONVAR_T const * var )
Get integer value from a cvar.
Plugin_Cvar_GetBoolean qboolean Plugin_Cvar_GetBoolean (CONVAR_T const * var )
Get boolean value from a cvar.
Plugin_Cvar_GetValue float Plugin_Cvar_GetValue (CONVAR_T const * var )
Get float value from a cvar.
Plugin_Cvar_GetString const char * Plugin_Cvar_GetString (CONVAR_T const * var )
Get string value from a cvar.
Example: if ( Plugin_Cvar_GetBoolean (enabled)) { int max = Plugin_Cvar_GetInteger (max_players); float mult = Plugin_Cvar_GetValue (multiplier); const char * name = Plugin_Cvar_GetString (my_name); Com_Printf ( "Enabled: %d players, %f x, name= %s \n " , max, mult, name); }
Setting CVars Plugin_Cvar_SetInt void Plugin_Cvar_SetInt (CONVAR_T const * var , int val )
Plugin_Cvar_SetBool void Plugin_Cvar_SetBool (CONVAR_T const * var , qboolean val )
Plugin_Cvar_SetFloat void Plugin_Cvar_SetFloat (CONVAR_T const * var , float val )
Plugin_Cvar_SetString void Plugin_Cvar_SetString (CONVAR_T const * var , char const * string )
Accessing CVars by Name Plugin_Cvar_VariableIntegerValue int Plugin_Cvar_VariableIntegerValue ( const char * var_name )
Get cvar integer value by name.
Plugin_Cvar_VariableString const char * Plugin_Cvar_VariableString ( const char * var_name )
Get cvar string value by name.
Plugin_Cvar_Set void Plugin_Cvar_Set ( const char * var_name , const char * value )
Set cvar value by name.
Example: Plugin_Cvar_Set ( "sv_hostname" , "My Custom Server" );
File Operations Plugin_FS_SV_WriteFile int Plugin_FS_SV_WriteFile ( const char * qpath , const void * buffer , int size )
Write data to a file (creates or overwrites).
File path relative to server directory
Returns: Number of bytes writtenExample: char data [] = "Player statistics \n " ; int written = Plugin_FS_SV_WriteFile ( "stats/data.txt" , data, strlen (data)); if (written != strlen (data)) { Com_PrintError ( "Failed to write file \n " ); }
Plugin_FS_SV_FOpenFileRead int Plugin_FS_SV_FOpenFileRead ( const char * filename , fileHandle_t * fp )
Open a file for reading.
Returns: File size in bytes, or negative value on errorPlugin_FS_SV_FOpenFileWrite fileHandle_t Plugin_FS_SV_FOpenFileWrite ( const char * filename )
Open a file for writing.
Returns: File handlePlugin_FS_Read int Plugin_FS_Read ( void * buffer , int len , fileHandle_t f )
Read data from an open file.
Returns: Number of bytes readPlugin_FS_Write int Plugin_FS_Write ( const void * buffer , int len , fileHandle_t h )
Write data to an open file.
Returns: Number of bytes writtenPlugin_FS_FCloseFile qboolean Plugin_FS_FCloseFile ( fileHandle_t f )
Close an open file.
Example: fileHandle_t file; char buffer [ 1024 ]; int len = Plugin_FS_SV_FOpenFileRead ( "config.txt" , & file ); if (len > 0 ) { Plugin_FS_Read (buffer, sizeof (buffer), file); Plugin_FS_FCloseFile (file); Com_Printf ( "Read: %s \n " , buffer); }
Networking TCP Functions Plugin_TcpConnect qboolean Plugin_TcpConnect ( int connection , const char * remote )
Open a TCP connection.
Remote address (hostname:port or IP:port)
Returns: qtrue on success, qfalse on failureExample: if ( Plugin_TcpConnect ( 0 , "api.example.com:8080" )) { Com_Printf ( "Connected! \n " ); }
Plugin_TcpSendData qboolean Plugin_TcpSendData ( int connection , void * data , int len )
Send data over TCP connection.
Returns: qtrue on successPlugin_TcpGetData int Plugin_TcpGetData ( int connection , void * buf , int size )
Receive data from TCP connection.
Returns:
-1 - Connection closed0 - No data available>0 - Number of bytes received
Plugin_TcpCloseConnection void Plugin_TcpCloseConnection ( int connection )
Close a TCP connection.
UDP Functions Plugin_UdpSendData qboolean Plugin_UdpSendData ( netadr_t * to , void * data , int len )
Send a UDP packet.
Plugin_NET_StringToAdr int Plugin_NET_StringToAdr ( const char * string , netadr_t * , netadrtype_t )
Convert string to network address.
Example: netadr_t addr; Plugin_NET_StringToAdr ( "192.168.1.1:28960" , & addr , NA_IP);
Plugin_NET_AdrToString const char * Plugin_NET_AdrToString ( netadr_t * a )
Convert network address to string.
Script Functions Extend GSC (Game Script Code) with custom functions.
Plugin_ScrAddFunction void Plugin_ScrAddFunction ( char * name , xfunction_t function )
Register a GSC function.
Example: void GScr_MyFunction () { int arg = Plugin_Scr_GetInt ( 0 ); Plugin_Scr_AddInt (arg * 2 ); } PCL int OnInit () { Plugin_ScrAddFunction ( "myfunction" , GScr_MyFunction); return 0 ; }
Plugin_ScrAddMethod void Plugin_ScrAddMethod ( char * name , xfunction_t function )
Register a GSC method (called on entities).
Plugin_Scr_GetNumParam int Plugin_Scr_GetNumParam ( void )
Get number of parameters passed from GSC.
Plugin_Scr_GetInt int Plugin_Scr_GetInt ( unsigned int paramIndex )
Get integer parameter from GSC.
Plugin_Scr_GetFloat float Plugin_Scr_GetFloat ( unsigned int paramIndex )
Get float parameter from GSC.
Plugin_Scr_GetString char * Plugin_Scr_GetString ( unsigned int paramIndex )
Get string parameter from GSC.
Plugin_Scr_GetEntity gentity_t * Plugin_Scr_GetEntity ( unsigned int paramIndex )
Get entity parameter from GSC.
Plugin_Scr_GetVector void Plugin_Scr_GetVector ( unsigned int paramIndex , vec3_t * out )
Get vector parameter from GSC.
Plugin_Scr_AddInt void Plugin_Scr_AddInt ( int value )
Return integer value to GSC.
Plugin_Scr_AddFloat void Plugin_Scr_AddFloat ( float value )
Return float value to GSC.
Plugin_Scr_AddString void Plugin_Scr_AddString ( const char * string )
Return string value to GSC.
Plugin_Scr_AddBool void Plugin_Scr_AddBool (qboolean value )
Return boolean value to GSC.
Plugin_Scr_Error void Plugin_Scr_Error ( const char * string )
Throw an error in GSC.
Game Entities Plugin_GetGentityForEntityNum gentity_t * Plugin_GetGentityForEntityNum ( int entnum )
Get game entity by entity number.
Plugin_GetClientForClientNum client_t * Plugin_GetClientForClientNum ( int clientnum )
Get client structure by client number.
Example: client_t * client = Plugin_GetClientForClientNum (clientNum); Com_Printf ( "Ping: %d \n " , client -> ping );
Plugin_SV_GameClientNum playerState_t * Plugin_SV_GameClientNum ( int num )
Get player state by client number.
Time Functions Plugin_GetLevelTime int Plugin_GetLevelTime ( void )
Get current level time in milliseconds.
Plugin_GetServerTime int Plugin_GetServerTime ( void )
Get server time in milliseconds.
Plugin_Milliseconds int Plugin_Milliseconds ()
Get milliseconds since server start.
Utility Functions Plugin_IsSvRunning qboolean Plugin_IsSvRunning ()
Check if server is running.
Plugin_Error void Plugin_Error ( int code , const char * fmt , ...)
Report a plugin error.
Error code: P_ERROR_DISABLE or P_ERROR_TERMINATE
Example: if (critical_failure) { Plugin_Error (P_ERROR_DISABLE, "Critical failure in plugin" ); }
Plugin_AddCommand void Plugin_AddCommand ( char * name , xcommand_t command , int defaultpower )
Register a server command.
Function to call when command is executed
Required power level (0-100)
Data Types pluginInfo_t typedef struct { struct { int major; int minor; } handlerVersion; struct { int major; int minor; } pluginVersion; char fullName [ 256 ]; char shortDescription [ 256 ]; char longDescription [ 1024 ]; } pluginInfo_t ;
clientScoreboard_t typedef struct { int score; int deaths; int kills; int assists; } clientScoreboard_t ;
netadr_t typedef struct { netadrtype_t type; int scope_id; unsigned short port; int sock; union { byte ip [ 4 ]; byte ip6 [ 16 ]; }; } netadr_t ;
Constants Plugin Handler Version PLUGIN_HANDLER_VERSION_MAJOR // Major version PLUGIN_HANDLER_VERSION_MINOR // Minor version
Error Codes P_ERROR_DISABLE // Disable the plugin P_ERROR_TERMINATE // Terminate the server
Boolean Values qtrue // True qfalse // False
Cvar Flags CVAR_ARCHIVE // Save to config CVAR_USERINFO // Send on connect CVAR_SERVERINFO // Sent to clients CVAR_SYSTEMINFO // Duplicated on clients CVAR_INIT // Command line only CVAR_LATCH // Changes on restart CVAR_ROM // Read-only CVAR_CHEAT // Requires cheats CVAR_TEMP // Not archived CVAR_NORESTART // Not cleared on restart
Next Steps
Development Guide Learn how to use these APIs in practice
Example Plugins See real-world usage examples