Optimizing Plugins (SourceMod Scripting) - Revision history

Luki1412 at 19:11, 2 September 2025

2025-09-02T19:11:40Z

Joinedsenses: Update syntax. Remove decl notes (deprecated)

2020-03-29T23:49:31Z

Update syntax. Remove decl notes (deprecated)

Psychonic: pre -> sourcepawn

2020-03-26T19:51:58Z

pre -> sourcepawn

BAILOPAN at 01:40, 11 December 2011

2011-12-11T01:40:07Z

Show changes

TheY4Kman: /* Stock */ Clarified "include"

2008-03-02T04:47:06Z

‎Stock: Clarified "include"

TheY4Kman: /* Decl on Local Arrays */ Uh, fuck. Forgot to close the `tag`

2008-03-02T04:39:55Z ‎Decl on Local Arrays: Uh, fuck. Forgot to close the <tt> tag ← Older revision Revision as of 04:39, 2 March 2008 Line 189: Line 189: <pawn>decl var = 5;</pawn> <pawn>decl var = 5;</pawn> − Since the purpose of <tt>decl</tt> is to avoid initializaton, such a line would have no meaning, and thus it is invalid syntax. You must use <tt>new<tt> in order to do initialize: + Since the purpose of <tt>decl</tt> is to avoid initializaton, such a line would have no meaning, and thus it is invalid syntax. You must use <tt>new</tt> in order to do initialize: <pawn>new var = 5;</pawn> <pawn>new var = 5;</pawn>

TheY4Kman: /* Decl on Local Arrays */ Edited for consistency of semicolons and clarification on intialization. 2008-03-02T04:39:01Z ‎Decl on Local Arrays: Edited for consistency of semicolons and clarification on intialization. ← Older revision Revision as of 04:39, 2 March 2008 Line 158: Line 158: There is a small caveat to the 'new' statement in Pawn; it automatically writes a zero for every byte in the data structure. For example: There is a small caveat to the 'new' statement in Pawn; it automatically writes a zero for every byte in the data structure. For example: − <pawn>new String:elephant[512]</pawn> + <pawn>new String:elephant[512];</pawn> If placed inside local scope, all 512 bytes of the variable will be cleared every time the variable is created. In a performance-sensitive callback, this could be disastrous. Even something as innocuous as: If placed inside local scope, all 512 bytes of the variable will be cleared every time the variable is created. In a performance-sensitive callback, this could be disastrous. Even something as innocuous as: − <pawn>new temp_players[MAX_PLAYERS]</pawn> + <pawn>new temp_players[MAX_PLAYERS];</pawn> Could be a significant slow-down if called too often. To solve this, SourceMod has a special replacement for <tt>new</tt> called <tt>decl</tt>. Unlike <tt>new</tt>, <tt>decl</tt> does not bother setting the entire array or structure to zero. Thus, the data will be filled with random garbage. Could be a significant slow-down if called too often. To solve this, SourceMod has a special replacement for <tt>new</tt> called <tt>decl</tt>. Unlike <tt>new</tt>, <tt>decl</tt> does not bother setting the entire array or structure to zero. Thus, the data will be filled with random garbage. Line 187: Line 187: Note that <tt>decl</tt> will work on any local variable type (array, string, float, integer, et cetera). The one thing it cannot be used for is initialization. This is invalid: Note that <tt>decl</tt> will work on any local variable type (array, string, float, integer, et cetera). The one thing it cannot be used for is initialization. This is invalid: − <pawn>decl var = 5</pawn> + <pawn>decl var = 5;</pawn> − Since the purpose of <tt>decl</tt> is to avoid initializaton, such a line would have no meaning, and thus it is invalid syntax. + Since the purpose of <tt>decl</tt> is to avoid initializaton, such a line would have no meaning, and thus it is invalid syntax. You must use <tt>new<tt> in order to do initialize: + <pawn>new var = 5;</pawn> =Avoid Large KeyValues= =Avoid Large KeyValues= BAILOPAN at 00:11, 16 November 2007 2007-11-16T00:11:04Z ← Older revision Revision as of 00:11, 16 November 2007 Line 222: Line 222: − [[Category:SourceMod Development]] + [[Category:SourceMod Scripting]] BAILOPAN at 20:27, 10 September 2007 2007-09-10T20:27:25Z ← Older revision Revision as of 20:27, 10 September 2007 Line 222: Line 222: − [[Category:SourceMod Scripting]] + [[Category:SourceMod Development]] BAILOPAN: added section about kvs and public/stock 2007-09-10T16:58:02Z added section about kvs and public/stock ← Older revision Revision as of 16:58, 10 September 2007 Line 190: Line 190: Since the purpose of <tt>decl</tt> is to avoid initializaton, such a line would have no meaning, and thus it is invalid syntax. Since the purpose of <tt>decl</tt> is to avoid initializaton, such a line would have no meaning, and thus it is invalid syntax. + + + =Avoid Large KeyValues= + KeyValues is an n-ary structure using linked lists. This type of structure is extremely expensive to allocate and traverse. While it might be suitable for tiny pieces of information (that is, under 10KB of data or so), its complexity growth is very poor. + + If you load KeyValues data, you should make an effort to, at the very least, cache its Handle so you don't need to reparse the file every time. Caching its contents on a needed basis would be a bonus as well. + + If you're trying to use a KeyValues file with thousands of entries and updating/loading it on events such as player connections or disconnections, you will find that the structure will grow to an unmanageably slow size. If that's the case, you should consider moving to something like SQLite or MySQL. + + + =Use Stock/Public Correctly= + Using <tt>stock</tt> and <tt>public</tt> correctly won't necessarily optimize your plugin, but they will help your code be more maintainable and will eliminate extra exports/data being written to your plugin file. + + ==Stock== + A <tt>stock</tt> function is compiled, but only written to the plugin's binary if it's used. Generally, you should use the <tt>stock</tt> keyword if: + *You may use the function in the future, and don't want the compiler telling you it's never used; + *You are writing an include file and don't want the function compiled if it's never used. + + ==Public== + A <tt>public</tt> function is exported externally. Every plugin binary has a list of all its <tt>public</tt> functions, and Core uses this table whenever it needs to find a matching <tt>forward</tt>. + + Generally, there are only two reasons you should ever use <tt>public</tt>: + *You are implementing a <tt>forward</tt>. + *You are implementing a callback to another function, and it requires you to use <tt>public</tt>. + + It seems common for users to randomly add <tt>public</tt> to completely private functions -- not only is that unnecessary, but it only adds to the amount of work Core has to do to find functions in your plugin. + + + =Conclusion= + Although optimization is important, you should always keep context in mind. Don't replace every single <tt>new</tt> in your plugin with <tt>decl</tt> just because it might be faster. Identify the areas of your plugin where optimization is significant, and tweak from there. + [[Category:SourceMod Scripting]] [[Category:SourceMod Scripting]]

← Older revision		Revision as of 19:11, 2 September 2025
Line 54:		Line 54:
	If you're trying to use a KeyValues file with thousands of entries and updating/loading it on events such as player connections or disconnections, you will find that the structure will grow to an unmanageably slow size. If that's the case, you should consider moving to something like SQLite or MySQL.		If you're trying to use a KeyValues file with thousands of entries and updating/loading it on events such as player connections or disconnections, you will find that the structure will grow to an unmanageably slow size. If that's the case, you should consider moving to something like SQLite or MySQL.

		+	=Consider using "switch" statements instead of "if else" statements where possible=
		+	Consider the following code:
		+	<sourcepawn>
		+	int iConVarMode = GetConVarInt(g_hCVMode);
		+
		+	if (iConVarMode == 0)
		+	{
		+	// do stuff
		+	}
		+	else if (iConVarMode == 1)
		+	{
		+	// do stuff
		+	}
		+	else if (iConVarMode == 2)
		+	{
		+	// do stuff
		+	}
		+	else
		+	{
		+	// do stuff
		+	}
		+	</sourcepawn>
		+	Since we are checking the same variable for its value multiple times, it is better to use a switch statement here:
		+	<sourcepawn>
		+	int iConVarMode = GetConVarInt(g_hCVMode);
		+
		+	switch (iConVarMode)
		+	{
		+	case 0:
		+	{
		+	// do stuff
		+	}
		+	case 1:
		+	{
		+	// do stuff
		+	}
		+	case 2:
		+	{
		+	// do stuff
		+	}
		+	default:
		+	{
		+	// do stuff
		+	}
		+	}
		+	</sourcepawn>
	[[Category:SourceMod Scripting]]		[[Category:SourceMod Scripting]]

@@ Line 16: / Line 16: @@
 Let's try this with a simple example loop below. Most syntactic language features have a simple cost. Natives can be trickier.
-<sourcepawn>for (new i = 0; i < strlen(string); i++) {
+<sourcepawn>for (int i = 0; i < strlen(string); i++)
      if (string[i] == '"')
          return i;
+}
 </sourcepawn>
@@ Line 32: / Line 35: @@
 This example is easy to fix. We can identify that <tt>strlen</tt> magnifies the cost of the loop, and rewrite it like this:
-<sourcepawn>new length = strlen(string);
+<sourcepawn>int length = strlen(string);
-for (new i = 0; i < length; i++) {
+for (int i = 0; i < length; i++)
      if (string[i] == '"')
          return i;
+}
 </sourcepawn>
 Now the cost of this loop is just: <tt>n</tt> times a very, very small amount of time.
 =Avoid Large KeyValues=

@@ Line 16: / Line 16: @@
 Let's try this with a simple example loop below. Most syntactic language features have a simple cost. Natives can be trickier.
-<pre>for (new i = 0; i < strlen(string); i++) {
+<sourcepawn>for (new i = 0; i < strlen(string); i++) {
      if (string[i] == '"')
          return i;
+}
-</pre>
+</sourcepawn>
 First, let's determine how many times this loop will run. If the length of <tt>string</tt> is ''n'', then the loop will run ''n'' times. Next, let's see what each iteration of the loop costs:
@@ Line 32: / Line 32: @@
 This example is easy to fix. We can identify that <tt>strlen</tt> magnifies the cost of the loop, and rewrite it like this:
-<pre>new length = strlen(string);
+<sourcepawn>new length = strlen(string);
 for (new i = 0; i < length; i++) {
      if (string[i] == '"')
          return i;
+}
-</pre>
+</sourcepawn>
 Now the cost of this loop is just: <tt>n</tt> times a very, very small amount of time.
@@ Line 44: / Line 44: @@
 Here is another example, using OnGameFrame:
-<pre>public OnGameFrame()
+<sourcepawn>public OnGameFrame()
+{
      new String:buffer[4096];
-}</pre>
+}</sourcepawn>
 When you declare an array with <tt>new</tt>, Pawn initializes each slot to 0. Let's say writing to an array slot costs 1 unit of time. Declaring this array therefore costs a fixed 4096 units of time. Is that a problem? Well, the game server ticks at 33 times per second. Therefore this costs about 150,000 units of time per second. If a "unit of time" is a nanosecond, we could estimate this costing around 0.1 milliseconds. That could be a lot depending on what your plugin does. You get about 15ms per frame, of which about half is used by the server. If you use more than this time, you could start delaying frames.
@@ Line 53: / Line 53: @@
 Let's say that you have declared this big array inside a loop, inside OnGameFrame, and you are worried about the cost. The preferred way of solving this is to use <tt>decl</tt> instead of <tt>new</tt>, which does not perform any initialization:
-<pre>public OnGameFrame()
+<sourcepawn>public OnGameFrame()
+{
      decl String:buffer[4096];
-}</pre>
+}</sourcepawn>
 '''NOTE: You must be very careful not to read from uninitialized variables. They will contain garbage, and you could crash the server by attempting to print or operate on garbage strings.'''

@@ Line 207: / Line 207: @@
 A <tt>stock</tt> function is compiled, but only written to the plugin's binary if it's used.  Generally, you should use the <tt>stock</tt> keyword if:
 *You may use the function in the future, and don't want the compiler telling you it's never used;
-*You are writing an include file and don't want the function compiled if it's never used.
+*You are writing an include file and don't want the function put in the binary if it's never used.
 ==Public==

@@ Line 189: / Line 189: @@
 <pawn>decl var = 5;</pawn>
-Since the purpose of <tt>decl</tt> is to avoid initializaton, such a line would have no meaning, and thus it is invalid syntax.  You must use <tt>new<tt> in order to do initialize:
+Since the purpose of <tt>decl</tt> is to avoid initializaton, such a line would have no meaning, and thus it is invalid syntax.  You must use <tt>new</tt> in order to do initialize:
 <pawn>new var = 5;</pawn>

@@ Line 158: / Line 158: @@
 There is a small caveat to the 'new' statement in Pawn; it automatically writes a zero for every byte in the data structure.  For example:
-<pawn>new String:elephant[512]</pawn>
+<pawn>new String:elephant[512];</pawn>
 If placed inside local scope, all 512 bytes of the variable will be cleared every time the variable is created.  In a performance-sensitive callback, this could be disastrous.  Even something as innocuous as:
-<pawn>new temp_players[MAX_PLAYERS]</pawn>
+<pawn>new temp_players[MAX_PLAYERS];</pawn>
 Could be a significant slow-down if called too often.  To solve this, SourceMod has a special replacement for <tt>new</tt> called <tt>decl</tt>.  Unlike <tt>new</tt>, <tt>decl</tt> does not bother setting the entire array or structure to zero.  Thus, the data will be filled with random garbage.
@@ Line 187: / Line 187: @@
 Note that <tt>decl</tt> will work on any local variable type (array, string, float, integer, et cetera).  The one thing it cannot be used for is initialization.  This is invalid:
-<pawn>decl var = 5</pawn>
+<pawn>decl var = 5;</pawn>
-Since the purpose of <tt>decl</tt> is to avoid initializaton, such a line would have no meaning, and thus it is invalid syntax.
+Since the purpose of <tt>decl</tt> is to avoid initializaton, such a line would have no meaning, and thus it is invalid syntax.  You must use <tt>new<tt> in order to do initialize:
 =Avoid Large KeyValues=

← Older revision		Revision as of 00:11, 16 November 2007
Line 222:		Line 222:


−	[[Category:SourceMod ~~Development~~]]	+	[[Category:SourceMod Scripting]]

← Older revision		Revision as of 20:27, 10 September 2007
Line 222:		Line 222:


−	[[Category:SourceMod ~~Scripting~~]]	+	[[Category:SourceMod Development]]

← Older revision		Revision as of 16:58, 10 September 2007
Line 190:		Line 190:

	Since the purpose of <tt>decl</tt> is to avoid initializaton, such a line would have no meaning, and thus it is invalid syntax.		Since the purpose of <tt>decl</tt> is to avoid initializaton, such a line would have no meaning, and thus it is invalid syntax.
		+
		+
		+	=Avoid Large KeyValues=
		+	KeyValues is an n-ary structure using linked lists. This type of structure is extremely expensive to allocate and traverse. While it might be suitable for tiny pieces of information (that is, under 10KB of data or so), its complexity growth is very poor.
		+
		+	If you load KeyValues data, you should make an effort to, at the very least, cache its Handle so you don't need to reparse the file every time. Caching its contents on a needed basis would be a bonus as well.
		+
		+	If you're trying to use a KeyValues file with thousands of entries and updating/loading it on events such as player connections or disconnections, you will find that the structure will grow to an unmanageably slow size. If that's the case, you should consider moving to something like SQLite or MySQL.
		+
		+
		+	=Use Stock/Public Correctly=
		+	Using <tt>stock</tt> and <tt>public</tt> correctly won't necessarily optimize your plugin, but they will help your code be more maintainable and will eliminate extra exports/data being written to your plugin file.
		+
		+	==Stock==
		+	A <tt>stock</tt> function is compiled, but only written to the plugin's binary if it's used. Generally, you should use the <tt>stock</tt> keyword if:
		+	*You may use the function in the future, and don't want the compiler telling you it's never used;
		+	*You are writing an include file and don't want the function compiled if it's never used.
		+
		+	==Public==
		+	A <tt>public</tt> function is exported externally. Every plugin binary has a list of all its <tt>public</tt> functions, and Core uses this table whenever it needs to find a matching <tt>forward</tt>.
		+
		+	Generally, there are only two reasons you should ever use <tt>public</tt>:
		+	*You are implementing a <tt>forward</tt>.
		+	*You are implementing a callback to another function, and it requires you to use <tt>public</tt>.
		+
		+	It seems common for users to randomly add <tt>public</tt> to completely private functions -- not only is that unnecessary, but it only adds to the amount of work Core has to do to find functions in your plugin.
		+
		+
		+	=Conclusion=
		+	Although optimization is important, you should always keep context in mind. Don't replace every single <tt>new</tt> in your plugin with <tt>decl</tt> just because it might be faster. Identify the areas of your plugin where optimization is significant, and tweak from there.
		+

	[[Category:SourceMod Scripting]]		[[Category:SourceMod Scripting]]

Optimizing Plugins (SourceMod Scripting) - Revision history

Luki1412 at 19:11, 2 September 2025

Joinedsenses: Update syntax. Remove decl notes (deprecated)

Psychonic: pre -> sourcepawn

BAILOPAN at 01:40, 11 December 2011

TheY4Kman: /* Stock */ Clarified "include"

TheY4Kman: /* Decl on Local Arrays */ Uh, fuck. Forgot to close the tag

TheY4Kman: /* Decl on Local Arrays */ Edited for consistency of semicolons and clarification on intialization.

BAILOPAN at 00:11, 16 November 2007

BAILOPAN at 20:27, 10 September 2007

BAILOPAN: added section about kvs and public/stock

TheY4Kman: /* Decl on Local Arrays */ Uh, fuck. Forgot to close the `tag`