User:Nosoop/Guide/Basics - Revision history

Nosoop: Insert notes on comments

2023-04-16T10:30:48Z

Insert notes on comments

Nosoop: /* Entity Properties */ Reword some bits

2023-04-16T10:22:30Z

‎Entity Properties: Reword some bits

Nosoop: /* Entity Properties */ Phrasing!

2023-04-04T15:58:05Z

‎Entity Properties: Phrasing!

Nosoop: /* Entity Properties */ Add example of working with entity properties

2023-04-04T14:37:35Z

‎Entity Properties: Add example of working with entity properties

Nosoop: /* Entity Properties */ Describe what an entity is

2023-04-04T14:17:58Z

‎Entity Properties: Describe what an entity is

Nosoop: /* What's in a Plugin */ Add notes to include, clarify 'forward' functions

2023-04-04T10:52:10Z

‎What's in a Plugin: Add notes to include, clarify 'forward' functions

Nosoop: /* SDKHooks */ Link over to DHooks

2023-01-03T10:35:01Z

‎SDKHooks: Link over to DHooks

Nosoop: /* Debugging */ Hoist hyphen out of code block

2022-06-21T10:48:54Z

‎Debugging: Hoist hyphen out of code block

Nosoop: /* Timers */ Add note on entity equality tests

2022-06-10T06:02:17Z

‎Timers: Add note on entity equality tests

Nosoop: /* Handles */ Add mentions of handle creation and disposal

2022-03-19T10:39:59Z

‎Handles: Add mentions of handle creation and disposal

@@ Line 8: / Line 8: @@
 <pre class="sourcepawn">#include &lt;sourcemod&gt;
 public void OnPluginStart() {
@@ Line 75: / Line 77: @@
 Immediately after the line is a blank line. It serves no other purpose other than to visually organize code, but organization is good.
 <pre>public void OnPluginStart() {

@@ Line 163: / Line 163: @@
 Most entities of relevance have ''netprops'' and / or ''datamaps''.  These specific names are Source Engine-specific constructs.
-* sendprops / netprops are properties that are sent over the network.
+* sendprops / netprops are properties that are sent over the network and intended to ensure the server and connected clients have the correct information.
-* dataprops / datamaps are properties that are saved / restored. (In all honesty, I'm not sure what this means.  Someone should edit this with a better explanation, because this is a wiki.)
+* dataprops / datamaps are properties that are saved / restored. (In all honesty, I'm not sure what this means; probably related to either snapshots or game saves.  Someone should edit this with a better explanation, because this is a wiki.)
-While they are stored in different ways in the engine, they both correspond to (some, not all) member variables on the entity class.
+While they are stored in different ways in the engine, they both correspond to (some, not all) member variables on the entity class that need to be kept track of in some way.
 Before we can actually work with them, we need to know which ones exist, so we'll dump them for your game. Open up your server console and type in the following:
@@ Line 177: / Line 177: @@
 Check the server's game (mod) folder and you should see the <code>netprops.txt</code> and <code>datamaps.txt</code> files.  This will provide you with a list of properties associated with each entity class.
-{{Note|Some names are listed as both netprops and dataprops on the same class.  In that case, using the netprop is preferred, as it will inform the engine that the change needs to be propagated to clients.}}
+{{Note|Some names are listed as both netprops and dataprops on the same class.  In that situation, using the netprop is preferred, as it will inform the engine that the change needs to be propagated to clients.}}
 Here's an example of how to manipulate entities - this plugin zeros out the clip on the active weapon of the player that runs it:

@@ Line 175: / Line 175: @@
 </pre>
-Check the server's game (mod) folder and you should see the <code>netprops.txt</code> and <code>datamaps.txt</code>.  This will provide you with a list of properties associated with each entity class.
+Check the server's game (mod) folder and you should see the <code>netprops.txt</code> and <code>datamaps.txt</code> files.  This will provide you with a list of properties associated with each entity class.
-{{Note|Some names refer to both netprops and dataprops.  In that case, using the netprop is preferred, as it will inform the engine that the change needs to be propagated to clients.}}
+{{Note|Some names are listed as both netprops and dataprops on the same class.  In that case, using the netprop is preferred, as it will inform the engine that the change needs to be propagated to clients.}}
 Here's an example of how to manipulate entities - this plugin zeros out the clip on the active weapon of the player that runs it:

← Older revision		Revision as of 14:37, 4 April 2023
Line 178:		Line 178:

	{{Note\|Some names refer to both netprops and dataprops. In that case, using the netprop is preferred, as it will inform the engine that the change needs to be propagated to clients.}}		{{Note\|Some names refer to both netprops and dataprops. In that case, using the netprop is preferred, as it will inform the engine that the change needs to be propagated to clients.}}
		+
		+	Here's an example of how to manipulate entities - this plugin zeros out the clip on the active weapon of the player that runs it:
		+
		+	<pre>#include <sourcemod>
		+
		+	public void OnPluginStart() {
		+	RegConsoleCmd("sm_no_clip", RemoveClip);
		+	}
		+
		+	Action RemoveClip(int client, int argc) {
		+	if (client == 0) {
		+	// this command is being run by the server console, not an actual player; we can't work with that
		+	return Plugin_Handled;
		+	}
		+
		+	// client is an entity index - we perform a lookup to get the entity assigned to m_hActiveWeapon, if one exists
		+	int weapon = GetEntPropEnt(client, Prop_Send, "m_hActiveWeapon");
		+	if (IsValidEntity(weapon)) {
		+	// the client has an active weapon - zero out its clip
		+	SetEntProp(weapon, Prop_Send, "m_iClip1", 0);
		+	}
		+	return Plugin_Handled;
		+	}
		+	</pre>
		+
		+	There are many ways to get entities depending on what you are doing. Some of them are passed directly as a callback argument, others you need to call a function to get one, and others you enumerate over a known allocated space to check.
		+
		+	{{Note\|Some properties may not work when set directly.}}

	= Timers =		= Timers =

← Older revision		Revision as of 14:17, 4 April 2023
Line 158:		Line 158:

	In this section we will talk about entity send / data properties, and some examples on how to use them.		In this section we will talk about entity send / data properties, and some examples on how to use them.
		+
		+	An ''entity'' is an instance of an object in the world. These include things like players, weapons, grenades, but also abstract things like spawn points, objective areas, and round timers.

	Most entities of relevance have ''netprops'' and / or ''datamaps''. These specific names are Source Engine-specific constructs.		Most entities of relevance have ''netprops'' and / or ''datamaps''. These specific names are Source Engine-specific constructs.

@@ Line 72: / Line 72: @@
 <pre class="sourcepawn">#include &lt;sourcemod&gt;
 </pre>
-This line is a ''preprocessor directive''. Lines starting with <code>#</code> are instructions for the compiler (rather, the preprocessor that examines the code before compilation occurs). In this case, <code>#include &lt;sourcemod&gt;</code> tells the preprocessor to include the files that make up SourceMod's standard library.
+This line is a ''preprocessor directive''. Lines starting with <code>#</code> are instructions for the compiler (rather, the preprocessor that examines the code before compilation occurs). In this case, <code>#include &lt;sourcemod&gt;</code> tells the preprocessor to include the files that make up SourceMod's standard library.  There are other first- and third-party libraries that you may want to include later on.
 Immediately after the line is a blank line. It serves no other purpose other than to visually organize code, but organization is good.
@@ Line 78: / Line 78: @@
 <pre>public void OnPluginStart() {
 </pre>
-This line defines a function named {{SourceMod API|file=sourcemod|function=OnPluginStart}} in SourceMod. It is a function that has <code>public</code> visibility, returns nothing (indicated by <code>void</code>), and has no parameters (indicated by the lack of text between the parentheses <code>()</code>). The curly brackets, <code>{}</code>, indicate the function body.
+This line defines a function named {{SourceMod API|file=sourcemod|function=OnPluginStart}} in SourceMod (click the link to see the documentation for it). It is a ''forward'' function that has <code>public</code> visibility, returns nothing (indicated by <code>void</code>), and has no parameters (indicated by the lack of text between the parentheses <code>()</code>). The curly brackets, <code>{}</code>, indicate the function body.
-SourceMod plugins are callback-based. In this case, when the plugin was loaded, SourceMod found that it had an <code>OnPluginStart</code> function (because of the public visibility mentioned previously), then ran the code within the curly brackets.
+SourceMod plugins are callback-based. In this case, when the plugin was loaded, SourceMod found that it had an <code>OnPluginStart</code> ''forward'' function (because of the public visibility mentioned previously), then ran the code within the curly brackets.  If <code>public</code> is not specified, SourceMod won't know that there's a function it should run automatically.
 <pre>    PrintToServer(&quot;Hello, world!&quot;);

← Older revision		Revision as of 10:35, 3 January 2023
Line 268:		Line 268:

	{{Note\|This section is a work-in-progress.}}		{{Note\|This section is a work-in-progress.}}
		+
		+	If SDKHooks doesn't have a hook on a function you're interested in, you can [[User:Nosoop/Guide/Advanced#Hooking_Game_Functions_.28with_DHooks.29\|hook a specific function of your choosing with DHooks]].

	= Debugging =		= Debugging =

@@ Line 276: / Line 276: @@
 * Print the ''exact'' values that are being shown if they're relevant.  It narrows down possible issues when you can see that something "is X", instead of just "is not Y".
-* Sprinkle in messages at the start of <code>if</code>- or <code>else-</code>statements so you know what code paths are being taken in your plugin.
+* Sprinkle in messages at the start of <code>if</code>- or <code>else</code>- statements so you know what code paths are being taken in your plugin.
 = Further Reading =

@@ Line 213: / Line 213: @@
 * {{SourceMod API|file=clients|function=GetClientSerial}} / {{SourceMod API|file=clients|function=GetClientFromSerial}} returns 0 if the client isn't valid anymore
 * {{SourceMod API|file=halflife|function=EntIndexToEntRef}} / {{SourceMod API|file=halflife|function=EntRefToEntIndex}} returns <code>INVALID_ENT_REFERENCE</code> if the entity isn't valid; most, if not all SourceMod core functions that accept entity indices also accept entity references, so you may not need to unwrap the reference. Just check with {{SourceMod API|file=entity|function=IsValidEntity}}.
 * {{SourceMod API|file=clients|function=GetClientUserId}} / {{SourceMod API|file=clients|function=GetClientOfUserId}} also returns 0 if the client isn't valid anymore. The values start at 1 and are incremented on player connections and map changes.

@@ Line 219: / Line 219: @@
 A handle is a special type that represents a non-primitive type in SourceMod (any value that isn't a <code>float</code>, <code>int</code>, <code>bool</code>, or <code>char</code>). Such non-primitive types are implemented as C++ objects, managed by SourceMod, and exposed to SourcePawn plugins indirectly as an integer value.
-When you called {{SourceMod API|file=timers|function=CreateTimer}} in the previous section, the function actually returned a timer handle value! We ignored it since we didn't need to worry about storing it in that case, but you generally will want to store handle values in variables.
+When you called {{SourceMod API|file=timers|function=CreateTimer}} in the previous section, the function actually returned a timer handle value! We ignored it since we didn't need to worry about storing it (timer handles are a peculiar case), but you generally will want to store handle values in variables.
 We'll expand on the timer example above by storing a few more values.  You normally can only pass one value to the timer callback, so we will use a {{SourceMod API|file=datapack|function=DataPack}} to pass more values around.  Take a look at the following code:
@@ Line 233: / Line 233: @@
      GetCmdArgString(message, sizeof(message));
      DataPack pack;
      CreateDataTimer(5.0, EchoResponse, pack);
@@ Line 255: / Line 256: @@
 </pre>
-{{Note|This section is a work-in-progress.  Work on a <code>DataPack</code> example as a follow-up to the timer example above.}}
+{{Note|This section is a work-in-progress.  Discuss handle deletion, and why neither the Timer nor DataPack in the example above need to be deleted.}}
 For other examples, see the [[Handles (SourceMod Scripting)|Handles page]] on the AlliedModders wiki.