AlliedModders Wiki - User contributions [en]

Events (SourceMod Scripting)

2010-07-26T08:07:51Z

Flintb: Fixed error.

:''To view all the events, click [[Game Events (Source)|here]].''

Events are short, named messages sent by the server. Although they are used for internal message passing, they are also networked to clients.

All event natives are found in <tt>scripting/include/events.inc</tt>.

=Introduction=
Events are documented in <tt>.res</tt> files under a mod's <tt>resource</tt> folder. The "default" events are located in <tt>hl2/resource/gameevents.res</tt> and <tt>hl2/resource/serverevents.res</tt>. Mods can extend these events with their own.

For example, let's look at <tt>player_death</tt> from <tt>hl2/resource/gameevents.res</tt>:
<pre>"player_death"
{
"userid" "short" // user ID who died
"attacker" "short" // user ID who killed
}</pre>

Counter-Strike:Source extends this definition in <tt>cstrike/resource/modevents.res</tt>:
<pre>"player_death"
{
"userid" "short" // user ID who died
"attacker" "short" // user ID who killed
"weapon" "string" // weapon name killer used
"headshot" "bool" // signals a headshot
}</pre>

Note that the event is structured in the following format:
<pre>"name"
{
"key1" "valueType1"
"key2" "valueType2"
...
}</pre>

=Sending Events=
Events are very easy to send. For example, let's say we want to send a death message using the <tt>player_death</tt> event from above. For Counter-Strike:Source, this would look like:

<pawn>SendDeathMessage(attacker, victim, const String:weapon[], bool:headshot)
{
new Handle:event = CreateEvent("player_death")
if (event == INVALID_HANDLE)
{
return
}

SetEventInt(event, "userid", GetClientUserId(victim))
SetEventInt(event, "attacker", GetClientUserId(attacker))
SetEventString(event, "weapon", weapon)
SetEventBool(event, "headshot", headshot)
FireEvent(event)
}</pawn>

Notes:
*You don't need to call <tt>CloseHandle()</tt>, <tt>FireEvent()</tt> does this for us.
*Even though "userid" and "attacker" are shorts, we set them as ints. The term "short" is only used to tell the engine how many bytes of the integer are needed to be networked.
*It is possible for event creation to fail; this can happen if the event does not exist, or nothing is hooking the event. Thus, you should always make sure <tt>CreateEvent</tt> calls return a valid Handle.
*Most events use client userids instead of client indexes.
*By default, <tt>FireEvent()</tt> broadcasts messages to clients. This can be prevented by passing <tt>dontBroadcast</tt> as true.

=Hooking Events=
When hooking an event, there are three modes to choose from:
*<tt>Pre</tt> - Hook the event before it is fired.
*<tt>Post</tt> - Hook the event after it is fired.
*<tt>Post_NoCopy</tt> - Hook the event, but do not save any of its information (special optimization).

Hooking an event is usually done for one of the following goals. To get an idea of which mode to use, see the list below each goal:
*Blocking the event (preventing it from being fired)
**'''Always <tt>Pre</tt>'''
*Rewriting the event (changing its parameters)
**'''Always <tt>Pre</tt>'''
*Acting upon the event (doing something once the event is completed)
**'''<tt>Pre</tt>''' if your action must come before the mod's action.
**'''<tt>Post</tt>''' if your action must come after the mod's action.
**'''<tt>PostNoCopy</tt>''' if your action is <tt>Post</tt> and only requires the event name.

As always, you do not need to unhook events when your plugin unloads. They are automatically removed.

==Blocking Events==
Blocking events is the easiest thing to do. Let's say we want to block death events that are headshots:

<pawn>public OnPluginStart()
{
HookEvent("player_death", Event_PlayerDeath, EventHookMode_Pre)
}

public Action:Event_PlayerDeath(Handle:event, const String:name[], bool:dontBroadcast)
{
if (GetEventBool(event, "headshot"))
{
return Plugin_Handled
}
return Plugin_Continue
}</pawn>

==Rewriting Events==
Rewriting events is just as easy -- events can be modified in pre hooks. For example, say we want to remove headshots from all events:

<pawn>public OnPluginStart()
{
HookEvent("player_death", Event_PlayerDeath, EventHookMode_Pre)
}

public Action:Event_PlayerDeath(Handle:event, const String:name[], bool:dontBroadcast)
{
SetEventBool(event, "headshot", false)
return Plugin_Changed
}</pawn>

Be sure to return '''Plugin_Changed''' instead of '''Plugin_Continue''' when modifying the event or its properties.

==Post Hooks==
Post hooks are default, and will usually be the most common usage. For example, say we want to print a message to every client that dies:

<pawn>public OnPluginStart()
{
HookEvent("player_death", Event_PlayerDeath)
}

public Event_PlayerDeath(Handle:event, const String:name[], bool:dontBroadcast)
{
decl String:weapon[64]
new victimId = GetEventInt(event, "userid")
new attackerId = GetEventInt(event, "attacker")
new bool:headshot = GetEventBool(event, "headshot")
GetEventString(event, "weapon", weapon, sizeof(weapon))

decl String:name[64]
new victim = GetClientOfUserId(victimId)
new attacker = GetClientOfUserId(attackerId)
GetClientName(attacker, name, sizeof(name))

PrintToConsole(victim,
"You were killed by \"%s\" (weapon \"%s\") (headshot \"%d\")",
name,
weapon,
headshot)
}</pawn>

This will print a message to a player's console telling them who killed them, with what weapon, and whether it was a headshot or not.

Note that the return value for post hooks is ignored, so the <tt>Action</tt> tag is not needed.

==PostNoCopy Hooks==
Lastly, there are some hooks where the only piece of information needed is the name of the event. <tt>PostNoCopy</tt> is a special optimization for this case. When transitioning from <tt>Pre</tt> to <tt>Post</tt>, SourceMod must duplicate the event and all of its key/value pairs. <tt>PostNoCopy</tt> prevents that sequence from happening.

For example, let's say we want to find when a certain sequence of events is called.

<pawn>public OnPluginStart()
{
HookEvent("game_newmap", GameEvents, EventHookMode_PostNoCopy)
HookEvent("game_start", GameEvents, EventHookMode_PostNoCopy)
HookEvent("game_end", GameEvents, EventHookMode_PostNoCopy)
HookEvent("game_message", GameEvents, EventHookMode_PostNoCopy)
}

public GameEvents(Handle:event, const String:name[], bool:dontBroadcast)
{
PrintToServer("Event has been fired (event \"%s\") (nobcast \"%d\")", name, dontBroadcast)
}</pawn>

Note that like normal <tt>Post</tt> hooks, there is no return value needed. However, the <tt>event</tt> parameter for <tt>PostNoCopy</tt> will '''always''' be equal to <tt>INVALID_HANDLE</tt>. Thus, the <tt>name</tt> parameter must be used instead of <tt>GetEventName</tt>.

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Talk:Events (SourceMod Scripting)

2010-07-12T09:21:36Z

Flintb: Created page with 'The sending event example doesn't really make sense to me. Can someone give an other example (possible using TF2 if you can). I'm trying to force a bot to shoot. ~Flint B.'

The sending event example doesn't really make sense to me. Can someone give an other example (possible using TF2 if you can). I'm trying to force a bot to shoot. ~Flint B.

Team Fortress 2 Weapons

2010-07-12T07:22:18Z

Flintb: Added a note about multiple weapons have the same name. Also put class names in bold for easier reading.

This is a current list of the weapon entity names for Team Fortress 2. 
 
These are sorted by Class -- Primary, Secondary, and Melee. 
 
Also keep in mind that two or more weapons may have the same name. For example, the Heavy's primary weapons are called "Minigun" and "Natasha" but both are named "tf_weapon_minigun" according to GetClientWeapon(). 
 
'''DemoMan''' 
tf_weapon_pipebomblauncher 
tf_weapon_grenadelauncher 
tf_weapon_bottle 
tf_weapon_sword 
 
'''Engineer''' 
tf_weapon_shotgun_primary 
tf_weapon_pistol 
tf_weapon_wrench 
tf_weapon_robot_arm 
tf_weapon_builder 
tf_weapon_objectselection 
tf_weapon_pda_engineer_build 
tf_weapon_pda_engineer_destroy 
 
'''Heavy''' 
tf_weapon_minigun 
tf_weapon_shotgun_hwg 
tf_weapon_fists 
 
'''Medic''' 
tf_weapon_syringegun_medic 
tf_weapon_medigun 
tf_weapon_bonesaw 
 
'''Pyro''' 
tf_weapon_flamethrower 
tf_weapon_flaregun 
tf_weapon_shotgun_pyro 
tf_weapon_fireaxe 
 
'''Scout''' 
tf_weapon_scattergun 
tf_weapon_pistol_scout 
tf_weapon_bat 
tf_weapon_bat_wood 
tf_weapon_lunchbox_drink 
 
'''Sniper''' 
tf_weapon_sniperrifle 
tf_weapon_smg 
tf_weapon_club 
 
'''Soldier''' 
tf_weapon_rocketlauncher 
tf_weapon_rocketlauncher_directhit 
tf_weapon_shotgun_soldier 
tf_weapon_buff_item 
tf_weapon_shovel 
 
'''Spy''' 
tf_weapon_revolver 
tf_weapon_knife 
tf_weapon_pda_spy 
tf_weapon_invis

Team Fortress 2 Weapons

2010-07-12T07:15:30Z

Flintb: Updated with a few new weapons (I didn't completely update though) and arranged classes by alphabetical order (they were in random order ).

This is a current list of the weapon entity names for Team Fortress 2. 
 
These are sorted by Class -- Primary, Secondary, and Melee. 
 
DemoMan 
tf_weapon_pipebomblauncher 
tf_weapon_grenadelauncher 
tf_weapon_bottle 
tf_weapon_sword 
 
Engineer 
tf_weapon_shotgun_primary 
tf_weapon_pistol 
tf_weapon_wrench 
tf_weapon_robot_arm 
tf_weapon_builder 
tf_weapon_objectselection 
tf_weapon_pda_engineer_build 
tf_weapon_pda_engineer_destroy 
 
Heavy 
tf_weapon_minigun 
tf_weapon_shotgun_hwg 
tf_weapon_fists 
 
Medic 
tf_weapon_syringegun_medic 
tf_weapon_medigun 
tf_weapon_bonesaw 
 
Pyro 
tf_weapon_flamethrower 
tf_weapon_flaregun 
tf_weapon_shotgun_pyro 
tf_weapon_fireaxe 
 
Scout 
tf_weapon_scattergun 
tf_weapon_pistol_scout 
tf_weapon_bat 
tf_weapon_bat_wood 
tf_weapon_lunchbox_drink 
 
Sniper 
tf_weapon_sniperrifle 
tf_weapon_smg 
tf_weapon_club 
 
Soldier 
tf_weapon_rocketlauncher 
tf_weapon_rocketlauncher_directhit 
tf_weapon_shotgun_soldier 
tf_weapon_buff_item 
tf_weapon_shovel 
 
Spy 
tf_weapon_revolver 
tf_weapon_knife 
tf_weapon_pda_spy 
tf_weapon_invis

Tags (Scripting)

2010-07-11T10:55:22Z

Flintb:

=Introduction=
Tags are a concept in the original Small/Pawn language that work around the inherent lack of data types present. For example, Java/C would declare variables like so:
<java>double dNumber = 5.0;
int iNumber = 5;
char cLetter = 'a';
</java>

In Java, the sizes of these types respectively are eight bytes, four bytes, and two bytes. However, Pawn is only capable of one data type size. In SourcePawn, that's 32bit (four bytes). Therefore, tags serve two purposes:
*Allow overloads and restrictions of basic math operators
*Introduce weak typing and coalescence

An example of this is:
<pawn>new Float:fNum = 5.0;
new iNum = 5;
new char = 'A';</pawn>

In this example, all of the variables are the same ''type'', the <tt>cell</tt>, which is four bytes. But the <tt>fNum</tt> variable is ''tagged'' as a <tt>Float</tt>, and so it uses a set of overloaded operators for floating point math. The <tt>iNum</tt> and <tt>char</tt> variables are both integers. Even though <tt>char</tt> is only holding one byte of data (an ASCII character), it is still a 32bit data type.

==Usage==
Tags are identified by prefixing the tag name and a colon to a variable name. Note that you still need the <tt>new</tt> declaration, as tags aren't a declaration in and of themselves. Example:
<pawn>//this is valid
new ValidTag:crab = something;
//this is not
InvalidTag:tag = something;
</pawn>

Tags can be used for enumerations. For example, the following defines a list of constant symbols which are each tagged as the enumeration name.
<pawn>enum Clam
{
Oyster = 0, /* Oyster has the Clam tag */
Quahog = 1, /* Quahog has the Clam tag */
};</pawn>

==Mismatches and Coalescence==
If you attempt to mix tags in an expression, you will get the infamous (213) "Tag mismatch" warning from the compiler. Although it is only a warning, it ''can'' be a serious error, and it is important that your plugins do not carry this warning (or, if they do, it is carefully understood to be safe).

An example of a tag mismatch, using the above enumeration, might be:
<pawn>stock GetClamNumber()
{
return Oyster;
}

stock Clam:GetOyster()
{
return 0;
}</pawn>

Both of these functions will generate tag mismatch warnings by the compiler. This is because 0 is not inherently an Oyster, and Oyster is a <tt>Clam</tt>, not a raw number.

Luckily in Pawn, you can 'coalesce' tags. This means you can convert one tag to another. This is usually a bad idea, however, it can be important for converting a bitstring to another bitstring, or a raw integer. The generic, or "empty" tag is <tt>_</tt>, and this symbol will effectively strip a tag from a tagged variable. For example:
<pawn>stock GetClamNumber()
{
return _:Oyster;
}

stock Clam:GetOyster()
{
return Clam:0;
}</pawn>

This forces the tags to be correct. ''Note that the second function could simply return <tt>Oyster</tt>. This mistake was for example purposes only.''

=Built-in Tags=
Pawn has two built-in tags by default. These are '''bool''' and '''Float'''.

==Boolean==
The <tt>bool</tt> tag (note case sensitivity) can be set to two values:
*'''true''' - 1
*'''false''' - 0

Again, it is not faster or slower than an integer 1 or 0, because the data type is the same. This tag simply provides better looking code.

==Float==
The <tt>Float</tt> tag (note case sensitivity) is used for floating point math. If the compiler detects a number to have a decimal point, it is automatically tagged as Float. Floats have the following operators defined. Note that these operators are not intrinsic to the compiler, and are written in <tt>float.inc</tt>.
*'''Math'''
** '''Binary''' +, -, /, * (at least one side must be a Float)
** '''Unary''' ++, --
** '''Unary''' -
*'''Comparison'''
** '''Binary''' ==, != (at least one side must be a Float)
** '''Binary''' >=, >, <, <= (at least one side must be a Float)
** '''Unary''' !

=SourceMod Specific=
==New Magic Tags==
In SourceMod, the rules for tags change in two cases, as there are a few 'magic' tags. These magic tags are:
<ul>
<li>'''Function''': This is the tag returned when using a function without a call. For example: <pawn>stock Function() { }
new Function:fCall = Function;</pawn></li>
<li>'''String''': This is a "magic" tag similar to <tt>Float</tt>. It is inherent to literal strings. Unlike <tt>Float</tt>, it secretly changes the storage method -- this makes it a true data type internally, unlike any other tag. Any array tagged as a String is stored in ''bytes'', not ''cells''. Observe the example: <pawn>new String:hello[] = "Hello";
new hello2[] = "Hello";
new hello3[] = {'H', 'e', 'l', 'l', 'o', 0};</pawn>
In this example, <tt>hello</tt> is a valid string array. To the scripter, this appears normal. Internally, it is roughly 6 bytes. This is specifically to make C++ coding of Pawn very fast and easy, in order to avoid cell to string conversion. <tt>hello2</tt> is an invalid declaration, as it is a tag mismatch. <tt>hello3</tt> is a valid declaration, but uses one cell for each character, rather than one byte. Thus, it will be incompatible with natives that use Strings. ''This is a good example of why tag coalescence is often dangerous.'' If you attempt to manually rewrite tags for strings, the result will be very unexpected, and may even crash.

Note, however, that is still possible to do assignments like this:
<pawn>new String:string[20]
new letter = 'a'
string[3] = 'a'
string[a] = letter</pawn>

These assignments work because the <tt>String</tt> tag is a true type underneath, and will correctly cast other tags when necessary.</li>
</ul>

==Function Enumerations==
SourceMod features "function enumerations," which are normal enums, except they define function prototypes rather than constants. Each of the prototypes is given a unique sub-tag that only matches a <tt>Function</tt> of that prototype. These will be explained more in the future, as they are not used yet.

==New General Tags==
SourceMod introduces one important general tag.
*'''Handle''': Used for the [[Handles (SourceMod Scripting)|Handle System]].

=AMX Mod X Specific=
AMX Mod X has literally a plethora of tags, but has no new "magic" tags. Some of these tags are:
*'''Sql''': An SQL index for the DBI system.
*'''Result''': An SQL Result index for the DBI system.
*'''Handle''': An SQL Handle (precursor to SourceMod's <tt>Handle</tt>) for the SQLX system.
*'''Vault''': An index for a vault opened with the nVault module.

[[Category:SourceMod Scripting]]
[[Category:Scripting (AMX Mod X)]]

Tags (Scripting)

2010-07-11T10:54:55Z

Flintb:

=Introduction=
Tags are a concept in the original Small/Pawn language that work around the inherent lack of data types present. For example, Java/C would declare variables like so:
<java>double dNumber = 5.0;
int iNumber = 5;
char cLetter = 'a';
</java>

In Java, the sizes of these types respectively are eight bytes, four bytes, and two bytes. However, Pawn is only capable of one data type size. In SourcePawn, that's 32bit (four bytes). Therefore, tags serve two purposes:
*Allow overloads and restrictions of basic math operators
*Introduce weak typing and coalescence

An example of this is:
<pawn>new Float:fNum = 5.0f;
new iNum = 5;
new char = 'A';</pawn>

In this example, all of the variables are the same ''type'', the <tt>cell</tt>, which is four bytes. But the <tt>fNum</tt> variable is ''tagged'' as a <tt>Float</tt>, and so it uses a set of overloaded operators for floating point math. The <tt>iNum</tt> and <tt>char</tt> variables are both integers. Even though <tt>char</tt> is only holding one byte of data (an ASCII character), it is still a 32bit data type.

==Usage==
Tags are identified by prefixing the tag name and a colon to a variable name. Note that you still need the <tt>new</tt> declaration, as tags aren't a declaration in and of themselves. Example:
<pawn>//this is valid
new ValidTag:crab = something;
//this is not
InvalidTag:tag = something;
</pawn>

Tags can be used for enumerations. For example, the following defines a list of constant symbols which are each tagged as the enumeration name.
<pawn>enum Clam
{
Oyster = 0, /* Oyster has the Clam tag */
Quahog = 1, /* Quahog has the Clam tag */
};</pawn>

==Mismatches and Coalescence==
If you attempt to mix tags in an expression, you will get the infamous (213) "Tag mismatch" warning from the compiler. Although it is only a warning, it ''can'' be a serious error, and it is important that your plugins do not carry this warning (or, if they do, it is carefully understood to be safe).

An example of a tag mismatch, using the above enumeration, might be:
<pawn>stock GetClamNumber()
{
return Oyster;
}

stock Clam:GetOyster()
{
return 0;
}</pawn>

Both of these functions will generate tag mismatch warnings by the compiler. This is because 0 is not inherently an Oyster, and Oyster is a <tt>Clam</tt>, not a raw number.

Luckily in Pawn, you can 'coalesce' tags. This means you can convert one tag to another. This is usually a bad idea, however, it can be important for converting a bitstring to another bitstring, or a raw integer. The generic, or "empty" tag is <tt>_</tt>, and this symbol will effectively strip a tag from a tagged variable. For example:
<pawn>stock GetClamNumber()
{
return _:Oyster;
}

stock Clam:GetOyster()
{
return Clam:0;
}</pawn>

This forces the tags to be correct. ''Note that the second function could simply return <tt>Oyster</tt>. This mistake was for example purposes only.''

=Built-in Tags=
Pawn has two built-in tags by default. These are '''bool''' and '''Float'''.

==Boolean==
The <tt>bool</tt> tag (note case sensitivity) can be set to two values:
*'''true''' - 1
*'''false''' - 0

Again, it is not faster or slower than an integer 1 or 0, because the data type is the same. This tag simply provides better looking code.

==Float==
The <tt>Float</tt> tag (note case sensitivity) is used for floating point math. If the compiler detects a number to have a decimal point, it is automatically tagged as Float. Floats have the following operators defined. Note that these operators are not intrinsic to the compiler, and are written in <tt>float.inc</tt>.
*'''Math'''
** '''Binary''' +, -, /, * (at least one side must be a Float)
** '''Unary''' ++, --
** '''Unary''' -
*'''Comparison'''
** '''Binary''' ==, != (at least one side must be a Float)
** '''Binary''' >=, >, <, <= (at least one side must be a Float)
** '''Unary''' !

=SourceMod Specific=
==New Magic Tags==
In SourceMod, the rules for tags change in two cases, as there are a few 'magic' tags. These magic tags are:
<ul>
<li>'''Function''': This is the tag returned when using a function without a call. For example: <pawn>stock Function() { }
new Function:fCall = Function;</pawn></li>
<li>'''String''': This is a "magic" tag similar to <tt>Float</tt>. It is inherent to literal strings. Unlike <tt>Float</tt>, it secretly changes the storage method -- this makes it a true data type internally, unlike any other tag. Any array tagged as a String is stored in ''bytes'', not ''cells''. Observe the example: <pawn>new String:hello[] = "Hello";
new hello2[] = "Hello";
new hello3[] = {'H', 'e', 'l', 'l', 'o', 0};</pawn>
In this example, <tt>hello</tt> is a valid string array. To the scripter, this appears normal. Internally, it is roughly 6 bytes. This is specifically to make C++ coding of Pawn very fast and easy, in order to avoid cell to string conversion. <tt>hello2</tt> is an invalid declaration, as it is a tag mismatch. <tt>hello3</tt> is a valid declaration, but uses one cell for each character, rather than one byte. Thus, it will be incompatible with natives that use Strings. ''This is a good example of why tag coalescence is often dangerous.'' If you attempt to manually rewrite tags for strings, the result will be very unexpected, and may even crash.

Note, however, that is still possible to do assignments like this:
<pawn>new String:string[20]
new letter = 'a'
string[3] = 'a'
string[a] = letter</pawn>

These assignments work because the <tt>String</tt> tag is a true type underneath, and will correctly cast other tags when necessary.</li>
</ul>

==Function Enumerations==
SourceMod features "function enumerations," which are normal enums, except they define function prototypes rather than constants. Each of the prototypes is given a unique sub-tag that only matches a <tt>Function</tt> of that prototype. These will be explained more in the future, as they are not used yet.

==New General Tags==
SourceMod introduces one important general tag.
*'''Handle''': Used for the [[Handles (SourceMod Scripting)|Handle System]].

=AMX Mod X Specific=
AMX Mod X has literally a plethora of tags, but has no new "magic" tags. Some of these tags are:
*'''Sql''': An SQL index for the DBI system.
*'''Result''': An SQL Result index for the DBI system.
*'''Handle''': An SQL Handle (precursor to SourceMod's <tt>Handle</tt>) for the SQLX system.
*'''Vault''': An index for a vault opened with the nVault module.

[[Category:SourceMod Scripting]]
[[Category:Scripting (AMX Mod X)]]

Talk:Introduction to SourcePawn (legacy syntax)

2010-07-11T10:07:45Z

Flintb: Created page with 'Is it possible to have a two-dimensional array? ~Flint B.'

Is it possible to have a two-dimensional array? ~Flint B.