Creating Natives (SourceMod Scripting) - Revision history

Nosoop: Fix incorrect type for My_AddNumbers parameter

2022-04-20T14:18:13Z

Fix incorrect type for My_AddNumbers parameter

Nosoop: Drop unnecessary public visibility from native implementations

2022-04-20T13:36:40Z

Drop unnecessary public visibility from native implementations

Bacardi: /* Arrays */ const int[] array

2021-10-16T14:32:24Z

‎Arrays: const int[] array

Bacardi: /* Arrays */ : error 161: brackets after variable name indicate a fixed-size array, but a dynamic size was given - did you mean to use 'new int[size]' syntax?

2021-10-16T14:22:27Z

‎Arrays: : error 161: brackets after variable name indicate a fixed-size array, but a dynamic size was given - did you mean to use 'new int[size]' syntax?

DJ Tsunami: /* Creating the Native */

2021-01-15T09:48:47Z

‎Creating the Native

Psychonic: pawn -> sourcepawn tag

2020-03-26T19:49:07Z

pawn -> sourcepawn tag

Show changes

DJ Tsunami at 20:22, 12 January 2020

2020-01-12T20:22:52Z

Show changes

Joinedsenses: /* Variable Arguments */ updated syntax

2018-12-26T02:12:04Z

‎Variable Arguments: updated syntax

Joinedsenses: /* Throwing Errors */ Removed misused semicolon

2018-12-26T02:10:32Z

‎Throwing Errors: Removed misused semicolon

Nosoop: Add section for natives in methodmaps

2017-09-01T04:17:17Z

Add section for natives in methodmaps

@@ Line 22: / Line 22: @@
   * @return        The float value of the integer and float added together.
   */
-native float My_AddNumbers(int num1, int num2);</sourcepawn>
+native float My_AddNumbers(int num1, float num2);</sourcepawn>
 The documentation and commenting style above is a SourceMod Development Team convention.  While you are not required to follow it for your own code, it may be a good idea to enhance readability (as readers will expect the style to conform).

@@ Line 31: / Line 31: @@
 Thus, we have a function like:
-<sourcepawn>public any Native_My_AddNumbers(Handle plugin, int numParams)
+<sourcepawn>any Native_My_AddNumbers(Handle plugin, int numParams)
+{
 }</sourcepawn>
@@ Line 38: / Line 38: @@
 Next, we need to implement our native.
-<sourcepawn>public any Native_My_AddNumbers(Handle plugin, int numParams)
+<sourcepawn>any Native_My_AddNumbers(Handle plugin, int numParams)
+{
 	/* Retrieve the first parameter we receive */
@@ Line 79: / Line 79: @@
 An implementation of this would look like:
-<sourcepawn>public int Native_AltCloseHandle(Handle plugin, int numParams)
+<sourcepawn>int Native_AltCloseHandle(Handle plugin, int numParams)
+{
 	Handle hndl = view_as<Handle>(GetNativeCellRef(1));
@@ Line 99: / Line 99: @@
 An implementation of this is very easy, because of dynamic arrays:
-<sourcepawn>public int Native_StringToUpper(Handle plugin, int numParams)
+<sourcepawn>int Native_StringToUpper(Handle plugin, int numParams)
+{
 	int len;
@@ Line 138: / Line 138: @@
 An implementation of this could look like:
-<sourcepawn>public int Native_SumArray(Handle plugin, int numParams)
+<sourcepawn>int Native_SumArray(Handle plugin, int numParams)
+{
 	int size = GetNativeCell(2);
@@ Line 173: / Line 173: @@
 An implementation of this would look like:
-<sourcepawn>public int Native_SumParams(Handle plugin, int numParams)
+<sourcepawn>int Native_SumParams(Handle plugin, int numParams)
+{
 	int base = GetNativeCell(1);
@@ Line 216: / Line 216: @@
 For example, let's say we have a native that operates on clients.  We want to throw an error if we get a client index that is invalid or disconnected.  We could do this like so:
-<sourcepawn>public int MyFunction(Handle plugin, int numParams)
+<sourcepawn>int MyFunction(Handle plugin, int numParams)
+{
 	int client = GetNativeCell(1);
@@ Line 246: / Line 246: @@
+}
-public int Native_PrintNumberToClient(Handle plugin, int numParams)
+int Native_PrintNumberToClient(Handle plugin, int numParams)
+{
 	int number = GetNativeCell(1);

@@ Line 135: / Line 135: @@
   * @return          Sum of the array elements.
   */
-native int SumArray(const int array[], int size);</sourcepawn>
+native int SumArray(const int[] array, int size);</sourcepawn>
 An implementation of this could look like:

@@ Line 146: / Line 146: @@
+	}
-	int array[size], total;
+	int[] array = new int[size];
 	GetNativeArray(1, array, size);

@@ Line 27: / Line 27: @@
 ==Creating the Native==
-To actually create the native, first let's define the native handler itself.  From <tt>functions.inc</tt> we can see that this follows the prototype:
+To actually create the native, first let's define the native handler itself.  From the [https://sm.alliedmods.net/new-api/functions/NativeCall API reference] we can see that there are two prototypes. We will use the second one:
-<sourcepawn>typedef NativeCall = function int (Handle plugin, int numParams);</sourcepawn>
+<sourcepawn>function any (Handle plugin, int numParams)</sourcepawn>
 Thus, we have a function like:
-<sourcepawn>public int Native_My_AddNumbers(Handle plugin, int numParams)
+<sourcepawn>public any Native_My_AddNumbers(Handle plugin, int numParams)
+{
 }</sourcepawn>
@@ Line 38: / Line 38: @@
 Next, we need to implement our native.
-<sourcepawn>public int Native_My_AddNumbers(Handle plugin, int numParams)
+<sourcepawn>public any Native_My_AddNumbers(Handle plugin, int numParams)
+{
 	/* Retrieve the first parameter we receive */
@@ Line 50: / Line 50: @@
 }</sourcepawn>
-You should note four important details.  The first is that we have to manually grab the parameters -- they're not easily sent via arguments.  This is for technical reasons that go beyond the scope of this document.  That means you have to know exactly ''how'' to grab each parameter.  For our example, we know that both parameters are simply cells, and thus we can use <tt>GetNativeCell</tt>.
+You should note three important details.  The first is that we have to manually grab the parameters -- they're not easily sent via arguments.  This is for technical reasons that go beyond the scope of this document.  That means you have to know exactly ''how'' to grab each parameter.  For our example, we know that both parameters are simply cells, and thus we can use <tt>GetNativeCell</tt>.
-However, the second detail is that there is no <tt>GetNativeCellFloat</tt>.  This is because a <tt>Float</tt> is still a cell; the data is just interpreted differently.  Thus, we ''change'' the tag to <tt>Float</tt> manual.  '''This is different from calling float(GetNativeCell(2)).'''  In fact, that would not work; the <tt>float()</tt> call would interpret the cell as an integer, when in fact it's already a float, just with the wrong tag (i.e., no tag at all).
+However, the second detail is that there is no <tt>GetNativeCellFloat</tt>.  This is because a <tt>float</tt> is still a cell; the data is just interpreted differently.  Thus, we ''cast'' the type to <tt>float</tt> manually.  '''This is different from calling float(GetNativeCell(2)).'''  In fact, that would not work; the <tt>float()</tt> call would interpret the cell as an integer, when in fact it's already a float, just with the wrong type (i.e., no type at all).
 Lastly, we did not need to verify <tt>numParams</tt>.  The compiler will always send the correct amount of parameters - the user can't mess this up in any easy way.  Only if you use variadic arguments, or add parameters and need to support older binaries, do you need to handle <tt>numParams</tt> variations.

@@ Line 171: / Line 171: @@
   * @return       Sum of all numbers passed.
   */
-native SumParams(num, ...);</pawn>
+native int SumParams(int num, ...);</pawn>
 An implementation of this would look like:
-<pawn>public Native_SumParams(Handle:plugin, numParams)
+<pawn>public int Native_SumParams(Handle plugin, int numParams)
+{
-    new base = GetNativeCell(1);
+    int base = GetNativeCell(1);
-    for (new i = 2; i <= numParams; i++)
+    for (int i = 2; i <= numParams; i++)
+    {
        base += GetNativeCellRef(i);

@@ Line 220: / Line 220: @@
+{
     int client = GetNativeCell(1);
-    if (client < 1 || client > MaxClients);
+    if (client < 1 || client > MaxClients)
+    {
        return ThrowNativeError(SP_ERROR_NATIVE, "Invalid client index (%d)", client);

@@ Line 229: / Line 229: @@
+    }
     /* Code */
 }</pawn>
 [[Category:SourceMod Scripting]]