SourceMod 1.4.0 API Changes
This page is a work-in-progress as SourceMod 1.4.0 is not yet released.
Contents
Additions
BaseComm
The BaseComm base plugin now has a brand new API to fully interact with it, without conflict.
/** * Returns whether or not a client is gagged * * @param client Client index. * @return True if client is gagged, false otherwise. */ native bool:BaseComm_IsClientGagged(client);
/** * Returns whether or not a client is muted * * @param client Client index. * @return True if client is muted, false otherwise. */ native bool:BaseComm_IsClientMuted(client);
/** * Sets a client's gag state * * @param client Client index. * @param gagState True to gag client, false to ungag. * @return True if this caused a change in gag state, false otherwise. */ native bool:BaseComm_SetClientGag(client, bool:gagState);
/** * Sets a client's mute state * * @param client Client index. * @param muteState True to mute client, false to unmute. * @return True if this caused a change in mute state, false otherwise. */ native bool:BaseComm_SetClientMute(client, bool:muteState);
ClientPrefs
ClientPrefs now allows altering cookie values for clients that are not presently in-game.
/** * Sets the value of a Client preference cookie based on an authID string. * * @param authID String Auth/STEAM ID of player to set. * @param cookie Client preference cookie handle. * @param value String value to set. * @noreturn * @error Invalid cookie handle. */ native SetAuthIdCookie(const String:authID[], Handle:cookie, const String:value[]);
Core
Clients
Clients can now be easily identified as being the SourceTV or replay bot, regardless of when they are checked, what they were renamed to, or when they were enabled.
/** * Returns if a certain player is the SourceTV bot. * * @param client Player index. * @return True if player is the SourceTV bot, false otherwise. */ native bool:IsClientSourceTV(client);
/** * Returns if a certain player is the Replay bot. * * @param client Player index. * @return True if player is the Replay bot, false otherwise. */ native bool:IsClientReplay(client);
CommandFilters
Command filters are no longer limited to extensions. Multi-target filters can now be dynamically created, evaluated, and removed natively in Sourcepawn.
/** * Adds clients to a multi-target filter. * * @param pattern Pattern name. * @param clients Array to fill with unique, valid client indexes. * @return True if pattern was recognized, false otherwise. */ functag public bool:MultiTargetFilter(const String:pattern[], Handle:clients);
/** * Adds a multi-target filter function for ProcessTargetString(). * * @param pattern Pattern to match (case sensitive). * @param filter Filter function. * @param phrase Descriptive phrase to display on successful match. * @param phraseIsML True if phrase is multi-lingual, false otherwise. * @noreturn */ native AddMultiTargetFilter(const String:pattern[], MultiTargetFilter:filter, const String:phrase[], bool:phraseIsML);
/** * Removes a multi-target filter function from ProcessTargetString(). * * @param pattern Pattern to match (case sensitive). * @param filter Filter function. * @noreturn */ native RemoveMultiTargetFilter(const String:pattern[], MultiTargetFilter:filter);
See plugins/testsuite/ptstest.sp for example usage.
Console
Server command output is now retrievable with the new ServerCommandEx native..
/** * Executes a server command as if it were on the server console (or RCON) * and stores the printed text into buffer. * * Warning: This calls ServerExecute internally and may have issues if * certain commands are in the buffer, only use when you really need * the response. * Also, on L4D2 this will not print the command output to the server console. * * @param buffer String to store command result into. * @param maxlen Length of buffer. * @param format Formatting rules. * @param ... Variable number of format parameters. * @noreturn */ native ServerCommandEx(String:buffer[], maxlen, const String:format[], any:...);
Command and ability access can now be checked directly with an AdminId, rather than requiring an in-game client. This can be useful in checking permissions while still obeying overrides in custom authentication systems such as might be used in IRC relay plugins or custom "RCon" solutions.
/** * Returns whether an admin has access to a given command string. The string * can be any override string, as overrides can be independent of * commands. This feature essentially allows you to create custom flags * using the override system. * * @param id AdminId of the admin. * @param command Command name. If the command is not found, the default * flags are used. * @param flags Flag string to use as a default, if the command or override * is not found. * @param override_only If true, SourceMod will not attempt to find a matching * command, and it will only use the default flags specified. * Otherwise, SourceMod will ignore the default flags if * there is a matching admin command. * @return True if the admin has access, false otherwise. */ native bool:CheckAccess(AdminId:id, const String:command[], flags, bool:override_only=false);
SourceMod
Game config files now support looking up addresses calculated from other gamedata.
For more information, see SDKTools_(SourceMod_Scripting)#Raw_address_lookups
/* * Finds an address calculation in a GameConfig file, * performs LoadFromAddress on it as appropriate, then returns the final address. * * @param gameconf GameConfig Handle, or INVALID_HANDLE to use sdktools.games.txt. * @param name Name of the property to find. * @return An address calculated on success, or 0 on failure. */ native Address:GameConfGetAddress(Handle:gameconf, const String:name[]);
From pawn, you can now directly read and write values at these raw addresses. SDKTools also now supports calls using a raw address as a |this| pointer (see SourceMod_1.4.0_API_Changes#SDKTools).
/** * Load up to 4 bytes from a memory address. * * @param addr Address to a memory location. * @param size How many bytes should be read. * @return The value that is stored at that address. */ native LoadFromAddress(Address:addr, NumberType:size);
/** * Store up to 4 bytes to a memory address. * * @param addr Address to a memory location. * @param data Value to store at the address. * @param size How many bytes should be written. * @noreturn */ native StoreToAddress(Address:addr, data, NumberType:size);
CStrike
Allows the ability to view buy commands issued by client and block the command.
/** * Called when a player attempts to purchase an item. * Return Plugin_Continue to allow the purchase or return a * higher action to deny. * * @param client Client index * @param weapon User input for weapon name */ forward Action:CS_OnBuyCommand(client, const String:weapon[]);
Allows the ability to block weapon drop called by CSWeaponDrop
/** * Called when CSWeaponDrop is called * Return Plugin_Continue to allow the call or return a * higher action to deny. * * @param client Client index * @param weapon Weapon index */ forward Action:CS_OnCSWeaponDrop(client, weaponIndex);
Adds the ability to change weapon price on a per player basis.
/** * Called when game retrieves a weapon's price for a player. * Return Plugin_Continue to use default value or return a higher * action to use a newly-set price. * * @note This can be called multiple times per weapon purchase * * @param client Client index * @param weapon Weapon classname * @param price Buffer param for the price of the weapon * * @note Not all "weapons" call GetWeaponPrice. Example: c4, knife, vest, vest helmet, night vision. */ forward Action:CS_OnGetWeaponPrice(client, const String:weapon[], &price);
Adds the ability to block round ending.
/** * Called when TerminateRound is called. * Return Plugin_Continue to ignore, return Plugin_Changed to continue, * using the given delay and reason, or return Plugin_Handled or a higher * action to block TerminateRound from firing. * * @param delay Time (in seconds) until new round starts * @param reason Reason for round end */ forward Action:CS_OnTerminateRound(&Float:delay, &CSRoundEndReason:reason);
Calls CSWeaponDrop without having to create separate gamedata
/** * Forces a player to drop or toss their weapon * * @param client Player's index. * @param weaponIndex Index of weapon to drop. * @param toss True to toss weapon (with velocity) or false to just drop weapon * @param blockhook Set to true to stop the corresponding CS_OnCSWeaponDrop * * @noreturn * @error Invalid client index, client not in game, or invalid weapon index. */ native CS_DropWeapon(client, weaponIndex, bool:toss, bool:blockhook = false);
Allows the ability to end a round with a specific reason.
/** * Forces round to end with a reason * * @param delay Time (in seconds) to delay before new round starts * @param reason Reason for the round ending * @param blockhook Set to true to stop the corresponding CS_OnTerminateRound * forward from being called. * @noreturn */ native CS_TerminateRound(Float:delay, CSRoundEndReason:reason, bool:blockhook = false);
Allows passing buy aliases and retrieving the actual name for the weapon.
/** * Gets a weapon name from a weapon alias * * @param alias Weapons alias to get weapon name for. * @param weapon Buffer to store weapons name * @param size Size of buffer to store the weapons name. * @noreturn * * @note Will set the buffer to the original alias if it is not an alias to a weapon. */ native CS_GetTranslatedWeaponAlias(const String:alias[], String:weapon[], size);
Allows getting a weapons price, while still obeying the forward call to get price if modified.
/** * Gets a weapon's price * * @param client Client to check weapon price for. * @param id Weapon id for the weapon to check * @param defaultprice Set to true to get defaultprice. * @return Returns price of the weapon (even if modified) * * @error Invalid client, failing to get weapon info, or failing to get price offset. * @note c4, knife and shield will always return 0. vest, vest helmet and night vision will always return default price. */ native CS_GetWeaponPrice(client, CSWeaponID:id, bool:defaultprice = false);
Adds the ability to get a clients clan tag.
/** * Gets a clients clan tag * @param client Client index to get clan tag for. * @param buffer Buffer to store clients clan tag in. * @param size Size of the buffer. * @return Number of non-null bytes written. * * @error Invalid client. */ native CS_GetClientClanTag(client, String:buffer[], size);
Adds the ability to set a clients clan tag.
/** * Sets a clients clan tag * @param client Client index to set clan tag for. * @param tag Tag to set clients clan tag as. * @noreturn * * @error Invalid client. */ native CS_SetClientClanTag(client, const String:tag[]);
MapChooser
/** * Called when mapchooser starts a Map Vote. */ forward OnMapVoteStarted();
Nominations
/** * Attempt to remove a map from the mapchooser map list. * * @param map Map to remove. * @return True if the nomination was found and removed, or false if the nomination was not found. */ native bool:RemoveNominationByMap(const String:map[]);
/** * Attempt to remove a map from the mapchooser map list. * * @param owner Client index of the nominater. * @return True if the nomination was found and removed, or false if the nomination was not found. */ native bool:RemoveNominationByOwner(owner);
/** * Gets the current list of nominated maps. * * @param maparray An ADT array handle to add the map strings to. * @param ownerarray An optional ADT array handle to add the nominator client indexes to. * @noreturn */ native GetNominatedMapList(Handle:maparray, Handle:ownerarray = INVALID_HANDLE);
SDKTools
A new SDKCallType, SDKCall_Raw has been added. This is to be used with the new Address variables to make calls with custom |this| pointers.
Client
It is now possible to directly control some aspects of a client's netchannel in a way that, among other things, you can cause them to reconnect to the current server like at a map change.
/** * Sets the client to an inactive state waiting for a new map * * @param client The client index * @noreturn */ native InactivateClient(client);
/** * Reconnect a client without dropping the netchannel * * @param client The client index * @noreturn */ native ReconnectClient(client);
GameRules
Property values networked on the GameRulesProxy entity can now be looked up and set directly on the GameRules class. On the proxy, values read could be stale, and attempting to change values only resulted in them being changed on the client or not at all.
The functions work very similarly to their GetEntProp equivalents.
- GameRules_GetProp
- GameRules_SetProp
- GameRules_GetPropFloat
- GameRules_SetPropFloat
- GameRules_GetPropEnt
- GameRules_SetPropEnt
- GameRules_GetPropVector
- GameRules_SetPropVector
- GameRules_GetPropString
- GameRules_SetPropString
For more info on things that can be done with these, see http://forums.alliedmods.net/showthread.php?t=154217.
Sound
You can now use the engine's function for sound gain calculation based on sound level and distance from listener.
/** *Calculates gain of sound on given distance with given sound level in decibel * * @param soundlevel decibel of sound, like SNDLEVEL_NORMAL or integer value * @param distance distance of sound to calculate, not meter or feet, but Source Engine`s normal Coordinate unit * @return gain of sound. you can multiply this with original sound`s volume to calculate volume on given distance */ native Float:GetDistGainFromSoundLevel(soundlevel, Float:distance);
TF2
Notification is now available when "WaitingForPlayers" both begins and ends (or current state can be queried as any time with the new GameRules natives).
/** * Called when the server enters the Waiting for Players round state * * @noreturn */ forward TF2_OnWaitingForPlayersStart();
/** * Called when the server exits the Waiting for Players round state * * @noreturn */ forward TF2_OnWaitingForPlayersEnd();
Condition addition and removal to and from players can now be detected. Due to various issues, these cannot be blocked, but conditions can be re-removed or re-added in the add and remove callbacks, leaving only a frame of difference.
/** * Called after a condition is added to a player * * @param client Index of the client to which the conditon is being added. * @param condition Condition that is being added. * @noreturn */ forward TF2_OnConditionAdded(client, TFCond:condition);
/** * Called after a condition is removed from a player * * @param client Index of the client to which the condition is being removed. * @param condition Condition that is being removed. * @noreturn */ forward TF2_OnConditionRemoved(client, TFCond:condition);
Other Changes
Core
Entities
The following functions now have an optional last parameter of element to be used with props that are arrays (ie. m_iAmmo, m_hMyWeapons)
- GetEntProp
- SetEntProp
- GetEntPropFloat
- SetEntPropFloat
- GetEntPropEnt
- SetEntPropEnt
- GetEntPropVector
- SetEntPropVector
- GetEntPropString
Previously, the only way to access anything but the first array member was using the GetEntData and SetEntData funcs with manual offset calculations. Now you can just specify the 0-based index and keep the type-checking and offset-caching benefits of the GetEntProp and SetEntProp functions.
A GetEntPropArraySize native has also been added to retrieve the number of available indexes.
Lang
GetClientLanguage and SetClientLanguage now only require a client to be connected, rather than in-game.
Menus
The MENUFLAG_BUTTON_NOVOTE menu option flag has been added to allow creation of an automatic "No Vote" option at the start of the menu.
DBI
SQL_GetAffectedRows now works properly with threaded query handles.
The handle passed to both SQL_GetInsertId and SQL_GetError can now be a query handle.
SDKTools
Functions
The ForceEdictIndex parameter in CreateEntityByName is now always ignored on ep2 (orangebox) and later (resulting in the same behavior as keeping its default value of -1).
This change was made because 1) forcing edict indexes can be unsafe ("crashy") if misused, and 2) it allows CreateEntityByName to now be automatically supported by all ep2 and later games and mods, without requiring gamedata.
