SDKTools (SourceMod Scripting)

2021-06-23T14:22:17Z

BrianD:

The SDKTools extension is an extension for various functions provided by the Source SDK. Additionally, it has the ability to dynamically call many C++ functions in the SDK, for example, from CBaseEntity or any derived class.

SDKTools contains simplified versions of SDK functions pre-written for ease of use. These can be found in the additional include files:
*<tt>sdktools_functions.inc</tt> - Popular functions from the SDK.
*<tt>sdktools_sound.inc</tt> - [[#Sound Functions|Sound-related functions]].
*<tt>sdktools_tempents.inc</tt> - [[#TempEnt Functions|TempEnt-related functions]].
*<tt>sdktools_tempents_stocks.inc</tt> - [[TempEnts (SourceMod SDKTools)|TempEnt Stocks for convenience]].

SDKTools is powered by "BinTools," a powerful extension for creating dynamic C/C++ calls. BinTools is automatically loaded by SDKTools.

=GameConfigs=
GameConfig files go into the "gamedata" folder under "sourcemod." In older revisions it was under "sourcemod/configs" which is now deprecated.

==Virtual Offsets==
For adding virtual offsets, add sub-sections to the "Offsets" section of your game config file. For example:

<pre>
"Games"
{
"cstrike"
{
"Offsets"
{
"GiveNamedItem"
{
"windows" "329"
"linux" "330"
}
"EyePosition"
{
"windows" "117"
"linux" "118"
}

// Get offset of CPlayerResource::m_iBotDifficulty sendprop.
// Dynamic way for FindSendPropInfo(class, prop);
"BotDifficulty"
{
"class" "CPlayerResource"
"prop" "m_iBotDifficulty"
}
}
}
}</pre>

==Signature Scans==
For automated signature scans, add sub-sections to the "Signatures" section of your game config file. These are the properties for a signature:
*<tt>library</tt>: The library to search for the pattern or symbol for: "server", "engine" or "matchmaking_ds" (defaults to "server").
*<tt>windows</tt>, <tt>linux</tt> or <tt>mac</tt>: A pattern or symbol for that platform:

You can put a pattern to search for in memory or a symbol name to lookup:
*A signature written in binary; for example, "\x56" instead of "0x56" -- the '*' (\x2A) character is a single byte wildcard.
*A named symbol. To use a named symbol, start the string with the '@' character. If a signature begins with '@', write the character in hexadecimal as above.

Example:
<pre>
"Games"
{
"cstrike"
{
"Signatures"
{
"RoundRespawn"
{
"library" "server"
"windows" "\x56\x8B\xF1\x8B\x06\xFF\x90*\x04\x00\x00\x8B\x86*\x0D\x00"
"linux" "@_ZN9CCSPlayer12RoundRespawnEv"
}
}
}
}</pre>

==Raw address lookups==
Lets you peek and poke (limitation may apply) the Source Dedicated Server memory space, and get a raw address value in an automated way.

Example:
<pre>
"Games"
{
"left4dead2"
{
"Addresses"
{
"CDirector"
{
"windows"
{
"signature" "DirectorMusicBanks_OnRoundStart"
"read" "8"
}
"linux"
{
"signature" "TheDirector"
}
"read" "0"
// Since SourceMod 1.9
"offset" "4"
}
}
"Signatures"
{
/* Used solely to get the offset for TheDirector */
"DirectorMusicBanks_OnRoundStart"
{
"library" "server"
"windows" "\x83\xEC\x14\x57\x8B\xF9\x8B\x0D\x2A\x2A\x2A\x2A\xE8\x2A\x2A\x2A\x2A\x84\xC0\x0F\x2A\x2A\x2A\x2A\x2A\x53\x55\x6A\x24\xE8"
/* 83 EC 14 57 8B F9 8B 0D ? ? ? ? E8 ? ? ? ? 84 C0 0F ? ? ? ? ? 53 55 6A 24 E8 */
}

/* Find the Director/ZombieManager singleton classes */

"TheDirector"
{
"library" "server"
"linux" "@TheDirector"
}
}
}
}
</pre>

The data in an Address entry is parse from top to bottom as commands. This example would accomplish the same thing as the following pseudo-C++ code:

<pre>
BYTE * GetCDirectorAddress()
{
BYTE * pAddr;

#if WINDOWS

pAddr = FindSignature("DirectorMusicBanks_OnRoundStart");
pAddr = *(pAddr + 8);

#elif LINUX

pAddr = FindSignature("TheDirector");

#endif

pAddr = *(pAddr + 0);
// Since SourceMod 1.9
pAddr = pAddr + 4;

return pAddr;
}</pre>

To invoke this address lookup in your Sourcepawn code, you would simply set up your GameConf handle and run something like the following:

<pre>
stock Address:GetTheDirector()
{
return GameConfGetAddress(g_hMyGameConf, "CDirector");
}</pre>

For more code examples, [https://github.com/confoglteam/l4d2_direct l4d2_direct] relies heavily on Address: functions.

==Custom Key Values==
To read arbitary key value pairs from a gamedata file, add them to the "Keys" section of your game config file.
You can have different values per platform or have a key only be available on selected platforms.

Example:
<pre>
"Games"
{
"cstrike"
{
"Keys"
{
"INTERFACEVERSION_GAMEEVENTSMANAGER2" "GAMEEVENTSMANAGER002"

// Different values per platform (since SourceMod 1.10+)
"MyGreatKey"
{
"windows" "this is wundows speaking"
"linux" "linux best linux"
"mac" "wat"
}

"JustForLinux"
{
"linux" "not relevant for other platforms!"
}

}
}
}</pre>

You can access the keys using
<pre>
char buffer[512];
GameConfGetKeyValue(g_hMyGameConf, "MyGreatKey", buffer, sizeof(buffer));
</pre>

==Inheritance==
If you wish for multiple mods to inherit from one block, you can add a special "#supported" section under a "#default" section. For example:

<pre>
"Games"
{
"#default"
{
"#supported"
{
"game" "dod"
}
}
}</pre>

This specifies that the given block will be read for Day of Defeat as well.

=Calling Functions=
Calling functions is complicated and requires strict attention to the C++ API you are trying to use. If you make a mistake, something bad '''will''' happen (and if not, you got lucky!) SDKTools is more complicated than PimpinJuice's "Hacks" extension because it precompiles all of the information needed to convert from Plugin memory to C++ types. This precompilation step ensures better safety and speed, but it lengthens the preparation process.

With that said, let's look at an overview of the call creation process. Before making calls, we must ''prepare'' the call. This will give us a <tt>Handle</tt> which will let us make as many calls as we like.
<ol>
<li>Init - The preparation must be initialized. Here we can specify the calling convention, which is either static, or BaseEntity/BasePlayer-based. BasePlayer should be used when only player entities should be allowed as the <tt>this</tt> pointer.</li>
<li>Destination - The call must have a destination address or virtual index to use. This is normally done via <tt>PrepSDKCall_SetFromConf</tt> which ties into gameconf files.</li>
<li>Return Info - If the call has return information, it must be set via <tt>PrepSDKCall_SetReturnInfo</tt>.</li>
<li>Parameters - Each parameter (if any) must be added with <tt>PrepSDKCall_AddParameter</tt>.</li>
<li>Finalize - The call must be finalized with <tt>EndPrepSDKCall</tt>, which will return a <tt>Handle</tt>. If it doesn't, one or more of the preparation operations failed.</li>
</ol>

For the examples below, consider a plugin called "sdkexamples.sp" which has a gamedata file of "plugin.sdkexamples.txt" containing the definitions in the first section.

==RoundRespawn Example==
CCSPlayer::RoundRespawn is a Counter-Strike Source function which respawns players. It used by CS:S DM. Prototype:
<pre>void CCSPlayer::RoundRespawn()</pre>

SDKCall example:
<sourcepawn>#include <sourcemod>
#include <sdktools>

Handle hGameConf;
Handle hRoundRespawn;

public void OnPluginStart()
{
hGameConf = LoadGameConfigFile("plugin.sdkexamples");
StartPrepSDKCall(SDKCall_Player);
PrepSDKCall_SetFromConf(hGameConf, SDKConf_Signature, "RoundRespawn");
hRoundRespawn = EndPrepSDKCall();
}

void RespawnPlayer(int client)
{
SDKCall(hRoundRespawn, client);
}</sourcepawn>

Note that we did not have to set any extra information for parameters or return info, since CCSPlayer::RoundRespawn has no parameters and has a void return.

==GiveNamedItem Example==
GiveNamedItem will give a player a named item. Prototype:
<pre>virtual CBaseEntity *CBasePlayer::GiveNamedItem(const char *item, int iSubType = 0);</pre>

<sourcepawn>#include <sourcemod>
#include <sdktools>

Handle hGameConf;
Handle hGiveNamedItem;

public OnPluginStart()
{
hGameConf = LoadGameConfigFile("plugin.sdkexamples");

StartPrepSDKCall(SDKCall_Player);
PrepSDKCall_SetFromConf(hGameConf, SDKConf_Virtual, "GiveNamedItem");
PrepSDKCall_SetReturnInfo(SDKType_CBaseEntity, SDKPass_Pointer);
PrepSDKCall_AddParameter(SDKType_String, SDKPass_Pointer);
PrepSDKCall_AddParameter(SDKType_PlainOldData, SDKPass_Plain);
hGiveNamedItem = EndPrepSDKCall();
}

any GiveItem(int client, const char[] item)
{
return SDKCall(hGiveNamedItem, client, item, 0);
}</sourcepawn>

==GetEyePosition Example==
Prototype:
<pre>virtual Vector CBaseEntity::EyePosition();</pre>

<sourcepawn>#include <sourcemod>
#include <sdktools>

Handle hGameConf;
Handle hGetEyePosition;

public void OnPluginStart()
{
hGameConf = LoadGameConfigFile("plugin.sdkexamples");

StartPrepSDKCall(SDKCall_Player);
PrepSDKCall_SetFromConf(hGameConf, SDKConf_Virtual, "EyePosition");
PrepSDKCall_SetReturnInfo(SDKType_Vector, SDKPass_ByValue);
hGetEyePosition= EndPrepSDKCall();
}

any GetEyePosition(int client, float pos[3])
{
SDKCall(hGetEyePosition, client, pos);
}</sourcepawn>

Note that the vector is returned as the third parameter (first parameter after the <tt>this</tt> pointer).

=TempEnt Functions=
TempEnts, also called "temporary entities," "tempentities," or "TEs," are quick graphical displays that are too simple to justify the overhead of a <tt>CBaseEntity</tt> instantiation or full server-side networkability. In the SDK, they are statically defined instances that can be "played back" to the client by simply sending a copy of its network class properties.

Temporary Entities are mod-dependent, in that a mod can change any of their properties or even the <tt>ITempEnts</tt> class definition. Because of this, SourceMod takes a very flexible approach:
*First, a temp entity is ''started'' by name using <tt>TE_Start</tt>. A list of all tempent names and their network classes can be dumped with <tt>sm_print_telist</tt> (SDKTools must be loaded).
*Second, all of the tempent's properties are set via the <tt>TE_Write</tt> natives. All tempent properties can be dumped to a file using <tt>sm_dump_teprops</tt>.
*Third, the properties are transmitted using <tt>TE_Send</tt>, <tt>TE_SendToAll</tt>, or <tt>TE_SendToClient</tt>.

As a convenience, SourceMod provides a number of pre-written stocks for SDK-defined temporary entities. While the <tt>TE_*</tt> natives are guaranteed to work on any fully-supported SourceMod mod, the <tt>TE_Setup*</tt> stocks are not, as a mod might change the property layouts or the functionalities of the SDK-defined tempents.

Some examples are below. For pictures, see [[TempEnts (SourceMod SDKTools)]].

Using stocks:
<sourcepawn>void SparkClient(int client, const float pos[3], const float dir[3])
{
TE_SetupMetalSparks(pos, dir);
TE_SendToClient(client);
}</sourcepawn>

Not using stocks:
<sourcepawn>void SparkClient(int client, const float pos[3], const float dir[3])
{
TE_Start("Metal Sparks");
TE_WriteVector("m_vecPos", pos);
TE_WriteVector("m_vecDir", dir);
TE_SendToClient(client);
}</sourcepawn>

=Sound Functions=
SDKTools exposes various sound-related members of IVEngineServer and IEngineSound. The basic functions are in <tt>sdktools_sound.inc</tt>:
*<tt>EmitAmbientSound</tt>: Plays an ambient sound from an origin.
*<tt>EmitSound, EmitSoundToClient, EmitSoundToAll</tt>: Plays a sound to a list of clients from a specific entity.

There are a few important properties about sounds:
*Entity: The entity the sound should come from. When playing a generic sound file to player(s), you should use <tt>SOUND_FROM_PLAYER</tt>, which is a special SourceMod macro for making the sound come from the player target. For ambient sounds you'd use <tt>SOUND_FROM_WORLD</tt>, and for sounds from an entity you'd use the entity index.
*Channel: Exposed as <tt>SNDCHAN_*</tt>, normally you only need to use <tt>SNDCHAN_AUTO</tt>. The channel affects how the sound is spatialized[?]
*Level: The decibel level. There are a number of predefined levels as <tt>SNDLEVEL_*</tt> -- the standard one is <tt>SNDLEVEL_NORMAL</tt>. Half-Life 1 used attenuation values instead; you can convert from these using <tt>ATTN_TO_SNDLEVEL()</tt>.
*Volume: The volume, on a scale of 0.0 to 1.0. To use a volume other than the default, the <tt>SND_CHANGEVOL</tt> flag should be included in the "flags" parameter. The default volume is <tt>SNDVOL_NORMAL</tt>.
*Pitch: The pitch; predefined values are <tt>SNDPITCH_*</tt> with <tt>SNDPITCH_NORMAL</tt> being the default. <tt>SND_CHANGEPITCH</tt> should be passed to use a non-default pitch.
*Origin: If specified, an origin to play the sound from.

Some very simple examples:
<sourcepawn>
EmitSoundToClient(client, "bot/affirmative.wav");
EmitSoundToAll("radio/terwin.wav");
</sourcepawn>

=Supported Mods=
SDKTools must have specific support added for each mod. So far, default support exists for the following modifications:
*Counter-Strike: Source
*Day of Defeat: Source
*Dystopia
*Half-Life 2: Deathmatch
*Insurgency (only some of the CBasePlayer SDK functions are available)
*Pirates, Vikings, and Knights II
*The Ship
*SourceForts

=See Also=
*[[Vfunc_offsets_%28SourceMM%29|Virtual Functions]]
*[[TempEnts (SourceMod SDKTools)|TempEnts]]
*[[Useful_Signatures_%28Source%29|Useful Signatures]]
*[[Signature_Scanning|Signature Scanning]]

[[Category:SourceMod Scripting]]

AlliedModders Wiki - User contributions [en]

SDKTools (SourceMod Scripting)