Natives (SourceMod Development)

Natives are functions which are available to plugins via Core itself, or a C extension. They are called "natives" because they must be translated via a native interface. This article explains the various parameter passing conventions in SourcePawn, as well as how to use them in your own natives.

To understand the contents of this article, you will need to read Creating Natives, the Native section in the introductory article on creating extensions.

In this article, float refers to the C/C data type, and Float (note capital 'F') refers to the SourcePawn tag.

By Value versus By Reference

There are two ways to pass integers/Floats to native implementations. They are by value (ByVal) and by reference (ByRef). ByVal means that a copy of the value is passed to the native. This is the default behaviour. ByRef means a reference is passed to the native, and this reference points to the value. Both will be explained below.

Note that arrays and strings, as will be explained later, are always passed by reference. This is because they are usually larger structures, and passing them ByVal would require copying their data, wasting CPU cycles.

By Value

Passing by value is the default behaviour for primitive data types (integers, Floats, or any tag that's cell-based). Data is treated normally as raw, copied input. Observe the following native:

/**
 * Returns the number decremented by one.
 *
 * @param num		Number to decrement.
 * @return		Decremented number.
 */
native Decrement(num);

How would we use this native? Since num is passed as a value, it cannot change in the native code. This means we have to use the return value as such:

//Decrements a number 5 times
Example(num)
{
	num = Decrement(num);
	num = Decrement(num);
	num = Decrement(num);
	num = Decrement(num);
	num = Decrement(num);
	return num;
}

By Reference

Let's reuse the above example to use reference passing. Observe the new native below:

<pawn>/**

* Subtracts one from the given number, by reference.
*
* @param num		Number to subtract, by reference.
* @noreturn
*/

native Decrement(