SourceMod 1.6.0 API Changes

These are just the API changes from SourceMod 1.5.3 to SourceMod 1.6.0. Click here for the full SourceMod 1.6.0 Release Notes.

Plugins

ADT Trie

While the ADT Trie API has not changed at all, it should be noted that they are no longer backed by actual tries. Instead, they are now backed by hash maps internally.

Clients

The following natives no longer require clients to be in-game and now only require them to be connected: GetClientDataRate, IsClientTimingOut, GetClientTime, GetClientLatency, GetClientAvgLatency, GetClientAvgLoss, GetClientAvgChoke, GetClietnAvgData, GetClientAvgPackets.

Console

OnClientSayCommand and OnClientSayCommand_Post now automatically strip double-quotes from the chat message, either on both sides, or single double-quote on either side. This removes the need for any manual stripping, but may affect some logic already in place.

Non-silent chat triggers also go through these forwards now. Returning Plugin_Handled or higher in OnClientSayCommand will only block the triggers from chat and will not block the command itself. This is intentional.

Additionally, a new CommandExists helper function has been added.

/**
 * Returns true if the supplied command exists.
 *
 * @param command	Command to find.
 * @return			True if command is found, false otherwise.
 */
stock bool:CommandExists(const String:command[])

CStrike

Defines for the CS_DMG_HEADSHOT damage flag and CS_WEAPON_KNIFE weapon slot have been added.

DBI

A new off-thread database transaction API has been added.

Normal usage is to call SQL_CreateTransaction to get a transaction handle, and then add queries with SQL_AddQuery. You would then call SQL_ExecuteTransaction to execute the queries as a batch. If any fail, your SQLTxnFailure callback is called, else SQLTxnSuccess. You only need to close your transaction handle manually if you do not execute it.

/**
 * Creates a new transaction object. A transaction object is a list of queries
 * that can be sent to the database thread and executed as a single transaction.
 *
 * @return              A transaction handle.
 */
native Handle:SQL_CreateTransaction();

/**
 * Adds a query to a transaction object.
 *
 * @param txn           A transaction handle.
 * @param query         Query string.
 * @param data			Extra data value to pass to the final callback.
 * @return              The index of the query in the transaction's query list.
 * @error               Invalid transaction handle.
 */
native SQL_AddQuery(Handle:txn, const String:query[], any:data=0);

/**
 * Callback for a successful transaction.
 *
 * @param db            Database handle.
 * @param data          Data value passed to SQL_ExecuteTransaction().
 * @param numQueries    Number of queries executed in the transaction.
 * @param results       An array of Query handle results, one for each of numQueries. They are closed automatically.
 * @param queryData     An array of each data value passed to SQL_AddQuery().
 * @noreturn
 */
functag public SQLTxnSuccess(Handle:db, any:data, numQueries, Handle:results[], any:queryData[]);

/**
 * Callback for a failed transaction.
 *
 * @param db            Database handle.
 * @param data          Data value passed to SQL_ExecuteTransaction().
 * @param numQueries    Number of queries executed in the transaction.
 * @param error         Error message.
 * @param failIndex      Index of the query that failed, or -1 if something else.
 * @param queryData     An array of each data value passed to SQL_AddQuery().
 * @noreturn
 */
functag public SQLTxnFailure(Handle:db, any:data, numQueries, const String:error[], failIndex, any:queryData[]);

/**
 * Sends a transaction to the database thread. The transaction handle is
 * automatically closed. When the transaction completes, the optional
 * callback is invoked.
 *
 * @param db            A database handle.
 * @param txn           A transaction handle.
 * @param onSuccess     An optional callback to receive a successful transaction.
 * @param onError       An optional callback to receive an error message.
 * @param data          An optional value to pass to callbacks.
 * @param prio          Priority queue to use.
 * @noreturn
 * @error               An invalid handle.
 */
native SQL_ExecuteTransaction(
		Handle:db,
		Handle:txn,
		SQLTxnSuccess:onSuccess=SQLTxnSuccess:-1,
		SQLTxnFailure:onError=SQLTxnFailure:-1,
		any:data=0,
		DBPriority:priority=DBPrio_Normal);

Entity

The FindDataMapInfo native has been added as a complement to the FindSendPropInfo native. It retrieves the offset of a given property in an entity's datadesc, supporting nested datadesc tables.

/**
 * Given an entity, finds a nested datamap property offset.
 * This information is cached for future calls.
 *
 * @param entity		Entity index.
 * @param prop			Property name.
 * @param type			Optional parameter to store the type.
 * @param num_bits		Optional parameter to store the number of bits the field 
 *						uses.  The bit count will either be 1 (for boolean) or 
 *						divisible by 8 (including 0 if unknown).
 * @param local_offset	Optional parameter to store the local offset, as 
 *						FindDataMapOffs() would return.
 * @return				An offset, or -1 on failure.
 */
native FindDataMapInfo(entity, 
					   const String:prop[],
					   &PropFieldType:type=PropFieldType:0,
					   &num_bits=0,
					   &local_offset=0);

Files

The FileSize native now has an optional boolean param to support files in Valve filesystem search paths, similar to the same param on the FileExists native.

Functions

The RequestFrame native has been added for the common case of wanting to run logic exactly one frame in the future. You pass to it a callback, and optionally, one cell of data for context - similar to a timer.

/**
 * Defines a RequestFrame Callback.
 *
 * @param data			Data passed to the RequestFrame native.
 * @noreturn
 */
functag public RequestFrameCallback(any:data);

/**
 * Creates a single use Next Frame hook.
 *
 * @param Function	Function to call on the next frame.
 * @param data			Value to be passed on the invocation of the Function.
 * @noreturn
 */
native RequestFrame(RequestFrameCallback:Function, any:data=0);

Protobuf

Like CS:GO, Dota 2 also uses protobuf serialized usermessages.

PbReadInt, PbSetInt, and PbAddInt can now be used to read/write protobuf enum values.

A new PbRemoveRepeatedFieldValue native has been added to allow removing a value from a protobuf repeated field - the counter to the PbAdd* natives.

/**
 * Removes a value by index from a protobuf message repeated field.
 *
 * @param pb			protobuf handle.
 * @param field			Field name.
 * @param index			Index into repeated field.
 * @noreturn
 * @error				Invalid or incorrect Handle, non-existent field, or incorrect field type.
 */ 
native PbRemoveRepeatedFieldValue(Handle:pb, const String:field[], index);

Lastly, the PbReadRepeated* natives that have been deprecated since version 1.5.0 have been completely removed. They only ever existed in 1.5.0-dev versions. The path forward is still to use the PbRead* natives, specified the index of the value you want if it's a repeated field.

SDKTools

SDKCalls now support using addresses using either PrepSDKCall_SetFromConf with SDKConf_Address or, for development purposes, the new PrepSDKCall_SetAddress native.

Testing

A new, brief testing API has been added for debugging. The Assert* functions will print to the server upon success, and throw an error on failure.

SetTestContext(const String:context[])

AssertEq(const String:text[], cell1, cell2)

AssertFalse(const String:text[], bool:value)

AssertTrue(const String:text[], bool:value)

TF2

/**
 * Returns whether or not a holiday is active
 *
 * @param holiday		Holiday being checked.
 * @return				Boolean of whether or not the holiday is active.
 */
native bool:TF2_IsHolidayActive(TFHoliday:holiday);

TopMenus

/**
 * Displays a TopMenu category to a client.
 *
 * @param topmenu			TopMenu Handle.
 * @param category		Category object id.
 * @param client			Client index.
 * @return					True on success, false on failure.
 * @error					Invalid TopMenu Handle or client not in game.
 */
native bool:DisplayTopMenuCategory(Handle:topmenu, TopMenuObject:category, client);

/**
 * Change the menu title caching behaviour of the TopMenu. By default the titles are cached to reduce overhead.
 * If you need dynamic menu titles, which can change everytime the menu is displayed to a user, set this to false.
 *
 * @param topmenu       TopMenu Handle.
 * @param cache_titles  Cache the menu titles and don't call the handler with TopMenuAction_DisplayTitle everytime the menu is drawn?
 * @noreturn
 * @error               Invalid TopMenu Handle
 */
native SetTopMenuTitleCaching(Handle:topmenu, bool:cache_titles);

Extensions

IExtensionInterface

A OnDependenciesDropped call has been added for the case noted in the function description.

/**
 * @brief Called once all dependencies have been unloaded. This is
 * called AFTER OnExtensionUnload(), but before the extension library
 * has been unloaded. It can be used as an alternate unload hook for
 * cases where having no dependent plugins would make shutdown much
 * simplier.
 */
virtual void OnDependenciesDropped()
{
}

IGameHelpers

FindDataMapInfo has been added as a replacement to FindInDataMap and a companion to FindSendPropInfo. It retrieves an sm_datatable_info_t structure that will have the actual offset for the variable, which differs from the offset in the typedescription if data descriptions are nested.

/**
 * @brief Finds a datamap_t definition.
 *
 * @param pMap			datamap_t pointer.
 * @param offset			Property name.
 * @param pDataTable	Buffer to store sm_datatable_info_t data.
 * @return				typedescription_t pointer on success, NULL 
 *						on failure.
 */
virtual bool FindDataMapInfo(datamap_t *pMap, const char *offset, sm_datatable_info_t *pDataTable) =0;

IShareSys

OverrideNatives is now deprecated and no longer has any functionality.

IGamePlayer

The following two new functions have been added to IGamePlayer as retrieved from IPlayerManager.

/**
 * @brief Returns the client's edict/entity index.
 *
 * @return			Client's index.
 */
virtual int GetIndex() const =0;

/**
 * @brief Prints a string to the client console.
 *
 * @param pMsg		String to print.
 */
virtual void PrintToConsole(const char *pMsg) =0;

ILibrarySys

/**
 * @brief Retrieve the file component of the given path.
 *
 * @param buffer	Output buffer.
 * @param maxlength	Length of the output buffer.
 * @param path		Path to search for a filename.
 * @return			Number of bytes written to buffer, not including the null terminator.
 */
virtual size_t GetFileFromPath(char *buffer, size_t maxlength, const char *path) =0;