Difference between revisions of "SourceMod 1.4.0 API Changes"

From AlliedModders Wiki
Jump to: navigation, search
(Menus)
(Core)
Line 243: Line 243:
  
 
===Core===
 
===Core===
 +
 +
====Entities====
 +
 +
The following functions now have an optional last parameter of <tt>element</tt> to be used with props that are arrays (ie. <tt>m_iAmmo</tt>, <tt>m_hMyWeapons</tt>)
 +
 +
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.
  
 
====Menus====
 
====Menus====

Revision as of 14:33, 25 October 2011

This page is a work-in-progress as SourceMod 1.4.0 is not yet released.


Sourcepawn API Changes

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);

CStrike

TODO

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

Clients

GameRules

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);

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.

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.

Extension API Changes