SDKTools (SourceMod Scripting)

From AlliedModders Wiki
Revision as of 10:06, 23 August 2015 by Xerox8521 (talk | contribs) (→‎GiveNamedItem Example)
Jump to: navigation, search

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:

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: 

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

Signature Scans

For automated signature scans, add sub-sections to the "Signatures" section of your game config file. There are three properties for a signature:

  • library: Must be "server" right now.
  • windows: A signature written in binary; for example, "\x56" instead of "0x56" -- the '*' character is a single byte wildcard.
  • linux: Either a signature as with windows, or 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: 

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

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: 

"Games"
{
	"left4dead2"
	{
		"Addresses"
		{
			"CDirector"
			{
				"windows"
				{
					"signature" "DirectorMusicBanks_OnRoundStart"
					"read" "8"
				}
				"linux"
				{
					"signature" "TheDirector"
				}
				"read" "0"
			}
		}
		"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"
			}
		}
	}
}

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: 

BYTE * GetCDirectorAddress()
{
    BYTE * pAddr;

#if WINDOWS

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

#elif LINUX

    pAddr = FindSignature("TheDirector");

#endif

    pAddr = *(pAddr + 0);

    return pAddr;
}

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

stock Address:GetTheDirector()
{
   return GameConfGetAddress(g_hMyGameConf, "CDirector");
}

For more code examples, l4d2_direct relies heavily on Address: functions.

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: 

"Games"
{
	"#default"
	{
		"#supported"
		{
			"game"		"dod"
		}
	}
}

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 Handle which will let us make as many calls as we like.

  1. 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 this pointer.
  2. Destination - The call must have a destination address or virtual index to use. This is normally done via PrepSDKCall_SetFromConf which ties into gameconf files.
  3. Return Info - If the call has return information, it must be set via PrepSDKCall_SetReturnInfo.
  4. Parameters - Each parameter (if any) must be added with PrepSDKCall_AddParameter.
  5. Finalize - The call must be finalized with EndPrepSDKCall, which will return a Handle. If it doesn't, one or more of the preparation operations failed.

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: 

void CCSPlayer::RoundRespawn()

SDKCall example: 

#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);
}

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: 

virtual CBaseEntity *CBasePlayer::GiveNamedItem(const char *item, int iSubType = 0);
#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);
}

GetEyePosition Example

Prototype: 

virtual Vector CBaseEntity::EyePosition();
#include <sourcemod>
#include <sdktools>
 
new Handle:hGameConf;
new Handle:hGetEyePosition;
 
public OnPluginStart()
{
	hGameConf = LoadGameConfigFile("plugin.sdkexamples");
 
	StartPrepSDKCall(SDKCall_Player);
	PrepSDKCall_SetFromConf(hGameConf, SDKConf_Virtual, "EyePosition");
	PrepSDKCall_SetReturnInfo(SDKType_Vector, SDKPass_ByValue);
	hGetEyePosition= EndPrepSDKCall();
}
 
GetEyePosition(client, Float:pos[3])
{
	SDKCall(hGetEyePosition, client, pos);
}

Note that the vector is returned as the third parameter (first parameter after the this 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 CBaseEntity 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 ITempEnts class definition. Because of this, SourceMod takes a very flexible approach:

  • First, a temp entity is started by name using TE_Start. A list of all tempent names and their network classes can be dumped with sm_print_telist (SDKTools must be loaded).
  • Second, all of the tempent's properties are set via the TE_Write natives. All tempent properties can be dumped to a file using sm_dump_teprops.
  • Third, the properties are transmitted using TE_Send, TE_SendToAll, or TE_SendToClient.

As a convenience, SourceMod provides a number of pre-written stocks for SDK-defined temporary entities. While the TE_* natives are guaranteed to work on any fully-supported SourceMod mod, the TE_Setup* 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: 

SparkClient(client, const Float:pos[3], const Float:dir[3])
{
	TE_SetupMetalSparks(pos, dir);
	TE_SendToClient(client);
}

Not using stocks: 

SparkClient(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);
}


Sound Functions

SDKTools exposes various sound-related members of IVEngineServer and IEngineSound. The basic functions are in sdktools_sound.inc:

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

Some very simple examples: 

EmitSoundToClient(client, "bot/affirmative.wav");
EmitSoundToAll("radio/terwin.wav");

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

Retrieved from "https://wiki.alliedmods.net/index.php?title=SDKTools_(SourceMod_Scripting)&oldid=9991"