AlliedModders Wiki - User contributions [en]

Clients (SourceMod Scripting)

2020-10-16T19:50:24Z

ProdigySim: Created page with "SourceMod assigns a Client Index number to client in the server. You can use these numbers to refer to specific clients in various SourceMod APIs. In particular, the [Clie..."

[[SourceMod]] assigns a Client Index number to client in the server. You can use these numbers to refer to specific clients in various SourceMod APIs. In particular, the [Clients APIs https://sm.alliedmods.net/new-api/clients].

The server is given client index 0, and the first connected user will have client index 1.

There are two variables that can be used to talk about the maximum number of clients:

* <tt>MaxClients</tt>: The maximum number of players currently allowed to connect to the server.
** This is set at runtime based on <tt>gpGlobals->maxClients</tt> in the game server.
* <tt>MAXPLAYERS</tt>: The theoretical maximum number of clients allowed on any Source game.
** This number is set to 65, enough for 64 players + a SourceTV client.

These values represent the '''maximum count of clients'''. Since Client indexing starts at 1, be wary of off-by-one errors here!

It's recommended that you use <tt><= MaxClients</tt> when looping through the client list, and <tt>MAXPLAYERS+1</tt> when initializing an array to contain data for individual clients.

For example:
<sourcepawn>
// Declare static arrays to support the maximum number of clients possible.
new playerVotes[MAXPLAYERS+1];

public void OnPluginStart()
{
RegConsoleCmd("start_vote", Command_StartVote);
RegConsoleCmd("vote", Command_Vote);
}

public Action Command_StartVote(int client, int args)
{
// Loop through all clients based on current number of max clients.
for(int i = 0; i <= MaxClients; i++) {
playerVotes[i] = 0;
}
}

public Action Command_Vote(int client, int args)
{
char arg[128];
if( args > 0)
{
GetCmdArg(i, arg, sizeof(arg));
// Associate data with clients at their client index in an array.
playerVotes[client] = StringToInt(arg);
}

return Plugin_Handled;
}
</sourcepawn>

Other notes:

The game engine's CBaseServer has its own <tt>m_clients</tt> list. You can subtract 1 from a SourceMod client index to get the <tt>CBaseServer::m_clients</tt> index.

SDKTools (SourceMod Scripting)

2013-02-27T11:00:08Z

ProdigySim: Adding more info about Address functions and examples.

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"
}
}
}
}</pre>

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

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.

==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:
<pawn>#include <sourcemod>
#include <sdktools>

new Handle:hGameConf;
new Handle:hRoundRespawn;

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

RespawnPlayer(client)
{
SDKCall(hRoundRespawn, client);
}</pawn>

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>

<pawn>#include <sourcemod>
#include <sdktools>

new Handle:hGameConf;
new 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();
}

GiveItem(client, const String:item[])
{
return SDKCall(hGiveNamedItem, client, item, 0);
}</pawn>

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

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

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:
<pawn>SparkClient(client, const Float:pos[3], const Float:dir[3])
{
TE_SetupMetalSparks(pos, dir);
TE_SendToClient(client);
}</pawn>

Not using stocks:
<pawn>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);
}</pawn>

=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:
<pawn>
EmitSoundToClient(client, "bot/affirmative.wav");
EmitSoundToAll("radio/terwin.wav");
</pawn>

=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]]

[[Category:SourceMod Scripting]]

Talk:Left 4 Dead 2 Events

2010-07-07T16:23:28Z

ProdigySim: More opinions on organization

Is it ok for me to add more information to the event pages, like when the event is called, what the variables are used for?
[[User:Oshroth|Oshroth]] 05:09, 19 February 2010 (UTC)

Of course, if you have more Infos for events then add them
----
__NOTOC__
Is it alright for me to rearrange the events into an easier-to-read list, or at least move the explain_* events to the bottom of the list? Since there is over 70 explain_* events spread throughout the list, making it harder to find the events you are looking for [[User:Oshroth|Oshroth]] 06:42, 20 May 2010 (UTC)

e.g.
=== Player related events ===
* player_death
* player_hurt
* player_team
* etc...
=== Item related events ===
* item_pickup
* ammo_pickup
* grenade_bounce
* etc...
=== Achievement related events ===
* chair_charged
* song_played
* foot_locker_opened
* etc...
=== Explain (i.e. Game Instructor) related events ===
* explain_coaster
* explain_mall_alarm
* explain_float
* etc...
----
__NOTOC__
The structure of the events should be the same as in the modevents.res to make it easier for contributors to add and modify events according to the modevents.res if something changes.
Maybe it's possible to create a new structured menu without modifying the events structure itself.
:I would support adding a new section for Event Uses or somesuch. Information about when these events are called in relation to in-game happening would be useful. I have some of my own information to add. e.g. item_pickup is called when a player takes control of a SI, including during a tank pass. It would be nice to have this information organized in a way that is more intuitive for people seeking events to hook. --[[User:ProdigySim|ProdigySim]] 16:23, 7 July 2010 (UTC)

Vice keys

2010-06-03T14:49:22Z

ProdigySim: Added Left4Dead2's VScript .nuc VICE key

VICE keys are used to encrypt the game's weapon config files in an effort to make them more difficult to tamper with. It's not really a great protection, as usually the key is just hardcoded into the server binaries. Some games, such as Golden Eye Source, try to make it more difficult to retrieve these, but even then it's trivial.

These keys can be used to decrypt the CTX files that many games provide.

{|
!width="300"| Game
!width="100"| Key
|-
| Counter-Strike: Source
| d7NSuLq2
|-
| CSPromod
| H1aRQ0n1
|-
| Day of Defeat: Source
| Wl0u5B3F
|-
| Dystopia
| pH3apO8w
|-
| Golden Eye Source
| Gr3naDes
|-
| Half-Life 2: Deathmatch
| x9Ke0BY7
|-
| Insurgency
| DrA5e3EB
|-
| Left 4 Dead 2 (VScript .nuc)
| SDhfi878
|-
| TF2 (items.ctx)
| A5fSXbf7
|-
| TF2 (everything else)
| E2NcUkG2
|-
| ZPS
| 5R0ni0pZ
|}