https://wiki.alliedmods.net/api.php?action=feedcontributions&feedformat=atom&user=Xerox8521 2026-05-08T15:44:20Z User contributions MediaWiki 1.31.6 https://wiki.alliedmods.net/index.php?title=Zombie_Panic!_Source_Events&diff=11270 2022-02-02T18:13:22Z

<p>Xerox8521: Removed events that are not called by the game.</p> <hr /> <div>:''Refer back to [[Game Events (Source)]] for more events.''<br /> === player_feed ===<br /> {{qnotice|Whenever the player feed is updated. This is also called whenever someone becomes infected by a player}}&lt;br&gt;<br /> {{begin-hl2msg|player_feed|string}}<br /> {{hl2msg|short|userid|player who died or got infected}}<br /> {{hl2msg|short|attacker|player who killed or caused the infection}}<br /> {{hl2msg|short|assistant|player who assisted the attacker}}<br /> {{hl2msg|string|weapon|name of the weapon}}<br /> {{hl2msg|bool|headshot|true if player died from headshot}}<br /> {{hl2msg|bool|death|true if the player died}}<br /> {{hl2msg|short|dmgbits|damage type}}<br /> {{end-hl2msg}}<br /> <br /> === player_spawn ===<br /> {{qnotice|When a player spawns}}&lt;br&gt;<br /> {{begin-hl2msg|player_spawn|string}}<br /> {{hl2msg|short|entindex|Entity index of the player that spawned}}<br /> {{end-hl2msg}}<br /> <br /> === player_exploded ===<br /> {{qnotice|When a player explodes}}&lt;br&gt;<br /> {{begin-hl2msg|player_exploded|string}}<br /> {{hl2msg|float|x|X Position of the player}}<br /> {{hl2msg|float|y|Y Position of the player}}<br /> {{hl2msg|float|z|Z Position of the player}}<br /> {{end-hl2msg}}<br /> <br /> === player_connected ===<br /> {{qnotice|When a player joins the server}}&lt;br&gt;<br /> {{begin-hl2msg|player_connected|string}}<br /> {{hl2msg|string|name|name of the player that connected}}<br /> {{end-hl2msg}}<br /> <br /> === player_disconnected ===<br /> {{qnotice|When a player leaves the server}}&lt;br&gt;<br /> {{begin-hl2msg|player_disconnected|string}}<br /> {{hl2msg|string|name|name of the player that left}}<br /> {{hl2msg|short|flag}}<br /> {{hl2msg|short|userid|player who left}}<br /> {{hl2msg|string|reason|reason why the player left}}<br /> {{end-hl2msg}}<br /> <br /> === map_change ===<br /> {{qnotice|Called when the map changes}}&lt;br&gt;<br /> {{begin-hl2msg|map_change|string}}<br /> {{hl2msg|string|map|name of the map that is being switched to}}<br /> {{end-hl2msg}}<br /> <br /> === clientsound ===<br /> {{qnotice|Called when a specific sound is played. Eg. Round Start, Round End, Survivor Escapes etc.}}&lt;br&gt;<br /> {{begin-hl2msg|clientsound|string}}<br /> {{hl2msg|string|sound|File path for the song, or the SoundScript}}<br /> {{hl2msg|short|teamid|(optional) If specified, it will only send to clients within a specific team}}<br /> {{end-hl2msg}}<br /> <br /> === clientsound_player ===<br /> {{qnotice|Called when a specific sound to a player is played. Eg. Using an Inoculator, Flashlight, Panic etc.}}&lt;br&gt;<br /> {{begin-hl2msg|clientsound_player|string}}<br /> {{hl2msg|short|entindex|Entity index concerned by this sound}}<br /> {{hl2msg|string|sound|File path for the song, or the SoundScript}}<br /> {{end-hl2msg}}<br /> <br /> === force_song ===<br /> {{qnotice|Called when the logic_music entity changes the song}}&lt;br&gt;<br /> {{begin-hl2msg|force_song|string}}<br /> {{hl2msg|string|song|File path for the song}}<br /> {{hl2msg|string|title|Custom song title}}<br /> {{end-hl2msg}}<br /> <br /> === armmodel_as ===<br /> {{qnotice|Called when a new arm model is set from AngelScript}}&lt;br&gt;<br /> {{begin-hl2msg|armmodel_as|string}}<br /> {{hl2msg|short|entindex|player who's arm model got changed}}<br /> {{hl2msg|string|model|arm model that should be used}}<br /> {{end-hl2msg}}<br /> <br /> === spawned_player ===<br /> {{qnotice|Called when player has spawned}}&lt;br&gt;<br /> {{begin-hl2msg|spawned_player|string}}<br /> {{hl2msg|string|name|name of the player that spawned}}<br /> {{end-hl2msg}}<br /> <br /> === reset_arms ===<br /> {{qnotice|Called when player has fully turned into a zombie}}&lt;br&gt;<br /> {{begin-hl2msg|reset_arms|string}}<br /> {{hl2msg|short|entindex|Entindex of the player}}<br /> {{hl2msg|bool|infected|Whether to use the infected model or not. Seems to be always true}}<br /> {{end-hl2msg}}<br /> <br /> === discord_callstatusupdate ===<br /> {{qnotice|Send an Update to Discord RPC}}&lt;br&gt;<br /> {{begin-hl2msg|discord_callstatusupdate|string}}<br /> {{hl2msg|string|hostname|Server Hostname}}<br /> {{hl2msg|string|gamemode|Gamemode}}<br /> {{hl2msg|string|party_id|}}<br /> {{hl2msg|string|party_port|Server Port?}}<br /> {{hl2msg|string|party_size|Player count currently playing}}<br /> {{hl2msg|string|party_max|How many players can join}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === cleanupmap ===<br /> {{qnotice|when the server calls CleanUpMap(), it will tell the client todo the same for temp and client sided entities}}&lt;br&gt;<br /> {{begin-hl2msg|cleanupmap|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === achievement_earned ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|achievement_earned|string}}<br /> {{hl2msg|short|userid|player who earned the achievement}}<br /> {{hl2msg|string|achid|achievement id}}<br /> {{hl2msg|string|achtitle|title of the achievement}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_tutor ===<br /> {{qnotice|Called from the instructor tutorial}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_tutor|string}}<br /> {{hl2msg|long|userid}}<br /> {{hl2msg|long|entindex}}<br /> {{hl2msg|string|strbind}}<br /> {{hl2msg|string|strmsg}}<br /> {{hl2msg|string|icon_onscreen}}<br /> {{hl2msg|string|icon_offscreen}}<br /> {{hl2msg|bool|nooffscreen}}<br /> {{hl2msg|int|posx}}<br /> {{hl2msg|int|posy}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_server_hint_create ===<br /> {{qnotice|create a hint using data supplied entirely by the server/map. Intended for hints to smooth playtests before content is ready to make the hint unneccessary. NOT INTENDED AS A SHIPPABLE CRUTCH}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_server_hint_create|string}}<br /> {{hl2msg|string|hint_name|what to name the hint. For referencing it again later (e.g. a kill command for the hint instead of a timeout)}}<br /> {{hl2msg|string|hint_replace_key|type name so that messages of the same type will replace each other}}<br /> {{hl2msg|long|hint_target|entity id that the hint should display at}}<br /> {{hl2msg|long|hint_instance|the hint instance}}<br /> {{hl2msg|short|hint_activator_userid|userid id of the activator}}<br /> {{hl2msg|short|hint_timeout|how long in seconds until the hint automatically times out, 0 means never}}<br /> {{hl2msg|string|hint_icon_onscreen|the hint icon to use when the hint is onscreen. e.g. &quot;icon_alert_red&quot;}}<br /> {{hl2msg|string|hint_icon_offscreen|the hint icon to use when the hint is offscreen. e.g. &quot;icon_alert&quot;}}<br /> {{hl2msg|string|hint_caption|the hint caption. e.g. &quot;#ThisIsDangerous&quot;}}<br /> {{hl2msg|string|hint_activator_caption|the hint caption that only the activator sees e.g. &quot;#YouPushedItGood&quot;}}<br /> {{hl2msg|string|hint_color|the hint color in &quot;r,g,b&quot; format where each component is 0-255}}<br /> {{hl2msg|float|hint_icon_offset|how far on the z axis to offset the hint from entity origin}}<br /> {{hl2msg|float|hint_range|range before the hint is culled}}<br /> {{hl2msg|long|hint_flags|hint flags}}<br /> {{hl2msg|string|hint_binding|bindings to use when use_binding is the onscreen icon}}<br /> {{hl2msg|bool|hint_allow_nodraw_target|if false, the hint will dissappear if the target entity is invisible}}<br /> {{hl2msg|bool|hint_nooffscreen|if true, the hint will not show when outside the player view}}<br /> {{hl2msg|bool|hint_forcecaption|if true, the hint caption will show even if the hint is occluded}}<br /> {{hl2msg|bool|hint_local_player_only|if true, only the local player will see the hint}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_server_hint_stop ===<br /> {{qnotice|destroys a server/map created hint}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_server_hint_stop|string}}<br /> {{hl2msg|string|hint_name|The hint to stop. Will stop ALL hints with this name}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_survivor_supply ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_survivor_supply|string}}<br /> {{hl2msg|long|hint_player|entity id that the hint will display for}}<br /> {{hl2msg|long|hint_target|entity id that the hint should display at}}<br /> {{hl2msg|string|hint_caption|the hint caption. e.g. &quot;#ThisIsDangerous&quot;}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === endslate ===<br /> {{qnotice|Called when the round ends}}&lt;br&gt;<br /> {{begin-hl2msg|endslate|string}}<br /> {{hl2msg|string|win_text|Who won?}}<br /> {{hl2msg|string|timespent|Time spent on the round}}<br /> {{hl2msg|string|gamemode|Current Gamemode}}<br /> {{hl2msg|string|map|Current Map (If official, it shows the title of the map)}}<br /> {{end-hl2msg}}<br /> <br /> === vote_started ===<br /> {{qnotice|Called when a vote has started}}&lt;br&gt;<br /> {{begin-hl2msg|vote_started|string}}<br /> {{hl2msg|string|title|Title of the vote}}<br /> {{hl2msg|string|desc|Description of the vote}}<br /> {{hl2msg|string|arg|Argument(s) of the vote}}<br /> {{hl2msg|short|maxargs|Amount of arguments for the vote}}<br /> {{hl2msg|short|caller|player who started the vote}}<br /> {{hl2msg|float|time|Duration of the vote?}}<br /> {{hl2msg|float|time_real|Time when the vote started?}}<br /> {{end-hl2msg}}<br /> <br /> === vote_update ===<br /> {{qnotice|Called when a vote updates}}&lt;br&gt;<br /> {{begin-hl2msg|vote_update|string}}<br /> {{hl2msg|string|title|Title of the vote}}<br /> {{hl2msg|string|desc|Description of the vote}}<br /> {{hl2msg|string|arg|Argument(s) of the vote}}<br /> {{hl2msg|short|caller|player who started the vote}}<br /> {{hl2msg|byte|result|}}<br /> {{hl2msg|byte|maxargs|}}<br /> {{hl2msg|byte|option0|}}<br /> {{hl2msg|byte|option1|}}<br /> {{hl2msg|byte|option2|}}<br /> {{hl2msg|byte|option3|}}<br /> {{hl2msg|byte|option4|}}<br /> {{hl2msg|byte|option5|}}<br /> {{end-hl2msg}}<br /> <br /> === vote_ended ===<br /> {{qnotice|Called when a vote has ended}}&lt;br&gt;<br /> {{begin-hl2msg|vote_ended|string}}<br /> {{hl2msg|string|arg|Argument(s) of the vote}}<br /> {{hl2msg|string|endmsg|}}<br /> {{hl2msg|short|target|player who got targeted by the caller}}<br /> {{hl2msg|short|caller|player who started the vote}}<br /> {{hl2msg|short|state|}}<br /> {{hl2msg|short|result|}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === badge_reward_announce ===<br /> {{qnotice|Called when the player is notified about receiving a badge reward.}}&lt;br&gt;<br /> {{begin-hl2msg|badge_reward_announce|string}}<br /> {{hl2msg|long|entindex|player who got the badge reward}}<br /> {{hl2msg|string|name|Name of the badge reward}}<br /> {{hl2msg|string|desc|Description of the badge reward}}<br /> {{hl2msg|string|icon|Icon which is shown}}<br /> {{hl2msg|long|reward|}}<br /> {{end-hl2msg}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Zombie_Panic!_Source_Events&diff=11269 2022-02-02T17:52:03Z

<p>Xerox8521: Fixed argument name in badge_reward_announce</p> <hr /> <div>:''Refer back to [[Game Events (Source)]] for more events.''<br /> === player_feed ===<br /> {{qnotice|Whenever the player feed is updated. This is also called whenever someone becomes infected by a player}}&lt;br&gt;<br /> {{begin-hl2msg|player_feed|string}}<br /> {{hl2msg|short|userid|player who died or got infected}}<br /> {{hl2msg|short|attacker|player who killed or caused the infection}}<br /> {{hl2msg|short|assistant|player who assisted the attacker}}<br /> {{hl2msg|string|weapon|name of the weapon}}<br /> {{hl2msg|bool|headshot|true if player died from headshot}}<br /> {{hl2msg|bool|death|true if the player died}}<br /> {{hl2msg|short|dmgbits|damage type}}<br /> {{end-hl2msg}}<br /> <br /> === player_spawn ===<br /> {{qnotice|When a player spawns}}&lt;br&gt;<br /> {{begin-hl2msg|player_spawn|string}}<br /> {{hl2msg|short|entindex|Entity index of the player that spawned}}<br /> {{end-hl2msg}}<br /> <br /> === player_exploded ===<br /> {{qnotice|When a player explodes}}&lt;br&gt;<br /> {{begin-hl2msg|player_exploded|string}}<br /> {{hl2msg|float|x|X Position of the player}}<br /> {{hl2msg|float|y|Y Position of the player}}<br /> {{hl2msg|float|z|Z Position of the player}}<br /> {{end-hl2msg}}<br /> <br /> === player_connected ===<br /> {{qnotice|When a player joins the server}}&lt;br&gt;<br /> {{begin-hl2msg|player_connected|string}}<br /> {{hl2msg|string|name|name of the player that connected}}<br /> {{end-hl2msg}}<br /> <br /> === player_disconnected ===<br /> {{qnotice|When a player leaves the server}}&lt;br&gt;<br /> {{begin-hl2msg|player_disconnected|string}}<br /> {{hl2msg|string|name|name of the player that left}}<br /> {{hl2msg|short|flag}}<br /> {{hl2msg|short|userid|player who left}}<br /> {{hl2msg|string|reason|reason why the player left}}<br /> {{end-hl2msg}}<br /> <br /> === map_change ===<br /> {{qnotice|Called when the map changes}}&lt;br&gt;<br /> {{begin-hl2msg|map_change|string}}<br /> {{hl2msg|string|map|name of the map that is being switched to}}<br /> {{end-hl2msg}}<br /> <br /> === clientsound ===<br /> {{qnotice|Called when a specific sound is played. Eg. Round Start, Round End, Survivor Escapes etc.}}&lt;br&gt;<br /> {{begin-hl2msg|clientsound|string}}<br /> {{hl2msg|string|sound|File path for the song, or the SoundScript}}<br /> {{hl2msg|short|teamid|(optional) If specified, it will only send to clients within a specific team}}<br /> {{end-hl2msg}}<br /> <br /> === clientsound_player ===<br /> {{qnotice|Called when a specific sound to a player is played. Eg. Using an Inoculator, Flashlight, Panic etc.}}&lt;br&gt;<br /> {{begin-hl2msg|clientsound_player|string}}<br /> {{hl2msg|short|entindex|Entity index concerned by this sound}}<br /> {{hl2msg|string|sound|File path for the song, or the SoundScript}}<br /> {{end-hl2msg}}<br /> <br /> === force_song ===<br /> {{qnotice|Called when the logic_music entity changes the song}}&lt;br&gt;<br /> {{begin-hl2msg|force_song|string}}<br /> {{hl2msg|string|song|File path for the song}}<br /> {{hl2msg|string|title|Custom song title}}<br /> {{end-hl2msg}}<br /> <br /> === armmodel_as ===<br /> {{qnotice|Called when a new arm model is set from AngelScript}}&lt;br&gt;<br /> {{begin-hl2msg|armmodel_as|string}}<br /> {{hl2msg|short|entindex|player who's arm model got changed}}<br /> {{hl2msg|string|model|arm model that should be used}}<br /> {{end-hl2msg}}<br /> <br /> === spawned_player ===<br /> {{qnotice|Called when player has spawned}}&lt;br&gt;<br /> {{begin-hl2msg|spawned_player|string}}<br /> {{hl2msg|string|name|name of the player that spawned}}<br /> {{end-hl2msg}}<br /> <br /> === reset_arms ===<br /> {{qnotice|Called when player has fully turned into a zombie}}&lt;br&gt;<br /> {{begin-hl2msg|reset_arms|string}}<br /> {{hl2msg|short|entindex|Entindex of the player}}<br /> {{hl2msg|bool|infected|Whether to use the infected model or not. Seems to be always true}}<br /> {{end-hl2msg}}<br /> <br /> === discord_callstatusupdate ===<br /> {{qnotice|Send an Update to Discord RPC}}&lt;br&gt;<br /> {{begin-hl2msg|discord_callstatusupdate|string}}<br /> {{hl2msg|string|hostname|Server Hostname}}<br /> {{hl2msg|string|gamemode|Gamemode}}<br /> {{hl2msg|string|party_id|}}<br /> {{hl2msg|string|party_port|Server Port?}}<br /> {{hl2msg|string|party_size|Player count currently playing}}<br /> {{hl2msg|string|party_max|How many players can join}}<br /> {{end-hl2msg}}<br /> <br /> === angelscript_callevent===<br /> {{qnotice|When the AS calls the function CallEvent()}}&lt;br&gt;<br /> {{begin-hl2msg|angelscript_callevent|string}}<br /> {{hl2msg|short|clientid}}<br /> {{hl2msg|short|typeid}}<br /> {{hl2msg|string|msg}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === cleanupmap ===<br /> {{qnotice|when the server calls CleanUpMap(), it will tell the client todo the same for temp and client sided entities}}&lt;br&gt;<br /> {{begin-hl2msg|cleanupmap|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === gravity_change ===<br /> {{qnotice|When the gravity changes}}&lt;br&gt;<br /> {{begin-hl2msg|gravity_change|string}}<br /> {{hl2msg|float|newgravity|New value after the change}}<br /> {{end-hl2msg}}<br /> <br /> === spec_target_updated ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|spec_target_updated|string}}<br /> {{hl2msg|none|none}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === achievement_earned ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|achievement_earned|string}}<br /> {{hl2msg|short|userid|player who earned the achievement}}<br /> {{hl2msg|string|achid|achievement id}}<br /> {{hl2msg|string|achtitle|title of the achievement}}<br /> {{end-hl2msg}}<br /> <br /> === general_hint ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|general_hint|string}}<br /> {{hl2msg|short|userid|the player who activated it}}<br /> {{end-hl2msg}}<br /> <br /> === movement_hint ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|movement_hint|string}}<br /> {{hl2msg|short|userid|the player who needs the hint}}<br /> {{end-hl2msg}}<br /> <br /> === movement_hint_success ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|movement_hint_success|string}}<br /> {{hl2msg|short|userid|the player succeeded}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === gameinstructor_draw ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|gameinstructor_draw|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === gameinstructor_nodraw ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|gameinstructor_nodraw|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === set_instructor_group_enabled ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|set_instructor_group_enabled|string}}<br /> {{hl2msg|string|group}}<br /> {{hl2msg|short|enabled}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_tutor ===<br /> {{qnotice|Called from the instructor tutorial}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_tutor|string}}<br /> {{hl2msg|long|userid}}<br /> {{hl2msg|long|entindex}}<br /> {{hl2msg|string|strbind}}<br /> {{hl2msg|string|strmsg}}<br /> {{hl2msg|string|icon_onscreen}}<br /> {{hl2msg|string|icon_offscreen}}<br /> {{hl2msg|bool|nooffscreen}}<br /> {{hl2msg|int|posx}}<br /> {{hl2msg|int|posy}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_server_hint_create ===<br /> {{qnotice|create a hint using data supplied entirely by the server/map. Intended for hints to smooth playtests before content is ready to make the hint unneccessary. NOT INTENDED AS A SHIPPABLE CRUTCH}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_server_hint_create|string}}<br /> {{hl2msg|string|hint_name|what to name the hint. For referencing it again later (e.g. a kill command for the hint instead of a timeout)}}<br /> {{hl2msg|string|hint_replace_key|type name so that messages of the same type will replace each other}}<br /> {{hl2msg|long|hint_target|entity id that the hint should display at}}<br /> {{hl2msg|long|hint_instance|the hint instance}}<br /> {{hl2msg|short|hint_activator_userid|userid id of the activator}}<br /> {{hl2msg|short|hint_timeout|how long in seconds until the hint automatically times out, 0 means never}}<br /> {{hl2msg|string|hint_icon_onscreen|the hint icon to use when the hint is onscreen. e.g. &quot;icon_alert_red&quot;}}<br /> {{hl2msg|string|hint_icon_offscreen|the hint icon to use when the hint is offscreen. e.g. &quot;icon_alert&quot;}}<br /> {{hl2msg|string|hint_caption|the hint caption. e.g. &quot;#ThisIsDangerous&quot;}}<br /> {{hl2msg|string|hint_activator_caption|the hint caption that only the activator sees e.g. &quot;#YouPushedItGood&quot;}}<br /> {{hl2msg|string|hint_color|the hint color in &quot;r,g,b&quot; format where each component is 0-255}}<br /> {{hl2msg|float|hint_icon_offset|how far on the z axis to offset the hint from entity origin}}<br /> {{hl2msg|float|hint_range|range before the hint is culled}}<br /> {{hl2msg|long|hint_flags|hint flags}}<br /> {{hl2msg|string|hint_binding|bindings to use when use_binding is the onscreen icon}}<br /> {{hl2msg|bool|hint_allow_nodraw_target|if false, the hint will dissappear if the target entity is invisible}}<br /> {{hl2msg|bool|hint_nooffscreen|if true, the hint will not show when outside the player view}}<br /> {{hl2msg|bool|hint_forcecaption|if true, the hint caption will show even if the hint is occluded}}<br /> {{hl2msg|bool|hint_local_player_only|if true, only the local player will see the hint}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_server_hint_stop ===<br /> {{qnotice|destroys a server/map created hint}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_server_hint_stop|string}}<br /> {{hl2msg|string|hint_name|The hint to stop. Will stop ALL hints with this name}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_survivor_supply ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_survivor_supply|string}}<br /> {{hl2msg|long|hint_player|entity id that the hint will display for}}<br /> {{hl2msg|long|hint_target|entity id that the hint should display at}}<br /> {{hl2msg|string|hint_caption|the hint caption. e.g. &quot;#ThisIsDangerous&quot;}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === endslate ===<br /> {{qnotice|Called when the round ends}}&lt;br&gt;<br /> {{begin-hl2msg|endslate|string}}<br /> {{hl2msg|string|win_text|Who won?}}<br /> {{hl2msg|string|timespent|Time spent on the round}}<br /> {{hl2msg|string|gamemode|Current Gamemode}}<br /> {{hl2msg|string|map|Current Map (If official, it shows the title of the map)}}<br /> {{end-hl2msg}}<br /> <br /> === vote_started ===<br /> {{qnotice|Called when a vote has started}}&lt;br&gt;<br /> {{begin-hl2msg|vote_started|string}}<br /> {{hl2msg|string|title|Title of the vote}}<br /> {{hl2msg|string|desc|Description of the vote}}<br /> {{hl2msg|string|arg|Argument(s) of the vote}}<br /> {{hl2msg|short|maxargs|Amount of arguments for the vote}}<br /> {{hl2msg|short|caller|player who started the vote}}<br /> {{hl2msg|float|time|Duration of the vote?}}<br /> {{hl2msg|float|time_real|Time when the vote started?}}<br /> {{end-hl2msg}}<br /> <br /> === vote_update ===<br /> {{qnotice|Called when a vote updates}}&lt;br&gt;<br /> {{begin-hl2msg|vote_update|string}}<br /> {{hl2msg|string|title|Title of the vote}}<br /> {{hl2msg|string|desc|Description of the vote}}<br /> {{hl2msg|string|arg|Argument(s) of the vote}}<br /> {{hl2msg|short|caller|player who started the vote}}<br /> {{hl2msg|byte|result|}}<br /> {{hl2msg|byte|maxargs|}}<br /> {{hl2msg|byte|option0|}}<br /> {{hl2msg|byte|option1|}}<br /> {{hl2msg|byte|option2|}}<br /> {{hl2msg|byte|option3|}}<br /> {{hl2msg|byte|option4|}}<br /> {{hl2msg|byte|option5|}}<br /> {{end-hl2msg}}<br /> <br /> === vote_ended ===<br /> {{qnotice|Called when a vote has ended}}&lt;br&gt;<br /> {{begin-hl2msg|vote_ended|string}}<br /> {{hl2msg|string|arg|Argument(s) of the vote}}<br /> {{hl2msg|string|endmsg|}}<br /> {{hl2msg|short|target|player who got targeted by the caller}}<br /> {{hl2msg|short|caller|player who started the vote}}<br /> {{hl2msg|short|state|}}<br /> {{hl2msg|short|result|}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === badge_reward_announce ===<br /> {{qnotice|Called when the player is notified about receiving a badge reward.}}&lt;br&gt;<br /> {{begin-hl2msg|badge_reward_announce|string}}<br /> {{hl2msg|long|entindex|player who got the badge reward}}<br /> {{hl2msg|string|name|Name of the badge reward}}<br /> {{hl2msg|string|desc|Description of the badge reward}}<br /> {{hl2msg|string|icon|Icon which is shown}}<br /> {{hl2msg|long|reward|}}<br /> {{end-hl2msg}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Zombie_Panic!_Source_Events&diff=11268 2022-02-02T17:29:11Z

<p>Xerox8521: Updated event information for 3.1</p> <hr /> <div>:''Refer back to [[Game Events (Source)]] for more events.''<br /> === player_feed ===<br /> {{qnotice|Whenever the player feed is updated. This is also called whenever someone becomes infected by a player}}&lt;br&gt;<br /> {{begin-hl2msg|player_feed|string}}<br /> {{hl2msg|short|userid|player who died or got infected}}<br /> {{hl2msg|short|attacker|player who killed or caused the infection}}<br /> {{hl2msg|short|assistant|player who assisted the attacker}}<br /> {{hl2msg|string|weapon|name of the weapon}}<br /> {{hl2msg|bool|headshot|true if player died from headshot}}<br /> {{hl2msg|bool|death|true if the player died}}<br /> {{hl2msg|short|dmgbits|damage type}}<br /> {{end-hl2msg}}<br /> <br /> === player_spawn ===<br /> {{qnotice|When a player spawns}}&lt;br&gt;<br /> {{begin-hl2msg|player_spawn|string}}<br /> {{hl2msg|short|entindex|Entity index of the player that spawned}}<br /> {{end-hl2msg}}<br /> <br /> === player_exploded ===<br /> {{qnotice|When a player explodes}}&lt;br&gt;<br /> {{begin-hl2msg|player_exploded|string}}<br /> {{hl2msg|float|x|X Position of the player}}<br /> {{hl2msg|float|y|Y Position of the player}}<br /> {{hl2msg|float|z|Z Position of the player}}<br /> {{end-hl2msg}}<br /> <br /> === player_connected ===<br /> {{qnotice|When a player joins the server}}&lt;br&gt;<br /> {{begin-hl2msg|player_connected|string}}<br /> {{hl2msg|string|name|name of the player that connected}}<br /> {{end-hl2msg}}<br /> <br /> === player_disconnected ===<br /> {{qnotice|When a player leaves the server}}&lt;br&gt;<br /> {{begin-hl2msg|player_disconnected|string}}<br /> {{hl2msg|string|name|name of the player that left}}<br /> {{hl2msg|short|flag}}<br /> {{hl2msg|short|userid|player who left}}<br /> {{hl2msg|string|reason|reason why the player left}}<br /> {{end-hl2msg}}<br /> <br /> === map_change ===<br /> {{qnotice|Called when the map changes}}&lt;br&gt;<br /> {{begin-hl2msg|map_change|string}}<br /> {{hl2msg|string|map|name of the map that is being switched to}}<br /> {{end-hl2msg}}<br /> <br /> === clientsound ===<br /> {{qnotice|Called when a specific sound is played. Eg. Round Start, Round End, Survivor Escapes etc.}}&lt;br&gt;<br /> {{begin-hl2msg|clientsound|string}}<br /> {{hl2msg|string|sound|File path for the song, or the SoundScript}}<br /> {{hl2msg|short|teamid|(optional) If specified, it will only send to clients within a specific team}}<br /> {{end-hl2msg}}<br /> <br /> === clientsound_player ===<br /> {{qnotice|Called when a specific sound to a player is played. Eg. Using an Inoculator, Flashlight, Panic etc.}}&lt;br&gt;<br /> {{begin-hl2msg|clientsound_player|string}}<br /> {{hl2msg|short|entindex|Entity index concerned by this sound}}<br /> {{hl2msg|string|sound|File path for the song, or the SoundScript}}<br /> {{end-hl2msg}}<br /> <br /> === force_song ===<br /> {{qnotice|Called when the logic_music entity changes the song}}&lt;br&gt;<br /> {{begin-hl2msg|force_song|string}}<br /> {{hl2msg|string|song|File path for the song}}<br /> {{hl2msg|string|title|Custom song title}}<br /> {{end-hl2msg}}<br /> <br /> === armmodel_as ===<br /> {{qnotice|Called when a new arm model is set from AngelScript}}&lt;br&gt;<br /> {{begin-hl2msg|armmodel_as|string}}<br /> {{hl2msg|short|entindex|player who's arm model got changed}}<br /> {{hl2msg|string|model|arm model that should be used}}<br /> {{end-hl2msg}}<br /> <br /> === spawned_player ===<br /> {{qnotice|Called when player has spawned}}&lt;br&gt;<br /> {{begin-hl2msg|spawned_player|string}}<br /> {{hl2msg|string|name|name of the player that spawned}}<br /> {{end-hl2msg}}<br /> <br /> === reset_arms ===<br /> {{qnotice|Called when player has fully turned into a zombie}}&lt;br&gt;<br /> {{begin-hl2msg|reset_arms|string}}<br /> {{hl2msg|short|entindex|Entindex of the player}}<br /> {{hl2msg|bool|infected|Whether to use the infected model or not. Seems to be always true}}<br /> {{end-hl2msg}}<br /> <br /> === discord_callstatusupdate ===<br /> {{qnotice|Send an Update to Discord RPC}}&lt;br&gt;<br /> {{begin-hl2msg|discord_callstatusupdate|string}}<br /> {{hl2msg|string|hostname|Server Hostname}}<br /> {{hl2msg|string|gamemode|Gamemode}}<br /> {{hl2msg|string|party_id|}}<br /> {{hl2msg|string|party_port|Server Port?}}<br /> {{hl2msg|string|party_size|Player count currently playing}}<br /> {{hl2msg|string|party_max|How many players can join}}<br /> {{end-hl2msg}}<br /> <br /> === angelscript_callevent===<br /> {{qnotice|When the AS calls the function CallEvent()}}&lt;br&gt;<br /> {{begin-hl2msg|angelscript_callevent|string}}<br /> {{hl2msg|short|clientid}}<br /> {{hl2msg|short|typeid}}<br /> {{hl2msg|string|msg}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === cleanupmap ===<br /> {{qnotice|when the server calls CleanUpMap(), it will tell the client todo the same for temp and client sided entities}}&lt;br&gt;<br /> {{begin-hl2msg|cleanupmap|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === gravity_change ===<br /> {{qnotice|When the gravity changes}}&lt;br&gt;<br /> {{begin-hl2msg|gravity_change|string}}<br /> {{hl2msg|float|newgravity|New value after the change}}<br /> {{end-hl2msg}}<br /> <br /> === spec_target_updated ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|spec_target_updated|string}}<br /> {{hl2msg|none|none}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === achievement_earned ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|achievement_earned|string}}<br /> {{hl2msg|short|userid|player who earned the achievement}}<br /> {{hl2msg|string|achid|achievement id}}<br /> {{hl2msg|string|achtitle|title of the achievement}}<br /> {{end-hl2msg}}<br /> <br /> === general_hint ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|general_hint|string}}<br /> {{hl2msg|short|userid|the player who activated it}}<br /> {{end-hl2msg}}<br /> <br /> === movement_hint ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|movement_hint|string}}<br /> {{hl2msg|short|userid|the player who needs the hint}}<br /> {{end-hl2msg}}<br /> <br /> === movement_hint_success ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|movement_hint_success|string}}<br /> {{hl2msg|short|userid|the player succeeded}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === gameinstructor_draw ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|gameinstructor_draw|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === gameinstructor_nodraw ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|gameinstructor_nodraw|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === set_instructor_group_enabled ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|set_instructor_group_enabled|string}}<br /> {{hl2msg|string|group}}<br /> {{hl2msg|short|enabled}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_tutor ===<br /> {{qnotice|Called from the instructor tutorial}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_tutor|string}}<br /> {{hl2msg|long|userid}}<br /> {{hl2msg|long|entindex}}<br /> {{hl2msg|string|strbind}}<br /> {{hl2msg|string|strmsg}}<br /> {{hl2msg|string|icon_onscreen}}<br /> {{hl2msg|string|icon_offscreen}}<br /> {{hl2msg|bool|nooffscreen}}<br /> {{hl2msg|int|posx}}<br /> {{hl2msg|int|posy}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_server_hint_create ===<br /> {{qnotice|create a hint using data supplied entirely by the server/map. Intended for hints to smooth playtests before content is ready to make the hint unneccessary. NOT INTENDED AS A SHIPPABLE CRUTCH}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_server_hint_create|string}}<br /> {{hl2msg|string|hint_name|what to name the hint. For referencing it again later (e.g. a kill command for the hint instead of a timeout)}}<br /> {{hl2msg|string|hint_replace_key|type name so that messages of the same type will replace each other}}<br /> {{hl2msg|long|hint_target|entity id that the hint should display at}}<br /> {{hl2msg|long|hint_instance|the hint instance}}<br /> {{hl2msg|short|hint_activator_userid|userid id of the activator}}<br /> {{hl2msg|short|hint_timeout|how long in seconds until the hint automatically times out, 0 means never}}<br /> {{hl2msg|string|hint_icon_onscreen|the hint icon to use when the hint is onscreen. e.g. &quot;icon_alert_red&quot;}}<br /> {{hl2msg|string|hint_icon_offscreen|the hint icon to use when the hint is offscreen. e.g. &quot;icon_alert&quot;}}<br /> {{hl2msg|string|hint_caption|the hint caption. e.g. &quot;#ThisIsDangerous&quot;}}<br /> {{hl2msg|string|hint_activator_caption|the hint caption that only the activator sees e.g. &quot;#YouPushedItGood&quot;}}<br /> {{hl2msg|string|hint_color|the hint color in &quot;r,g,b&quot; format where each component is 0-255}}<br /> {{hl2msg|float|hint_icon_offset|how far on the z axis to offset the hint from entity origin}}<br /> {{hl2msg|float|hint_range|range before the hint is culled}}<br /> {{hl2msg|long|hint_flags|hint flags}}<br /> {{hl2msg|string|hint_binding|bindings to use when use_binding is the onscreen icon}}<br /> {{hl2msg|bool|hint_allow_nodraw_target|if false, the hint will dissappear if the target entity is invisible}}<br /> {{hl2msg|bool|hint_nooffscreen|if true, the hint will not show when outside the player view}}<br /> {{hl2msg|bool|hint_forcecaption|if true, the hint caption will show even if the hint is occluded}}<br /> {{hl2msg|bool|hint_local_player_only|if true, only the local player will see the hint}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_server_hint_stop ===<br /> {{qnotice|destroys a server/map created hint}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_server_hint_stop|string}}<br /> {{hl2msg|string|hint_name|The hint to stop. Will stop ALL hints with this name}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_survivor_supply ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_survivor_supply|string}}<br /> {{hl2msg|long|hint_player|entity id that the hint will display for}}<br /> {{hl2msg|long|hint_target|entity id that the hint should display at}}<br /> {{hl2msg|string|hint_caption|the hint caption. e.g. &quot;#ThisIsDangerous&quot;}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === endslate ===<br /> {{qnotice|Called when the round ends}}&lt;br&gt;<br /> {{begin-hl2msg|endslate|string}}<br /> {{hl2msg|string|win_text|Who won?}}<br /> {{hl2msg|string|timespent|Time spent on the round}}<br /> {{hl2msg|string|gamemode|Current Gamemode}}<br /> {{hl2msg|string|map|Current Map (If official, it shows the title of the map)}}<br /> {{end-hl2msg}}<br /> <br /> === vote_started ===<br /> {{qnotice|Called when a vote has started}}&lt;br&gt;<br /> {{begin-hl2msg|vote_started|string}}<br /> {{hl2msg|string|title|Title of the vote}}<br /> {{hl2msg|string|desc|Description of the vote}}<br /> {{hl2msg|string|arg|Argument(s) of the vote}}<br /> {{hl2msg|short|maxargs|Amount of arguments for the vote}}<br /> {{hl2msg|short|caller|player who started the vote}}<br /> {{hl2msg|float|time|Duration of the vote?}}<br /> {{hl2msg|float|time_real|Time when the vote started?}}<br /> {{end-hl2msg}}<br /> <br /> === vote_update ===<br /> {{qnotice|Called when a vote updates}}&lt;br&gt;<br /> {{begin-hl2msg|vote_update|string}}<br /> {{hl2msg|string|title|Title of the vote}}<br /> {{hl2msg|string|desc|Description of the vote}}<br /> {{hl2msg|string|arg|Argument(s) of the vote}}<br /> {{hl2msg|short|caller|player who started the vote}}<br /> {{hl2msg|byte|result|}}<br /> {{hl2msg|byte|maxargs|}}<br /> {{hl2msg|byte|option0|}}<br /> {{hl2msg|byte|option1|}}<br /> {{hl2msg|byte|option2|}}<br /> {{hl2msg|byte|option3|}}<br /> {{hl2msg|byte|option4|}}<br /> {{hl2msg|byte|option5|}}<br /> {{end-hl2msg}}<br /> <br /> === vote_ended ===<br /> {{qnotice|Called when a vote has ended}}&lt;br&gt;<br /> {{begin-hl2msg|vote_ended|string}}<br /> {{hl2msg|string|arg|Argument(s) of the vote}}<br /> {{hl2msg|string|endmsg|}}<br /> {{hl2msg|short|target|player who got targeted by the caller}}<br /> {{hl2msg|short|caller|player who started the vote}}<br /> {{hl2msg|short|state|}}<br /> {{hl2msg|short|result|}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === badge_reward_announce ===<br /> {{qnotice|Called when the player is notified about receiving a badge reward.}}&lt;br&gt;<br /> {{begin-hl2msg|badge_reward_announce|string}}<br /> {{hl2msg|long|entindex|player who got the badge reward}}<br /> {{hl2msg|string|name|Name of the badge reward}}<br /> {{hl2msg|string|desc|Description of the badge reward}}<br /> {{hl2msg|string|icon|Icon which is shown}}<br /> {{hl2msg|long|state|}}<br /> {{end-hl2msg}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Pawn_Tutorial&diff=10748 2019-04-10T11:54:31Z

<p>Xerox8521: Fixed link to Pawn Lang Guide pdf file.</p> <hr /> <div>{{qnotice|This guide is rather hardcoded to [[AMX Mod X]]. It needs to be mode generic.}}<br /> <br /> This guide is designed to give you a more in-depth overview of the basics of programming in [[Pawn]].<br /> <br /> =Introduction=<br /> Pawn is an embeddable, (almost) typeless, easy to use scripting language that is compiled for a virtual machine. [[AMX Mod X]] uses Pawn to route scripting functions to the Half-Life engine, using the Pawn [[Virtual Machine]] and [[Metamod]] ([[Pawn]] is written in C, Metamod is written in C++). While you write Pawn scripts in a text editor, the scripts must be compiled with a &quot;Compiler&quot;, which produces a binary for AMX Mod X. The AMX Mod X team distributes a specially modified Pawn compiler.<br /> <br /> Programming scripts in Pawn is relatively easy, and does not have concepts in other languages that are unnecessary for general use, such as pointers, vectors, structs, classes, allocation, et cetera. <br /> <br /> ==Language Paradigms==<br /> Pawn was originally named &quot;[[Small]]&quot; to emphasize the size of the language specification. The language sacrifices many features found in modern languages to achieve simplicity and speed, which are required for embedded uses.<br /> *No typing<br /> **Pawn only has one data type -- the &quot;[[Cell_(Pawn)|cell]]&quot;. It is the size of the processor's integral pointer (4 bytes for 32bit processor, 8 bytes for 64bit processors). This has two major implications - Pawn bytecode is processor specific, and pointers can fit inside a cell.<br /> **[[Tagging_(Pawn)|Tagging]] - Pawn lets you create weakly statically typed &quot;tags&quot;, which can be associated with variables for primitive operator overloading. For example, Pawn has no concept of floating point numbers (only integers). Instead, operators are overloaded with the Float: tag to redirect computation to new functions. Tag-checking is only enforced as a warning. If you're using SourcePawn (for SourceMod), there is actually a second type: String. In a String, letters are stored as separate bytes... essentially having 4 characters stored in every cell.<br /> **Since Pawn only has one datatype, it does not support structs, records, objects, or anything else.<br /> **Pawn &lt;i&gt;does&lt;/i&gt; support arrays of cells, which leads to C-style arrays for strings.<br /> *No garbage collection<br /> **Pawn has no &quot;heap&quot; allocation built-in. All variables are stored on the stack or in the data section. Therefore, no garbage collection is necessary and memory leaks are not possible from the language specification alone.<br /> *Procedural<br /> **Pawn is entirely comprised of single, non-nested subroutines. There are no lambda functions, member functions, constructors, et cetera. Functions can either be internal (within the script) or public (exposed to the VM by name, like C's &quot;extern&quot;).<br /> *No thread-safety<br /> **Pawn is targetted toward single-thread instances.<br /> <br /> ==Implementation Features==<br /> *Cross-platform compatible compiler, which outputs bytecode and debug browsing information.<br /> *Cross-platform compatible Virtual Machine (VM), with support for debug browsing, halting/stopping execution, and interacting with scripts from C/C++ libraries.<br /> *IA32 JIT Compiler for vastly increasing script execution time.<br /> <br /> Because the footprints of the VM and JIT are so small, Pawn is ideal inside games which need a simple and highly fast event system, embedded devices or applications, and realtime systems.<br /> <br /> ==License==<br /> Pawn is licensed under the [[ZLib/libpng_License]] license.<br /> <br /> =Variables=<br /> Variables are simple structures for holding data throughout a period of time in your script.<br /> <br /> ==Types==<br /> Small has just three data types for declaring variables. The default variable type is a regular whole number, or integer. A variable name, for backwards compatibility, should be 19 characters or less, and MUST start with a letter. It can contain the symbols A-Z, a-z, 0-9, and the underscore (&quot;_&quot;). It is important to note that variable names are case sensitive - &quot;myvar&quot;, &quot;MyVaR&quot;, and &quot;MYVAR&quot; are three separate symbols. <br /> <br /> ===Integers===<br /> The simplest data type in Pawn is an &quot;integer&quot;. Integers are whole numbers. To declare a new integer variable, use the &quot;new&quot; operator like so:<br /> <br /> &lt;pawn&gt;new a //Declare empty variable &quot;a&quot;<br /> new b=5 //Declare variable &quot;b&quot; and set it to 5.<br /> new c=5.0 //This is invalid, technically not a whole number!<br /> new d=&quot;hello&quot; //&quot;hello&quot; is not a number either, this is invalid.<br /> <br /> //You can also declare multiple variables on one line:<br /> new e,f,g,h<br /> new x=7, y=3<br /> new z = 1_000_000 // Pawn supports numbers like this. So big values are easier to read.&lt;/pawn&gt;<br /> <br /> ===Floats===<br /> You can also declare a variable as a &quot;Float&quot;, which means it can store numbers with decimal places. These are called &quot;floating point&quot; numbers:<br /> <br /> &lt;pawn&gt;new Float:a //Declare empty floating point variable &quot;a&quot;<br /> new Float:b=5.3 //This will declare a new variable &quot;b&quot; and assign 5.3 to it.<br /> new Float:c=5 //This is valid, but the compiler will give you a warning.<br /> new Float:d=&quot;hello&quot; //This is invalid, &quot;hello&quot; is not a decimal number.&lt;/pawn&gt;<br /> <br /> You can also do the following:<br /> &lt;pawn&gt;//float(n) is a function that takes a number n and makes it a<br /> // floating point number.<br /> new Float:var = float(5)<br /> new Float:var2 = 5.0 <br /> new Float:var3 = 1.0*5<br /> new var4 = floatround(5.0) <br /> //Note: floatround(n) is a function that takes a number n and rounds it to a whole number.<br /> // this makes the assignment to a regular integer variable valid.&lt;/pawn&gt;<br /> <br /> Note - Spacing does generally not matter, as long as the compiler can tell symbols apart from each other. If your spacing is REALLY bad, you will get errors or maybe even warnings. For example, &quot;new var = 5&quot; and &quot;new var=5&quot; are the same, but &quot;newvar=5&quot; is totally wrong.<br /> <br /> ===Booleans===<br /> The last variable type is &quot;boolean&quot;. It is very simple - it is either &quot;true&quot;, or &quot;false&quot;. Both &quot;true&quot; and &quot;false&quot; are predefined data structures.<br /> <br /> &lt;pawn&gt;new bool:IsItOn //Declares a new variable &quot;IsItOn&quot; which is automatically false<br /> new bool:xyz=true //Declares a new variable &quot;xyz&quot; set to true&lt;/pawn&gt;<br /> <br /> <br /> <br /> =Arrays=<br /> <br /> Pawn features basic &quot;arrays&quot;. An array is a simple type of aggregate data. This means you can store multiple values in one variable! An array follows the same rules as a regular variable, and it has the same types. It simply can contain multiple values. You define an array with brackets, and how many values it can hold. For example:<br /> <br /> &lt;pawn&gt;//This will declare a variable called &quot;Players&quot; which holds 32 numbers. <br /> new Players[32]<br /> <br /> //You can now store values in any of the 32 &quot;slots&quot; this array has. <br /> // The slots are numbered from 0 to n-1, or in this case, 0 to 31.<br /> //Every slot starts off as 0.<br /> <br /> //Set slot 0 to 5<br /> Players[0] = 5<br /> <br /> //Set slot 1 to whatever is in slot 0, in this case, the number 5<br /> Players[1] = Players[0]<br /> <br /> //This is invalid! <br /> //Although there are 32 slots, they are numbered from 0 to 31.<br /> //Doing this results in AMX Native Error 4 - AMX_ERR_BOUNDS<br /> // or, it simply won't compile!<br /> Players[32] = 15<br /> <br /> //This is also totally invalid <br /> Players[-1] = 6<br /> <br /> new a = 3<br /> //This is also totally invalid. <br /> //a must be a constant number.<br /> new BadArray[a]<br /> <br /> //So this is valid:<br /> const b = 3<br /> new GoodArray[b]<br /> <br /> //You can also use Compiler Directives (See last section)<br /> <br /> #define ARRAY_SIZE 3<br /> new Array[ARRAY_SIZE]&lt;/pawn&gt;<br /> <br /> Arrays can also be declared with groups of data default, such as:<br /> <br /> &lt;pawn&gt;new Numbers[4] = {0,1,2,3}<br /> //Note: it is important that you make sure the amount of numbers<br /> // you pass and the size of the array match&lt;/pawn&gt;<br /> <br /> <br /> You can also use any data type with arrays:<br /> <br /> &lt;pawn&gt;//Array of floating points:<br /> new Float:Numbers[4] = {0.0, 1.2, 2.4, 3.8}<br /> //Array of booleans. Note this sets every slot to true.<br /> new bool:playerHasGun[33] = {true, ...}&lt;/pawn&gt;<br /> <br /> =Strings=<br /> <br /> You have probably noticed that an important data type is missing - characters (letters and symbols). These are called &quot;strings&quot;, and in Pawn, they are technically numbers! A string is an array of numbers that translate to ASCII (character) symbols. For example:<br /> <br /> &lt;pawn&gt;//This will declare a number array &quot;myString&quot; that contains the data &quot;Hello&quot;. <br /> //It will have 6 slots, because there are 5 characters. <br /> //The last slot is reserved for the number 0, which tells the Pawn engine that it is a string.<br /> new myString[] = &quot;Hello&quot;<br /> // If you're using SourcePawn, do this instead:<br /> new String:myString[] = &quot;Hello&quot;&lt;/pawn&gt;<br /> <br /> Note: anything in between /* and */ is also a comment. You cannot use /* */ inside a /* */. The following set of commands achieves the same purpose, however, it is longer and not recommended. This works because each character of the string &quot;Hello&quot; is stored in a slot in the array.<br /> &lt;pawn&gt;new myString[6]<br /> myString[0] = 'H'<br /> myString[1] = 'e'<br /> myString[2] = 'l'<br /> myString[3] = 'l'<br /> myString[4] = 'o'<br /> myString[5] = 0&lt;/pawn&gt;<br /> <br /> {{qnotice|Arrays that are meant to be strings must end in a 0, or the null character. This is so you know where the string ends.}}<br /> <br /> You CANNOT do this! While it may compile, it is highly dangerous as it might cause overflow errors:<br /> &lt;pawn&gt;new myString[6]<br /> myString = &quot;Hello&quot; //INVALID!<br /> myString[0] = &quot;Hello&quot; //INVALID!<br /> //To add data to a string, you can do this:<br /> new goodString[7]<br /> copy(goodString, 6, &quot;Hello&quot;)&lt;/pawn&gt;<br /> <br /> {{qnotice|In SourcePawn, copy was renamed to strcopy and avoids the issue with copy noted below.}}<br /> <br /> Note that we copied 6 cells of the array into an array that can hold 7. If we were to copy 7 bytes into this array, copy() could potentially copy an extra byte for the Null character, overflowing the array. This is called a [[buffer overflow]] and must be carefully avoided.<br /> <br /> More examples:<br /> &lt;pawn&gt;//Copy is a function that takes three parameters:<br /> copy(destination[], length, source[])<br /> //It copies the string inside the source array and places <br /> // it into the destination array, but only copies up to length characters.<br /> <br /> //Lastly, to prove that a string is really an array of numbers, this is completely valid:<br /> new weird[6]<br /> weird[0] = 68<br /> weird[1] = 65<br /> weird[2] = 73<br /> weird[3] = 86<br /> weird[4] = 68<br /> weird[5] = 0<br /> //This will set the variable &quot;weird&quot; to the string &quot;DAVID&quot;.<br /> //To see how letters and symbols translate into numbers, visit www.asciitable.com &lt;/pawn&gt;<br /> <br /> =Functions=<br /> <br /> Pawn allows you to define your own functions. This comes in handy for removing code that is used in multiple places. Note that all functions should return a value. To do this, you use the &quot;return&quot; command, which immediately halts the function and returns the value of the expression passed to it. No code is executed in a function once the return is found. Here are some examples:<br /> <br /> &lt;pawn&gt;//This is a function that takes no parameters and returns 1.<br /> //When activated, it uses the (non-existant) print function.<br /> show()<br /> {<br /> print(&quot;Hello!&quot;)<br /> <br /> return 1 //End, return 1<br /> }<br /> <br /> //Activate like this:<br /> show()&lt;/pawn&gt;<br /> <br /> You can also declare functions to take parameters.<br /> <br /> &lt;pawn&gt;//This declares a function called &quot;add_two_numbers&quot;, which takes two numbers and returns the sum.<br /> add_two_numbers(first, second)<br /> {<br /> new sum = first + second<br /> <br /> return sum //Return the sum<br /> }<br /> //Then you can use your new function like this:<br /> <br /> new a,b<br /> a = 5<br /> b = 12<br /> new c = add_two_numbers(a,b)<br /> //c will now be equal to 17.&lt;/pawn&gt;<br /> <br /> You are not limited by what types of data parameters can accept. When you give parameters to a function, it is called &quot;passing&quot;. You can pass either data or a variable to a function.<br /> <br /> &lt;pawn&gt;//This defines a new function called &quot;add_two_floats&quot;<br /> // which takes two floating points and returns the sum<br /> Float:add_two_floats(Float:first, Float:second)<br /> {<br /> new Float:sum = first + second<br /> <br /> return sum<br /> }<br /> <br /> new Float:a<br /> new Float:b<br /> a = 5.0<br /> b = 6.3<br /> new Float:c<br /> c = add_two_floats( a+b )<br /> //c is now equal to 11.3&lt;/pawn&gt;<br /> <br /> You can even pass arrays! You do not have to specify the size of the array. If you do, you must make sure you are calling the function with an array of equal size and type.<br /> &lt;pawn&gt;add_two_from_array(array[], a, b)<br /> {<br /> new first = array[a]<br /> new second = array[b]<br /> new sum = add_two_numbers(first, second) //use our function from earlier<br /> <br /> return sum<br /> }&lt;/pawn&gt;<br /> <br /> Note, that when you pass arrays through a function they are passed through what is called &quot;by reference&quot;. When a normal variable is passed to a function, it is copied in memory, and the copy is sent and then deleted afterwards. This is not the case with an array. Because arrays can be very large, the array is &quot;referenced&quot; instead of copied. This means if you change the array, afterwards it will stay changed. For example:<br /> <br /> &lt;pawn&gt;//This function will switch slots a and b inside any array passed to this function.<br /> swap_slots(array[], a, b)<br /> {<br /> //Note, you need to temporarily hold one of the slots before swapping them<br /> //Otherwise, you can't swap both values! This is a classic problem.<br /> //If you have a and b, setting b equal to a eliminates the original value in b.<br /> new temp<br /> <br /> temp = array[b]<br /> array[b] = array[a]<br /> array[a] = temp<br /> }<br /> <br /> new myArray[2]<br /> myArray[0] = 5<br /> myArray[1] = 6<br /> swap_slots(myArray, 0, 1)<br /> //myArray[0] is 6, myArray[1] is 5&lt;/pawn&gt;<br /> <br /> You can prevent arrays from being modified by declaring them &quot;constant&quot;, like so:<br /> &lt;pawn&gt;add_two_from_array(const array[], a, b)<br /> {<br /> new first = array[a]<br /> new second = array[b]<br /> new sum = add_two_from_array(first, second)<br /> return sum<br /> }<br /> //Note, now when you use the function, you are guaranteed that the array will not be modified.&lt;/pawn&gt;<br /> <br /> This function modifies an array passed as a constant. It will not work.<br /> &lt;pawn&gt;bad_function(const array[])<br /> {<br /> array[0] = 0<br /> }&lt;/pawn&gt;<br /> <br /> =Expressions=<br /> <br /> Expressions are just what they sound like from mathematics. They are groupings of symbols that return one piece of data. Expressions are normally comprised of parenthetical expressions, and are evaluated in a certain order (from innermost to outermost, parenthesis first, then multiplication, division, addition, subtraction, et cetera). You can put expressions anywhere. You can set variables equal to them or pass them to functions.<br /> <br /> &lt;pawn&gt;//This is the simplest expression. It returns the number zero.<br /> 0<br /> //However, to make it easier to read, this is also valid:<br /> (0)&lt;/pawn&gt;<br /> <br /> If an expression is not zero or it is not false, it not only returns a value, it also returns &quot;true&quot;. Otherwise, it will return 0, which is also &quot;false&quot;.<br /> <br /> &lt;pawn&gt;//Here are more mathematical expressions. The mathematical operators are<br /> // + for addition<br /> // - for subtraction<br /> // * for multiplication<br /> // / for division<br /> // % for modulus (finding the remainder of one number divided by another (5%2 is 1)<br /> (5+6) //returns 11<br /> ((5*6)+3) //returns 33<br /> ((((5+3)/2)*4)-9) //returns 7<br /> ((5*6) % 7) //returns 2<br /> //Here are other expressions:<br /> (true) //returns true<br /> (5.0 + 2.3) //returns 7.3 as a floating point&lt;/pawn&gt;<br /> <br /> There are also extensions of these operators for direct use on variables.<br /> &lt;pawn&gt;new a = 5<br /> new b = 6<br /> //The first are the post/pre increment and decrement operators.<br /> a++ //returns a+1, or 6. This is a post increment.<br /> ++a //also returns a+1, or 6. This is a pre increment.&lt;/pawn&gt;<br /> <br /> The difference between the two is subtle but important. a++ is evaluated LAST in an expression, while ++a is evaluated FIRST. This differences comes in handy with code that uses loops in certain ways. It is also important to know that the increment/decrement operators will not only return a+1, but set the variable a to a+1.<br /> <br /> &lt;pawn&gt;a-- //returns 4, post decrement<br /> --a //returns 4, pre decrement&lt;/pawn&gt;<br /> <br /> Note that a++ essentially trims down this code:<br /> &lt;pawn&gt;a = a + 1&lt;/pawn&gt;<br /> However, there is another way to write lines of code of this form:<br /> &lt;pawn&gt;a = a OP y&lt;/pawn&gt;<br /> Where OP is a math operator. It can be shortened to:<br /> &lt;pawn&gt;a OP= x&lt;/pawn&gt;<br /> Observe:<br /> &lt;pawn&gt;a += 1 //This sets a to a + 1<br /> a -= b //This sets a to a - b<br /> a *= 0 //This multiplies a by 0<br /> a /= 2 //This divides a by 2.&lt;/pawn&gt;<br /> <br /> However, mathematical operators are not the only operators you are given. There are boolean operators to help you with logical circuits or logical decisions.<br /> <br /> The and operator takes in the left expression and right expression. If both are &quot;true&quot;, then it returns true.<br /> <br /> &lt;pawn&gt;//This is false, because 1 returns true and 0 returns false. <br /> //Since both are not true, &amp;&amp; returns false.<br /> (1 &amp;&amp; 0)<br /> (1 &amp;&amp; 2) //Both numbers are &quot;true&quot;, therefore the expression is true.<br /> (true &amp;&amp; false) //false<br /> (false &amp;&amp; false) //false<br /> (true &amp;&amp; true) //true&lt;/pawn&gt;<br /> <br /> The other important operator is &quot;or&quot;. It returns true if one of two expressions are true.<br /> &lt;pawn&gt;(1 || 0) //true, since one of the values is true.<br /> (1 || 2) //true<br /> (true || false) //true<br /> (false || false) //false<br /> (true || true) //true&lt;/pawn&gt;<br /> <br /> There are other operators as well, that you may not use as often. The &quot;bitwise and&quot; operator returns whether a binary bit sequence is contained in another sequence. In the technical terms, it does an &quot;and (&amp;&amp;)&quot; operation on each of the bits in both numbers. For example, say you have the number &quot;9&quot;, which is &quot;1001&quot; in binary. If you want to know if that sequence contains the number &quot;8&quot; (1000), you can do:<br /> <br /> &lt;pawn&gt;//This will return 8, which means 8 is indeed a bit in 9.<br /> (9 &amp; 8)<br /> //4 (00100) is not a bit inside 16 (10000) and this will return 0.<br /> (16 &amp; 4)<br /> //The next operator is &quot;bitwise or&quot; <br /> //which does an &quot;or (||)' operation on each of the bits in both numbers.<br /> //This will take 9 (1001) and match it with 3 (0011), resulting in 1011, or 11.<br /> (9 | 3)&lt;/pawn&gt;<br /> <br /> These two operators are also important, but not used often. They are the bitwise shift operators, &lt;&lt; is a left shift and &gt;&gt; is a right shift. They shift the bits in a number to one direction.<br /> <br /> &lt;pawn&gt;//This takes the number 3 (00011) and shifts it three places to binary (11000), or 24.<br /> (3 &lt;&lt; 3)<br /> //This takes the number 24 (11000) and shifts it three places to binary (00011), or 3.<br /> (24 &gt;&gt; 3)&lt;/pawn&gt;<br /> <br /> The last operator is &quot;bitwise not&quot;. It returns the exact opposite of whatever is given to it. When used on a number, it will return each of the bits flipped (1 to 0, 0 to 1).<br /> <br /> &lt;pawn&gt;//This returns false<br /> (!true)<br /> //This returns true<br /> (!false)<br /> //This takes 9 (binary 1001) and makes it 6 (binary 0110).<br /> //This is the &quot;bitwise complement&quot; operator, which performs a !(not) on each bit.<br /> (~(9))&lt;/pawn&gt;<br /> <br /> =Conditionals=<br /> <br /> Conditionals allow you to test if an expression meets a standard, and to execute code based on that decision. <br /> <br /> ==If Statements==<br /> <br /> The most important conditional is called &quot;if ... then&quot;. If evaluates whether a given expression is true or false. It if is true, it executes a block of code. If not, it executes a different block of code. For example:<br /> <br /> This is an example of the most basic if ... then statement. The first line checks to see if the expression is true. In this case, if the variable a is equal to 5, then the if statement will execute the block of code underneath it, which sets a to 6.<br /> <br /> &lt;pawn&gt;if (a == 5)<br /> {<br /> a = 6<br /> }&lt;/pawn&gt;<br /> <br /> However, what happens if a does not equal 5? Then the code will not be executed. However, you can tell it to execute code if the conditions are not met. Now, if a is equal to 5, a will be set to 6. Otherwise, it will be set to 7.<br /> <br /> &lt;pawn&gt;if (a == 5)<br /> {<br /> a = 6<br /> } else {<br /> a = 7<br /> }&lt;/pawn&gt;<br /> <br /> There are many different operators you can use inside the if () statement. In fact, you can use any [[#Expressions|expression]] that evaluates to true (not zero) or false (zero).<br /> <br /> &lt;pawn&gt;//This will return true if a does not equal 5<br /> if (a != 5) {}<br /> //Returns true if a is greater than 5<br /> if (a &gt; 5) {}<br /> //Returns true if a is less than 5<br /> if (a &lt; 5) {}<br /> //Returns true if a is greater than or equal to 5<br /> if (a &gt;= 5) {}<br /> //Returns true if a is less than or equal to 5<br /> if (a &lt;= 5) {}<br /> //Returns true because 11 is true<br /> if (5+6) {}<br /> //Returns true of both a and b are true<br /> if (a &amp;&amp; b) {}<br /> //Returns true if 7.5 is greater than c<br /> if ( ((5*3)/2) &gt; c) {}<br /> //Always returns true no matter what<br /> if (true) {}<br /> //Never returns true<br /> if (false) {}&lt;/pawn&gt;<br /> Note that array comparisons have restrictions. This is invalid:<br /> <br /> &lt;pawn&gt;my arrayOne[3]<br /> my arrayTwo[3]<br /> if (arrayOne == arrayTwo) {&lt;/pawn&gt;<br /> <br /> You must do:<br /> &lt;pawn&gt;if ((arrayOne[0] == arrayTwo[0]) &amp;&amp; <br /> (arrayOne[1] == arrayTwo[1]) &amp;&amp; <br /> (arrayOne[2] == arrayTwo[2])) {&lt;/pawn&gt;<br /> <br /> Obviously, this would get very tedious with large arrays. You will see later on how to easily compare strings and arrays.<br /> <br /> The if...then model of conditional switching can be brought up to another level. Pawn provides a way for you to provide multiple levels of true and false expressions.<br /> <br /> &lt;pawn&gt;//Example of &quot;if...else if&quot;<br /> if (a == 5) {<br /> //This code will be run if a is 5.<br /> } else if (a &lt; 6) {<br /> //This code will be run if a is less than 6<br /> } else if (a == 7) {<br /> //This code will be run if a is 7.<br /> } else {<br /> //If none of the above conditions are met, this code will be run.<br /> }&lt;/pawn&gt;<br /> <br /> <br /> It is important to note that in the above example, each code block is not &quot;fall through&quot;. That means each of the conditions will be checked in order, and if one is true, the code will be executed and the if statement is done. It will not execute multiple true conditions.<br /> <br /> ==Switch Statements==<br /> <br /> Lastly, there is one last type of conditional statement. It is called a &quot;switch&quot; statement, and it allows you to make a nicely ordered list of conditions similar to, but not as powerful as, &quot;if...else if&quot;.<br /> <br /> &lt;pawn&gt;//Example of a switch statement<br /> switch (a)<br /> {<br /> case 5:<br /> {<br /> //This code will run if a is equal to 5<br /> }<br /> <br /> case 6:<br /> {<br /> //This code will run if a is equal to 6<br /> }<br /> <br /> case 7:<br /> {<br /> //This code will run if a is equal to 7<br /> }<br /> <br /> default:<br /> {<br /> //This code will run if all other cases fail<br /> }<br /> }&lt;/pawn&gt;<br /> Multiple conditions are also possible in pawn:<br /> &lt;pawn&gt;//Example of an multiple switch statement<br /> switch (a)<br /> {<br /> case 1, 2, 3:<br /> {<br /> //This code will run if a is equal to 1 or 2 or 3<br /> }<br /> <br /> case 4, 5, 6:<br /> {<br /> //This code will run if a is equal to 4 or 5 or6<br /> }<br /> <br /> case 7, 8, 9:<br /> {<br /> //This code will run if a is equal to 7 or 8 or 9<br /> }<br /> <br /> default:<br /> {<br /> //This code will run if all other cases fail<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> Note that switch cases do not &quot;fall-through.&quot; If a case is true, no other cases are evaluated.<br /> <br /> =Looping=<br /> <br /> Looping is essential for any language. It allows you to perform the same block of code over and over, by constructing conditions on which code should be repeated.<br /> <br /> ==For Loops==<br /> <br /> The first and most widely used loop is called a &quot;for loop&quot;. It takes an initial value, a condition upon which it should stop, and an incremental step. Then it executes code until it the conditions are no longer true. This lets you repeat the same block of code any number of times. Example:<br /> <br /> &lt;pawn&gt;/*A for loop has three parameters:<br /> for (initial; condition; increment)<br /> {<br /> //your code here<br /> }<br /> <br /> Before the first loop executes, it runs your initial condition.<br /> Then it begins looping your code with these steps:<br /> 1. Check if the condition is true. If so, continue. If not, stop.<br /> 2. Run the code.<br /> 3. Run the &quot;increment&quot; parameter.<br /> 4. Go to step 1.<br /> */<br /> <br /> //Example of a for loop<br /> new i<br /> new sum<br /> for (i=1; i&lt;=10; i++)<br /> {<br /> sum += i<br /> }&lt;/pawn&gt;<br /> <br /> Explanation:<br /> <br /> #The first parameter, i=1, sets the i variable to one. This happens before the looping starts.<br /> #Next, the &quot;increment&quot; parameter is checked. This parameter is a post-increment operator, so 1 will be added to i after the entire code block is evaluated.<br /> #Then the condition is checked. Is i&lt;=10? It is currently 1, so it is indeed less than or equal to 10.<br /> #Since the condition is true, sum+=i is executed. This means i is added into sum.<br /> #The code block has finished, and i++ increments i to 2.<br /> #Now it repeats.<br /> #Is i&lt;=10? Yes, it is 2. Now sum+=i runs again, and now sum is equal to 3.<br /> #The code block has finished, and i now increments to 3.<br /> #This happens until...<br /> #The increment parameter sets i to 11. The condition is no longer true, and the for loop is finished.<br /> #The sum variable now holds the number 55, which is the sum of 1 through 10.<br /> <br /> This provides a nice way of managing arrays!<br /> <br /> &lt;pawn&gt;//Note: this provides a nice way to loop through arrays! Observe this function below.<br /> sum_of_array(myArray[], size)<br /> {<br /> //Note: Make sure the user passes the size of the array, so we don't overflow it.<br /> new i, sum<br /> <br /> //This loop will start at 0 and stop right before size is reached.<br /> //If the user passes the correct size of the array, <br /> // the loop will be going from 0 to size-1<br /> // This correctly matches the numbers of slots in the array.<br /> for (i=0; i&lt;size; i++)<br /> {<br /> //For every time this loop executes, <br /> // i will be a number from 0 to size-1<br /> //Add the value of the slot (i) in the array to sum.<br /> //Once this is finished, sum will contain <br /> // the sum of all slots in the array.<br /> sum += myArray[i]<br /> }<br /> <br /> return sum<br /> }<br /> <br /> new NumberArray[4]<br /> NumberArray[0] = 3<br /> NumberArray[1] = 1<br /> NumberArray[2] = 4<br /> NumberArray[3] = 1<br /> <br /> new answer = sum_of_array(NumberArray, 4)<br /> //answer will be 3+1+4+1, or 9<br /> <br /> //Here is a function to compare if one array is equal to another (i.e. a string)<br /> bool:compare_arrays(array1[], array2[], size)<br /> {<br /> new i<br /> for (i=0; i&lt;size; i++)<br /> {<br /> //If a slot does not match, halt the function and return false.<br /> if (array1[i] != array2[i])<br /> {<br /> return false<br /> }<br /> }<br /> <br /> //If the function got to this point without returning false, return true.<br /> return true<br /> }&lt;/pawn&gt;<br /> <br /> ==While Loops==<br /> <br /> The next kind of loop is also very important, and is simpler than a for loop. Called a &quot;while&quot; loop, it only takes one parameter: a condition. As long as the condition is true, it keeps executing code. See the above examples rewritten with while loops.<br /> <br /> &lt;pawn&gt;//Basic loop<br /> new i=0<br /> new sum<br /> <br /> while (++i &lt;= 10)<br /> {<br /> sum+=i<br /> }<br /> <br /> sum_of_array(array[], size)<br /> {<br /> new i=0, sum<br /> <br /> //Do this loop while i is less than the size.<br /> //i is incremented at the end of every loop.<br /> while (i++ &lt; size)<br /> {<br /> sum += array[i]<br /> }<br /> <br /> return sum<br /> }<br /> <br /> bool:compare_arrays(array1[], array2[], size)<br /> {<br /> new i<br /> while (i++ &lt; size)<br /> {<br /> if (array1[i] != array2[i])<br /> {<br /> return false<br /> }<br /> }<br /> <br /> return true<br /> }&lt;/pawn&gt;<br /> <br /> <br /> ==Two Dimensional Arrays==<br /> <br /> In Pawn it is possible to have arrays where each slot is another array. This is very useful for storing a table of data, where the first section of slots is a row and the second section of slots is a column. Two dimensional arrays are declared like so:<br /> <br /> &lt;pawn&gt;//This declares an array with 50 rows and 50 columns.<br /> new BigArray[50][50]<br /> //this declares a floating point array with 25 rows and 10 columns.<br /> new Float:BigArray[25][10]&lt;/pawn&gt;<br /> <br /> Each slot in the first subset of the array becomes its own array.<br /> <br /> &lt;pawn&gt;new BigArray[3][3]<br /> BigArray[0][0] = 10<br /> BigArray[0][1] = 20<br /> BigArray[0][2] = 30<br /> BigArray[1][0] = 40<br /> BigArray[1][1] = 50<br /> BigArray[1][2] = 60<br /> BigArray[2][0] = 70<br /> BigArray[2][1] = 80<br /> BigArray[2][2] = 90&lt;/pawn&gt;<br /> <br /> Will result in BigArray looking like this:<br /> :{|<br /> |-<br /> | BigArray<br /> | 0<br /> | 1<br /> | 2<br /> |-<br /> | 0<br /> | 10<br /> | 20<br /> | 30<br /> |-<br /> | 1<br /> | 40<br /> | 50<br /> | 60<br /> |-<br /> | 2<br /> | 70<br /> | 80<br /> | 90<br /> |}<br /> <br /> Note that our old sum_of_array() function can still work! We can do:<br /> <br /> &lt;pawn&gt;new sum = sum_of_array(BigArray[2], 3)&lt;/pawn&gt;<br /> <br /> Because BigArray[2] contains a second, single dimensional array, containing {7,8,9}. However, let's write a 2D sum of array function.<br /> <br /> &lt;pawn&gt;//This function will tally up a two dimensional array.<br /> sum_of_table(array[][], rows, cols)<br /> {<br /> new i, j, sum<br /> <br /> //Note, there is a loop inside the loop. <br /> //This lets you go through each array inside the <br /> // bigger array. <br /> for (i=0; i&lt;rows; i++)<br /> {<br /> for (j=0; j&lt;cols; j++)<br /> {<br /> sum += array[i][j]<br /> }<br /> }<br /> <br /> return sum<br /> }&lt;/pawn&gt;<br /> <br /> Note, it is also possible to store an array of strings using two dimensional arrays.<br /> <br /> &lt;pawn&gt;new StringList[3][] = {&quot;Hello&quot;, &quot;my&quot;, &quot;friend&quot;}<br /> /*<br /> StringList[0][0] through [0][5] contains &quot;Hello&quot;<br /> StringList[1][0] through [1][2] contains &quot;my&quot;<br /> StringList[2][0] through [2][6] contains &quot;friend&quot;<br /> */&lt;/pawn&gt;<br /> <br /> The table for StringList will look like:<br /> StringList 0 1 2 3 4 5 6<br /> 0 H e l l o \0 <br /> 1 m y \0 <br /> 2 f r i e n d \0<br /> <br /> Comparing strings in multidimensional arrays is also similar:<br /> <br /> &lt;pawn&gt;if (StringList[0] == &quot;Hello&quot;) //INVALID<br /> if (StringList[0][0] == &quot;Hello&quot;) //INVALID<br /> if (equali(StringList[0], &quot;Hello&quot;)) //Valid&lt;/pawn&gt;<br /> <br /> =Compiler Pre-processor Directives=<br /> <br /> Compiler directives allow you to change how your code is read. This is rather advanced and will only be run over briefly.<br /> <br /> &lt;pawn&gt;//To bind a symbol to a value, you can do this:<br /> #define SYMBOL VALUE<br /> //for example:<br /> <br /> #define MAX_STRING 250<br /> new String[MAX_STRING]<br /> <br /> #define HELLO &quot;Hello. This is a generic greeting.&quot;<br /> new Hello[MAX_STRING] = HELLO&lt;/pawn&gt;<br /> <br /> You can also use #defines to change the flow of code the compiler makes.<br /> &lt;pawn&gt;#if defined LINUX<br /> //This portion will be compiled if #define LINUX exists<br /> execute_command(&quot;ls -l&quot;)<br /> #else<br /> //This portion will be compiled if #define LINUX does not exist<br /> execute_command(&quot;dir&quot;)<br /> #endif&lt;/pawn&gt;<br /> <br /> You can also change how much memory your script uses.<br /> &lt;pawn&gt;#pragma dynamic 4096<br /> //This creates a 16K stack of memory (default).<br /> //It is measured in blocks of 4 byte cells.&lt;/pawn&gt;<br /> <br /> You can also specify whether semicolon usage is required to terminate a line of code (by default it is not required). <br /> &lt;pawn&gt;#pragma semicolon 1&lt;/pawn&gt;<br /> <br /> You can also change the control character( amxx std: '^' )<br /> &lt;pawn&gt;#pragma ctrlchar '\'<br /> //this sets the control character to backslash( c/c++/c#/java/... std )<br /> // now you have to use the \ instead of ^<br /> // e.g. &quot;this is ^&quot;:D^&quot; &quot; must be now &quot; this is \&quot;:D\&quot; &quot;&lt;/pawn&gt;<br /> <br /> =Conclusion=<br /> <br /> This guide should have given you a VERY brief introduction to basic Pawn programming. It is by no means comprehensive and it should not constitute the entirety of one's knowledge of Pawn. To read the official Pawn documentation and language guide, go this website: https://github.com/compuphase/pawn/blob/master/doc/Pawn_Language_Guide.pdf (Note, this guide is very long and should be used as a reference. You may want to try the Small forums or the AMX Mod X forums). Continue to the next Section to see how to apply Small programming to the Half-Life and AMX Mod X engine!<br /> <br /> =External Links=<br /> *[https://github.com/compuphase/pawn/blob/master/doc/Pawn_Language_Guide.pdf Pawn Language Reference]<br /> *[http://www.compuphase.com/pawn/pawn.htm Pawn Homepage]<br /> *[http://www.compuphase.com/ ITB CompuPhase]<br /> <br /> [[Category:Scripting (AMX Mod X)]]</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Pawn_Tutorial&diff=10747 2019-04-10T11:53:48Z

<p>Xerox8521: Fixed link to Pawn Lang Guide pdf file.</p> <hr /> <div>{{qnotice|This guide is rather hardcoded to [[AMX Mod X]]. It needs to be mode generic.}}<br /> <br /> This guide is designed to give you a more in-depth overview of the basics of programming in [[Pawn]].<br /> <br /> =Introduction=<br /> Pawn is an embeddable, (almost) typeless, easy to use scripting language that is compiled for a virtual machine. [[AMX Mod X]] uses Pawn to route scripting functions to the Half-Life engine, using the Pawn [[Virtual Machine]] and [[Metamod]] ([[Pawn]] is written in C, Metamod is written in C++). While you write Pawn scripts in a text editor, the scripts must be compiled with a &quot;Compiler&quot;, which produces a binary for AMX Mod X. The AMX Mod X team distributes a specially modified Pawn compiler.<br /> <br /> Programming scripts in Pawn is relatively easy, and does not have concepts in other languages that are unnecessary for general use, such as pointers, vectors, structs, classes, allocation, et cetera. <br /> <br /> ==Language Paradigms==<br /> Pawn was originally named &quot;[[Small]]&quot; to emphasize the size of the language specification. The language sacrifices many features found in modern languages to achieve simplicity and speed, which are required for embedded uses.<br /> *No typing<br /> **Pawn only has one data type -- the &quot;[[Cell_(Pawn)|cell]]&quot;. It is the size of the processor's integral pointer (4 bytes for 32bit processor, 8 bytes for 64bit processors). This has two major implications - Pawn bytecode is processor specific, and pointers can fit inside a cell.<br /> **[[Tagging_(Pawn)|Tagging]] - Pawn lets you create weakly statically typed &quot;tags&quot;, which can be associated with variables for primitive operator overloading. For example, Pawn has no concept of floating point numbers (only integers). Instead, operators are overloaded with the Float: tag to redirect computation to new functions. Tag-checking is only enforced as a warning. If you're using SourcePawn (for SourceMod), there is actually a second type: String. In a String, letters are stored as separate bytes... essentially having 4 characters stored in every cell.<br /> **Since Pawn only has one datatype, it does not support structs, records, objects, or anything else.<br /> **Pawn &lt;i&gt;does&lt;/i&gt; support arrays of cells, which leads to C-style arrays for strings.<br /> *No garbage collection<br /> **Pawn has no &quot;heap&quot; allocation built-in. All variables are stored on the stack or in the data section. Therefore, no garbage collection is necessary and memory leaks are not possible from the language specification alone.<br /> *Procedural<br /> **Pawn is entirely comprised of single, non-nested subroutines. There are no lambda functions, member functions, constructors, et cetera. Functions can either be internal (within the script) or public (exposed to the VM by name, like C's &quot;extern&quot;).<br /> *No thread-safety<br /> **Pawn is targetted toward single-thread instances.<br /> <br /> ==Implementation Features==<br /> *Cross-platform compatible compiler, which outputs bytecode and debug browsing information.<br /> *Cross-platform compatible Virtual Machine (VM), with support for debug browsing, halting/stopping execution, and interacting with scripts from C/C++ libraries.<br /> *IA32 JIT Compiler for vastly increasing script execution time.<br /> <br /> Because the footprints of the VM and JIT are so small, Pawn is ideal inside games which need a simple and highly fast event system, embedded devices or applications, and realtime systems.<br /> <br /> ==License==<br /> Pawn is licensed under the [[ZLib/libpng_License]] license.<br /> <br /> =Variables=<br /> Variables are simple structures for holding data throughout a period of time in your script.<br /> <br /> ==Types==<br /> Small has just three data types for declaring variables. The default variable type is a regular whole number, or integer. A variable name, for backwards compatibility, should be 19 characters or less, and MUST start with a letter. It can contain the symbols A-Z, a-z, 0-9, and the underscore (&quot;_&quot;). It is important to note that variable names are case sensitive - &quot;myvar&quot;, &quot;MyVaR&quot;, and &quot;MYVAR&quot; are three separate symbols. <br /> <br /> ===Integers===<br /> The simplest data type in Pawn is an &quot;integer&quot;. Integers are whole numbers. To declare a new integer variable, use the &quot;new&quot; operator like so:<br /> <br /> &lt;pawn&gt;new a //Declare empty variable &quot;a&quot;<br /> new b=5 //Declare variable &quot;b&quot; and set it to 5.<br /> new c=5.0 //This is invalid, technically not a whole number!<br /> new d=&quot;hello&quot; //&quot;hello&quot; is not a number either, this is invalid.<br /> <br /> //You can also declare multiple variables on one line:<br /> new e,f,g,h<br /> new x=7, y=3<br /> new z = 1_000_000 // Pawn supports numbers like this. So big values are easier to read.&lt;/pawn&gt;<br /> <br /> ===Floats===<br /> You can also declare a variable as a &quot;Float&quot;, which means it can store numbers with decimal places. These are called &quot;floating point&quot; numbers:<br /> <br /> &lt;pawn&gt;new Float:a //Declare empty floating point variable &quot;a&quot;<br /> new Float:b=5.3 //This will declare a new variable &quot;b&quot; and assign 5.3 to it.<br /> new Float:c=5 //This is valid, but the compiler will give you a warning.<br /> new Float:d=&quot;hello&quot; //This is invalid, &quot;hello&quot; is not a decimal number.&lt;/pawn&gt;<br /> <br /> You can also do the following:<br /> &lt;pawn&gt;//float(n) is a function that takes a number n and makes it a<br /> // floating point number.<br /> new Float:var = float(5)<br /> new Float:var2 = 5.0 <br /> new Float:var3 = 1.0*5<br /> new var4 = floatround(5.0) <br /> //Note: floatround(n) is a function that takes a number n and rounds it to a whole number.<br /> // this makes the assignment to a regular integer variable valid.&lt;/pawn&gt;<br /> <br /> Note - Spacing does generally not matter, as long as the compiler can tell symbols apart from each other. If your spacing is REALLY bad, you will get errors or maybe even warnings. For example, &quot;new var = 5&quot; and &quot;new var=5&quot; are the same, but &quot;newvar=5&quot; is totally wrong.<br /> <br /> ===Booleans===<br /> The last variable type is &quot;boolean&quot;. It is very simple - it is either &quot;true&quot;, or &quot;false&quot;. Both &quot;true&quot; and &quot;false&quot; are predefined data structures.<br /> <br /> &lt;pawn&gt;new bool:IsItOn //Declares a new variable &quot;IsItOn&quot; which is automatically false<br /> new bool:xyz=true //Declares a new variable &quot;xyz&quot; set to true&lt;/pawn&gt;<br /> <br /> <br /> <br /> =Arrays=<br /> <br /> Pawn features basic &quot;arrays&quot;. An array is a simple type of aggregate data. This means you can store multiple values in one variable! An array follows the same rules as a regular variable, and it has the same types. It simply can contain multiple values. You define an array with brackets, and how many values it can hold. For example:<br /> <br /> &lt;pawn&gt;//This will declare a variable called &quot;Players&quot; which holds 32 numbers. <br /> new Players[32]<br /> <br /> //You can now store values in any of the 32 &quot;slots&quot; this array has. <br /> // The slots are numbered from 0 to n-1, or in this case, 0 to 31.<br /> //Every slot starts off as 0.<br /> <br /> //Set slot 0 to 5<br /> Players[0] = 5<br /> <br /> //Set slot 1 to whatever is in slot 0, in this case, the number 5<br /> Players[1] = Players[0]<br /> <br /> //This is invalid! <br /> //Although there are 32 slots, they are numbered from 0 to 31.<br /> //Doing this results in AMX Native Error 4 - AMX_ERR_BOUNDS<br /> // or, it simply won't compile!<br /> Players[32] = 15<br /> <br /> //This is also totally invalid <br /> Players[-1] = 6<br /> <br /> new a = 3<br /> //This is also totally invalid. <br /> //a must be a constant number.<br /> new BadArray[a]<br /> <br /> //So this is valid:<br /> const b = 3<br /> new GoodArray[b]<br /> <br /> //You can also use Compiler Directives (See last section)<br /> <br /> #define ARRAY_SIZE 3<br /> new Array[ARRAY_SIZE]&lt;/pawn&gt;<br /> <br /> Arrays can also be declared with groups of data default, such as:<br /> <br /> &lt;pawn&gt;new Numbers[4] = {0,1,2,3}<br /> //Note: it is important that you make sure the amount of numbers<br /> // you pass and the size of the array match&lt;/pawn&gt;<br /> <br /> <br /> You can also use any data type with arrays:<br /> <br /> &lt;pawn&gt;//Array of floating points:<br /> new Float:Numbers[4] = {0.0, 1.2, 2.4, 3.8}<br /> //Array of booleans. Note this sets every slot to true.<br /> new bool:playerHasGun[33] = {true, ...}&lt;/pawn&gt;<br /> <br /> =Strings=<br /> <br /> You have probably noticed that an important data type is missing - characters (letters and symbols). These are called &quot;strings&quot;, and in Pawn, they are technically numbers! A string is an array of numbers that translate to ASCII (character) symbols. For example:<br /> <br /> &lt;pawn&gt;//This will declare a number array &quot;myString&quot; that contains the data &quot;Hello&quot;. <br /> //It will have 6 slots, because there are 5 characters. <br /> //The last slot is reserved for the number 0, which tells the Pawn engine that it is a string.<br /> new myString[] = &quot;Hello&quot;<br /> // If you're using SourcePawn, do this instead:<br /> new String:myString[] = &quot;Hello&quot;&lt;/pawn&gt;<br /> <br /> Note: anything in between /* and */ is also a comment. You cannot use /* */ inside a /* */. The following set of commands achieves the same purpose, however, it is longer and not recommended. This works because each character of the string &quot;Hello&quot; is stored in a slot in the array.<br /> &lt;pawn&gt;new myString[6]<br /> myString[0] = 'H'<br /> myString[1] = 'e'<br /> myString[2] = 'l'<br /> myString[3] = 'l'<br /> myString[4] = 'o'<br /> myString[5] = 0&lt;/pawn&gt;<br /> <br /> {{qnotice|Arrays that are meant to be strings must end in a 0, or the null character. This is so you know where the string ends.}}<br /> <br /> You CANNOT do this! While it may compile, it is highly dangerous as it might cause overflow errors:<br /> &lt;pawn&gt;new myString[6]<br /> myString = &quot;Hello&quot; //INVALID!<br /> myString[0] = &quot;Hello&quot; //INVALID!<br /> //To add data to a string, you can do this:<br /> new goodString[7]<br /> copy(goodString, 6, &quot;Hello&quot;)&lt;/pawn&gt;<br /> <br /> {{qnotice|In SourcePawn, copy was renamed to strcopy and avoids the issue with copy noted below.}}<br /> <br /> Note that we copied 6 cells of the array into an array that can hold 7. If we were to copy 7 bytes into this array, copy() could potentially copy an extra byte for the Null character, overflowing the array. This is called a [[buffer overflow]] and must be carefully avoided.<br /> <br /> More examples:<br /> &lt;pawn&gt;//Copy is a function that takes three parameters:<br /> copy(destination[], length, source[])<br /> //It copies the string inside the source array and places <br /> // it into the destination array, but only copies up to length characters.<br /> <br /> //Lastly, to prove that a string is really an array of numbers, this is completely valid:<br /> new weird[6]<br /> weird[0] = 68<br /> weird[1] = 65<br /> weird[2] = 73<br /> weird[3] = 86<br /> weird[4] = 68<br /> weird[5] = 0<br /> //This will set the variable &quot;weird&quot; to the string &quot;DAVID&quot;.<br /> //To see how letters and symbols translate into numbers, visit www.asciitable.com &lt;/pawn&gt;<br /> <br /> =Functions=<br /> <br /> Pawn allows you to define your own functions. This comes in handy for removing code that is used in multiple places. Note that all functions should return a value. To do this, you use the &quot;return&quot; command, which immediately halts the function and returns the value of the expression passed to it. No code is executed in a function once the return is found. Here are some examples:<br /> <br /> &lt;pawn&gt;//This is a function that takes no parameters and returns 1.<br /> //When activated, it uses the (non-existant) print function.<br /> show()<br /> {<br /> print(&quot;Hello!&quot;)<br /> <br /> return 1 //End, return 1<br /> }<br /> <br /> //Activate like this:<br /> show()&lt;/pawn&gt;<br /> <br /> You can also declare functions to take parameters.<br /> <br /> &lt;pawn&gt;//This declares a function called &quot;add_two_numbers&quot;, which takes two numbers and returns the sum.<br /> add_two_numbers(first, second)<br /> {<br /> new sum = first + second<br /> <br /> return sum //Return the sum<br /> }<br /> //Then you can use your new function like this:<br /> <br /> new a,b<br /> a = 5<br /> b = 12<br /> new c = add_two_numbers(a,b)<br /> //c will now be equal to 17.&lt;/pawn&gt;<br /> <br /> You are not limited by what types of data parameters can accept. When you give parameters to a function, it is called &quot;passing&quot;. You can pass either data or a variable to a function.<br /> <br /> &lt;pawn&gt;//This defines a new function called &quot;add_two_floats&quot;<br /> // which takes two floating points and returns the sum<br /> Float:add_two_floats(Float:first, Float:second)<br /> {<br /> new Float:sum = first + second<br /> <br /> return sum<br /> }<br /> <br /> new Float:a<br /> new Float:b<br /> a = 5.0<br /> b = 6.3<br /> new Float:c<br /> c = add_two_floats( a+b )<br /> //c is now equal to 11.3&lt;/pawn&gt;<br /> <br /> You can even pass arrays! You do not have to specify the size of the array. If you do, you must make sure you are calling the function with an array of equal size and type.<br /> &lt;pawn&gt;add_two_from_array(array[], a, b)<br /> {<br /> new first = array[a]<br /> new second = array[b]<br /> new sum = add_two_numbers(first, second) //use our function from earlier<br /> <br /> return sum<br /> }&lt;/pawn&gt;<br /> <br /> Note, that when you pass arrays through a function they are passed through what is called &quot;by reference&quot;. When a normal variable is passed to a function, it is copied in memory, and the copy is sent and then deleted afterwards. This is not the case with an array. Because arrays can be very large, the array is &quot;referenced&quot; instead of copied. This means if you change the array, afterwards it will stay changed. For example:<br /> <br /> &lt;pawn&gt;//This function will switch slots a and b inside any array passed to this function.<br /> swap_slots(array[], a, b)<br /> {<br /> //Note, you need to temporarily hold one of the slots before swapping them<br /> //Otherwise, you can't swap both values! This is a classic problem.<br /> //If you have a and b, setting b equal to a eliminates the original value in b.<br /> new temp<br /> <br /> temp = array[b]<br /> array[b] = array[a]<br /> array[a] = temp<br /> }<br /> <br /> new myArray[2]<br /> myArray[0] = 5<br /> myArray[1] = 6<br /> swap_slots(myArray, 0, 1)<br /> //myArray[0] is 6, myArray[1] is 5&lt;/pawn&gt;<br /> <br /> You can prevent arrays from being modified by declaring them &quot;constant&quot;, like so:<br /> &lt;pawn&gt;add_two_from_array(const array[], a, b)<br /> {<br /> new first = array[a]<br /> new second = array[b]<br /> new sum = add_two_from_array(first, second)<br /> return sum<br /> }<br /> //Note, now when you use the function, you are guaranteed that the array will not be modified.&lt;/pawn&gt;<br /> <br /> This function modifies an array passed as a constant. It will not work.<br /> &lt;pawn&gt;bad_function(const array[])<br /> {<br /> array[0] = 0<br /> }&lt;/pawn&gt;<br /> <br /> =Expressions=<br /> <br /> Expressions are just what they sound like from mathematics. They are groupings of symbols that return one piece of data. Expressions are normally comprised of parenthetical expressions, and are evaluated in a certain order (from innermost to outermost, parenthesis first, then multiplication, division, addition, subtraction, et cetera). You can put expressions anywhere. You can set variables equal to them or pass them to functions.<br /> <br /> &lt;pawn&gt;//This is the simplest expression. It returns the number zero.<br /> 0<br /> //However, to make it easier to read, this is also valid:<br /> (0)&lt;/pawn&gt;<br /> <br /> If an expression is not zero or it is not false, it not only returns a value, it also returns &quot;true&quot;. Otherwise, it will return 0, which is also &quot;false&quot;.<br /> <br /> &lt;pawn&gt;//Here are more mathematical expressions. The mathematical operators are<br /> // + for addition<br /> // - for subtraction<br /> // * for multiplication<br /> // / for division<br /> // % for modulus (finding the remainder of one number divided by another (5%2 is 1)<br /> (5+6) //returns 11<br /> ((5*6)+3) //returns 33<br /> ((((5+3)/2)*4)-9) //returns 7<br /> ((5*6) % 7) //returns 2<br /> //Here are other expressions:<br /> (true) //returns true<br /> (5.0 + 2.3) //returns 7.3 as a floating point&lt;/pawn&gt;<br /> <br /> There are also extensions of these operators for direct use on variables.<br /> &lt;pawn&gt;new a = 5<br /> new b = 6<br /> //The first are the post/pre increment and decrement operators.<br /> a++ //returns a+1, or 6. This is a post increment.<br /> ++a //also returns a+1, or 6. This is a pre increment.&lt;/pawn&gt;<br /> <br /> The difference between the two is subtle but important. a++ is evaluated LAST in an expression, while ++a is evaluated FIRST. This differences comes in handy with code that uses loops in certain ways. It is also important to know that the increment/decrement operators will not only return a+1, but set the variable a to a+1.<br /> <br /> &lt;pawn&gt;a-- //returns 4, post decrement<br /> --a //returns 4, pre decrement&lt;/pawn&gt;<br /> <br /> Note that a++ essentially trims down this code:<br /> &lt;pawn&gt;a = a + 1&lt;/pawn&gt;<br /> However, there is another way to write lines of code of this form:<br /> &lt;pawn&gt;a = a OP y&lt;/pawn&gt;<br /> Where OP is a math operator. It can be shortened to:<br /> &lt;pawn&gt;a OP= x&lt;/pawn&gt;<br /> Observe:<br /> &lt;pawn&gt;a += 1 //This sets a to a + 1<br /> a -= b //This sets a to a - b<br /> a *= 0 //This multiplies a by 0<br /> a /= 2 //This divides a by 2.&lt;/pawn&gt;<br /> <br /> However, mathematical operators are not the only operators you are given. There are boolean operators to help you with logical circuits or logical decisions.<br /> <br /> The and operator takes in the left expression and right expression. If both are &quot;true&quot;, then it returns true.<br /> <br /> &lt;pawn&gt;//This is false, because 1 returns true and 0 returns false. <br /> //Since both are not true, &amp;&amp; returns false.<br /> (1 &amp;&amp; 0)<br /> (1 &amp;&amp; 2) //Both numbers are &quot;true&quot;, therefore the expression is true.<br /> (true &amp;&amp; false) //false<br /> (false &amp;&amp; false) //false<br /> (true &amp;&amp; true) //true&lt;/pawn&gt;<br /> <br /> The other important operator is &quot;or&quot;. It returns true if one of two expressions are true.<br /> &lt;pawn&gt;(1 || 0) //true, since one of the values is true.<br /> (1 || 2) //true<br /> (true || false) //true<br /> (false || false) //false<br /> (true || true) //true&lt;/pawn&gt;<br /> <br /> There are other operators as well, that you may not use as often. The &quot;bitwise and&quot; operator returns whether a binary bit sequence is contained in another sequence. In the technical terms, it does an &quot;and (&amp;&amp;)&quot; operation on each of the bits in both numbers. For example, say you have the number &quot;9&quot;, which is &quot;1001&quot; in binary. If you want to know if that sequence contains the number &quot;8&quot; (1000), you can do:<br /> <br /> &lt;pawn&gt;//This will return 8, which means 8 is indeed a bit in 9.<br /> (9 &amp; 8)<br /> //4 (00100) is not a bit inside 16 (10000) and this will return 0.<br /> (16 &amp; 4)<br /> //The next operator is &quot;bitwise or&quot; <br /> //which does an &quot;or (||)' operation on each of the bits in both numbers.<br /> //This will take 9 (1001) and match it with 3 (0011), resulting in 1011, or 11.<br /> (9 | 3)&lt;/pawn&gt;<br /> <br /> These two operators are also important, but not used often. They are the bitwise shift operators, &lt;&lt; is a left shift and &gt;&gt; is a right shift. They shift the bits in a number to one direction.<br /> <br /> &lt;pawn&gt;//This takes the number 3 (00011) and shifts it three places to binary (11000), or 24.<br /> (3 &lt;&lt; 3)<br /> //This takes the number 24 (11000) and shifts it three places to binary (00011), or 3.<br /> (24 &gt;&gt; 3)&lt;/pawn&gt;<br /> <br /> The last operator is &quot;bitwise not&quot;. It returns the exact opposite of whatever is given to it. When used on a number, it will return each of the bits flipped (1 to 0, 0 to 1).<br /> <br /> &lt;pawn&gt;//This returns false<br /> (!true)<br /> //This returns true<br /> (!false)<br /> //This takes 9 (binary 1001) and makes it 6 (binary 0110).<br /> //This is the &quot;bitwise complement&quot; operator, which performs a !(not) on each bit.<br /> (~(9))&lt;/pawn&gt;<br /> <br /> =Conditionals=<br /> <br /> Conditionals allow you to test if an expression meets a standard, and to execute code based on that decision. <br /> <br /> ==If Statements==<br /> <br /> The most important conditional is called &quot;if ... then&quot;. If evaluates whether a given expression is true or false. It if is true, it executes a block of code. If not, it executes a different block of code. For example:<br /> <br /> This is an example of the most basic if ... then statement. The first line checks to see if the expression is true. In this case, if the variable a is equal to 5, then the if statement will execute the block of code underneath it, which sets a to 6.<br /> <br /> &lt;pawn&gt;if (a == 5)<br /> {<br /> a = 6<br /> }&lt;/pawn&gt;<br /> <br /> However, what happens if a does not equal 5? Then the code will not be executed. However, you can tell it to execute code if the conditions are not met. Now, if a is equal to 5, a will be set to 6. Otherwise, it will be set to 7.<br /> <br /> &lt;pawn&gt;if (a == 5)<br /> {<br /> a = 6<br /> } else {<br /> a = 7<br /> }&lt;/pawn&gt;<br /> <br /> There are many different operators you can use inside the if () statement. In fact, you can use any [[#Expressions|expression]] that evaluates to true (not zero) or false (zero).<br /> <br /> &lt;pawn&gt;//This will return true if a does not equal 5<br /> if (a != 5) {}<br /> //Returns true if a is greater than 5<br /> if (a &gt; 5) {}<br /> //Returns true if a is less than 5<br /> if (a &lt; 5) {}<br /> //Returns true if a is greater than or equal to 5<br /> if (a &gt;= 5) {}<br /> //Returns true if a is less than or equal to 5<br /> if (a &lt;= 5) {}<br /> //Returns true because 11 is true<br /> if (5+6) {}<br /> //Returns true of both a and b are true<br /> if (a &amp;&amp; b) {}<br /> //Returns true if 7.5 is greater than c<br /> if ( ((5*3)/2) &gt; c) {}<br /> //Always returns true no matter what<br /> if (true) {}<br /> //Never returns true<br /> if (false) {}&lt;/pawn&gt;<br /> Note that array comparisons have restrictions. This is invalid:<br /> <br /> &lt;pawn&gt;my arrayOne[3]<br /> my arrayTwo[3]<br /> if (arrayOne == arrayTwo) {&lt;/pawn&gt;<br /> <br /> You must do:<br /> &lt;pawn&gt;if ((arrayOne[0] == arrayTwo[0]) &amp;&amp; <br /> (arrayOne[1] == arrayTwo[1]) &amp;&amp; <br /> (arrayOne[2] == arrayTwo[2])) {&lt;/pawn&gt;<br /> <br /> Obviously, this would get very tedious with large arrays. You will see later on how to easily compare strings and arrays.<br /> <br /> The if...then model of conditional switching can be brought up to another level. Pawn provides a way for you to provide multiple levels of true and false expressions.<br /> <br /> &lt;pawn&gt;//Example of &quot;if...else if&quot;<br /> if (a == 5) {<br /> //This code will be run if a is 5.<br /> } else if (a &lt; 6) {<br /> //This code will be run if a is less than 6<br /> } else if (a == 7) {<br /> //This code will be run if a is 7.<br /> } else {<br /> //If none of the above conditions are met, this code will be run.<br /> }&lt;/pawn&gt;<br /> <br /> <br /> It is important to note that in the above example, each code block is not &quot;fall through&quot;. That means each of the conditions will be checked in order, and if one is true, the code will be executed and the if statement is done. It will not execute multiple true conditions.<br /> <br /> ==Switch Statements==<br /> <br /> Lastly, there is one last type of conditional statement. It is called a &quot;switch&quot; statement, and it allows you to make a nicely ordered list of conditions similar to, but not as powerful as, &quot;if...else if&quot;.<br /> <br /> &lt;pawn&gt;//Example of a switch statement<br /> switch (a)<br /> {<br /> case 5:<br /> {<br /> //This code will run if a is equal to 5<br /> }<br /> <br /> case 6:<br /> {<br /> //This code will run if a is equal to 6<br /> }<br /> <br /> case 7:<br /> {<br /> //This code will run if a is equal to 7<br /> }<br /> <br /> default:<br /> {<br /> //This code will run if all other cases fail<br /> }<br /> }&lt;/pawn&gt;<br /> Multiple conditions are also possible in pawn:<br /> &lt;pawn&gt;//Example of an multiple switch statement<br /> switch (a)<br /> {<br /> case 1, 2, 3:<br /> {<br /> //This code will run if a is equal to 1 or 2 or 3<br /> }<br /> <br /> case 4, 5, 6:<br /> {<br /> //This code will run if a is equal to 4 or 5 or6<br /> }<br /> <br /> case 7, 8, 9:<br /> {<br /> //This code will run if a is equal to 7 or 8 or 9<br /> }<br /> <br /> default:<br /> {<br /> //This code will run if all other cases fail<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> Note that switch cases do not &quot;fall-through.&quot; If a case is true, no other cases are evaluated.<br /> <br /> =Looping=<br /> <br /> Looping is essential for any language. It allows you to perform the same block of code over and over, by constructing conditions on which code should be repeated.<br /> <br /> ==For Loops==<br /> <br /> The first and most widely used loop is called a &quot;for loop&quot;. It takes an initial value, a condition upon which it should stop, and an incremental step. Then it executes code until it the conditions are no longer true. This lets you repeat the same block of code any number of times. Example:<br /> <br /> &lt;pawn&gt;/*A for loop has three parameters:<br /> for (initial; condition; increment)<br /> {<br /> //your code here<br /> }<br /> <br /> Before the first loop executes, it runs your initial condition.<br /> Then it begins looping your code with these steps:<br /> 1. Check if the condition is true. If so, continue. If not, stop.<br /> 2. Run the code.<br /> 3. Run the &quot;increment&quot; parameter.<br /> 4. Go to step 1.<br /> */<br /> <br /> //Example of a for loop<br /> new i<br /> new sum<br /> for (i=1; i&lt;=10; i++)<br /> {<br /> sum += i<br /> }&lt;/pawn&gt;<br /> <br /> Explanation:<br /> <br /> #The first parameter, i=1, sets the i variable to one. This happens before the looping starts.<br /> #Next, the &quot;increment&quot; parameter is checked. This parameter is a post-increment operator, so 1 will be added to i after the entire code block is evaluated.<br /> #Then the condition is checked. Is i&lt;=10? It is currently 1, so it is indeed less than or equal to 10.<br /> #Since the condition is true, sum+=i is executed. This means i is added into sum.<br /> #The code block has finished, and i++ increments i to 2.<br /> #Now it repeats.<br /> #Is i&lt;=10? Yes, it is 2. Now sum+=i runs again, and now sum is equal to 3.<br /> #The code block has finished, and i now increments to 3.<br /> #This happens until...<br /> #The increment parameter sets i to 11. The condition is no longer true, and the for loop is finished.<br /> #The sum variable now holds the number 55, which is the sum of 1 through 10.<br /> <br /> This provides a nice way of managing arrays!<br /> <br /> &lt;pawn&gt;//Note: this provides a nice way to loop through arrays! Observe this function below.<br /> sum_of_array(myArray[], size)<br /> {<br /> //Note: Make sure the user passes the size of the array, so we don't overflow it.<br /> new i, sum<br /> <br /> //This loop will start at 0 and stop right before size is reached.<br /> //If the user passes the correct size of the array, <br /> // the loop will be going from 0 to size-1<br /> // This correctly matches the numbers of slots in the array.<br /> for (i=0; i&lt;size; i++)<br /> {<br /> //For every time this loop executes, <br /> // i will be a number from 0 to size-1<br /> //Add the value of the slot (i) in the array to sum.<br /> //Once this is finished, sum will contain <br /> // the sum of all slots in the array.<br /> sum += myArray[i]<br /> }<br /> <br /> return sum<br /> }<br /> <br /> new NumberArray[4]<br /> NumberArray[0] = 3<br /> NumberArray[1] = 1<br /> NumberArray[2] = 4<br /> NumberArray[3] = 1<br /> <br /> new answer = sum_of_array(NumberArray, 4)<br /> //answer will be 3+1+4+1, or 9<br /> <br /> //Here is a function to compare if one array is equal to another (i.e. a string)<br /> bool:compare_arrays(array1[], array2[], size)<br /> {<br /> new i<br /> for (i=0; i&lt;size; i++)<br /> {<br /> //If a slot does not match, halt the function and return false.<br /> if (array1[i] != array2[i])<br /> {<br /> return false<br /> }<br /> }<br /> <br /> //If the function got to this point without returning false, return true.<br /> return true<br /> }&lt;/pawn&gt;<br /> <br /> ==While Loops==<br /> <br /> The next kind of loop is also very important, and is simpler than a for loop. Called a &quot;while&quot; loop, it only takes one parameter: a condition. As long as the condition is true, it keeps executing code. See the above examples rewritten with while loops.<br /> <br /> &lt;pawn&gt;//Basic loop<br /> new i=0<br /> new sum<br /> <br /> while (++i &lt;= 10)<br /> {<br /> sum+=i<br /> }<br /> <br /> sum_of_array(array[], size)<br /> {<br /> new i=0, sum<br /> <br /> //Do this loop while i is less than the size.<br /> //i is incremented at the end of every loop.<br /> while (i++ &lt; size)<br /> {<br /> sum += array[i]<br /> }<br /> <br /> return sum<br /> }<br /> <br /> bool:compare_arrays(array1[], array2[], size)<br /> {<br /> new i<br /> while (i++ &lt; size)<br /> {<br /> if (array1[i] != array2[i])<br /> {<br /> return false<br /> }<br /> }<br /> <br /> return true<br /> }&lt;/pawn&gt;<br /> <br /> <br /> ==Two Dimensional Arrays==<br /> <br /> In Pawn it is possible to have arrays where each slot is another array. This is very useful for storing a table of data, where the first section of slots is a row and the second section of slots is a column. Two dimensional arrays are declared like so:<br /> <br /> &lt;pawn&gt;//This declares an array with 50 rows and 50 columns.<br /> new BigArray[50][50]<br /> //this declares a floating point array with 25 rows and 10 columns.<br /> new Float:BigArray[25][10]&lt;/pawn&gt;<br /> <br /> Each slot in the first subset of the array becomes its own array.<br /> <br /> &lt;pawn&gt;new BigArray[3][3]<br /> BigArray[0][0] = 10<br /> BigArray[0][1] = 20<br /> BigArray[0][2] = 30<br /> BigArray[1][0] = 40<br /> BigArray[1][1] = 50<br /> BigArray[1][2] = 60<br /> BigArray[2][0] = 70<br /> BigArray[2][1] = 80<br /> BigArray[2][2] = 90&lt;/pawn&gt;<br /> <br /> Will result in BigArray looking like this:<br /> :{|<br /> |-<br /> | BigArray<br /> | 0<br /> | 1<br /> | 2<br /> |-<br /> | 0<br /> | 10<br /> | 20<br /> | 30<br /> |-<br /> | 1<br /> | 40<br /> | 50<br /> | 60<br /> |-<br /> | 2<br /> | 70<br /> | 80<br /> | 90<br /> |}<br /> <br /> Note that our old sum_of_array() function can still work! We can do:<br /> <br /> &lt;pawn&gt;new sum = sum_of_array(BigArray[2], 3)&lt;/pawn&gt;<br /> <br /> Because BigArray[2] contains a second, single dimensional array, containing {7,8,9}. However, let's write a 2D sum of array function.<br /> <br /> &lt;pawn&gt;//This function will tally up a two dimensional array.<br /> sum_of_table(array[][], rows, cols)<br /> {<br /> new i, j, sum<br /> <br /> //Note, there is a loop inside the loop. <br /> //This lets you go through each array inside the <br /> // bigger array. <br /> for (i=0; i&lt;rows; i++)<br /> {<br /> for (j=0; j&lt;cols; j++)<br /> {<br /> sum += array[i][j]<br /> }<br /> }<br /> <br /> return sum<br /> }&lt;/pawn&gt;<br /> <br /> Note, it is also possible to store an array of strings using two dimensional arrays.<br /> <br /> &lt;pawn&gt;new StringList[3][] = {&quot;Hello&quot;, &quot;my&quot;, &quot;friend&quot;}<br /> /*<br /> StringList[0][0] through [0][5] contains &quot;Hello&quot;<br /> StringList[1][0] through [1][2] contains &quot;my&quot;<br /> StringList[2][0] through [2][6] contains &quot;friend&quot;<br /> */&lt;/pawn&gt;<br /> <br /> The table for StringList will look like:<br /> StringList 0 1 2 3 4 5 6<br /> 0 H e l l o \0 <br /> 1 m y \0 <br /> 2 f r i e n d \0<br /> <br /> Comparing strings in multidimensional arrays is also similar:<br /> <br /> &lt;pawn&gt;if (StringList[0] == &quot;Hello&quot;) //INVALID<br /> if (StringList[0][0] == &quot;Hello&quot;) //INVALID<br /> if (equali(StringList[0], &quot;Hello&quot;)) //Valid&lt;/pawn&gt;<br /> <br /> =Compiler Pre-processor Directives=<br /> <br /> Compiler directives allow you to change how your code is read. This is rather advanced and will only be run over briefly.<br /> <br /> &lt;pawn&gt;//To bind a symbol to a value, you can do this:<br /> #define SYMBOL VALUE<br /> //for example:<br /> <br /> #define MAX_STRING 250<br /> new String[MAX_STRING]<br /> <br /> #define HELLO &quot;Hello. This is a generic greeting.&quot;<br /> new Hello[MAX_STRING] = HELLO&lt;/pawn&gt;<br /> <br /> You can also use #defines to change the flow of code the compiler makes.<br /> &lt;pawn&gt;#if defined LINUX<br /> //This portion will be compiled if #define LINUX exists<br /> execute_command(&quot;ls -l&quot;)<br /> #else<br /> //This portion will be compiled if #define LINUX does not exist<br /> execute_command(&quot;dir&quot;)<br /> #endif&lt;/pawn&gt;<br /> <br /> You can also change how much memory your script uses.<br /> &lt;pawn&gt;#pragma dynamic 4096<br /> //This creates a 16K stack of memory (default).<br /> //It is measured in blocks of 4 byte cells.&lt;/pawn&gt;<br /> <br /> You can also specify whether semicolon usage is required to terminate a line of code (by default it is not required). <br /> &lt;pawn&gt;#pragma semicolon 1&lt;/pawn&gt;<br /> <br /> You can also change the control character( amxx std: '^' )<br /> &lt;pawn&gt;#pragma ctrlchar '\'<br /> //this sets the control character to backslash( c/c++/c#/java/... std )<br /> // now you have to use the \ instead of ^<br /> // e.g. &quot;this is ^&quot;:D^&quot; &quot; must be now &quot; this is \&quot;:D\&quot; &quot;&lt;/pawn&gt;<br /> <br /> =Conclusion=<br /> <br /> This guide should have given you a VERY brief introduction to basic Pawn programming. It is by no means comprehensive and it should not constitute the entirety of one's knowledge of Pawn. To read the official Pawn documentation and language guide, go this website: https://github.com/compuphase/pawn/blob/master/doc/Pawn_Language_Guide.pdf (Note, this guide is very long and should be used as a reference. You may want to try the Small forums or the AMX Mod X forums). Continue to the next Section to see how to apply Small programming to the Half-Life and AMX Mod X engine!<br /> <br /> =External Links=<br /> *[http://www.compuphase.com/pawn/Pawn_Language_Guide.pdf Pawn Language Reference]<br /> *[http://www.compuphase.com/pawn/pawn.htm Pawn Homepage]<br /> *[http://www.compuphase.com/ ITB CompuPhase]<br /> <br /> [[Category:Scripting (AMX Mod X)]]</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Commands_(SourceMod_Scripting)&diff=10614 2018-09-05T14:14:22Z

<p>Xerox8521: Replaced ServerCommand with KickClient</p> <hr /> <div>[[SourceMod]] allows you to create console commands similar to [[AMX Mod X]]. There are two main types of console commands:<br /> *'''Server Commands''' - Fired from one of the following input methods:<br /> **the server console itself<br /> **the remote console (RCON)<br /> **the ServerCommand() function, either from SourceMod or the [[Half-Life 2]] engine<br /> *'''Console Commands''' - Fired from one of the following input methods:<br /> **a client's console<br /> **any of the server command input methods<br /> <br /> For server commands, there is no client index. For console/client commands, there is a client index, but it may be 0 to indicate that the command is from the server.<br /> <br /> Note that button-bound &quot;commands,&quot; such as +attack and +duck, are not actually console commands. They are a separate command stream sent over the network, as they need to be tied to a specific frame. <br /> <br /> =Server Commands=<br /> As noted above, server commands are fired through the server console, whether remote, local, or through the Source engine. There is no client index associated with a server command. <br /> <br /> Server commands are registered through the &lt;tt&gt;RegServerCmd()&lt;/tt&gt; function defined in &lt;tt&gt;console.inc&lt;/tt&gt;. When registering a server command, you may be hooking an already existing command, and thus the return value is important.<br /> *&lt;b&gt;&lt;tt&gt;Plugin_Continue&lt;/tt&gt;&lt;/b&gt; - The original server command will be processed, if there was one. If the server command was created by a plugin, this has no effect.<br /> *&lt;b&gt;&lt;tt&gt;Plugin_Handled&lt;/tt&gt;&lt;/b&gt; - The original server command will not be processed, if there was one. If the server command was created by a plugin, this has no effect.<br /> *&lt;b&gt;&lt;tt&gt;Plugin_Stop&lt;/tt&gt;&lt;/b&gt; - The original server command will not be processed, if there was one. Additionally, no further hooks will be called for this command until it is fired again.<br /> <br /> ==Adding Server Commands==<br /> Let's say we want to add a test command to show how Half-Life 2 breaks down command arguments. A possible implementation might be<br /> &lt;pawn&gt;<br /> public void OnPluginStart()<br /> {<br /> RegServerCmd(&quot;test_command&quot;, Command_Test);<br /> }<br /> <br /> public Action Command_Test(int args)<br /> {<br /> char arg[128];<br /> char full[256];<br /> <br /> GetCmdArgString(full, sizeof(full));<br /> <br /> PrintToServer(&quot;Argument string: %s&quot;, full);<br /> PrintToServer(&quot;Argument count: %d&quot;, args);<br /> for (int i=1; i&lt;=args; i++)<br /> {<br /> GetCmdArg(i, arg, sizeof(arg));<br /> PrintToServer(&quot;Argument %d: %s&quot;, i, arg);<br /> }<br /> return Plugin_Handled;<br /> }<br /> &lt;/pawn&gt;<br /> <br /> ==Blocking Server Commands==<br /> Let's say we wanted to disable the &quot;kickid&quot; command on the server. There's no real good reason to do this, but for example's sake:<br /> &lt;pawn&gt;<br /> public void OnPluginStart()<br /> {<br /> RegServerCmd(&quot;kickid&quot;, Command_KickId);<br /> }<br /> <br /> public Action Command_Kickid(int args)<br /> {<br /> return Plugin_Handled;<br /> }<br /> &lt;/pawn&gt;<br /> <br /> =Console Commands=<br /> Unlike server commands, console commands can be triggered by either the server or the client, so the callback function receives a client index as well as the argument count. If the server fired the command, the client index will be 0. <br /> <br /> When returning the &lt;tt&gt;Action&lt;/tt&gt; from the callback, the following effects will happen:<br /> *&lt;tt&gt;Plugin_Continue&lt;/tt&gt;: The original functionality of the command (if any) will still be processed. If there was no original functionality, the client will receive &quot;Unknown command&quot; in their console.<br /> *&lt;tt&gt;Plugin_Handled&lt;/tt&gt;: The original functionality of the command (if any) will be blocked. If there was no functionality originally, this prevents clients from seeing &quot;Unknown command&quot; in their console.<br /> *&lt;tt&gt;Plugin_Stop&lt;/tt&gt;: Same as &lt;tt&gt;Plugin_Handled&lt;/tt&gt;, except that this will be the last hook called.<br /> *&lt;tt&gt;Plugin_Changed&lt;/tt&gt;: Inputs or outputs have been overridden with new values.<br /> <br /> Note that, unlike AMX Mod X, SourceMod does not allow you to register command filters. I.e., there is no equivalent to this notation:<br /> &lt;pawn&gt;register_clcmd(&quot;say /ff&quot;, &quot;Command_SayFF&quot;);&lt;/pawn&gt;<br /> <br /> This notation was removed to make our internal code simpler and faster. Writing the same functionality is easy, and demonstrated below.<br /> <br /> ==Adding Commands==<br /> Adding client commands is very simple. Let's port our earlier testing command to display information about the client as well.<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> RegConsoleCmd(&quot;test_command&quot;, Command_Test);<br /> }<br /> <br /> public Action Command_Test(int client, int args)<br /> {<br /> char arg[128];<br /> char full[256];<br /> <br /> GetCmdArgString(full, sizeof(full));<br /> <br /> if (client)<br /> {<br /> PrintToServer(&quot;Command from client: %N&quot;, name);<br /> } else {<br /> PrintToServer(&quot;Command from server.&quot;);<br /> }<br /> <br /> PrintToServer(&quot;Argument string: %s&quot;, full);<br /> PrintToServer(&quot;Argument count: %d&quot;, args);<br /> for (int i=1; i&lt;=args; i++)<br /> {<br /> GetCmdArg(i, arg, sizeof(arg));<br /> PrintToServer(&quot;Argument %d: %s&quot;, i, arg);<br /> }<br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> ==Hooking Commands==<br /> A common example is hooking the say command. Let's say we want to tell players whether FF is enabled when they say '/ff' in game. <br /> <br /> Before we implement this, a common point of confusion with the 'say' command is that Half-Life 2 (and Half-Life 1), by default, send it with the text in one big quoted string. This means if you say &quot;I like hot dogs,&quot; your command will be broken down as such:<br /> *Argument string: &quot;I like hot dogs&quot;<br /> *Argument count: 1<br /> *Argument #1: I like hot dogs<br /> <br /> However, if a player types this in their console: &lt;tt&gt;say I like yams&lt;/tt&gt;, it will be broken up as:<br /> *Argument string: I like yams<br /> *Argument count: 3<br /> *Argument #1: I<br /> *Argument #2: like<br /> *Argument #3: yams<br /> <br /> &lt;pawn&gt;ConVar ff = null;<br /> <br /> public void OnPluginStart()<br /> {<br /> ff = FindConVar(&quot;mp_friendlyfire&quot;);<br /> }<br /> <br /> public Action OnClientSayCommand(int client, const char[] command, const char[] sArgs)<br /> {<br /> if (strcmp(sArgs, &quot;ff&quot;, false) == 0)<br /> {<br /> if (ff != null)<br /> {<br /> if (ff.BoolValue)<br /> {<br /> PrintToChat(client, &quot;Friendly fire is enabled.&quot;);<br /> } <br /> else <br /> {<br /> PrintToChat(client, &quot;Friendly fire is disabled.&quot;);<br /> }<br /> /* Block the client's messsage from broadcasting */<br /> return Plugin_Handled;<br /> }<br /> }<br /> <br /> /* Let say continue normally */<br /> return Plugin_Continue;<br /> }&lt;/pawn&gt;<br /> <br /> Here we use the OnClientSayCommand forward where as &lt;tt&gt;command&lt;/tt&gt; contains the type (example: &lt;tt&gt;say&lt;/tt&gt; or &lt;tt&gt;say_team&lt;/tt&gt;) and &lt;tt&gt;sArgs&lt;/tt&gt; containing the users input<br /> <br /> ==Creating Admin Commands==<br /> Let's create a simple admin command which kicks another player by their full name. <br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> RegAdminCmd(&quot;admin_kick&quot;, Command_Kick, ADMFLAG_KICK, &quot;Kicks a player by name&quot;);<br /> }<br /> <br /> public Action Command_Kick(int client, int args)<br /> {<br /> if (args &lt; 1)<br /> {<br /> PrintToConsole(client, &quot;Usage: admin_kick &lt;name&gt;&quot;);<br /> return Plugin_Handled;<br /> }<br /> <br /> char name[32];<br /> int target = -1;<br /> GetCmdArg(1, name, sizeof(name));<br /> <br /> for (int i=1; i&lt;=MaxClients; i++)<br /> {<br /> if (!IsClientConnected(i))<br /> {<br /> continue;<br /> }<br /> char other[32];<br /> GetClientName(i, other, sizeof(other));<br /> if (StrEqual(name, other))<br /> {<br /> target = i;<br /> }<br /> }<br /> <br /> if (target == -1)<br /> {<br /> PrintToConsole(client, &quot;Could not find any player with the name: \&quot;%s\&quot;&quot;, name);<br /> return Plugin_Handled;<br /> }<br /> <br /> KickClient(target);<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> ==Immunity==<br /> In our previous example, we did not take immunity into account. Immunity is a much more complex system in SourceMod than it was in AMX Mod X, and there is no simple flag to denote its permissions. Instead, two functions are provided:<br /> *&lt;tt&gt;CanAdminTarget&lt;/tt&gt;: Tests raw AdminId values for immunity.<br /> *&lt;tt&gt;CanUserTarget&lt;/tt&gt;: Tests in-game clients for immunity.<br /> <br /> While immunity is generally tested ''player versus player'', it is possible you might want to check for immunity and not have a targetting client. While there is no convenience function for this yet, a good idea might be to check for either ''default'' or ''global'' immunity on the player's groups (these can be user-defined for non-player targeted scenarios).<br /> <br /> When checking for immunity, the following heuristics are performed in this exact order:<br /> &lt;ol&gt;&lt;li&gt;If the targeting AdminId is &lt;tt&gt;INVALID_ADMIN_ID&lt;/tt&gt;, targeting fails.&lt;/li&gt;<br /> &lt;li&gt;If the targetted AdminId is &lt;tt&gt;INVALID_ADMIN_ID&lt;/tt&gt;, targeting succeeds.&lt;/li&gt;<br /> &lt;li&gt;If the targeting admin has &lt;tt&gt;Admin_Root&lt;/tt&gt; (&lt;tt&gt;ADMFLAG_ROOT&lt;/tt&gt;), targeting succeeds.&lt;/li&gt;<br /> &lt;li&gt;If the targetted admin has global immunity, targeting fails.&lt;/li&gt;<br /> &lt;li&gt;If the targetted admin has default immunity, and the targeting admin belongs to no groups, targeting fails.&lt;/li&gt;<br /> &lt;li&gt;If the targetted admin has specific immunity from the targeting admin via group immunities, targeting fails.&lt;/li&gt;<br /> &lt;li&gt;If no conclusion is reached via the previous steps, targeting succeeds.&lt;/li&gt;<br /> &lt;/ol&gt;<br /> <br /> So, how can we adapt our function about to use immunity?<br /> <br /> &lt;pawn&gt;public Action Command_Kick(int client, int args)<br /> {<br /> if (args &lt; 1)<br /> {<br /> PrintToConsole(client, &quot;Usage: admin_kick &lt;name&gt;&quot;);<br /> return Plugin_Handled;<br /> }<br /> <br /> char name[32];<br /> int target = -1;<br /> GetCmdArg(1, name, sizeof(name));<br /> <br /> for (int i=1; i&lt;=MaxClients; i++)<br /> {<br /> if (!IsClientConnected(i))<br /> {<br /> continue;<br /> }<br /> char other[32];<br /> GetClientName(i, other, sizeof(other));<br /> if (StrEqual(name, other))<br /> {<br /> target = i;<br /> }<br /> }<br /> <br /> if (target == -1)<br /> {<br /> PrintToConsole(client, &quot;Could not find any player with the name: \&quot;%s\&quot;&quot;, name);<br /> return Plugin_Handled;<br /> }<br /> <br /> if (!CanUserTarget(client, target))<br /> {<br /> PrintToConsole(client, &quot;You cannot target this client.&quot;);<br /> return Plugin_Handled;<br /> }<br /> <br /> KickClient(target);<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> =Client-Only Commands=<br /> SourceMod exposes a forward that is called whenever a client executes any command string in their console, called &lt;tt&gt;OnClientCommand&lt;/tt&gt;. An example of this looks like:<br /> <br /> &lt;pawn&gt;public Action OnClientCommand(int client, int args)<br /> {<br /> char cmd[16];<br /> GetCmdArg(0, cmd, sizeof(cmd)); /* Get command name */<br /> <br /> if (StrEqual(cmd, &quot;test_command&quot;))<br /> {<br /> /* Got the client command! Block it... */<br /> return Plugin_Handled;<br /> }<br /> <br /> return Plugin_Continue;<br /> }&lt;/pawn&gt;<br /> <br /> It is worth noting that not everything a client sends will be available through this command. Command registered via external sources in C++ may not be available, especially if they are created via &lt;tt&gt;CON_COMMAND&lt;/tt&gt; in the game mod itself. For example, &quot;say&quot; is usually implemented this way, because it can be used by both clients and the server, and thus it does not channel through this forward.<br /> <br /> <br /> =Chat Triggers=<br /> SourceMod will automatically create chat triggers for every command you make. For example, if you create a console command called &lt;tt&gt;&quot;sm_megaslap&quot;&lt;/tt&gt;, administrators will be able to type any of the following commands in &lt;tt&gt;say&lt;/tt&gt;/&lt;tt&gt;say_team&lt;/tt&gt; message modes:<br /> &lt;pre&gt;!sm_megaslap<br /> !megaslap<br /> /sm_megaslap<br /> /megaslap&lt;/pre&gt;<br /> <br /> SourceMod then executes this command and its arguments as if it came from the client console.<br /> *&quot;&lt;tt&gt;!&lt;/tt&gt;&quot; is the default ''public'' trigger (&lt;tt&gt;PublicChatTrigger&lt;/tt&gt; in &lt;tt&gt;configs/core.cfg&lt;/tt&gt;) and your entry will be displayed to all clients as normal.<br /> *&quot;&lt;tt&gt;/&lt;/tt&gt;&quot; is the default ''silent'' trigger (&lt;tt&gt;SilentChatTrigger&lt;/tt&gt; in &lt;tt&gt;configs/core.cfg&lt;/tt&gt;) and your entry will be blocked from being displayed.<br /> <br /> SourceMod will only execute commands registered with &lt;tt&gt;RegConsoleCmd&lt;/tt&gt; or &lt;tt&gt;RegAdminCmd&lt;/tt&gt;, and only if those commands are not already provided by Half-Life 2 or the game mod. If the command is prefixed with &quot;sm_&quot; then the &quot;sm_&quot; can be omitted from the chat trigger.<br /> <br /> Console commands which wish to support usage as a chat trigger should not use &lt;tt&gt;PrintTo*&lt;/tt&gt; natives. Instead, they should use &lt;tt&gt;ReplyToCommand()&lt;/tt&gt;, which will automatically print your message either as a chat message or to the client's console, depending on the source of the command.<br /> <br /> [[Category:SourceMod Scripting]]<br /> <br /> {{LanguageSwitch}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Commands_(SourceMod_Scripting)&diff=10613 2018-09-05T14:13:38Z

<p>Xerox8521: Replaced ServerCommand with KickClient</p> <hr /> <div>[[SourceMod]] allows you to create console commands similar to [[AMX Mod X]]. There are two main types of console commands:<br /> *'''Server Commands''' - Fired from one of the following input methods:<br /> **the server console itself<br /> **the remote console (RCON)<br /> **the ServerCommand() function, either from SourceMod or the [[Half-Life 2]] engine<br /> *'''Console Commands''' - Fired from one of the following input methods:<br /> **a client's console<br /> **any of the server command input methods<br /> <br /> For server commands, there is no client index. For console/client commands, there is a client index, but it may be 0 to indicate that the command is from the server.<br /> <br /> Note that button-bound &quot;commands,&quot; such as +attack and +duck, are not actually console commands. They are a separate command stream sent over the network, as they need to be tied to a specific frame. <br /> <br /> =Server Commands=<br /> As noted above, server commands are fired through the server console, whether remote, local, or through the Source engine. There is no client index associated with a server command. <br /> <br /> Server commands are registered through the &lt;tt&gt;RegServerCmd()&lt;/tt&gt; function defined in &lt;tt&gt;console.inc&lt;/tt&gt;. When registering a server command, you may be hooking an already existing command, and thus the return value is important.<br /> *&lt;b&gt;&lt;tt&gt;Plugin_Continue&lt;/tt&gt;&lt;/b&gt; - The original server command will be processed, if there was one. If the server command was created by a plugin, this has no effect.<br /> *&lt;b&gt;&lt;tt&gt;Plugin_Handled&lt;/tt&gt;&lt;/b&gt; - The original server command will not be processed, if there was one. If the server command was created by a plugin, this has no effect.<br /> *&lt;b&gt;&lt;tt&gt;Plugin_Stop&lt;/tt&gt;&lt;/b&gt; - The original server command will not be processed, if there was one. Additionally, no further hooks will be called for this command until it is fired again.<br /> <br /> ==Adding Server Commands==<br /> Let's say we want to add a test command to show how Half-Life 2 breaks down command arguments. A possible implementation might be<br /> &lt;pawn&gt;<br /> public void OnPluginStart()<br /> {<br /> RegServerCmd(&quot;test_command&quot;, Command_Test);<br /> }<br /> <br /> public Action Command_Test(int args)<br /> {<br /> char arg[128];<br /> char full[256];<br /> <br /> GetCmdArgString(full, sizeof(full));<br /> <br /> PrintToServer(&quot;Argument string: %s&quot;, full);<br /> PrintToServer(&quot;Argument count: %d&quot;, args);<br /> for (int i=1; i&lt;=args; i++)<br /> {<br /> GetCmdArg(i, arg, sizeof(arg));<br /> PrintToServer(&quot;Argument %d: %s&quot;, i, arg);<br /> }<br /> return Plugin_Handled;<br /> }<br /> &lt;/pawn&gt;<br /> <br /> ==Blocking Server Commands==<br /> Let's say we wanted to disable the &quot;kickid&quot; command on the server. There's no real good reason to do this, but for example's sake:<br /> &lt;pawn&gt;<br /> public void OnPluginStart()<br /> {<br /> RegServerCmd(&quot;kickid&quot;, Command_KickId);<br /> }<br /> <br /> public Action Command_Kickid(int args)<br /> {<br /> return Plugin_Handled;<br /> }<br /> &lt;/pawn&gt;<br /> <br /> =Console Commands=<br /> Unlike server commands, console commands can be triggered by either the server or the client, so the callback function receives a client index as well as the argument count. If the server fired the command, the client index will be 0. <br /> <br /> When returning the &lt;tt&gt;Action&lt;/tt&gt; from the callback, the following effects will happen:<br /> *&lt;tt&gt;Plugin_Continue&lt;/tt&gt;: The original functionality of the command (if any) will still be processed. If there was no original functionality, the client will receive &quot;Unknown command&quot; in their console.<br /> *&lt;tt&gt;Plugin_Handled&lt;/tt&gt;: The original functionality of the command (if any) will be blocked. If there was no functionality originally, this prevents clients from seeing &quot;Unknown command&quot; in their console.<br /> *&lt;tt&gt;Plugin_Stop&lt;/tt&gt;: Same as &lt;tt&gt;Plugin_Handled&lt;/tt&gt;, except that this will be the last hook called.<br /> *&lt;tt&gt;Plugin_Changed&lt;/tt&gt;: Inputs or outputs have been overridden with new values.<br /> <br /> Note that, unlike AMX Mod X, SourceMod does not allow you to register command filters. I.e., there is no equivalent to this notation:<br /> &lt;pawn&gt;register_clcmd(&quot;say /ff&quot;, &quot;Command_SayFF&quot;);&lt;/pawn&gt;<br /> <br /> This notation was removed to make our internal code simpler and faster. Writing the same functionality is easy, and demonstrated below.<br /> <br /> ==Adding Commands==<br /> Adding client commands is very simple. Let's port our earlier testing command to display information about the client as well.<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> RegConsoleCmd(&quot;test_command&quot;, Command_Test);<br /> }<br /> <br /> public Action Command_Test(int client, int args)<br /> {<br /> char arg[128];<br /> char full[256];<br /> <br /> GetCmdArgString(full, sizeof(full));<br /> <br /> if (client)<br /> {<br /> PrintToServer(&quot;Command from client: %N&quot;, name);<br /> } else {<br /> PrintToServer(&quot;Command from server.&quot;);<br /> }<br /> <br /> PrintToServer(&quot;Argument string: %s&quot;, full);<br /> PrintToServer(&quot;Argument count: %d&quot;, args);<br /> for (int i=1; i&lt;=args; i++)<br /> {<br /> GetCmdArg(i, arg, sizeof(arg));<br /> PrintToServer(&quot;Argument %d: %s&quot;, i, arg);<br /> }<br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> ==Hooking Commands==<br /> A common example is hooking the say command. Let's say we want to tell players whether FF is enabled when they say '/ff' in game. <br /> <br /> Before we implement this, a common point of confusion with the 'say' command is that Half-Life 2 (and Half-Life 1), by default, send it with the text in one big quoted string. This means if you say &quot;I like hot dogs,&quot; your command will be broken down as such:<br /> *Argument string: &quot;I like hot dogs&quot;<br /> *Argument count: 1<br /> *Argument #1: I like hot dogs<br /> <br /> However, if a player types this in their console: &lt;tt&gt;say I like yams&lt;/tt&gt;, it will be broken up as:<br /> *Argument string: I like yams<br /> *Argument count: 3<br /> *Argument #1: I<br /> *Argument #2: like<br /> *Argument #3: yams<br /> <br /> &lt;pawn&gt;ConVar ff = null;<br /> <br /> public void OnPluginStart()<br /> {<br /> ff = FindConVar(&quot;mp_friendlyfire&quot;);<br /> }<br /> <br /> public Action OnClientSayCommand(int client, const char[] command, const char[] sArgs)<br /> {<br /> if (strcmp(sArgs, &quot;ff&quot;, false) == 0)<br /> {<br /> if (ff != null)<br /> {<br /> if (ff.BoolValue)<br /> {<br /> PrintToChat(client, &quot;Friendly fire is enabled.&quot;);<br /> } <br /> else <br /> {<br /> PrintToChat(client, &quot;Friendly fire is disabled.&quot;);<br /> }<br /> /* Block the client's messsage from broadcasting */<br /> return Plugin_Handled;<br /> }<br /> }<br /> <br /> /* Let say continue normally */<br /> return Plugin_Continue;<br /> }&lt;/pawn&gt;<br /> <br /> Here we use the OnClientSayCommand forward where as &lt;tt&gt;command&lt;/tt&gt; contains the type (example: &lt;tt&gt;say&lt;/tt&gt; or &lt;tt&gt;say_team&lt;/tt&gt;) and &lt;tt&gt;sArgs&lt;/tt&gt; containing the users input<br /> <br /> ==Creating Admin Commands==<br /> Let's create a simple admin command which kicks another player by their full name. <br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> RegAdminCmd(&quot;admin_kick&quot;, Command_Kick, ADMFLAG_KICK, &quot;Kicks a player by name&quot;);<br /> }<br /> <br /> public Action Command_Kick(int client, int args)<br /> {<br /> if (args &lt; 1)<br /> {<br /> PrintToConsole(client, &quot;Usage: admin_kick &lt;name&gt;&quot;);<br /> return Plugin_Handled;<br /> }<br /> <br /> char name[32];<br /> int target = -1;<br /> GetCmdArg(1, name, sizeof(name));<br /> <br /> for (int i=1; i&lt;=MaxClients; i++)<br /> {<br /> if (!IsClientConnected(i))<br /> {<br /> continue;<br /> }<br /> char other[32];<br /> GetClientName(i, other, sizeof(other));<br /> if (StrEqual(name, other))<br /> {<br /> target = i;<br /> }<br /> }<br /> <br /> if (target == -1)<br /> {<br /> PrintToConsole(client, &quot;Could not find any player with the name: \&quot;%s\&quot;&quot;, name);<br /> return Plugin_Handled;<br /> }<br /> <br /> KickClient(target);<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> ==Immunity==<br /> In our previous example, we did not take immunity into account. Immunity is a much more complex system in SourceMod than it was in AMX Mod X, and there is no simple flag to denote its permissions. Instead, two functions are provided:<br /> *&lt;tt&gt;CanAdminTarget&lt;/tt&gt;: Tests raw AdminId values for immunity.<br /> *&lt;tt&gt;CanUserTarget&lt;/tt&gt;: Tests in-game clients for immunity.<br /> <br /> While immunity is generally tested ''player versus player'', it is possible you might want to check for immunity and not have a targetting client. While there is no convenience function for this yet, a good idea might be to check for either ''default'' or ''global'' immunity on the player's groups (these can be user-defined for non-player targeted scenarios).<br /> <br /> When checking for immunity, the following heuristics are performed in this exact order:<br /> &lt;ol&gt;&lt;li&gt;If the targeting AdminId is &lt;tt&gt;INVALID_ADMIN_ID&lt;/tt&gt;, targeting fails.&lt;/li&gt;<br /> &lt;li&gt;If the targetted AdminId is &lt;tt&gt;INVALID_ADMIN_ID&lt;/tt&gt;, targeting succeeds.&lt;/li&gt;<br /> &lt;li&gt;If the targeting admin has &lt;tt&gt;Admin_Root&lt;/tt&gt; (&lt;tt&gt;ADMFLAG_ROOT&lt;/tt&gt;), targeting succeeds.&lt;/li&gt;<br /> &lt;li&gt;If the targetted admin has global immunity, targeting fails.&lt;/li&gt;<br /> &lt;li&gt;If the targetted admin has default immunity, and the targeting admin belongs to no groups, targeting fails.&lt;/li&gt;<br /> &lt;li&gt;If the targetted admin has specific immunity from the targeting admin via group immunities, targeting fails.&lt;/li&gt;<br /> &lt;li&gt;If no conclusion is reached via the previous steps, targeting succeeds.&lt;/li&gt;<br /> &lt;/ol&gt;<br /> <br /> So, how can we adapt our function about to use immunity?<br /> <br /> &lt;pawn&gt;public Action Command_Kick(int client, int args)<br /> {<br /> if (args &lt; 1)<br /> {<br /> PrintToConsole(client, &quot;Usage: admin_kick &lt;name&gt;&quot;);<br /> return Plugin_Handled;<br /> }<br /> <br /> char name[32];<br /> int target = -1;<br /> GetCmdArg(1, name, sizeof(name));<br /> <br /> for (int i=1; i&lt;=MaxClients; i++)<br /> {<br /> if (!IsClientConnected(i))<br /> {<br /> continue;<br /> }<br /> char other[32];<br /> GetClientName(i, other, sizeof(other));<br /> if (StrEqual(name, other))<br /> {<br /> target = i;<br /> }<br /> }<br /> <br /> if (target == -1)<br /> {<br /> PrintToConsole(client, &quot;Could not find any player with the name: \&quot;%s\&quot;&quot;, name);<br /> return Plugin_Handled;<br /> }<br /> <br /> if (!CanUserTarget(client, target))<br /> {<br /> PrintToConsole(client, &quot;You cannot target this client.&quot;);<br /> return Plugin_Handled;<br /> }<br /> <br /> ServerCommand(&quot;kickid %d&quot;, GetClientUserId(target));<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> =Client-Only Commands=<br /> SourceMod exposes a forward that is called whenever a client executes any command string in their console, called &lt;tt&gt;OnClientCommand&lt;/tt&gt;. An example of this looks like:<br /> <br /> &lt;pawn&gt;public Action OnClientCommand(int client, int args)<br /> {<br /> char cmd[16];<br /> GetCmdArg(0, cmd, sizeof(cmd)); /* Get command name */<br /> <br /> if (StrEqual(cmd, &quot;test_command&quot;))<br /> {<br /> /* Got the client command! Block it... */<br /> return Plugin_Handled;<br /> }<br /> <br /> return Plugin_Continue;<br /> }&lt;/pawn&gt;<br /> <br /> It is worth noting that not everything a client sends will be available through this command. Command registered via external sources in C++ may not be available, especially if they are created via &lt;tt&gt;CON_COMMAND&lt;/tt&gt; in the game mod itself. For example, &quot;say&quot; is usually implemented this way, because it can be used by both clients and the server, and thus it does not channel through this forward.<br /> <br /> <br /> =Chat Triggers=<br /> SourceMod will automatically create chat triggers for every command you make. For example, if you create a console command called &lt;tt&gt;&quot;sm_megaslap&quot;&lt;/tt&gt;, administrators will be able to type any of the following commands in &lt;tt&gt;say&lt;/tt&gt;/&lt;tt&gt;say_team&lt;/tt&gt; message modes:<br /> &lt;pre&gt;!sm_megaslap<br /> !megaslap<br /> /sm_megaslap<br /> /megaslap&lt;/pre&gt;<br /> <br /> SourceMod then executes this command and its arguments as if it came from the client console.<br /> *&quot;&lt;tt&gt;!&lt;/tt&gt;&quot; is the default ''public'' trigger (&lt;tt&gt;PublicChatTrigger&lt;/tt&gt; in &lt;tt&gt;configs/core.cfg&lt;/tt&gt;) and your entry will be displayed to all clients as normal.<br /> *&quot;&lt;tt&gt;/&lt;/tt&gt;&quot; is the default ''silent'' trigger (&lt;tt&gt;SilentChatTrigger&lt;/tt&gt; in &lt;tt&gt;configs/core.cfg&lt;/tt&gt;) and your entry will be blocked from being displayed.<br /> <br /> SourceMod will only execute commands registered with &lt;tt&gt;RegConsoleCmd&lt;/tt&gt; or &lt;tt&gt;RegAdminCmd&lt;/tt&gt;, and only if those commands are not already provided by Half-Life 2 or the game mod. If the command is prefixed with &quot;sm_&quot; then the &quot;sm_&quot; can be omitted from the chat trigger.<br /> <br /> Console commands which wish to support usage as a chat trigger should not use &lt;tt&gt;PrintTo*&lt;/tt&gt; natives. Instead, they should use &lt;tt&gt;ReplyToCommand()&lt;/tt&gt;, which will automatically print your message either as a chat message or to the client's console, depending on the source of the command.<br /> <br /> [[Category:SourceMod Scripting]]<br /> <br /> {{LanguageSwitch}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Zombie_Panic!_Source_Events&diff=10535 2018-05-14T15:46:59Z

<p>Xerox8521: /* discord_callstatusupdate */</p> <hr /> <div>:''Refer back to [[Game Events (Source)]] for more events.''<br /> === player_death ===<br /> {{qnotice|When a player dies}}&lt;br&gt;<br /> {{begin-hl2msg|player_death|string}}<br /> {{hl2msg|short|userid|player who died}}<br /> {{hl2msg|short|attacker|player who killed}}<br /> {{hl2msg|short|assistant|player who assisted the attacker}}<br /> {{hl2msg|string|weapon|name of the weapon}}<br /> {{hl2msg|bool|headshot|true if player died from headshot}}<br /> {{hl2msg|short|dmgbits|damage type}}<br /> {{end-hl2msg}}<br /> <br /> === player_connected ===<br /> {{qnotice|When a player joins the server}}&lt;br&gt;<br /> {{begin-hl2msg|player_connected|string}}<br /> {{hl2msg|string|name|name of the player that connected}}<br /> {{end-hl2msg}}<br /> <br /> === player_disconnected ===<br /> {{qnotice|When a player leaves the server}}&lt;br&gt;<br /> {{begin-hl2msg|player_disconnected|string}}<br /> {{hl2msg|string|name|name of the player that left}}<br /> {{hl2msg|short|flag}}<br /> {{hl2msg|string|reason|reason why the player left}}<br /> {{end-hl2msg}}<br /> <br /> === map_change ===<br /> {{qnotice|Called when the map changes}}&lt;br&gt;<br /> {{begin-hl2msg|map_change|string}}<br /> {{hl2msg|string|map|name of the map that is being switched to}}<br /> {{end-hl2msg}}<br /> <br /> === zombie_lives ===<br /> {{qnotice|Called when the zombie lives changes}}&lt;br&gt;<br /> {{begin-hl2msg|zombie_lives|string}}<br /> {{hl2msg|byte|count|amount of zombie lives left}}<br /> {{end-hl2msg}}<br /> <br /> === ambient_play ===<br /> {{qnotice|Called when a sound plays}}&lt;br&gt;<br /> {{begin-hl2msg|ambient_play|string}}<br /> {{hl2msg|string|sound|sound file which played}}<br /> {{hl2msg|short|entity|entity which the sound plays from}}<br /> {{hl2msg|bool|fade|should the sound fade}}<br /> {{end-hl2msg}}<br /> <br /> === force_song ===<br /> {{qnotice|Called when the logic_music entity changes the song}}&lt;br&gt;<br /> {{begin-hl2msg|force_song_play|string}}<br /> {{hl2msg|string|song|file path for the song}}<br /> {{hl2msg|string|title|custom song title}}<br /> {{end-hl2msg}}<br /> <br /> === ambient_as ===<br /> {{qnotice|Called when a sound is played from AngelScript}}&lt;br&gt;<br /> {{begin-hl2msg|ambient_as|string}}<br /> {{hl2msg|string|sound|sound being played}}<br /> {{end-hl2msg}}<br /> <br /> === armmodel_as ===<br /> {{qnotice|Called when a new arm model is set from AngelScript}}&lt;br&gt;<br /> {{begin-hl2msg|armmodel_as|string}}<br /> {{hl2msg|string|model|arm model that should be used}}<br /> {{end-hl2msg}}<br /> <br /> === spawned_player ===<br /> {{qnotice|Called when player has spawned}}&lt;br&gt;<br /> {{begin-hl2msg|spawned_player|string}}<br /> {{hl2msg|string|name|name of the player that spawned}}<br /> {{end-hl2msg}}<br /> <br /> === discord_callstatusupdate ===<br /> {{qnotice|Send an Update to Discord RPC}}&lt;br&gt;<br /> {{begin-hl2msg|discord_callstatusupdate|string}}<br /> {{hl2msg|short|clientid}}<br /> {{hl2msg|string|hostname|Server Hostname}}<br /> {{hl2msg|string|serverip|Server IP}}<br /> {{hl2msg|string|serverport|Server Port}}<br /> {{hl2msg|string|model|Current Model of the client}}<br /> {{end-hl2msg}}<br /> <br /> === angelscript_callevent===<br /> {{qnotice|When the AS calls the function CallEvent()}}&lt;br&gt;<br /> {{begin-hl2msg|angelscript_callevent|string}}<br /> {{hl2msg|short|clientid}}<br /> {{hl2msg|short|typeid}}<br /> {{hl2msg|string|msg}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === cleanupmap ===<br /> {{qnotice|when the server calls CleanUpMap(), it will tell the client todo the same for temp and client sided entities}}&lt;br&gt;<br /> {{begin-hl2msg|cleanupmap|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === round_begins===<br /> {{qnotice|When the round begins}}&lt;br&gt;<br /> {{begin-hl2msg|round_begins|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === round_win===<br /> {{qnotice|When the round ends}}&lt;br&gt;<br /> {{begin-hl2msg|round_win|string}}<br /> {{hl2msg|string|mapname|name of the current map}}<br /> {{hl2msg|bool|humanwin|true if survivors won}}<br /> {{end-hl2msg}}<br /> <br /> === game_round_restart ===<br /> {{qnotice|When one team won the round and players can select their team again}}&lt;br&gt;<br /> {{begin-hl2msg|game_round_restart|string}}<br /> {{hl2msg|none|none}}<br /> {{end-hl2msg}}<br /> <br /> === gravity_change ===<br /> {{qnotice|When the gravity changes}}&lt;br&gt;<br /> {{begin-hl2msg|gravity_change|string}}<br /> {{hl2msg|float|newgravity|New value after the change}}<br /> {{end-hl2msg}}<br /> <br /> === achievement_earned ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|achievement_earned|string}}<br /> {{hl2msg|short|userid|player who earned the achievement}}<br /> {{hl2msg|string|achid|achievement id}}<br /> {{hl2msg|string|achtitle|title of the achievement}}<br /> {{end-hl2msg}}<br /> <br /> === spec_target_updated ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|spec_target_updated|string}}<br /> {{hl2msg|none|none}}<br /> {{end-hl2msg}}<br /> <br /> === zp_washuman ===<br /> {{qnotice|The player was a human player before we turned into zombie team (Only applies if there is no zombie lives left, or if the zombies won)}}&lt;br&gt;<br /> {{begin-hl2msg|zp_washuman|string}}<br /> {{hl2msg|short|userid|player that turned into a zombie}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === zp_infected ===<br /> {{qnotice|Calls whenever someone got infected}}&lt;br&gt;<br /> {{begin-hl2msg|zp_infected|string}}<br /> {{hl2msg|short|userid|player that got infected}}<br /> {{end-hl2msg}}<br /> <br /> === zp_entitypickedup ===<br /> {{qnotice|Calls whenever a button is pressed, or if an item is picked up}}&lt;br&gt;<br /> {{begin-hl2msg|zp_entitypickedup|string}}<br /> {{hl2msg|string|entkey|name of the button that is pressed or entity that is picked up}}<br /> {{end-hl2msg}}<br /> <br /> === general_hint ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|general_hint|string}}<br /> {{hl2msg|short|userid|the player who activated it}}<br /> {{end-hl2msg}}<br /> <br /> === movement_hint ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|movement_hint|string}}<br /> {{hl2msg|short|userid|the player who needs the hint}}<br /> {{end-hl2msg}}<br /> <br /> === movement_hint_success ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|movement_hint_success|string}}<br /> {{hl2msg|short|userid|the player succeeded}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === gameinstructor_draw ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|gameinstructor_draw|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === gameinstructor_nodraw ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|gameinstructor_nodraw|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === set_instructor_group_enabled ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|set_instructor_group_enabled|string}}<br /> {{hl2msg|string|group}}<br /> {{hl2msg|short|enabled}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_tutor ===<br /> {{qnotice|Called from the instructor tutorial}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_tutor|string}}<br /> {{hl2msg|long|userid}}<br /> {{hl2msg|long|entindex}}<br /> {{hl2msg|string|strbind}}<br /> {{hl2msg|string|strmsg}}<br /> {{hl2msg|string|icon_onscreen}}<br /> {{hl2msg|string|icon_offscreen}}<br /> {{hl2msg|bool|nooffscreen}}<br /> {{hl2msg|int|posx}}<br /> {{hl2msg|int|posy}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_server_hint_create ===<br /> {{qnotice|create a hint using data supplied entirely by the server/map. Intended for hints to smooth playtests before content is ready to make the hint unneccessary. NOT INTENDED AS A SHIPPABLE CRUTCH}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_server_hint_create|string}}<br /> {{hl2msg|string|hint_name|what to name the hint. For referencing it again later (e.g. a kill command for the hint instead of a timeout)}}<br /> {{hl2msg|string|hint_replace_key|type name so that messages of the same type will replace each other}}<br /> {{hl2msg|long|hint_target|entity id that the hint should display at}}<br /> {{hl2msg|long|hint_instance|the hint instance}}<br /> {{hl2msg|short|hint_activator_userid|userid id of the activator}}<br /> {{hl2msg|short|hint_timeout|how long in seconds until the hint automatically times out, 0 means never}}<br /> {{hl2msg|string|hint_icon_onscreen|the hint icon to use when the hint is onscreen. e.g. &quot;icon_alert_red&quot;}}<br /> {{hl2msg|string|hint_icon_offscreen|the hint icon to use when the hint is offscreen. e.g. &quot;icon_alert&quot;}}<br /> {{hl2msg|string|hint_caption|the hint caption. e.g. &quot;#ThisIsDangerous&quot;}}<br /> {{hl2msg|string|hint_activator_caption|the hint caption that only the activator sees e.g. &quot;#YouPushedItGood&quot;}}<br /> {{hl2msg|string|hint_color|the hint color in &quot;r,g,b&quot; format where each component is 0-255}}<br /> {{hl2msg|float|hint_icon_offset|how far on the z axis to offset the hint from entity origin}}<br /> {{hl2msg|float|hint_range|range before the hint is culled}}<br /> {{hl2msg|long|hint_flags|hint flags}}<br /> {{hl2msg|string|hint_binding|bindings to use when use_binding is the onscreen icon}}<br /> {{hl2msg|bool|hint_allow_nodraw_target|if false, the hint will dissappear if the target entity is invisible}}<br /> {{hl2msg|bool|hint_nooffscreen|if true, the hint will not show when outside the player view}}<br /> {{hl2msg|bool|hint_forcecaption|if true, the hint caption will show even if the hint is occluded}}<br /> {{hl2msg|bool|hint_local_player_only|if true, only the local player will see the hint}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_server_hint_stop ===<br /> {{qnotice|destroys a server/map created hint}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_server_hint_stop|string}}<br /> {{hl2msg|string|hint_name|The hint to stop. Will stop ALL hints with this name}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_survivor_supply ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_survivor_supply|string}}<br /> {{hl2msg|long|hint_player|entity id that the hint will display for}}<br /> {{hl2msg|long|hint_target|entity id that the hint should display at}}<br /> {{hl2msg|string|hint_caption|the hint caption. e.g. &quot;#ThisIsDangerous&quot;}}<br /> {{end-hl2msg}}<br /> <br /> === logicrounds_start ===<br /> {{qnotice|Called when the round has started (from logic_rounds)}}&lt;br&gt;<br /> {{begin-hl2msg|logicrounds_start|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === logicrounds_end ===<br /> {{qnotice|Called when the round ends (from logic_rounds)}}&lt;br&gt;<br /> {{begin-hl2msg|logicrounds_end|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === set_text ===<br /> {{qnotice|Called when AS sets the win text}}&lt;br&gt;<br /> {{begin-hl2msg|set_text|string}}<br /> {{hl2msg|string|txt}}<br /> {{end-hl2msg}}<br /> <br /> === vote_ended ===<br /> {{qnotice|Called when a vote has ended}}&lt;br&gt;<br /> {{begin-hl2msg|vote_ended|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === vote_generic_created ===<br /> {{qnotice|Called when a generic vote has been created}}&lt;br&gt;<br /> {{begin-hl2msg|vote_generic_created|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === vote_generic_clr ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|vote_generic_clr|string}}<br /> {{hl2msg|string|option}}<br /> {{hl2msg|long|red}}<br /> {{hl2msg|long|green}}<br /> {{hl2msg|long|blue}}<br /> {{end-hl2msg}}<br /> <br /> === vote_started ===<br /> {{qnotice|Called when a vote started}}&lt;br&gt;<br /> {{begin-hl2msg|vote_started|string}}<br /> {{hl2msg|string|issue}}<br /> {{hl2msg|string|param1}}<br /> {{hl2msg|byte|team}}<br /> {{hl2msg|long|initiator|entity id of the player who initiated the vote}}<br /> {{end-hl2msg}}<br /> <br /> === vote_changed ===<br /> {{qnotice|Called when a vote changed}}&lt;br&gt;<br /> {{begin-hl2msg|vote_changed|string}}<br /> {{hl2msg|byte|vote_option1}}<br /> {{hl2msg|byte|vote_option2}}<br /> {{hl2msg|byte|vote_option3}}<br /> {{hl2msg|byte|vote_option4}}<br /> {{hl2msg|byte|vote_option5}}<br /> {{hl2msg|byte|yesVotes}}<br /> {{hl2msg|byte|noVotes}}<br /> {{hl2msg|byte|potentialVotes}}<br /> {{end-hl2msg}}<br /> <br /> === vote_passed ===<br /> {{qnotice|Called when a vote passed}}&lt;br&gt;<br /> {{begin-hl2msg|vote_passed|string}}<br /> {{hl2msg|string|details}}<br /> {{hl2msg|string|param1}}<br /> {{hl2msg|byte|team}}<br /> {{end-hl2msg}}<br /> <br /> === vote_failed ===<br /> {{qnotice|Called when a vote failed}}&lt;br&gt;<br /> {{begin-hl2msg|vote_passed|string}}<br /> {{hl2msg|byte|team}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === vote_cast ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|vote_cast|string}}<br /> {{hl2msg|byte|vote|yes/no vote}}<br /> {{hl2msg|byte|team}}<br /> {{hl2msg|long|entityid|entity id of the voter}}<br /> {{end-hl2msg}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Zombie_Panic!_Source_Events&diff=10534 2018-05-14T15:44:55Z

<p>Xerox8521: Added discord_callstatusupdate and fixed angelscript_callevent params</p> <hr /> <div>:''Refer back to [[Game Events (Source)]] for more events.''<br /> === player_death ===<br /> {{qnotice|When a player dies}}&lt;br&gt;<br /> {{begin-hl2msg|player_death|string}}<br /> {{hl2msg|short|userid|player who died}}<br /> {{hl2msg|short|attacker|player who killed}}<br /> {{hl2msg|short|assistant|player who assisted the attacker}}<br /> {{hl2msg|string|weapon|name of the weapon}}<br /> {{hl2msg|bool|headshot|true if player died from headshot}}<br /> {{hl2msg|short|dmgbits|damage type}}<br /> {{end-hl2msg}}<br /> <br /> === player_connected ===<br /> {{qnotice|When a player joins the server}}&lt;br&gt;<br /> {{begin-hl2msg|player_connected|string}}<br /> {{hl2msg|string|name|name of the player that connected}}<br /> {{end-hl2msg}}<br /> <br /> === player_disconnected ===<br /> {{qnotice|When a player leaves the server}}&lt;br&gt;<br /> {{begin-hl2msg|player_disconnected|string}}<br /> {{hl2msg|string|name|name of the player that left}}<br /> {{hl2msg|short|flag}}<br /> {{hl2msg|string|reason|reason why the player left}}<br /> {{end-hl2msg}}<br /> <br /> === map_change ===<br /> {{qnotice|Called when the map changes}}&lt;br&gt;<br /> {{begin-hl2msg|map_change|string}}<br /> {{hl2msg|string|map|name of the map that is being switched to}}<br /> {{end-hl2msg}}<br /> <br /> === zombie_lives ===<br /> {{qnotice|Called when the zombie lives changes}}&lt;br&gt;<br /> {{begin-hl2msg|zombie_lives|string}}<br /> {{hl2msg|byte|count|amount of zombie lives left}}<br /> {{end-hl2msg}}<br /> <br /> === ambient_play ===<br /> {{qnotice|Called when a sound plays}}&lt;br&gt;<br /> {{begin-hl2msg|ambient_play|string}}<br /> {{hl2msg|string|sound|sound file which played}}<br /> {{hl2msg|short|entity|entity which the sound plays from}}<br /> {{hl2msg|bool|fade|should the sound fade}}<br /> {{end-hl2msg}}<br /> <br /> === force_song ===<br /> {{qnotice|Called when the logic_music entity changes the song}}&lt;br&gt;<br /> {{begin-hl2msg|force_song_play|string}}<br /> {{hl2msg|string|song|file path for the song}}<br /> {{hl2msg|string|title|custom song title}}<br /> {{end-hl2msg}}<br /> <br /> === ambient_as ===<br /> {{qnotice|Called when a sound is played from AngelScript}}&lt;br&gt;<br /> {{begin-hl2msg|ambient_as|string}}<br /> {{hl2msg|string|sound|sound being played}}<br /> {{end-hl2msg}}<br /> <br /> === armmodel_as ===<br /> {{qnotice|Called when a new arm model is set from AngelScript}}&lt;br&gt;<br /> {{begin-hl2msg|armmodel_as|string}}<br /> {{hl2msg|string|model|arm model that should be used}}<br /> {{end-hl2msg}}<br /> <br /> === spawned_player ===<br /> {{qnotice|Called when player has spawned}}&lt;br&gt;<br /> {{begin-hl2msg|spawned_player|string}}<br /> {{hl2msg|string|name|name of the player that spawned}}<br /> {{end-hl2msg}}<br /> <br /> === discord_callstatusupdate ===<br /> {{qnotice|Send an Update to Discord RPC}}&lt;br&gt;<br /> {{begin-hl2msg|discord_callstatusupdate|string}}<br /> {{hl2msg|short|clientid}}<br /> {{hl2msg|string|hostname}}<br /> {{hl2msg|string|serverip}}<br /> {{hl2msg|string|serverport}}<br /> {{hl2msg|string|model}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === angelscript_callevent===<br /> {{qnotice|When the AS calls the function CallEvent()}}&lt;br&gt;<br /> {{begin-hl2msg|angelscript_callevent|string}}<br /> {{hl2msg|short|clientid}}<br /> {{hl2msg|short|typeid}}<br /> {{hl2msg|string|msg}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === cleanupmap ===<br /> {{qnotice|when the server calls CleanUpMap(), it will tell the client todo the same for temp and client sided entities}}&lt;br&gt;<br /> {{begin-hl2msg|cleanupmap|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === round_begins===<br /> {{qnotice|When the round begins}}&lt;br&gt;<br /> {{begin-hl2msg|round_begins|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === round_win===<br /> {{qnotice|When the round ends}}&lt;br&gt;<br /> {{begin-hl2msg|round_win|string}}<br /> {{hl2msg|string|mapname|name of the current map}}<br /> {{hl2msg|bool|humanwin|true if survivors won}}<br /> {{end-hl2msg}}<br /> <br /> === game_round_restart ===<br /> {{qnotice|When one team won the round and players can select their team again}}&lt;br&gt;<br /> {{begin-hl2msg|game_round_restart|string}}<br /> {{hl2msg|none|none}}<br /> {{end-hl2msg}}<br /> <br /> === gravity_change ===<br /> {{qnotice|When the gravity changes}}&lt;br&gt;<br /> {{begin-hl2msg|gravity_change|string}}<br /> {{hl2msg|float|newgravity|New value after the change}}<br /> {{end-hl2msg}}<br /> <br /> === achievement_earned ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|achievement_earned|string}}<br /> {{hl2msg|short|userid|player who earned the achievement}}<br /> {{hl2msg|string|achid|achievement id}}<br /> {{hl2msg|string|achtitle|title of the achievement}}<br /> {{end-hl2msg}}<br /> <br /> === spec_target_updated ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|spec_target_updated|string}}<br /> {{hl2msg|none|none}}<br /> {{end-hl2msg}}<br /> <br /> === zp_washuman ===<br /> {{qnotice|The player was a human player before we turned into zombie team (Only applies if there is no zombie lives left, or if the zombies won)}}&lt;br&gt;<br /> {{begin-hl2msg|zp_washuman|string}}<br /> {{hl2msg|short|userid|player that turned into a zombie}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === zp_infected ===<br /> {{qnotice|Calls whenever someone got infected}}&lt;br&gt;<br /> {{begin-hl2msg|zp_infected|string}}<br /> {{hl2msg|short|userid|player that got infected}}<br /> {{end-hl2msg}}<br /> <br /> === zp_entitypickedup ===<br /> {{qnotice|Calls whenever a button is pressed, or if an item is picked up}}&lt;br&gt;<br /> {{begin-hl2msg|zp_entitypickedup|string}}<br /> {{hl2msg|string|entkey|name of the button that is pressed or entity that is picked up}}<br /> {{end-hl2msg}}<br /> <br /> === general_hint ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|general_hint|string}}<br /> {{hl2msg|short|userid|the player who activated it}}<br /> {{end-hl2msg}}<br /> <br /> === movement_hint ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|movement_hint|string}}<br /> {{hl2msg|short|userid|the player who needs the hint}}<br /> {{end-hl2msg}}<br /> <br /> === movement_hint_success ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|movement_hint_success|string}}<br /> {{hl2msg|short|userid|the player succeeded}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === gameinstructor_draw ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|gameinstructor_draw|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === gameinstructor_nodraw ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|gameinstructor_nodraw|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === set_instructor_group_enabled ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|set_instructor_group_enabled|string}}<br /> {{hl2msg|string|group}}<br /> {{hl2msg|short|enabled}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_tutor ===<br /> {{qnotice|Called from the instructor tutorial}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_tutor|string}}<br /> {{hl2msg|long|userid}}<br /> {{hl2msg|long|entindex}}<br /> {{hl2msg|string|strbind}}<br /> {{hl2msg|string|strmsg}}<br /> {{hl2msg|string|icon_onscreen}}<br /> {{hl2msg|string|icon_offscreen}}<br /> {{hl2msg|bool|nooffscreen}}<br /> {{hl2msg|int|posx}}<br /> {{hl2msg|int|posy}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_server_hint_create ===<br /> {{qnotice|create a hint using data supplied entirely by the server/map. Intended for hints to smooth playtests before content is ready to make the hint unneccessary. NOT INTENDED AS A SHIPPABLE CRUTCH}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_server_hint_create|string}}<br /> {{hl2msg|string|hint_name|what to name the hint. For referencing it again later (e.g. a kill command for the hint instead of a timeout)}}<br /> {{hl2msg|string|hint_replace_key|type name so that messages of the same type will replace each other}}<br /> {{hl2msg|long|hint_target|entity id that the hint should display at}}<br /> {{hl2msg|long|hint_instance|the hint instance}}<br /> {{hl2msg|short|hint_activator_userid|userid id of the activator}}<br /> {{hl2msg|short|hint_timeout|how long in seconds until the hint automatically times out, 0 means never}}<br /> {{hl2msg|string|hint_icon_onscreen|the hint icon to use when the hint is onscreen. e.g. &quot;icon_alert_red&quot;}}<br /> {{hl2msg|string|hint_icon_offscreen|the hint icon to use when the hint is offscreen. e.g. &quot;icon_alert&quot;}}<br /> {{hl2msg|string|hint_caption|the hint caption. e.g. &quot;#ThisIsDangerous&quot;}}<br /> {{hl2msg|string|hint_activator_caption|the hint caption that only the activator sees e.g. &quot;#YouPushedItGood&quot;}}<br /> {{hl2msg|string|hint_color|the hint color in &quot;r,g,b&quot; format where each component is 0-255}}<br /> {{hl2msg|float|hint_icon_offset|how far on the z axis to offset the hint from entity origin}}<br /> {{hl2msg|float|hint_range|range before the hint is culled}}<br /> {{hl2msg|long|hint_flags|hint flags}}<br /> {{hl2msg|string|hint_binding|bindings to use when use_binding is the onscreen icon}}<br /> {{hl2msg|bool|hint_allow_nodraw_target|if false, the hint will dissappear if the target entity is invisible}}<br /> {{hl2msg|bool|hint_nooffscreen|if true, the hint will not show when outside the player view}}<br /> {{hl2msg|bool|hint_forcecaption|if true, the hint caption will show even if the hint is occluded}}<br /> {{hl2msg|bool|hint_local_player_only|if true, only the local player will see the hint}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_server_hint_stop ===<br /> {{qnotice|destroys a server/map created hint}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_server_hint_stop|string}}<br /> {{hl2msg|string|hint_name|The hint to stop. Will stop ALL hints with this name}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_survivor_supply ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_survivor_supply|string}}<br /> {{hl2msg|long|hint_player|entity id that the hint will display for}}<br /> {{hl2msg|long|hint_target|entity id that the hint should display at}}<br /> {{hl2msg|string|hint_caption|the hint caption. e.g. &quot;#ThisIsDangerous&quot;}}<br /> {{end-hl2msg}}<br /> <br /> === logicrounds_start ===<br /> {{qnotice|Called when the round has started (from logic_rounds)}}&lt;br&gt;<br /> {{begin-hl2msg|logicrounds_start|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === logicrounds_end ===<br /> {{qnotice|Called when the round ends (from logic_rounds)}}&lt;br&gt;<br /> {{begin-hl2msg|logicrounds_end|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === set_text ===<br /> {{qnotice|Called when AS sets the win text}}&lt;br&gt;<br /> {{begin-hl2msg|set_text|string}}<br /> {{hl2msg|string|txt}}<br /> {{end-hl2msg}}<br /> <br /> === vote_ended ===<br /> {{qnotice|Called when a vote has ended}}&lt;br&gt;<br /> {{begin-hl2msg|vote_ended|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === vote_generic_created ===<br /> {{qnotice|Called when a generic vote has been created}}&lt;br&gt;<br /> {{begin-hl2msg|vote_generic_created|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === vote_generic_clr ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|vote_generic_clr|string}}<br /> {{hl2msg|string|option}}<br /> {{hl2msg|long|red}}<br /> {{hl2msg|long|green}}<br /> {{hl2msg|long|blue}}<br /> {{end-hl2msg}}<br /> <br /> === vote_started ===<br /> {{qnotice|Called when a vote started}}&lt;br&gt;<br /> {{begin-hl2msg|vote_started|string}}<br /> {{hl2msg|string|issue}}<br /> {{hl2msg|string|param1}}<br /> {{hl2msg|byte|team}}<br /> {{hl2msg|long|initiator|entity id of the player who initiated the vote}}<br /> {{end-hl2msg}}<br /> <br /> === vote_changed ===<br /> {{qnotice|Called when a vote changed}}&lt;br&gt;<br /> {{begin-hl2msg|vote_changed|string}}<br /> {{hl2msg|byte|vote_option1}}<br /> {{hl2msg|byte|vote_option2}}<br /> {{hl2msg|byte|vote_option3}}<br /> {{hl2msg|byte|vote_option4}}<br /> {{hl2msg|byte|vote_option5}}<br /> {{hl2msg|byte|yesVotes}}<br /> {{hl2msg|byte|noVotes}}<br /> {{hl2msg|byte|potentialVotes}}<br /> {{end-hl2msg}}<br /> <br /> === vote_passed ===<br /> {{qnotice|Called when a vote passed}}&lt;br&gt;<br /> {{begin-hl2msg|vote_passed|string}}<br /> {{hl2msg|string|details}}<br /> {{hl2msg|string|param1}}<br /> {{hl2msg|byte|team}}<br /> {{end-hl2msg}}<br /> <br /> === vote_failed ===<br /> {{qnotice|Called when a vote failed}}&lt;br&gt;<br /> {{begin-hl2msg|vote_passed|string}}<br /> {{hl2msg|byte|team}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === vote_cast ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|vote_cast|string}}<br /> {{hl2msg|byte|vote|yes/no vote}}<br /> {{hl2msg|byte|team}}<br /> {{hl2msg|long|entityid|entity id of the voter}}<br /> {{end-hl2msg}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Zombie_Panic!_Source_Events&diff=10492 2017-12-19T16:25:17Z

<p>Xerox8521: Added and Updated all events for ZPS 3.0</p> <hr /> <div>:''Refer back to [[Game Events (Source)]] for more events.''<br /> === player_death ===<br /> {{qnotice|When a player dies}}&lt;br&gt;<br /> {{begin-hl2msg|player_death|string}}<br /> {{hl2msg|short|userid|player who died}}<br /> {{hl2msg|short|attacker|player who killed}}<br /> {{hl2msg|short|assistant|player who assisted the attacker}}<br /> {{hl2msg|string|weapon|name of the weapon}}<br /> {{hl2msg|bool|headshot|true if player died from headshot}}<br /> {{hl2msg|short|dmgbits|damage type}}<br /> {{end-hl2msg}}<br /> <br /> === player_connected ===<br /> {{qnotice|When a player joins the server}}&lt;br&gt;<br /> {{begin-hl2msg|player_connected|string}}<br /> {{hl2msg|string|name|name of the player that connected}}<br /> {{end-hl2msg}}<br /> <br /> === player_disconnected ===<br /> {{qnotice|When a player leaves the server}}&lt;br&gt;<br /> {{begin-hl2msg|player_disconnected|string}}<br /> {{hl2msg|string|name|name of the player that left}}<br /> {{hl2msg|short|flag}}<br /> {{hl2msg|string|reason|reason why the player left}}<br /> {{end-hl2msg}}<br /> <br /> === map_change ===<br /> {{qnotice|Called when the map changes}}&lt;br&gt;<br /> {{begin-hl2msg|map_change|string}}<br /> {{hl2msg|string|map|name of the map that is being switched to}}<br /> {{end-hl2msg}}<br /> <br /> === zombie_lives ===<br /> {{qnotice|Called when the zombie lives changes}}&lt;br&gt;<br /> {{begin-hl2msg|zombie_lives|string}}<br /> {{hl2msg|byte|count|amount of zombie lives left}}<br /> {{end-hl2msg}}<br /> <br /> === ambient_play ===<br /> {{qnotice|Called when a sound plays}}&lt;br&gt;<br /> {{begin-hl2msg|ambient_play|string}}<br /> {{hl2msg|string|sound|sound file which played}}<br /> {{hl2msg|short|entity|entity which the sound plays from}}<br /> {{hl2msg|bool|fade|should the sound fade}}<br /> {{end-hl2msg}}<br /> <br /> === force_song ===<br /> {{qnotice|Called when the logic_music entity changes the song}}&lt;br&gt;<br /> {{begin-hl2msg|force_song_play|string}}<br /> {{hl2msg|string|song|file path for the song}}<br /> {{hl2msg|string|title|custom song title}}<br /> {{end-hl2msg}}<br /> <br /> === ambient_as ===<br /> {{qnotice|Called when a sound is played from AngelScript}}&lt;br&gt;<br /> {{begin-hl2msg|ambient_as|string}}<br /> {{hl2msg|string|sound|sound being played}}<br /> {{end-hl2msg}}<br /> <br /> === armmodel_as ===<br /> {{qnotice|Called when a new arm model is set from AngelScript}}&lt;br&gt;<br /> {{begin-hl2msg|armmodel_as|string}}<br /> {{hl2msg|string|model|arm model that should be used}}<br /> {{end-hl2msg}}<br /> <br /> === spawned_player ===<br /> {{qnotice|Called when player has spawned}}&lt;br&gt;<br /> {{begin-hl2msg|spawned_player|string}}<br /> {{hl2msg|string|name|name of the player that spawned}}<br /> {{end-hl2msg}}<br /> <br /> === angelscript_callevent ===<br /> {{qnotice|when AS calls the function CallEvent()}}&lt;br&gt;<br /> {{begin-hl2msg|angelscript_callevent|string}}<br /> {{hl2msg|short|clientid}}<br /> {{hl2msg|string|hostname}}<br /> {{hl2msg|string|serverip}}<br /> {{hl2msg|string|serverport}}<br /> {{hl2msg|string|model}}<br /> {{end-hl2msg}}<br /> <br /> === cleanupmap ===<br /> {{qnotice|when the server calls CleanUpMap(), it will tell the client todo the same for temp and client sided entities}}&lt;br&gt;<br /> {{begin-hl2msg|cleanupmap|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === round_begins===<br /> {{qnotice|When the round begins}}&lt;br&gt;<br /> {{begin-hl2msg|round_begins|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === round_win===<br /> {{qnotice|When the round ends}}&lt;br&gt;<br /> {{begin-hl2msg|round_win|string}}<br /> {{hl2msg|string|mapname|name of the current map}}<br /> {{hl2msg|bool|humanwin|true if survivors won}}<br /> {{end-hl2msg}}<br /> <br /> === game_round_restart ===<br /> {{qnotice|When one team won the round and players can select their team again}}&lt;br&gt;<br /> {{begin-hl2msg|game_round_restart|string}}<br /> {{hl2msg|none|none}}<br /> {{end-hl2msg}}<br /> <br /> === gravity_change ===<br /> {{qnotice|When the gravity changes}}&lt;br&gt;<br /> {{begin-hl2msg|gravity_change|string}}<br /> {{hl2msg|float|newgravity|New value after the change}}<br /> {{end-hl2msg}}<br /> <br /> === achievement_earned ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|achievement_earned|string}}<br /> {{hl2msg|short|userid|player who earned the achievement}}<br /> {{hl2msg|string|achid|achievement id}}<br /> {{hl2msg|string|achtitle|title of the achievement}}<br /> {{end-hl2msg}}<br /> <br /> === spec_target_updated ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|spec_target_updated|string}}<br /> {{hl2msg|none|none}}<br /> {{end-hl2msg}}<br /> <br /> === zp_washuman ===<br /> {{qnotice|The player was a human player before we turned into zombie team (Only applies if there is no zombie lives left, or if the zombies won)}}&lt;br&gt;<br /> {{begin-hl2msg|zp_washuman|string}}<br /> {{hl2msg|short|userid|player that turned into a zombie}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === zp_infected ===<br /> {{qnotice|Calls whenever someone got infected}}&lt;br&gt;<br /> {{begin-hl2msg|zp_infected|string}}<br /> {{hl2msg|short|userid|player that got infected}}<br /> {{end-hl2msg}}<br /> <br /> === zp_entitypickedup ===<br /> {{qnotice|Calls whenever a button is pressed, or if an item is picked up}}&lt;br&gt;<br /> {{begin-hl2msg|zp_entitypickedup|string}}<br /> {{hl2msg|string|entkey|name of the button that is pressed or entity that is picked up}}<br /> {{end-hl2msg}}<br /> <br /> === general_hint ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|general_hint|string}}<br /> {{hl2msg|short|userid|the player who activated it}}<br /> {{end-hl2msg}}<br /> <br /> === movement_hint ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|movement_hint|string}}<br /> {{hl2msg|short|userid|the player who needs the hint}}<br /> {{end-hl2msg}}<br /> <br /> === movement_hint_success ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|movement_hint_success|string}}<br /> {{hl2msg|short|userid|the player succeeded}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === gameinstructor_draw ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|gameinstructor_draw|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === gameinstructor_nodraw ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|gameinstructor_nodraw|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === set_instructor_group_enabled ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|set_instructor_group_enabled|string}}<br /> {{hl2msg|string|group}}<br /> {{hl2msg|short|enabled}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_tutor ===<br /> {{qnotice|Called from the instructor tutorial}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_tutor|string}}<br /> {{hl2msg|long|userid}}<br /> {{hl2msg|long|entindex}}<br /> {{hl2msg|string|strbind}}<br /> {{hl2msg|string|strmsg}}<br /> {{hl2msg|string|icon_onscreen}}<br /> {{hl2msg|string|icon_offscreen}}<br /> {{hl2msg|bool|nooffscreen}}<br /> {{hl2msg|int|posx}}<br /> {{hl2msg|int|posy}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_server_hint_create ===<br /> {{qnotice|create a hint using data supplied entirely by the server/map. Intended for hints to smooth playtests before content is ready to make the hint unneccessary. NOT INTENDED AS A SHIPPABLE CRUTCH}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_server_hint_create|string}}<br /> {{hl2msg|string|hint_name|what to name the hint. For referencing it again later (e.g. a kill command for the hint instead of a timeout)}}<br /> {{hl2msg|string|hint_replace_key|type name so that messages of the same type will replace each other}}<br /> {{hl2msg|long|hint_target|entity id that the hint should display at}}<br /> {{hl2msg|long|hint_instance|the hint instance}}<br /> {{hl2msg|short|hint_activator_userid|userid id of the activator}}<br /> {{hl2msg|short|hint_timeout|how long in seconds until the hint automatically times out, 0 means never}}<br /> {{hl2msg|string|hint_icon_onscreen|the hint icon to use when the hint is onscreen. e.g. &quot;icon_alert_red&quot;}}<br /> {{hl2msg|string|hint_icon_offscreen|the hint icon to use when the hint is offscreen. e.g. &quot;icon_alert&quot;}}<br /> {{hl2msg|string|hint_caption|the hint caption. e.g. &quot;#ThisIsDangerous&quot;}}<br /> {{hl2msg|string|hint_activator_caption|the hint caption that only the activator sees e.g. &quot;#YouPushedItGood&quot;}}<br /> {{hl2msg|string|hint_color|the hint color in &quot;r,g,b&quot; format where each component is 0-255}}<br /> {{hl2msg|float|hint_icon_offset|how far on the z axis to offset the hint from entity origin}}<br /> {{hl2msg|float|hint_range|range before the hint is culled}}<br /> {{hl2msg|long|hint_flags|hint flags}}<br /> {{hl2msg|string|hint_binding|bindings to use when use_binding is the onscreen icon}}<br /> {{hl2msg|bool|hint_allow_nodraw_target|if false, the hint will dissappear if the target entity is invisible}}<br /> {{hl2msg|bool|hint_nooffscreen|if true, the hint will not show when outside the player view}}<br /> {{hl2msg|bool|hint_forcecaption|if true, the hint caption will show even if the hint is occluded}}<br /> {{hl2msg|bool|hint_local_player_only|if true, only the local player will see the hint}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_server_hint_stop ===<br /> {{qnotice|destroys a server/map created hint}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_server_hint_stop|string}}<br /> {{hl2msg|string|hint_name|The hint to stop. Will stop ALL hints with this name}}<br /> {{end-hl2msg}}<br /> <br /> === instructor_survivor_supply ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|instructor_survivor_supply|string}}<br /> {{hl2msg|long|hint_player|entity id that the hint will display for}}<br /> {{hl2msg|long|hint_target|entity id that the hint should display at}}<br /> {{hl2msg|string|hint_caption|the hint caption. e.g. &quot;#ThisIsDangerous&quot;}}<br /> {{end-hl2msg}}<br /> <br /> === logicrounds_start ===<br /> {{qnotice|Called when the round has started (from logic_rounds)}}&lt;br&gt;<br /> {{begin-hl2msg|logicrounds_start|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === logicrounds_end ===<br /> {{qnotice|Called when the round ends (from logic_rounds)}}&lt;br&gt;<br /> {{begin-hl2msg|logicrounds_end|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === set_text ===<br /> {{qnotice|Called when AS sets the win text}}&lt;br&gt;<br /> {{begin-hl2msg|set_text|string}}<br /> {{hl2msg|string|txt}}<br /> {{end-hl2msg}}<br /> <br /> === vote_ended ===<br /> {{qnotice|Called when a vote has ended}}&lt;br&gt;<br /> {{begin-hl2msg|vote_ended|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === vote_generic_created ===<br /> {{qnotice|Called when a generic vote has been created}}&lt;br&gt;<br /> {{begin-hl2msg|vote_generic_created|string}}<br /> {{hl2msg|None|None|None}}<br /> {{end-hl2msg}}<br /> <br /> === vote_generic_clr ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|vote_generic_clr|string}}<br /> {{hl2msg|string|option}}<br /> {{hl2msg|long|red}}<br /> {{hl2msg|long|green}}<br /> {{hl2msg|long|blue}}<br /> {{end-hl2msg}}<br /> <br /> === vote_started ===<br /> {{qnotice|Called when a vote started}}&lt;br&gt;<br /> {{begin-hl2msg|vote_started|string}}<br /> {{hl2msg|string|issue}}<br /> {{hl2msg|string|param1}}<br /> {{hl2msg|byte|team}}<br /> {{hl2msg|long|initiator|entity id of the player who initiated the vote}}<br /> {{end-hl2msg}}<br /> <br /> === vote_changed ===<br /> {{qnotice|Called when a vote changed}}&lt;br&gt;<br /> {{begin-hl2msg|vote_changed|string}}<br /> {{hl2msg|byte|vote_option1}}<br /> {{hl2msg|byte|vote_option2}}<br /> {{hl2msg|byte|vote_option3}}<br /> {{hl2msg|byte|vote_option4}}<br /> {{hl2msg|byte|vote_option5}}<br /> {{hl2msg|byte|yesVotes}}<br /> {{hl2msg|byte|noVotes}}<br /> {{hl2msg|byte|potentialVotes}}<br /> {{end-hl2msg}}<br /> <br /> === vote_passed ===<br /> {{qnotice|Called when a vote passed}}&lt;br&gt;<br /> {{begin-hl2msg|vote_passed|string}}<br /> {{hl2msg|string|details}}<br /> {{hl2msg|string|param1}}<br /> {{hl2msg|byte|team}}<br /> {{end-hl2msg}}<br /> <br /> === vote_failed ===<br /> {{qnotice|Called when a vote failed}}&lt;br&gt;<br /> {{begin-hl2msg|vote_passed|string}}<br /> {{hl2msg|byte|team}}<br /> {{end-hl2msg}}<br /> <br /> <br /> === vote_cast ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|vote_cast|string}}<br /> {{hl2msg|byte|vote|yes/no vote}}<br /> {{hl2msg|byte|team}}<br /> {{hl2msg|long|entityid|entity id of the voter}}<br /> {{end-hl2msg}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Zombie_Panic!_Source_Events&diff=10491 2017-12-19T14:19:32Z

<p>Xerox8521: Updated for ZPS 3.0</p> <hr /> <div>:''Refer back to [[Game Events (Source)]] for more events.''<br /> === player_death ===<br /> {{qnotice|When a player dies}}&lt;br&gt;<br /> {{begin-hl2msg|player_death|string}}<br /> {{hl2msg|short|userid|player who died}}<br /> {{hl2msg|short|attacker|player who killed}}<br /> {{hl2msg|short|assistant|player who assisted the attacker}}<br /> {{hl2msg|string|weapon|name of the weapon}}<br /> {{hl2msg|bool|headshot|true if player died from headshot}}<br /> {{hl2msg|short|dmgbits|damage type}}<br /> {{end-hl2msg}}<br /> <br /> === player_connected ===<br /> {{qnotice|When a player joins the server}}&lt;br&gt;<br /> {{begin-hl2msg|player_connected|string}}<br /> {{hl2msg|string|name|name of the player that connected}}<br /> {{end-hl2msg}}<br /> <br /> === ambient_play ===<br /> {{qnotice|Called when a sound plays}}&lt;br&gt;<br /> {{begin-hl2msg|ambient_play|string}}<br /> {{hl2msg|string|sound|Sound file which played}}<br /> {{hl2msg|bool|fade}}<br /> {{end-hl2msg}}<br /> <br /> === game_round_restart ===<br /> {{qnotice|When one team won the round and players can select their team again}}&lt;br&gt;<br /> {{begin-hl2msg|game_round_restart|string}}<br /> {{hl2msg|none|none}}<br /> {{end-hl2msg}}<br /> <br /> === gravity_change ===<br /> {{qnotice|When the gravity changes}}&lt;br&gt;<br /> {{begin-hl2msg|gravity_change|string}}<br /> {{hl2msg|float|newgravity|New value after the change}}<br /> {{end-hl2msg}}<br /> <br /> === achievement_earned ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|achievement_earned|string}}<br /> {{hl2msg|byte|player}}<br /> {{hl2msg|short|achievement}}<br /> {{end-hl2msg}}<br /> <br /> === spec_target_updated ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|spec_target_updated|string}}<br /> {{hl2msg|none|none}}<br /> {{end-hl2msg}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Zombie_Panic!_Source_Events&diff=10490 2017-12-19T14:16:34Z

<p>Xerox8521: Updated for ZPS 3.0</p> <hr /> <div>:''Refer back to [[Game Events (Source)]] for more events.''<br /> === player_death ===<br /> {{qnotice|When a player dies}}&lt;br&gt;<br /> {{begin-hl2msg|player_death|string}}<br /> {{hl2msg|short|userid|player who died}}<br /> {{hl2msg|short|attacker|player who killed}}<br /> {{hl2msg|short|assistant|player who assisted the attacker}}<br /> {{hl2msg|string|weapon|name of the weapon}}<br /> {{hl2msg|bool|headshot|true if player died from headshot}}<br /> {{hl2msg|short|dmgbits|damage type}}<br /> {{end-hl2msg}}<br /> <br /> === zombie_death ===<br /> {{qnotice|When a zombie dies}}&lt;br&gt;<br /> {{begin-hl2msg|zombie_death|string}}<br /> {{hl2msg|byte|count}}<br /> {{end-hl2msg}}<br /> <br /> === ambient_play ===<br /> {{qnotice|Called when a sound plays}}&lt;br&gt;<br /> {{begin-hl2msg|ambient_play|string}}<br /> {{hl2msg|string|sound|Sound file which played}}<br /> {{hl2msg|bool|fade}}<br /> {{end-hl2msg}}<br /> <br /> === game_round_restart ===<br /> {{qnotice|When one team won the round and players can select their team again}}&lt;br&gt;<br /> {{begin-hl2msg|game_round_restart|string}}<br /> {{hl2msg|none|none}}<br /> {{end-hl2msg}}<br /> <br /> === gravity_change ===<br /> {{qnotice|When the gravity changes}}&lt;br&gt;<br /> {{begin-hl2msg|gravity_change|string}}<br /> {{hl2msg|float|newgravity|New value after the change}}<br /> {{end-hl2msg}}<br /> <br /> === achievement_earned ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|achievement_earned|string}}<br /> {{hl2msg|byte|player}}<br /> {{hl2msg|short|achievement}}<br /> {{end-hl2msg}}<br /> <br /> === spec_target_updated ===<br /> {{qnotice|None}}&lt;br&gt;<br /> {{begin-hl2msg|spec_target_updated|string}}<br /> {{hl2msg|none|none}}<br /> {{end-hl2msg}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Scripting_FAQ_(SourceMod)&diff=10384 2017-08-18T02:40:51Z

<p>Xerox8521: Updated API Links from &quot;old&quot; to &quot;new&quot;</p> <hr /> <div>[[Image:Yak.gif]]<br /> yak wuz heer<br /> <br /> =How do I learn SourcePawn?=<br /> A good start is on the [[Introduction_to_SourcePawn_1.7]] page, which will teach you the SourcePawn language. Then go through the [[Introduction to SourceMod Plugins]], which will teach you how to write your first plug-in.<br /> <br /> =Where can I find all the SourcePawn functions and other information?=<br /> All SourceMod plug-ins have this line:<br /> <br /> &lt;pawn&gt;#include &lt;sourcemod&gt;&lt;/pawn&gt;<br /> <br /> This line instructs the compiler to retrieve the file &lt;tt&gt;sourcemod.inc&lt;/tt&gt; from the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder. Every function, variable, and definition can be found in the &lt;tt&gt;.inc&lt;/tt&gt; files inside the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder.<br /> <br /> But searching through all those files can be quite tedious. Thankfully, the honourable [https://forums.alliedmods.net/member.php?u=9443 Nican] created an API reference viewable on the web, complete with searching and commenting: [https://sm.alliedmods.net/new-api/ https://sm.alliedmods.net/new-api/]<br /> <br /> Also, if you are in the SourceMod IRC channel ([irc://irc.gamesurge.net/sourcemod #sourcemod on GameSurge]), you can use the &lt;tt&gt;!api&lt;/tt&gt; command to search [https://forums.alliedmods.net/member.php?u=9443 Nican's] API reference:<br /> &lt;pre&gt;&lt;theY4Kman&gt; !api Netclass<br /> &lt;yakbot&gt; theY4Kman: bool GetEntityNetClass(int edict, char[] clsname, int maxlength): Retrieves an entity's networkable serverclass name. This is not the same as the classname and is used for networkable state changes. (https://sm.alliedmods.net/new-api/entity/GetEntityNetClass)&lt;/pre&gt;<br /> <br /> =How do I find the classname of an entity? (e.g., &quot;&lt;tt&gt;weapon_knife&lt;/tt&gt;&quot; or &quot;&lt;tt&gt;prop_physics&lt;/tt&gt;&quot;)=<br /> The classname of an entity (not to be confused with a netclass such as &lt;tt&gt;CCSPlayer&lt;/tt&gt;) is a unique identifier. It's the most well known of entity names. To find it, use the function [https://sm.alliedmods.net/new-api/entity/GetEdictClassname GetEdictClassname()]:<br /> <br /> &lt;pawn&gt;char classname[128];<br /> GetEdictClassname(myentity, classname, sizeof(classname));<br /> <br /> PrintToServer(&quot;myentity classname: %s&quot;, classname);<br /> // myentity classname: weapon_knife&lt;/pawn&gt;<br /> <br /> =How do I block regular commands, such as &lt;tt&gt;kill&lt;/tt&gt; and &lt;tt&gt;say&lt;/tt&gt;?=<br /> As of version 1.3, the recommended way to hook and block commands is with [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()]. Previously, using [https://sm.alliedmods.net/new-api/console/RegConsoleCmd RegConsoleCmd()] with the command name was the only way to hook commands, but this creates a whole new command for the command dispatch to check every time any command is executed. [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] creates only a lightweight hook, processed only when the specific command is executed.<br /> <br /> Here's how to use it to block the &lt;tt&gt;say&lt;/tt&gt; command:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> AddCommandListener(SayCallback, &quot;say&quot;);<br /> }<br /> <br /> public Action SayCallback(int client, const char[] command, int argc)<br /> {<br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I hook +commands, such as &lt;tt&gt;+zoom&lt;/tt&gt; and &lt;tt&gt;+attack&lt;/tt&gt;?=<br /> Unlike regular commands, &lt;tt&gt;+commands&lt;/tt&gt; are handled on the client's computer, then sent to the server in a more compressed fashion. This means [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] cannot be used to hook &lt;tt&gt;+commands&lt;/tt&gt;. As of version 1.3, the recommended solution is to use the global forward [https://sm.alliedmods.net/new-api/sdktools_hooks/OnPlayerRunCmd OnPlayerRunCmd()]. This forward is fired every time a player uses a movement button. To detect or block a &lt;tt&gt;+command&lt;/tt&gt;, you'll first have to find out its proper &lt;tt&gt;IN_&lt;/tt&gt; constant (see &lt;tt&gt;[https://sm.alliedmods.net/new-api/entity_prop_stocks/__raw entity_prop_stocks.inc]&lt;/tt&gt;).<br /> <br /> Here's how to use it to block crouching when attacking:<br /> <br /> &lt;pawn&gt;public Action OnPlayerRunCmd(int client, int &amp;buttons, int &amp;impulse, float vel[3], float angles[3], int &amp;weapon)<br /> {<br /> // Check if the player is attacking (+attack)<br /> if ((buttons &amp; IN_ATTACK) == IN_ATTACK)<br /> {<br /> // If so, block their crouching (+duck)<br /> buttons &amp;= ~IN_DUCK;<br /> }<br /> <br /> // We must return Plugin_Continue to let the changes be processed.<br /> // Otherwise, we can return Plugin_Handled to block the commands<br /> return Plugin_Continue;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of loose indentation warnings?=<br /> &lt;pre&gt;myplugin.sp(#) : warning 217: loose indentation&lt;/pre&gt;<br /> <br /> Loose indentation warnings arise when indentation in your code is inconsistent. This usually means using both tabs and spaces as indentation. However, it can also mean a different amount of spaces or tabs are being used. Therefore, to correct it, use just one type of indentation. Because different editors have different settings for the size of tab stops, it is recommended you use 4 spaces to indent.<br /> <br /> Good:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> int myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> Bad:<br /> <br /> &lt;pawn&gt;public voidOnPluginStart()<br /> {<br /> int myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of tag mismatch warnings?=<br /> Though every variable in SourcePawn is one cell (4 bytes), with the exception of strings, there are many different ways to interpret what's inside a cell. To signify a cell's contents, tags are used. The most common are &lt;tt&gt;_&lt;/tt&gt; (the default tag: a vanilla cell. This tag is implied when no other tag is specified.), &lt;tt&gt;float&lt;/tt&gt;, &lt;tt&gt;bool&lt;/tt&gt;, and &lt;tt&gt;char&lt;/tt&gt;. See [[Introduction_to_SourcePawn_1.7#Variables_2]] for more information.<br /> <br /> Functions wear these tags on their parameters so you can tell what needs to be passed to the function:<br /> &lt;pawn&gt;native int SetEntPropFloat(int entity, PropType type, const char[] prop, float value, int element)&lt;/pawn&gt;<br /> <br /> This function calls for '''&lt;tt&gt;entity&lt;/tt&gt;''', a cell with the implied tag '''''&lt;tt&gt;int&lt;/tt&gt;'''''; '''&lt;tt&gt;type&lt;/tt&gt;''', with the developer-defined tag '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; '''&lt;tt&gt;prop&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;char&lt;/tt&gt;'''''; and '''&lt;tt&gt;value&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;float&lt;/tt&gt;'''''.<br /> To call this function, then, you must pass values with the specified tags. For example:<br /> &lt;pawn&gt;SetEntPropFloat(1234, Prop_Send, &quot;m_fNumber&quot;, 1.0);&lt;/pawn&gt;<br /> <br /> This calls the function correctly: &lt;tt&gt;1234&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''), &lt;tt&gt;Prop_Send&lt;/tt&gt; is a variable defined in the enum '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [https://sm.alliedmods.net/new-api/entity/__raw entity.inc], &lt;tt&gt;&quot;m_fNumber&quot;&lt;/tt&gt; is a '''''&lt;tt&gt;char&lt;/tt&gt;''''', and &lt;tt&gt;1.0&lt;/tt&gt; is a '''''&lt;tt&gt;float&lt;/tt&gt;'''''. For a nonexample:<br /> &lt;pawn&gt;SetEntPropFloat(1234.0, 1, &quot;m_fNumber&quot;, 1337);&lt;/pawn&gt;<br /> <br /> This is incorrect! &lt;tt&gt;1234.0&lt;/tt&gt; is a '''''&lt;tt&gt;float&lt;/tt&gt;''''' that should be a regular cell ('''''&lt;tt&gt;int&lt;/tt&gt;'''''); &lt;tt&gt;1&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;int&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; and &lt;tt&gt;1337&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;int&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;float&lt;/tt&gt;'''''. This call will generate a tag mismatch warning. To correct it, simply use a value with the correct tag. Most of the time, tags that are not built-in (such as '''''&lt;tt&gt;PropType&lt;/tt&gt;''''') can be found in the same file where a function uses them (you can find '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [https://sm.alliedmods.net/new-api/entity/__raw entity.inc]).<br /> <br /> =How do I add color to my messages?=<br /> Though the actual colors will vary depending on the mod, you can add color to any chat message using the characters &lt;tt&gt;0x01&lt;/tt&gt; to &lt;tt&gt;0x08&lt;/tt&gt;. For example:<br /> &lt;pawn&gt;PrintToChatAll (&quot;\x01 1 .. \x02 2 .. \x03 3 .. \x04 4 .. \x05 5 .. \x06 6 .. \x07 7 .. \x08 8&quot;);&lt;/pawn&gt;<br /> <br /> Example output from Left 4 Dead:<br /> <br /> [[Image:Left_4_Dead_Colors.png]]<br /> <br /> With a little experimenting, you can learn the colors for a mod. However, the meaning behind the colors is generally as follows:<br /> <br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x01&lt;/tt&gt; = Normal color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x02&lt;/tt&gt; = Use team color to the end of a player's name. When used, it can be the only color used, and it must be at the start of the message.<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x03&lt;/tt&gt; = Team color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x04&lt;/tt&gt; = Location color<br /> <br /> This data comes from Counter-Strike: Source.<br /> <br /> For CS:GO, here are some colors:<br /> &lt;pawn&gt;PrintToChat(&quot;\x011\x022\x033\x044\x055\x066\x077\x088\x099\x0AA\x0BB\x0CC\x0DD\x0EE\x0FF&quot;);&lt;/pawn&gt;<br /> <br /> Unfortunately, to use players' team colors, you must use UserMessages, because there is no way for the current SourceMod functions to know which team color to use. Here's an example:<br /> <br /> &lt;pawn&gt;Handle hBf;<br /> hBf = StartMessageOne(&quot;SayText2&quot;, player_to); // To send the message to all players, use StartMessageAll(&quot;SayText2&quot;);<br /> if (hBf != null)<br /> {<br /> BfWriteByte(hBf, player_from); <br /> BfWriteByte(hBf, 0); <br /> BfWriteString(hBf, &quot;&lt;\x03player_from team color\x01&gt; My message&quot;);<br /> EndMessage();<br /> }&lt;/pawn&gt;<br /> <br /> &lt;tt&gt;player_to&lt;/tt&gt; is the client index to send the message to (or use [https://sm.alliedmods.net/new-api/usermessages/StartMessageAll StartMessageAll()] instead of [https://sm.alliedmods.net/new-api/usermessages/StartMessageOne StartMessageOne()] to send the message to all players). &lt;tt&gt;player_from&lt;/tt&gt; is the client index of the player whose team color will be utilized in the message. The message will now look like this (assuming &lt;tt&gt;player_from&lt;/tt&gt; is on the RED team):<br /> <br /> &lt;span style=&quot;color:#AA0&quot;&gt;&amp;lt;&lt;/span&gt;&lt;span style=&quot;color:#F00&quot;&gt;player_from team color&lt;/span&gt;&lt;span style=&quot;color:#AA0&quot;&gt;&amp;gt; My message&lt;/span&gt;<br /> <br /> There's another catch, however: this is only known to work in CS:S and TF2. For other mods, your mileage may vary.<br /> <br /> ==Color Libraries==<br /> There are a few libraries that can handle colors for you, so you don't have to muck with UserMessages:<br /> <br /> ===exvel's Colors===<br /> This is a simple include file, allowing easy control over chat coloring. You can grab it [http://forums.alliedmods.net/showthread.php?t=96831 on the forums]. Instead of hex codes, colors are denoted with tags, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{default}&lt;/tt&gt;&lt;/span&gt;, &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;, or &lt;span style=&quot;color: #00F;&quot;&gt;&lt;tt&gt;{blue}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> Here's some example usage. Note that this code assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;colors&gt;<br /> <br /> public void OnPluginStart()<br /> {<br /> CPrintToChatAll(&quot;{green}Hello {red}World! {default}Test 1 concluded.&quot;);<br /> <br /> int client_on_blu_team = 1;<br /> CPrintToChatAllEx(client_on_blu_team, &quot;{teamcolor}BLU team {default}says {green}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> Note that to use a team color, there needs to be at least one player on that team. Otherwise, it will default to &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> ===SMLib===<br /> [http://forums.alliedmods.net/showthread.php?p=1398699 SMLib] is a huge collection of stock functions to keep plug-in developers from reinventing the wheel. It includes a [http://forums.alliedmods.net/showthread.php?p=1398702#post1398702 colors API] very similar to [[#exvel's Colors|exvel's]]. The benefits of SMLib are it supports shorthand color names, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{N}&lt;/tt&gt;&lt;/span&gt; and &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{G}&lt;/tt&gt;&lt;/span&gt;, and all colors are supported in its &lt;tt&gt;Client_PrintToChat()&lt;/tt&gt; function.<br /> <br /> Here's how to print the same thing as the above example with SMLib. Note that this code also assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;smlib&gt;<br /> <br /> public void OnPluginStart()<br /> {<br /> Client_PrintToChatAll(&quot;{G}Hello {R}World! {N}Test 1 concluded.&quot;);<br /> <br /> int client_on_blu_team = 1;<br /> Client_PrintToChatAll(client_on_blu_team, &quot;{T}BLU team {N}says {G}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> =Why do I get an &quot;unknown symbol&quot; error when using an SDKTools native?=<br /> None of SourceMod's or SDKTools's functions are built into SourcePawn. Therefore, every time you use one of their functions, SourcePawn needs to know how to call the function. Normally, this is done using includes. Just like you would #include &lt;sourcemod&gt; to use SourceMod's functions, you need to:<br /> &lt;pawn&gt;#include &lt;sdktools&gt;&lt;/pawn&gt;<br /> to use an SDKTools native.<br /> <br /> =Why is Source telling me my command is an &quot;Unknown command&quot;?=<br /> This is because you're not returning &lt;tt&gt;Plugin_Handled&lt;/tt&gt; in your callback. If you don't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so.<br /> <br /> &lt;pawn&gt;public Action MyCommand(int client, int args)<br /> {<br /> // Do something...<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Left_4_Dead_2_Events&diff=10284 2017-03-31T17:59:22Z

<p>Xerox8521: Added missing ability_throw for tanks</p> <hr /> <div>:''Refer back to [[Game Events (Source)]] for more events.''<br /> === player_death ===<br /> {{qnotice|a game event, name may be 32 charaters long; this extents the original player_death by a new fields}}&lt;br&gt;<br /> {{begin-hl2msg|player_death|string}}<br /> {{hl2msg|short|userid|user ID who died}}<br /> {{hl2msg|long|entityid|entity ID who died, userid should be used first, to get the dead Player. Otherwise, it is not a player, so use this.}}<br /> {{hl2msg|short|attacker|user ID who killed}}<br /> {{hl2msg|string|attackername|What type of zombie, so we don't have zombie names}}<br /> {{hl2msg|long|attackerentid|if killer not a player, the entindex of who killed. Again, use attacker first}}<br /> {{hl2msg|string|weapon|weapon name killer used}}<br /> {{hl2msg|bool|headshot|signals a headshot}}<br /> {{hl2msg|bool|attackerisbot|is the attacker a bot}}<br /> {{hl2msg|string|victimname|What type of zombie, so we don't have zombie names}}<br /> {{hl2msg|bool|victimisbot|is the victim a bot}}<br /> {{hl2msg|bool|abort|did the victim abort}}<br /> {{hl2msg|long|type|damage type}}<br /> {{hl2msg|float|victim_x|}}<br /> {{hl2msg|float|victim_y|}}<br /> {{hl2msg|float|victim_z|}}<br /> {{end-hl2msg}}<br /> <br /> === player_hurt ===<br /> {{qnotice|Registers all playable classes (Hunter, Smoker, Boomer, Tank, Survivors). See infected_hurt for Witch and Common Infected}}&lt;br&gt;<br /> {{begin-hl2msg|player_hurt|string}}<br /> {{hl2msg|1|local|Not networked}}<br /> {{hl2msg|short|userid|user ID who was hurt}}<br /> {{hl2msg|short|attacker|user id who attacked}}<br /> {{hl2msg|long|attackerentid|entity id who attacked, if attacker not a player, and userid therefore invalid}}<br /> {{hl2msg|short|health|remaining health points}}<br /> {{hl2msg|byte|armor|remaining armor points}}<br /> {{hl2msg|string|weapon|weapon name attacker used, if not the world}}<br /> {{hl2msg|short|dmg_health|damage done to health}}<br /> {{hl2msg|byte|dmg_armor|damage done to armor}}<br /> {{hl2msg|byte|hitgroup|hitgroup that was damaged}}<br /> {{hl2msg|long|type|damage type}}<br /> {{end-hl2msg}}<br /> === player_team ===<br /> {{qnotice|player change his team}}&lt;br&gt;<br /> {{begin-hl2msg|player_team|string}}<br /> {{hl2msg|short|userid|user ID on server}}<br /> {{hl2msg|byte|team|team id}}<br /> {{hl2msg|byte|oldteam|old team id}}<br /> {{hl2msg|bool|disconnect|team change because player disconnects}}<br /> {{hl2msg|string|name|}}<br /> {{hl2msg|bool|isbot|}}<br /> {{end-hl2msg}}<br /> === player_bot_replace ===<br /> {{qnotice|Bot replaced a player}}&lt;br&gt;<br /> {{begin-hl2msg|player_bot_replace|string}}<br /> {{hl2msg|short|player|user ID of the player}}<br /> {{hl2msg|short|bot|user ID of the bot}}<br /> {{end-hl2msg}}<br /> === bot_player_replace ===<br /> {{qnotice|Player replaced a bot}}&lt;br&gt;<br /> {{begin-hl2msg|bot_player_replace|string}}<br /> {{hl2msg|short|bot|user ID of the bot}}<br /> {{hl2msg|short|player|user ID of the player}}<br /> {{end-hl2msg}}<br /> === player_afk ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|player_afk|string}}<br /> {{hl2msg|short|player|user ID of the player}}<br /> {{end-hl2msg}}<br /> === weapon_fire ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|weapon_fire|string}}<br /> {{hl2msg|1|local|don't network this, its way too spammy}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|string|weapon|used weapon name}}<br /> {{hl2msg|short|weaponid|used weapon ID}}<br /> {{hl2msg|short|count|number of bullets}}<br /> {{end-hl2msg}}<br /> === weapon_fire_on_empty ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|weapon_fire_on_empty|string}}<br /> {{hl2msg|1|local|don't network this, its way too spammy}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|string|weapon|weapon name used}}<br /> {{hl2msg|short|count|number of bullets}}<br /> {{end-hl2msg}}<br /> === weapon_reload ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|weapon_reload|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|bool|manual|player manually started the reload}}<br /> {{end-hl2msg}}<br /> === weapon_zoom ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|weapon_zoom|string}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}<br /> === ability_use ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{eventnote|Called|When an infected uses their ability}}<br /> {{eventnote|Issues|Doesn't fire for jockey}}<br /> {{begin-hl2msg|ability_use|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|string|ability|Classname of ability. Possible values:<br /> *ability_lunge<br /> *ability_toungue<br /> *ability_vomit<br /> *ability_charge<br /> *ability_spit<br /> *ability_throw<br /> for the Hunter, Smoker, Boomer, Charger, Spitter and Tank respectively.}}<br /> {{hl2msg|short|context|enum of the way it was used (different for each ability)}}<br /> {{end-hl2msg}}<br /> <br /> === ammo_pickup ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|ammo_pickup|string}}<br /> {{hl2msg|short|userid|The player who got some ammo from a weapon_ammo_spawner}}<br /> {{end-hl2msg}}<br /> === item_pickup ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|item_pickup|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|string|item|either a weapon such as 'tmp' or 'hegrenade', or an item such as 'nvgs'}}<br /> {{end-hl2msg}}<br /> === grenade_bounce ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|grenade_bounce|string}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}<br /> === hegrenade_detonate ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|hegrenade_detonate|string}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}<br /> === bullet_impact ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|bullet_impact|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|float|x|}}<br /> {{hl2msg|float|y|}}<br /> {{hl2msg|float|z|}}<br /> {{end-hl2msg}}<br /> === player_footstep ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|player_footstep|string}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}<br /> === player_jump ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|player_jump|string}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}<br /> === player_blind ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|player_blind|string}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}<br /> === player_falldamage ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|player_falldamage|string}}<br /> {{hl2msg|short|userid|Who got hurt}}<br /> {{hl2msg|float|damage|for how much}}<br /> {{hl2msg|short|causer|Who caused them to do so (if anyone)}}<br /> {{end-hl2msg}}<br /> === player_ledge_grab ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|player_ledge_grab|string}}<br /> {{hl2msg|short|userid|Who grabbed the ledge}}<br /> {{hl2msg|short|causer|Who caused them to do so (if anyone)}}<br /> {{end-hl2msg}}<br /> === player_ledge_release ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|player_ledge_release|string}}<br /> {{hl2msg|short|userid|person who released from the ledge}}<br /> {{end-hl2msg}}<br /> === door_moving ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|door_moving|string}}<br /> {{hl2msg|long|entindex|}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}<br /> === door_open ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|door_open|string}}<br /> {{hl2msg|short|userid|Who opened the door}}<br /> {{hl2msg|bool|checkpoint|Is the door a checkpoint door}}<br /> {{hl2msg|bool|closed|Was the door closed when it started opening?}}<br /> {{end-hl2msg}}<br /> === door_close ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|door_close|string}}<br /> {{hl2msg|short|userid|Who closed the door}}<br /> {{hl2msg|bool|checkpoint|Is the door a checkpoint door}}<br /> {{end-hl2msg}}<br /> === door_unlocked ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|door_unlocked|string}}<br /> {{hl2msg|short|userid|Who opened the door}}<br /> {{hl2msg|bool|checkpoint|Is the door a checkpoint door}}<br /> {{end-hl2msg}}<br /> === rescue_door_open ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|rescue_door_open|string}}<br /> {{hl2msg|short|userid|Who opened the door}}<br /> {{hl2msg|long|entindex|door that opened}}<br /> {{end-hl2msg}}<br /> === waiting_checkpoint_door_used ===<br /> {{qnotice|Someone tried to open a checkpoint door that is locked till everyone loads in}}&lt;br&gt;<br /> {{begin-hl2msg|waiting_checkpoint_door_used|string}}<br /> {{hl2msg|short|userid|player who tried to open it}}<br /> {{hl2msg|long|entindex|door that was used}}<br /> {{end-hl2msg}}<br /> === waiting_door_used_versus ===<br /> {{qnotice|Someone tried to open a checkpoint door that is locked till everyone loads in}}&lt;br&gt;<br /> {{begin-hl2msg|waiting_door_used_versus|string}}<br /> {{hl2msg|short|userid|player who tried to open it}}<br /> {{hl2msg|long|entindex|door that was used}}<br /> {{end-hl2msg}}<br /> === waiting_checkpoint_button_used ===<br /> {{qnotice|Someone tried to push a button that's locked until everyone is gathered}}&lt;br&gt;<br /> {{begin-hl2msg|waiting_checkpoint_button_used|string}}<br /> {{hl2msg|short|userid|player who tried to open it}}<br /> {{end-hl2msg}}<br /> === success_checkpoint_button_used ===<br /> {{qnotice|Someone pushed a button that's locked until everyone is gathered}}&lt;br&gt;<br /> {{begin-hl2msg|success_checkpoint_button_used|string}}<br /> {{hl2msg|short|userid|player who openned it}}<br /> {{end-hl2msg}}<br /> === round_freeze_end ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|round_freeze_end|string}}<br /> {{hl2msg|None|None|}}<br /> {{end-hl2msg}}<br /> === round_start_pre_entity ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|round_start_pre_entity|string}}<br /> {{hl2msg|None|None|}}<br /> {{end-hl2msg}}<br /> === round_start_post_nav ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|round_start_post_nav|string}}<br /> {{hl2msg|None|None|}}<br /> {{end-hl2msg}}<br /> === nav_blocked ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|nav_blocked|string}}<br /> {{hl2msg|long|area|}}<br /> {{hl2msg|bool|blocked|}}<br /> {{end-hl2msg}}<br /> === nav_generate ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|nav_generate|string}}<br /> {{hl2msg|None|None|}}<br /> {{end-hl2msg}}<br /> === round_end_message ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|round_end_message|string}}<br /> {{hl2msg|byte|winner|winner team/user i}}<br /> {{hl2msg|byte|reason|reson why team won}}<br /> {{hl2msg|string|message|end round message}}<br /> {{end-hl2msg}}<br /> === round_end ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|round_end|string}}<br /> {{hl2msg|byte|winner|winner team/user i}}<br /> {{hl2msg|byte|reason|reson why team won}}<br /> {{hl2msg|string|message|end round message}}<br /> {{hl2msg|float|time|}}<br /> {{end-hl2msg}}<br /> === vote_ended ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|vote_ended|string}}<br /> {{hl2msg|None|None|}}<br /> {{end-hl2msg}}<br /> === vote_started ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|vote_started|string}}<br /> {{hl2msg|string|issue|}}<br /> {{hl2msg|string|param1|}}<br /> {{hl2msg|string|votedata|}}<br /> {{hl2msg|byte|team|}}<br /> {{hl2msg|long|initiator|entity id of the player who initiated the vote}}<br /> {{hl2msg|1|reliable|this event is reliable}}<br /> {{end-hl2msg}}<br /> <br /> === vote_changed ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|vote_changed|string}}<br /> {{hl2msg|byte|yesVotes|}}<br /> {{hl2msg|byte|noVotes|}}<br /> {{hl2msg|byte|potentialVotes|}}<br /> {{end-hl2msg}}<br /> === vote_passed ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|vote_passed|string}}<br /> {{hl2msg|string|details|}}<br /> {{hl2msg|string|param1|}}<br /> {{hl2msg|byte|team|}}<br /> {{hl2msg|1|reliable|this event is reliable}}<br /> {{end-hl2msg}}<br /> <br /> === vote_failed ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|vote_failed|string}}<br /> {{hl2msg|byte|team|}}<br /> {{hl2msg|1|reliable|this event is reliable}}<br /> {{end-hl2msg}}<br /> <br /> === vote_cast_yes ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|vote_cast_yes|string}}<br /> {{hl2msg|byte|team|}}<br /> {{hl2msg|long|entityid|entity id of the voter}}<br /> {{end-hl2msg}}<br /> === vote_cast_no ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|vote_cast_no|string}}<br /> {{hl2msg|byte|team|}}<br /> {{hl2msg|long|entityid|entity id of the voter}}<br /> {{end-hl2msg}}<br /> === infected_hurt ===<br /> {{qnotice|Registers for non-playable classes (Common Infected, Witch). See player_hurt for other playable classes}}&lt;br&gt;<br /> {{begin-hl2msg|infected_hurt|string}}<br /> {{hl2msg|1|local|don't network this, its way too spammy}}<br /> {{hl2msg|short|attacker|player userid who attacked}}<br /> {{hl2msg|long|entityid|entity id of infected}}<br /> {{hl2msg|byte|hitgroup|hitgroup that was damaged}}<br /> {{hl2msg|short|amount|how much damage was done}}<br /> {{hl2msg|long|type|damage type}}<br /> {{end-hl2msg}}<br /> === infected_death ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|infected_death|string}}<br /> {{hl2msg|short|attacker|user ID who killed}}<br /> {{hl2msg|short|infected_id|ID of the infected that died}}<br /> {{hl2msg|short|gender|gender (type) of the infected}}<br /> {{hl2msg|short|weapon_id|ID of the weapon used}}<br /> {{hl2msg|bool|headshot|signals a headshot}}<br /> {{hl2msg|bool|minigun|signals a minigun kill}}<br /> {{hl2msg|bool|blast|signals a death from blast damage}}<br /> {{hl2msg|bool|submerged|indicates the infected was submerged}}<br /> {{end-hl2msg}}<br /> === hostname_changed ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|hostname_changed|string}}<br /> {{hl2msg|string|hostname|}}<br /> {{end-hl2msg}}<br /> === difficulty_changed ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|difficulty_changed|string}}<br /> {{hl2msg|short|newDifficulty|}}<br /> {{hl2msg|short|oldDifficulty|}}<br /> {{end-hl2msg}}<br /> === finale_start ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|finale_start|string}}<br /> {{hl2msg|short|rushes|}}<br /> {{end-hl2msg}}<br /> === finale_rush ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|finale_rush|string}}<br /> {{hl2msg|None|None|}}<br /> {{end-hl2msg}}<br /> === finale_escape_start ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|finale_escape_start|string}}<br /> {{hl2msg|None|None|}}<br /> {{end-hl2msg}}<br /> === finale_vehicle_incoming ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|finale_vehicle_incoming|string}}<br /> {{hl2msg|string|campaign|}}<br /> {{end-hl2msg}}<br /> === finale_vehicle_ready ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|finale_vehicle_ready|string}}<br /> {{hl2msg|string|campaign|}}<br /> {{end-hl2msg}}<br /> === finale_vehicle_leaving ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|finale_vehicle_leaving|string}}<br /> {{hl2msg|short|survivorcount|number of survivors that made it out}}<br /> {{end-hl2msg}}<br /> === finale_win ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|finale_win|string}}<br /> {{hl2msg|string|map_name|}}<br /> {{hl2msg|short|difficulty|}}<br /> {{end-hl2msg}}<br /> === mission_lost ===<br /> {{qnotice|As in, the survivor team failed. Opposite of finale_win, but not necessarily during the finale.}}&lt;br&gt;<br /> {{begin-hl2msg|mission_lost|string}}<br /> {{hl2msg|None|None|}}<br /> {{end-hl2msg}}<br /> === finale_radio_start ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|finale_radio_start|string}}<br /> {{hl2msg|short|health|}}<br /> {{end-hl2msg}}<br /> === finale_radio_damaged ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|finale_radio_damaged|string}}<br /> {{hl2msg|short|health|}}<br /> {{end-hl2msg}}<br /> === final_reportscreen ===<br /> {{qnotice|Right before the final report screen comes up, let awards possibly fire}}&lt;br&gt;<br /> {{begin-hl2msg|final_reportscreen|string}}<br /> {{hl2msg|None|None|}}<br /> {{end-hl2msg}}<br /> === map_transition ===<br /> {{qnotice|When campaign cinematics start}}&lt;br&gt;<br /> {{begin-hl2msg|map_transition|string}}<br /> {{hl2msg|None|None|}}<br /> {{end-hl2msg}}<br /> <br /> === player_transitioned ===<br /> {{qnotice|When campaign cinematics end and player is transitioned to first person view}}&lt;br&gt;<br /> {{begin-hl2msg|player_transitioned|string}}<br /> {{hl2msg|short|userid|the person that just finished transitioning}}<br /> {{end-hl2msg}}<br /> <br /> === heal_begin ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|heal_begin|string}}<br /> {{hl2msg|short|userid|person doing the healing}}<br /> {{hl2msg|short|subject|person being healed}}<br /> {{end-hl2msg}}<br /> === heal_success ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|heal_success|string}}<br /> {{hl2msg|short|userid|person doing the healing}}<br /> {{hl2msg|short|subject|person being healed}}<br /> {{hl2msg|short|health_restored|amount of health restored}}<br /> {{end-hl2msg}}<br /> === heal_end ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{eventnote|Issues|subject is broken for this event, it always appears to be the player doing the healing}}<br /> {{begin-hl2msg|heal_end|string}}<br /> {{hl2msg|short|userid|person doing the healing}}<br /> {{hl2msg|short|subject|person being healed}}<br /> {{end-hl2msg}}<br /> <br /> === heal_interrupted ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|heal_interrupted|string}}<br /> {{hl2msg|short|userid|person who was being healed, but moved.}}<br /> {{hl2msg|short|subject|person being healed}}<br /> {{end-hl2msg}}<br /> === ammo_pack_used ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|ammo_pack_used|string}}<br /> {{hl2msg|short|userid|person giving the ammo}}<br /> {{hl2msg|short|subject|person receiving ammo}}<br /> {{end-hl2msg}}<br /> === give_weapon ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|give_weapon|string}}<br /> {{hl2msg|short|userid|The giver of the weapon}}<br /> {{hl2msg|short|recipient|The recipient of the weapon}}<br /> {{hl2msg|short|weapon|The ID of the weapon given}}<br /> {{end-hl2msg}}<br /> === pills_used ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|pills_used|string}}<br /> {{hl2msg|short|userid|person who had the pills}}<br /> {{hl2msg|short|subject|person swallowing the pills}}<br /> {{end-hl2msg}}<br /> === pills_used_fail ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|pills_used_fail|string}}<br /> {{hl2msg|short|userid|person who tried to use the pills}}<br /> {{end-hl2msg}}<br /> === ammo_pack_used_fail_no_weapon ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|ammo_pack_used_fail_no_weapon|string}}<br /> {{hl2msg|short|userid|person who tried to use the ammo pack}}<br /> {{hl2msg|short|subject|person it failed to help}}<br /> {{end-hl2msg}}<br /> === ammo_pack_used_fail_full ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|ammo_pack_used_fail_full|string}}<br /> {{hl2msg|short|userid|person who tried to use the ammo pack}}<br /> {{hl2msg|short|subject|person it failed to help}}<br /> {{end-hl2msg}}<br /> === ammo_pack_used_fail_doesnt_use_ammo ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|ammo_pack_used_fail_doesnt_use_ammo|string}}<br /> {{hl2msg|short|userid|person who tried to use the ammo pack}}<br /> {{hl2msg|short|subject|person it failed to help}}<br /> {{end-hl2msg}}<br /> === ammo_pile_weapon_cant_use_ammo ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|ammo_pile_weapon_cant_use_ammo|string}}<br /> {{hl2msg|short|userid|person who tried to use an ammo pile with a grenade launcher}}<br /> {{end-hl2msg}}<br /> === defibrillator_begin ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|defibrillator_begin|string}}<br /> {{hl2msg|short|userid|person who is defibrillating.}}<br /> {{hl2msg|short|subject|person being revived}}<br /> {{end-hl2msg}}<br /> === defibrillator_used ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|defibrillator_used|string}}<br /> {{hl2msg|short|userid|person who used the defibrillator}}<br /> {{hl2msg|short|subject|person it helped}}<br /> {{end-hl2msg}}<br /> === defibrillator_used_fail ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|defibrillator_used_fail|string}}<br /> {{hl2msg|short|userid|person who tried to use the defibrillator}}<br /> {{hl2msg|short|subject|person it failed to help}}<br /> {{end-hl2msg}}<br /> === defibrillator_interrupted ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|defibrillator_interrupted|string}}<br /> {{hl2msg|short|userid|person who was defibrillating, but moved.}}<br /> {{hl2msg|short|subject|person being revived}}<br /> {{end-hl2msg}}<br /> === upgrade_pack_begin ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|upgrade_pack_begin|string}}<br /> {{hl2msg|short|userid|person who is deploying the pack}}<br /> {{end-hl2msg}}<br /> === upgrade_pack_used ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|upgrade_pack_used|string}}<br /> {{hl2msg|short|upgradeid|}}<br /> {{hl2msg|short|userid|person who is deploying the pack}}<br /> {{end-hl2msg}}<br /> === upgrade_item_already_used ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|upgrade_item_already_used|string}}<br /> {{hl2msg|short|userid|person who tried to use an ammo upgrade twice}}<br /> {{hl2msg|string|upgradeclass|classname of the upgrade we tried to use}}<br /> {{end-hl2msg}}<br /> === upgrade_failed_no_primary ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|upgrade_failed_no_primary|string}}<br /> {{hl2msg|short|userid|person who tried to use an upgrade without having a primary weapon}}<br /> {{hl2msg|string|upgrade|name of the upgrade we tried to use, eg &quot;INCENDIARY_AMMO&quot;}}<br /> {{end-hl2msg}}<br /> === dead_survivor_visible ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|dead_survivor_visible|string}}<br /> {{hl2msg|short|userid|The player who sees the entity}}<br /> {{hl2msg|long|subject|Entindex of the entity they see}}<br /> {{hl2msg|short|deadplayer|user id of the dead player represented}}<br /> {{end-hl2msg}}<br /> === adrenaline_used ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|adrenaline_used|string}}<br /> {{hl2msg|short|userid|person who had and used the adrenaline}}<br /> {{end-hl2msg}}<br /> === revive_begin ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|revive_begin|string}}<br /> {{hl2msg|short|userid|person doing the reviving}}<br /> {{hl2msg|short|subject|person being revived}}<br /> {{end-hl2msg}}<br /> === revive_success ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|revive_success|string}}<br /> {{hl2msg|short|userid|person doing the reviving}}<br /> {{hl2msg|short|subject|person who was revived}}<br /> {{hl2msg|bool|lastlife|person revived will die if they fall again}}<br /> {{hl2msg|bool|ledge_hang|1 if person revived was ledge hanging}}<br /> {{end-hl2msg}}<br /> === revive_end ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|revive_end|string}}<br /> {{hl2msg|short|userid|person doing the reviving}}<br /> {{hl2msg|short|subject|person being revived}}<br /> {{hl2msg|bool|ledge_hang|person is ledge hanging}}<br /> {{end-hl2msg}}<br /> === drag_begin ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|drag_begin|string}}<br /> {{hl2msg|short|userid|person doing the dragging}}<br /> {{hl2msg|short|subject|person being dragged}}<br /> {{end-hl2msg}}<br /> === drag_end ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|drag_end|string}}<br /> {{hl2msg|short|userid|person doing the dragging}}<br /> {{hl2msg|short|subject|person being dragged}}<br /> {{end-hl2msg}}<br /> === player_incapacitated ===<br /> {{qnotice|when a player becomes incapacitated. This is also called when a tank is killed.}}&lt;br&gt;<br /> {{begin-hl2msg|player_incapacitated|string}}<br /> {{hl2msg|short|userid|person who became incapacitated}}<br /> {{hl2msg|short|attacker|user ID who made us incapacitated}}<br /> {{hl2msg|long|attackerentid|if attacker not player, entindex of who made us incapacitated}}<br /> {{hl2msg|string|weapon|weapon name attacker used}}<br /> {{hl2msg|long|type|damage type}}<br /> {{end-hl2msg}}<br /> === player_incapacitated_start ===<br /> {{qnotice|when a player is about to become incapacitated, so you can see his last living state}}&lt;br&gt;<br /> {{begin-hl2msg|player_incapacitated_start|string}}<br /> {{hl2msg|short|userid|person who became incapacitated}}<br /> {{hl2msg|short|attacker|user ID who made us incapacitated}}<br /> {{hl2msg|long|attackerentid|if attacker not player, entindex of who made us incapacitated}}<br /> {{hl2msg|string|weapon|weapon name attacker used}}<br /> {{hl2msg|long|type|damage type}}<br /> {{end-hl2msg}}<br /> === player_entered_start_area ===<br /> {{qnotice|when a player spawns into the player start area}}&lt;br&gt;<br /> {{begin-hl2msg|player_entered_start_area|string}}<br /> {{hl2msg|short|userid|person who entered}}<br /> {{end-hl2msg}}<br /> === player_first_spawn ===<br /> {{qnotice|when a player spawns for the first time in a given mission}}&lt;br&gt;<br /> {{begin-hl2msg|player_first_spawn|string}}<br /> {{hl2msg|short|userid|person who spawned}}<br /> {{hl2msg|string|map_name|}}<br /> {{hl2msg|bool|isbot|}}<br /> {{end-hl2msg}}<br /> {{qnotice|This Event doesnt exist anymore 1.10.2012}}&lt;br&gt;&lt;br&gt;<br /> <br /> === player_left_start_area ===<br /> {{qnotice|when a player leaves the player start area}}&lt;br&gt;<br /> {{begin-hl2msg|player_left_start_area|string}}<br /> {{hl2msg|short|userid|person who left}}<br /> {{end-hl2msg}}<br /> === player_entered_checkpoint ===<br /> {{qnotice|when a basecombatcharacter enters a checkpoint area}}&lt;br&gt;<br /> {{begin-hl2msg|player_entered_checkpoint|string}}<br /> {{hl2msg|short|userid|player who entered}}<br /> {{hl2msg|long|entityid|If not a player, the entity index of the one entering}}<br /> {{hl2msg|long|door|Entindex of the checkpoint door the player entered to get here.}}<br /> {{hl2msg|long|area|}}<br /> {{hl2msg|string|doorname|name of the entity they see}}<br /> {{end-hl2msg}}<br /> === player_left_checkpoint ===<br /> {{qnotice|when a player leaves a checkpoint area}}&lt;br&gt;<br /> {{begin-hl2msg|player_left_checkpoint|string}}<br /> {{hl2msg|short|userid|player who left}}<br /> {{hl2msg|long|entityid|If not a player, the entity index of the one exiting}}<br /> {{hl2msg|long|area|}}<br /> {{end-hl2msg}}<br /> === player_shoved ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|player_shoved|string}}<br /> {{hl2msg|short|userid|player index who was shoved}}<br /> {{hl2msg|short|attacker|player index who attacked them}}<br /> {{end-hl2msg}}<br /> === entity_shoved ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|entity_shoved|string}}<br /> {{hl2msg|short|entityid|the entity index of the one who was shoved}}<br /> {{hl2msg|short|attacker|player index who attacked them}}<br /> {{end-hl2msg}}<br /> === player_jump_apex ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|player_jump_apex|string}}<br /> {{hl2msg|short|userid|player who jumped}}<br /> {{end-hl2msg}}<br /> === player_blocked ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|player_blocked|string}}<br /> {{hl2msg|short|userid|player index who was trying to move}}<br /> {{hl2msg|short|blocker|player index who kept them from moving}}<br /> {{end-hl2msg}}<br /> === player_now_it ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|player_now_it|string}}<br /> {{hl2msg|short|userid|Player who is now it}}<br /> {{hl2msg|short|attacker|player that did the it-ing}}<br /> {{hl2msg|bool|exploded|whether it was vomit or explosion}}<br /> {{hl2msg|bool|infected|is the vomit infectious}}<br /> {{hl2msg|bool|by_boomer|came from a boomer}}<br /> {{end-hl2msg}}<br /> === player_no_longer_it ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|player_no_longer_it|string}}<br /> {{hl2msg|short|userid|Player who is now no longer it}}<br /> {{end-hl2msg}}<br /> === witch_harasser_set ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|witch_harasser_set|string}}<br /> {{hl2msg|short|userid|Player who woke up the witch}}<br /> {{hl2msg|long|witchid|Entindex of witch woken up}}<br /> {{hl2msg|bool|first|First time the witch set a harasser}}<br /> {{end-hl2msg}}<br /> === witch_spawn ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|witch_spawn|string}}<br /> {{hl2msg|long|witchid|Entindex of witch spawning right now.}}<br /> {{end-hl2msg}}<br /> === witch_killed ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|witch_killed|string}}<br /> {{hl2msg|short|userid|Player who killed the witch}}<br /> {{hl2msg|long|witchid|Entindex of witch that was killed.}}<br /> {{hl2msg|bool|oneshot|TRUE if the Witch was killed with one shot}}<br /> {{end-hl2msg}}<br /> === tank_spawn ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|tank_spawn|string}}<br /> {{hl2msg|short|userid|User ID of the tank spawning now}}<br /> {{hl2msg|long|tankid|Entindex of tank spawning right now.}}<br /> {{end-hl2msg}}<br /> === melee_kill ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|melee_kill|string}}<br /> {{hl2msg|short|userid|Player who bashed the infected}}<br /> {{hl2msg|long|entityid|Entindex of infected what got killed}}<br /> {{hl2msg|bool|ambush|Infected was unaware when killed}}<br /> {{end-hl2msg}}<br /> === area_cleared ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|area_cleared|string}}<br /> {{hl2msg|short|userid|person who cleared the area}}<br /> {{hl2msg|long|area|id of the cleared area}}<br /> {{end-hl2msg}}<br /> === award_earned ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|award_earned|string}}<br /> {{hl2msg|short|userid|player who earned the award}}<br /> {{hl2msg|long|entityid|client likes ent id}}<br /> {{hl2msg|long|subjectentid|entity id of other party in the award, if any}}<br /> {{hl2msg|short|award|id of award earned}}<br /> {{end-hl2msg}}<br /> === tongue_grab ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|tongue_grab|string}}<br /> {{hl2msg|short|userid|player who did the grabbing}}<br /> {{hl2msg|short|victim|player that got grabbed}}<br /> {{end-hl2msg}}<br /> === tongue_broke_bent ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|tongue_broke_bent|string}}<br /> {{hl2msg|short|userid|Tongue owner}}<br /> {{end-hl2msg}}<br /> === tongue_broke_victim_died ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|tongue_broke_victim_died|string}}<br /> {{hl2msg|short|userid|Tongue owner}}<br /> {{end-hl2msg}}<br /> === tongue_release ===<br /> {{qnotice|Fired in all cases where the tongue releases a victim, whether choked or not, etc.}}&lt;br&gt;<br /> {{begin-hl2msg|tongue_release|string}}<br /> {{hl2msg|short|userid|The tongue owner}}<br /> {{hl2msg|short|victim|The (now released) victim}}<br /> {{hl2msg|long|distance|Distance the victim was dragged.}}<br /> {{end-hl2msg}}<br /> <br /> === choke_start ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|choke_start|string}}<br /> {{hl2msg|short|userid|The choker}}<br /> {{hl2msg|short|victim|The person being choked}}<br /> {{end-hl2msg}}<br /> === choke_end ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|choke_end|string}}<br /> {{hl2msg|short|userid|The choker}}<br /> {{hl2msg|short|victim|The person being choked}}<br /> {{end-hl2msg}}<br /> === choke_stopped ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|choke_stopped|string}}<br /> {{hl2msg|short|userid|Who stopped it}}<br /> {{hl2msg|short|victim|And who was being choked}}<br /> {{hl2msg|short|smoker|The tongue owner}}<br /> {{hl2msg|short|release_type|How did it break?}}<br /> {{end-hl2msg}}<br /> === tongue_pull_stopped ===<br /> {{qnotice|Called when a smoker tongue is cleared on a dragging player. Includes cuts.}}&lt;br&gt;<br /> {{begin-hl2msg|tongue_pull_stopped|string}}<br /> {{hl2msg|short|userid|Who stopped it}}<br /> {{hl2msg|short|victim|And who was being pulled}}<br /> {{hl2msg|short|smoker|The tongue owner}}<br /> {{hl2msg|short|release_type|How did it break?}}<br /> {{end-hl2msg}}<br /> <br /> === lunge_shove ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|lunge_shove|string}}<br /> {{hl2msg|short|userid|player who did the lunging}}<br /> {{hl2msg|short|victim|player that got lunged}}<br /> {{end-hl2msg}}<br /> === lunge_pounce ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|lunge_pounce|string}}<br /> {{hl2msg|short|userid|player who did the lunging}}<br /> {{hl2msg|short|victim|player that got lunged}}<br /> {{hl2msg|long|distance|Distance from pounce start to contact}}<br /> {{end-hl2msg}}<br /> === pounce_end ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|pounce_end|string}}<br /> {{hl2msg|short|userid|Who stopped it}}<br /> {{hl2msg|short|victim|And who was being pounced}}<br /> {{end-hl2msg}}<br /> === pounce_stopped ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|pounce_stopped|string}}<br /> {{hl2msg|short|userid|Who stopped it}}<br /> {{hl2msg|short|victim|And who was being pounced}}<br /> {{end-hl2msg}}<br /> === fatal_vomit ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|fatal_vomit|string}}<br /> {{hl2msg|short|userid|Who vomited}}<br /> {{hl2msg|short|victim|And who was killed or incapped}}<br /> {{end-hl2msg}}<br /> === survivor_call_for_help ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|survivor_call_for_help|string}}<br /> {{hl2msg|short|userid|The actual player entity who is awaiting rescue.}}<br /> {{hl2msg|long|subject|SurvivorRescue entity representing the player who needs to be rescued from the closet (used for position)}}<br /> {{end-hl2msg}}<br /> === survivor_rescued ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|survivor_rescued|string}}<br /> {{hl2msg|short|rescuer|player that did the rescuing}}<br /> {{hl2msg|short|victim|the survivor being rescued}}<br /> {{end-hl2msg}}<br /> === survivor_rescue_abandoned ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|survivor_rescue_abandoned|string}}<br /> {{hl2msg|None|None|}}<br /> {{end-hl2msg}}<br /> === relocated ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|relocated|string}}<br /> {{hl2msg|short|userid|player who was relocated}}<br /> {{end-hl2msg}}<br /> === respawning ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|respawning|string}}<br /> {{hl2msg|short|userid|player who started respawning}}<br /> {{end-hl2msg}}<br /> === tank_frustrated ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|tank_frustrated|string}}<br /> {{hl2msg|short|userid|player who was culled}}<br /> {{end-hl2msg}}<br /> === weapon_given ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|weapon_given|string}}<br /> {{hl2msg|short|userid|player who got the weapon}}<br /> {{hl2msg|short|giver|player that did the giving}}<br /> {{hl2msg|short|weapon|weapon id given}}<br /> {{hl2msg|short|weaponentid|weapon entity id}}<br /> {{end-hl2msg}}<br /> === weapon_drop ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{eventnote|Called|When an item is removed from a survivor's inventory}}<br /> {{eventnote|Related Events|Called before heal_success, defibrillator_used, upgrade_pack_used, but called after pills_used and adrenaline_used}}<br /> {{begin-hl2msg|weapon_drop|string}}<br /> {{hl2msg|short|userid|player who dropped the weapon}}<br /> {{hl2msg|string|item|either a weapon such as 'tmp' or 'hegrenade', or an item such as 'nvgs'}}<br /> {{hl2msg|short|propid|entindex of the dropped weapon}}<br /> {{end-hl2msg}}<br /> === break_breakable ===<br /> {{qnotice|Override from gameevents.res}}&lt;br&gt;<br /> {{begin-hl2msg|break_breakable|string}}<br /> {{hl2msg|short|userid|userid of breaker}}<br /> {{hl2msg|long|entindex|entindex of thing breaking}}<br /> {{hl2msg|byte|material|BREAK_GLASS, BREAK_WOOD, etc}}<br /> {{hl2msg|bool|hulkonly|SF_BREAK_HULK_ONLY}}<br /> {{end-hl2msg}}<br /> === achievement_earned ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|achievement_earned|string}}<br /> {{hl2msg|byte|player|entindex of the player}}<br /> {{hl2msg|short|achievement|achievement ID}}<br /> {{end-hl2msg}}<br /> === spec_target_updated ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|spec_target_updated|string}}<br /> {{hl2msg|None|None|}}<br /> {{end-hl2msg}}<br /> === spawner_give_item ===<br /> {{qnotice|A spawner has given a player an item (weapon, pills, ammo, health kit, etc)}}&lt;br&gt;<br /> {{begin-hl2msg|spawner_give_item|string}}<br /> {{hl2msg|short|userid|Item recipient}}<br /> {{hl2msg|string|item|Name of item given}}<br /> {{hl2msg|long|spawner|entindex of the spawner entity}}<br /> {{end-hl2msg}}<br /> === create_panic_event ===<br /> {{qnotice|A panic event has been created, though not necessarily started}}&lt;br&gt;<br /> {{begin-hl2msg|create_panic_event|string}}<br /> {{hl2msg|short|userid|player who was started the panic}}<br /> {{end-hl2msg}}<br /> === explain_pills ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_pills|string}}<br /> {{hl2msg|long|subject|The weapon_pain_pills spawner that will be indicated}}<br /> {{end-hl2msg}}<br /> === explain_weapons ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_weapons|string}}<br /> {{hl2msg|long|subject|The weapon_pain_pills spawner that will be indicated}}<br /> {{end-hl2msg}}<br /> === entity_visible ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|entity_visible|string}}<br /> {{hl2msg|short|userid|The player who sees the entity}}<br /> {{hl2msg|long|subject|Entindex of the entity they see}}<br /> {{hl2msg|string|classname|Classname of the entity they see}}<br /> {{hl2msg|string|entityname|name of the entity they see}}<br /> {{end-hl2msg}}<br /> === weapon_spawn_visible ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|weapon_spawn_visible|string}}<br /> {{hl2msg|short|userid|The player who sees the entity}}<br /> {{hl2msg|long|subject|Entindex of the entity they see}}<br /> {{hl2msg|string|weaponname|weapon name, or &quot;melee&quot;}}<br /> {{hl2msg|string|subtype|melee weapon name}}<br /> {{end-hl2msg}}<br /> === boomer_near ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|boomer_near|string}}<br /> {{hl2msg|short|userid|The boomer}}<br /> {{hl2msg|short|victim|The survivor whom the boomer has gotten very close to}}<br /> {{end-hl2msg}}<br /> === explain_pre_radio ===<br /> {{qnotice|explain the rescue radio will remind you to ready for the finale}}&lt;br&gt;<br /> {{begin-hl2msg|explain_pre_radio|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === started_pre_radio ===<br /> {{qnotice|explain the rescue radio will remind you to ready for the finale}}&lt;br&gt;<br /> {{begin-hl2msg|started_pre_radio|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_radio ===<br /> {{qnotice|explain the rescue radio will start the finale}}&lt;br&gt;<br /> {{begin-hl2msg|explain_radio|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_gas_truck ===<br /> {{qnotice|explain how pulling the lever on the gas truck will start the finale}}&lt;br&gt;<br /> {{begin-hl2msg|explain_gas_truck|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|The lever}}<br /> {{end-hl2msg}}<br /> === explain_panic_button ===<br /> {{qnotice|explain that pressing this button will start a panic event.}}&lt;br&gt;<br /> {{begin-hl2msg|explain_panic_button|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|The panic button}}<br /> {{end-hl2msg}}<br /> === explain_elevator_button ===<br /> {{qnotice|explain how to operate the hospital elevator button.}}&lt;br&gt;<br /> {{begin-hl2msg|explain_elevator_button|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|The button}}<br /> {{end-hl2msg}}<br /> === explain_lift_button ===<br /> {{qnotice|explain how to operate the lift button.}}&lt;br&gt;<br /> {{begin-hl2msg|explain_lift_button|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|The lift button}}<br /> {{end-hl2msg}}<br /> === explain_church_door ===<br /> {{qnotice|explain how to provoke the crazy church guy.}}&lt;br&gt;<br /> {{begin-hl2msg|explain_church_door|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|The saferoom door}}<br /> {{end-hl2msg}}<br /> === explain_emergency_door ===<br /> {{qnotice|explain how to open the emergency door.}}&lt;br&gt;<br /> {{begin-hl2msg|explain_emergency_door|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|The door}}<br /> {{end-hl2msg}}<br /> === explain_crane ===<br /> {{qnotice|explain how to lower the box on the crane.}}&lt;br&gt;<br /> {{begin-hl2msg|explain_crane|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|The lever/button}}<br /> {{end-hl2msg}}<br /> === explain_bridge ===<br /> {{qnotice|explain how to close the gates to make a bridge.}}&lt;br&gt;<br /> {{begin-hl2msg|explain_bridge|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|The button}}<br /> {{end-hl2msg}}<br /> === explain_gas_can_panic ===<br /> {{qnotice|explain how to shoot the gas can.}}&lt;br&gt;<br /> {{begin-hl2msg|explain_gas_can_panic|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|The gas can}}<br /> {{end-hl2msg}}<br /> === explain_van_panic ===<br /> {{qnotice|explain how to start the van.}}&lt;br&gt;<br /> {{begin-hl2msg|explain_van_panic|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|The van}}<br /> {{end-hl2msg}}<br /> === explain_mainstreet ===<br /> {{qnotice|explain how to lower the forklift}}&lt;br&gt;<br /> {{begin-hl2msg|explain_mainstreet|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|The forklift}}<br /> {{end-hl2msg}}<br /> === explain_train_lever ===<br /> {{qnotice|explain how to operate the train lever.}}&lt;br&gt;<br /> {{begin-hl2msg|explain_train_lever|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|The lever on box car}}<br /> {{end-hl2msg}}<br /> === explain_disturbance ===<br /> {{qnotice|explain that disturbances (car alarm) attract infected horde}}&lt;br&gt;<br /> {{begin-hl2msg|explain_disturbance|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|The source of disturbance}}<br /> {{end-hl2msg}}<br /> === explain_scavenge_goal ===<br /> {{qnotice|explain where to put the scavenge mode items}}&lt;br&gt;<br /> {{begin-hl2msg|explain_scavenge_goal|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|The collection device}}<br /> {{end-hl2msg}}<br /> === explain_scavenge_leave_area ===<br /> {{qnotice|explain that leaving the area, starts round}}&lt;br&gt;<br /> {{begin-hl2msg|explain_scavenge_leave_area|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|The entity}}<br /> {{end-hl2msg}}<br /> === begin_scavenge_overtime ===<br /> {{qnotice|enter overtime in a scavenge round}}&lt;br&gt;<br /> {{begin-hl2msg|begin_scavenge_overtime|string}}<br /> {{end-hl2msg}}<br /> === scavenge_round_start ===<br /> {{qnotice|a scavenge round has begun}}&lt;br&gt;<br /> {{begin-hl2msg|scavenge_round_start|string}}<br /> {{hl2msg|byte|round|round number, 1 based}}<br /> {{hl2msg|bool|firsthalf|start of the first half of the round}}<br /> {{end-hl2msg}}<br /> <br /> === scavenge_round_halftime ===<br /> {{qnotice|a scavenge round is in halftime}}&lt;br&gt;<br /> {{begin-hl2msg|scavenge_round_halftime|string}}<br /> {{end-hl2msg}}<br /> === scavenge_round_finished ===<br /> {{qnotice|a scavenge round has ended}}&lt;br&gt;<br /> {{begin-hl2msg|scavenge_round_finished|string}}<br /> {{end-hl2msg}}<br /> === scavenge_score_tied ===<br /> {{qnotice|a team just tied the score}}&lt;br&gt;<br /> {{begin-hl2msg|scavenge_score_tied|string}}<br /> {{end-hl2msg}}<br /> === versus_round_start ===<br /> {{qnotice|a versus round has begun}}&lt;br&gt;<br /> {{begin-hl2msg|versus_round_start|string}}<br /> {{end-hl2msg}}<br /> === gascan_pour_blocked ===<br /> {{qnotice|can't pour the gas, someone else already is}}&lt;br&gt;<br /> {{begin-hl2msg|gascan_pour_blocked|string}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}<br /> === gascan_pour_completed ===<br /> {{qnotice|player finished pouring a can}}&lt;br&gt;<br /> {{begin-hl2msg|gascan_pour_completed|string}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}<br /> === gascan_dropped ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|gascan_dropped|string}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}<br /> === gascan_pour_interrupted ===<br /> {{qnotice|we got interuppted pouring the gas can}}&lt;br&gt;<br /> {{begin-hl2msg|gascan_pour_interrupted|string}}<br /> {{hl2msg|short|userid|person who interuppted us}}<br /> {{end-hl2msg}}<br /> === scavenge_match_finished ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|scavenge_match_finished|string}}<br /> {{hl2msg|byte|winners|winner team}}<br /> {{end-hl2msg}}<br /> === versus_match_finished ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|versus_match_finished|string}}<br /> {{hl2msg|byte|winners|winner team}}<br /> {{end-hl2msg}}<br /> === use_target ===<br /> {{qnotice|a new use target has been found}}&lt;br&gt;<br /> {{begin-hl2msg|use_target|string}}<br /> {{hl2msg|long|targetid|Entindex of the use target}}<br /> {{hl2msg|string|classname|classname of the use target}}<br /> {{hl2msg|bool|isprop|is this a prop that can be carried}}<br /> {{end-hl2msg}}<br /> === player_use ===<br /> {{qnotice|a new use target has been found}}&lt;br&gt;<br /> {{eventnote|Called|When a Survivor presses +USE on a useable entity. i.e. Weapons, items, doors}}<br /> {{eventnote|Related Events|If targetid is an item, item_pickup will be called prior to player_use}}<br /> {{begin-hl2msg|player_use|string}}<br /> {{hl2msg|short|userid|userid of user}}<br /> {{hl2msg|long|targetid|Entindex of the used entity}}<br /> {{end-hl2msg}}<br /> === friendly_fire ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|friendly_fire|string}}<br /> {{hl2msg|short|attacker|player who fired the weapon}}<br /> {{hl2msg|short|victim|player who got shot}}<br /> {{hl2msg|short|guilty|player who was at fault}}<br /> {{hl2msg|long|type|damage type}}<br /> {{end-hl2msg}}<br /> === gameinstructor_draw ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|gameinstructor_draw|string}}<br /> {{hl2msg|None|None|}}<br /> {{end-hl2msg}}<br /> === gameinstructor_nodraw ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|gameinstructor_nodraw|string}}<br /> {{hl2msg|None|None|}}<br /> {{end-hl2msg}}<br /> === request_weapon_stats ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|request_weapon_stats|string}}<br /> {{hl2msg|short|userid|userid of user requesting their stats}}<br /> {{end-hl2msg}}<br /> === player_talking_state ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|player_talking_state|string}}<br /> {{hl2msg|byte|player|}}<br /> {{hl2msg|bool|istalking|}}<br /> {{end-hl2msg}}<br /> === weapon_pickup ===<br /> {{qnotice|client event for player has picked up a weapon}}&lt;br&gt;<br /> {{begin-hl2msg|weapon_pickup|string}}<br /> {{hl2msg|byte|context|split screen message context}}<br /> {{hl2msg|byte|weaponid|}}<br /> {{hl2msg|byte|weaponslot|}}<br /> {{hl2msg|byte|dropped_by_infected|gender of the Infected that dropped the weapon}}<br /> {{end-hl2msg}}<br /> <br /> === hunter_punched ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|hunter_punched|string}}<br /> {{hl2msg|short|userid|player who caused ignition}}<br /> {{hl2msg|long|hunteruserid|user ID of Hunter}}<br /> {{hl2msg|bool|islunging|TRUE if the Hunter was in the act of lunging}}<br /> {{end-hl2msg}}<br /> === hunter_headshot ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|hunter_headshot|string}}<br /> {{hl2msg|short|userid|player who made the headshot}}<br /> {{hl2msg|long|hunteruserid|user ID of Hunter}}<br /> {{hl2msg|bool|islunging|TRUE if the Hunter was in the act of lunging}}<br /> {{end-hl2msg}}<br /> === zombie_ignited ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|zombie_ignited|string}}<br /> {{hl2msg|short|userid|player who caused ignition}}<br /> {{hl2msg|short|gender|gender (type) of the infected}}<br /> {{hl2msg|long|entityid|entity ID of Tank}}<br /> {{hl2msg|string|victimname|&quot;Witch&quot;, &quot;Tank&quot;, &quot;Hunter&quot;, &quot;Smoker&quot;, or &quot;Infected&quot;}}<br /> {{hl2msg|bool|fire_ammo|true if incendiary ammo was used}}<br /> {{end-hl2msg}}<br /> === boomer_exploded ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|boomer_exploded|string}}<br /> {{hl2msg|short|userid|Boomer that exploded}}<br /> {{hl2msg|short|attacker|player who caused the explosion}}<br /> {{hl2msg|bool|splashedbile|Exploding boomer splashed bile on Survivors}}<br /> {{end-hl2msg}}<br /> === non_pistol_fired ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|non_pistol_fired|string}}<br /> {{hl2msg|short|userid|User that fired a non-pistol weapon}}<br /> {{end-hl2msg}}<br /> === weapon_fire_at_40 ===<br /> {{qnotice|This is networked, special event for game instructor}}&lt;br&gt;<br /> {{begin-hl2msg|weapon_fire_at_40|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|string|weapon|used weapon name}}<br /> {{hl2msg|short|weaponid|used weapon ID}}<br /> {{hl2msg|short|count|number of bullets}}<br /> {{end-hl2msg}}<br /> <br /> === total_ammo_below_40 ===<br /> {{qnotice|sent for any ammo type, except those with max ammo 1, or infinite ammo, like pistols}}&lt;br&gt;<br /> {{begin-hl2msg|total_ammo_below_40|string}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}<br /> === player_hurt_concise ===<br /> {{qnotice|Abbreviated version of 'player_hurt' that is networked}}&lt;br&gt;<br /> {{begin-hl2msg|player_hurt_concise|string}}<br /> {{hl2msg|short|userid|user ID who was hurt}}<br /> {{hl2msg|long|attackerentid|entity id who attacked, if attacker not a player, and userid therefore invalid}}<br /> {{hl2msg|long|type|damage type}}<br /> {{hl2msg|short|dmg_health|damage done to health}}<br /> {{end-hl2msg}}<br /> <br /> === tank_killed ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|tank_killed|string}}<br /> {{hl2msg|short|userid|user ID of dead tank}}<br /> {{hl2msg|short|attacker|user id of killer}}<br /> {{hl2msg|bool|solo|TRUE if a player single-handedly killed the Tank}}<br /> {{hl2msg|bool|melee_only|TRUE if the tank was only killed by melee attacks (no blast, burn, or bullet damage)}}<br /> {{hl2msg|bool|l4d1_only|TRUE if l4d1 survivors inflicted damage and the l4d2 survivors did not)}}<br /> {{end-hl2msg}}<br /> <br /> === achievement_write_failed ===<br /> {{qnotice|Used for a notification message when an achievement fails to write}}&lt;br&gt;<br /> {{begin-hl2msg|achievement_write_failed|string}}<br /> {{hl2msg|None|None|}}<br /> {{end-hl2msg}}<br /> <br /> === ghost_spawn_time ===<br /> {{qnotice|Used for clients to know how long until they become a ghost (and can spawn)}}&lt;br&gt;<br /> {{begin-hl2msg|ghost_spawn_time|string}}<br /> {{hl2msg|short|userid|user ID of the player that is becoming a ghost}}<br /> {{hl2msg|short|spawntime|How long of a wait until player is a ghost}}<br /> {{end-hl2msg}}<br /> <br /> === survival_at_30min ===<br /> {{qnotice|Used to know when we elapse 30 minutes on a survival map}}&lt;br&gt;<br /> {{begin-hl2msg|survival_at_30min|string}}<br /> {{end-hl2msg}}<br /> === explain_pre_drawbridge ===<br /> {{qnotice|Point out the button that will start the gauntlet finale.}}&lt;br&gt;<br /> {{begin-hl2msg|explain_pre_drawbridge|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_drawbridge ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_drawbridge|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_perimeter ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_perimeter|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_deactivate_alarm ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_deactivate_alarm|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_impound_lot ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_impound_lot|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_decon ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_decon|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_mall_window ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_mall_window|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_mall_alarm ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_mall_alarm|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_coaster ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_coaster|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_coaster_stop ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_coaster_stop|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_decon_wait ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_decon_wait|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === gauntlet_finale_start ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|gauntlet_finale_start|string}}<br /> {{end-hl2msg}}<br /> === explain_float ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_float|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_ferry_button ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_ferry_button|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_hatch_button ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_hatch_button|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_shack_button ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_shack_button|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === upgrade_incendiary_ammo ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|upgrade_incendiary_ammo|string}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}<br /> === upgrade_explosive_ammo ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|upgrade_explosive_ammo|string}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}<br /> === receive_upgrade ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|receive_upgrade|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|string|upgrade|}}<br /> {{end-hl2msg}}<br /> === explain_vehicle_arrival ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_vehicle_arrival|string}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === mounted_gun_start ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|mounted_gun_start|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === mounted_gun_overheated ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|mounted_gun_overheated|string}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}<br /> === explain_burger_sign ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_burger_sign|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_carousel_button ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_carousel_button|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_carousel_destination ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_carousel_destination|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_stage_lighting ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_stage_lighting|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_stage_finale_start ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_stage_finale_start|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_stage_survival_start ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_stage_survival_start|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === ability_out_of_range ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|ability_out_of_range|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|string|ability|ability classname}}<br /> {{end-hl2msg}}<br /> === explain_stage_pyrotechnics ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_stage_pyrotechnics|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_c3m4_radio1 ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_c3m4_radio1|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_c3m4_radio2 ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_c3m4_radio2|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_gates_are_open ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_gates_are_open|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_c2m4_ticketbooth ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_c2m4_ticketbooth|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_c3m4_rescue ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_c3m4_rescue|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_hotel_elevator_doors ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_hotel_elevator_doors|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_gun_shop_tanker ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_gun_shop_tanker|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_gun_shop ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_gun_shop|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_store_alarm ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_store_alarm|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_store_item ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_store_item|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_store_item_stop ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_store_item_stop|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_survival_generic ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_survival_generic|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_survival_alarm ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_survival_alarm|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_survival_radio ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_survival_radio|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_survival_carousel ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_survival_carousel|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_return_item ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_return_item|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_save_items ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_save_items|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === spit_burst ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|spit_burst|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === entered_spit ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|entered_spit|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === temp_c4m1_getgas ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|temp_c4m1_getgas|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === temp_c4m3_return_to_boat ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|temp_c4m3_return_to_boat|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_c1m4_finale ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_c1m4_finale|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === c1m4_scavenge_instructions ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|c1m4_scavenge_instructions|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === punched_clown ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|punched_clown|string}}<br /> {{hl2msg|short|userid|player who punched the clown}}<br /> {{end-hl2msg}}<br /> === charger_killed ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|charger_killed|string}}<br /> {{hl2msg|short|userid|user ID of dead charger}}<br /> {{hl2msg|short|attacker|user id of killer}}<br /> {{hl2msg|bool|melee|TRUE if a player killed the charger with a melee weapon}}<br /> {{hl2msg|bool|charging|TRUE if the charger was charging when it died}}<br /> {{end-hl2msg}}<br /> === spitter_killed ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|spitter_killed|string}}<br /> {{hl2msg|short|userid|user ID of dead spitter}}<br /> {{hl2msg|short|attacker|user id of killer}}<br /> {{hl2msg|bool|has_spit|TRUE if the spitter spit at some point}}<br /> {{end-hl2msg}}<br /> === jockey_ride ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|jockey_ride|string}}<br /> {{hl2msg|short|userid|player who did the lunging}}<br /> {{hl2msg|short|victim|player that got lunged}}<br /> {{end-hl2msg}}<br /> === jockey_ride_end ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|jockey_ride_end|string}}<br /> {{hl2msg|short|userid|player who did the lunging}}<br /> {{hl2msg|short|victim|player that got lunged}}<br /> {{hl2msg|short|rescuer|Who stopped it}}<br /> {{hl2msg|float|ride_length|Duration of our ride}}<br /> {{end-hl2msg}}<br /> === jockey_killed ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|jockey_killed|string}}<br /> {{hl2msg|short|userid|user ID of dead jockey}}<br /> {{hl2msg|short|attacker|user id of killer}}<br /> {{end-hl2msg}}<br /> === non_melee_fired ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|non_melee_fired|string}}<br /> {{hl2msg|short|userid|User that fired a non-melee weapon}}<br /> {{end-hl2msg}}<br /> === infected_decapitated ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|infected_decapitated|string}}<br /> {{hl2msg|short|userid|userid of the player who did the decapitation}}<br /> {{hl2msg|string|weapon|melee weapon name}}<br /> {{end-hl2msg}}<br /> <br /> === upgrade_pack_added ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|upgrade_pack_added|string}}<br /> {{hl2msg|short|upgradeid|}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}<br /> === vomit_bomb_tank ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|vomit_bomb_tank|string}}<br /> {{hl2msg|short|userid|userid of the player who used the bomb}}<br /> {{end-hl2msg}}<br /> === triggered_car_alarm ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|triggered_car_alarm|string}}<br /> {{end-hl2msg}}<br /> === panic_event_finished ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|panic_event_finished|string}}<br /> {{end-hl2msg}}<br /> === charger_charge_start ===<br /> {{qnotice|The moment when the charger starts charging}}&lt;br&gt;<br /> {{begin-hl2msg|charger_charge_start|string}}<br /> {{hl2msg|short|userid|user ID of the charger}}<br /> {{end-hl2msg}}<br /> === charger_charge_end ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|charger_charge_end|string}}<br /> {{hl2msg|short|userid|user ID of the charger}}<br /> {{end-hl2msg}}<br /> === charger_carry_start ===<br /> {{qnotice|The moment when the charger grabs a survivor}}&lt;br&gt;<br /> {{begin-hl2msg|charger_carry_start|string}}<br /> {{hl2msg|short|userid|user ID of the charger}}<br /> {{hl2msg|short|victim|user ID of the player who was charged}}<br /> {{end-hl2msg}}<br /> === charger_carry_end ===<br /> {{qnotice|The moment when the charger stops charging a survivor (and will soon start pummeling)}}&lt;br&gt;<br /> {{begin-hl2msg|charger_carry_end|string}}<br /> {{hl2msg|short|userid|user ID of the charger}}<br /> {{hl2msg|short|victim|user ID of the player who was charged}}<br /> {{end-hl2msg}}<br /> === charger_impact ===<br /> {{qnotice|When a charger impacts a survivor they aren't carrying}}&lt;br&gt;<br /> {{begin-hl2msg|charger_impact|string}}<br /> {{hl2msg|short|userid|user ID of the charger}}<br /> {{hl2msg|short|victim|user ID of the player who was impacted}}<br /> {{end-hl2msg}}<br /> === charger_pummel_start ===<br /> {{qnotice|The moment when the charger starts pummeling a survivor}}&lt;br&gt;<br /> {{begin-hl2msg|charger_pummel_start|string}}<br /> {{hl2msg|short|userid|user ID of the charger}}<br /> {{hl2msg|short|victim|user ID of the player who was charged}}<br /> {{end-hl2msg}}<br /> === charger_pummel_end ===<br /> {{qnotice|When the charger is cleared from the survivor or the survivor dies.}}&lt;br&gt;<br /> {{begin-hl2msg|charger_pummel_end|string}}<br /> {{hl2msg|short|userid|user ID of the charger}}<br /> {{hl2msg|short|victim|}}<br /> {{hl2msg|short|rescuer|user ID of the player who rescued them}}<br /> {{end-hl2msg}}<br /> === strongman_bell_knocked_off ===<br /> {{qnotice|The arcade bell on c2m4_barns}}&lt;br&gt;<br /> {{begin-hl2msg|strongman_bell_knocked_off|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|short|subject|}}<br /> {{end-hl2msg}}<br /> === molotov_thrown ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|molotov_thrown|string}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}<br /> === gas_can_forced_drop ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|gas_can_forced_drop|string}}<br /> {{hl2msg|short|userid|player that forced the drop}}<br /> {{hl2msg|short|victim|player that dropped it}}<br /> {{end-hl2msg}}<br /> === explain_need_gnome_to_continue ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_need_gnome_to_continue|string}}<br /> {{hl2msg|none|none|}}<br /> {{end-hl2msg}}<br /> === explain_survivor_glows_disabled ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_survivor_glows_disabled|string}}<br /> {{hl2msg|short|userid|The player we're explaining to}}<br /> {{end-hl2msg}}<br /> === explain_item_glows_disabled ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_item_glows_disabled|string}}<br /> {{hl2msg|short|userid|The player we're explaining to}}<br /> {{end-hl2msg}}<br /> === explain_rescue_disabled ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_rescue_disabled|string}}<br /> {{hl2msg|short|userid|The player we're explaining to}}<br /> {{end-hl2msg}}<br /> === explain_bodyshots_reduced ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_bodyshots_reduced|string}}<br /> {{hl2msg|short|userid|The player we're explaining to}}<br /> {{end-hl2msg}}<br /> === explain_witch_instant_kill ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_witch_instant_kill|string}}<br /> {{hl2msg|short|userid|The player we're explaining to}}<br /> {{end-hl2msg}}<br /> === set_instructor_group_enabled ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|set_instructor_group_enabled|string}}<br /> {{hl2msg|string|group|}}<br /> {{hl2msg|short|enabled|}}<br /> {{end-hl2msg}}<br /> === stashwhacker_game_won ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|stashwhacker_game_won|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|short|subject|}}<br /> {{end-hl2msg}}<br /> === versus_marker_reached ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|versus_marker_reached|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|short|marker|}}<br /> {{end-hl2msg}}<br /> === start_score_animation ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|start_score_animation|string}}<br /> {{end-hl2msg}}<br /> === survival_round_start ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|survival_round_start|string}}<br /> {{end-hl2msg}}<br /> === scavenge_gas_can_destroyed ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|scavenge_gas_can_destroyed|string}}<br /> {{hl2msg|short|userid|The player that destroyed it}}<br /> {{end-hl2msg}}<br /> === explain_sewer_gate ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_sewer_gate|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_sewer_run ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_sewer_run|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === explain_c6m3_finale ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|explain_c6m3_finale|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === finale_bridge_lowering ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|finale_bridge_lowering|string}}<br /> {{hl2msg|short|userid|}}<br /> {{hl2msg|long|subject|}}<br /> {{end-hl2msg}}<br /> === m60_streak_ended ===<br /> {{qnotice|I was holding down the m60 trigger, and now I'm not}}&lt;br&gt;<br /> {{begin-hl2msg|m60_streak_ended|string}}<br /> {{hl2msg|none|none|}}<br /> {{end-hl2msg}}<br /> === chair_charged ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|chair_charged|string}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}<br /> === song_played ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|song_played|string}}<br /> {{hl2msg|none|none|}}<br /> {{end-hl2msg}}<br /> === foot_locker_opened ===<br /> {{qnotice|}}&lt;br&gt;<br /> {{begin-hl2msg|foot_locker_opened|string}}<br /> {{hl2msg|short|userid|}}<br /> {{end-hl2msg}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Handles_(SourceMod_Scripting)&diff=10174 2016-06-17T12:26:47Z

<p>Xerox8521: Updated to 1.7 Syntax</p> <hr /> <div>Handles are a special data type used in [[:Category:SourceMod Scripting|SourceMod Scripting]]. They represent a single internal and unique object. For example, there are &quot;File&quot; Handles for files, and &quot;Menu&quot; Handles for menus, but they are both encapsulated under the &quot;Handle&quot; [[Tags (SourceMod Scripting)|tag]].<br /> <br /> Handles are more than &quot;pointers&quot; from C or C++ because they have a ''reference count''. This means that the number of copies floating around in memory is tracked. The actual internal object is not destroyed until each copy is also destroyed.<br /> <br /> Since SourcePawn does not have [[Garbage Collection]], Handles are a special way of intelligently allowing plugins and SourceMod to manage their own memory.<br /> <br /> For more information on using Handles in the SourceMod API, see [[Handle API (SourceMod)]].<br /> <br /> =Opening Handles=<br /> Opening a Handle is usually done implicitly by a native function. For example, OpenDirectory opens a new Handle which is used in other Directory natives. This associates a ''type'' with the Handle. Trying to use a Directory Handle with any other non-Directory native will cause an error (HandleError_Type), because Handles are type checked.<br /> <br /> &lt;pawn&gt;Handle hndl = OpenDirectory(&quot;addons/sourcemod/configs&quot;);<br /> &lt;/pawn&gt;<br /> <br /> =Closing Handles=<br /> ==Basic operation==<br /> Closing a Handle means seeing if the internal object can be removed from memory. For example, if a plugin creates an SQL connection, closing the Handle means closing and destroying the connection. This is almost always done using the CloseHandle() native function.<br /> <br /> ==When to close==<br /> When a plugin unloads, all of its Handles are automatically destroyed. This does not mean, however, that closing Handles is optional. Consider the following code:<br /> <br /> &lt;pawn&gt;stock bool IsFileInFolder(const char[] path, const char[] file)<br /> {<br /> char path[PLATFORM_MAX_PATH];<br /> FileType type;<br /> <br /> Handle dir = OpenDirectory(path);<br /> if (dir == INVALID_HANDLE)<br /> {<br /> return false;<br /> }<br /> <br /> while (ReadDirEntry(dir, path, sizeof(path), type))<br /> {<br /> if (type == FileType_File &amp;&amp; StrEqual(path, file))<br /> {<br /> return true;<br /> }<br /> }<br /> <br /> delete dir;<br /> <br /> return false;<br /> }<br /> &lt;/pawn&gt;<br /> <br /> This function searches a directory for a single file. If this function were to omit the call to CloseHandle, it would [[Memory Leak|leak memory]] every time it was called, and eventually the script would fill up with a large number of lingering Handles that were left open.<br /> <br /> So, when do you close Handles? There are generally two rules of thumb to go by:<br /> *If the native uses terminology such as &quot;Opens a [...]&quot; or &quot;Creates a [...]&quot; or gives explicit directions for closing.<br /> *If the Handle represents a temporary object or piece of information, and you will no longer be using it.<br /> <br /> Most of the time, you will be closing Handles. Check the Handle Type documentation at the end of this page.<br /> <br /> ==When you can't close==<br /> There are a few Handle types that cannot be closed. The major one is the Handle which identifies a plugin. Plugins cannot unload themselves, and thus destroying their own Handles is not allowed.<br /> <br /> Furthermore, a script cannot close a Handle that is owned by another plugin. This is for protection against API mistakes and accidental errors. For example, if a Handle is shared between two plugins, one accidental free could invalidate a Handle unexpectedly. To allow the sharing of Handles, see [[#Cloning Handles|Cloning Handles]].<br /> <br /> ==Reference counters==<br /> Closing Handles does not always destroy the internal data. This is the case when Handles are [[#Cloning Handles|cloned]]. Each clone adds a ''reference count'' to the Handle, and closing each clone removes one reference count. The original object is only actually destroyed once the Handle has no more reference counters. <br /> <br /> =Cloning Handles=<br /> As briefly described earlier, there is a problem when scripts try to share Handles. Imagine this scenario:<br /> *Plugin 'A' creates a Handle.<br /> *Plugin 'B' received the Handle.<br /> *Plugin 'A' is unloaded, and the Handle is destroyed.<br /> *Plugin 'B' tries to use the Handle.<br /> <br /> To prevent this, the CloneHandle native is provided. This function returns a ''new'' Handle that is a &quot;copy&quot; of the original. While their values won't be equal, they contain the same internal data. The data itself will not be destroyed until each copy and the original are closed with CloseHandle. It does not matter what order they are freed in, however, each Handle can only be freed once.<br /> <br /> There are two ways of cloning. A plugin can either clone a Handle itself, and become the owner, or it can explicitly set a new owner. The difference is one of API design. Example of the former:<br /> &lt;pawn&gt;DataBase g_hSQL;<br /> /**<br /> * The other plugin calling this function must pass his ID in,<br /> * but doesn't have to call CloneHandle()<br /> */<br /> public Database GetGlobalSQL(Handle otherPlugin)<br /> {<br /> return view_as&lt;DataBase&gt;(CloneHandle(g_hSQL, otherPlugin));<br /> }<br /> <br /> /**<br /> * This code would appear in the other plugin<br /> */<br /> DataBase sql = GetGlobalSQL(myself);<br /> /* ... */<br /> delete sql;<br /> &lt;/pawn&gt;<br /> <br /> Example of the latter:<br /> &lt;pawn&gt;DataBase g_hSQL;<br /> /**<br /> * The calling plugin must call CloneHandle() himself.<br /> */<br /> public DataBase GetGlobalSQL()<br /> {<br /> return g_hSQL;<br /> }<br /> <br /> /**<br /> * This code would appear in the other plugin<br /> */<br /> DataBase sql = GetGlobalSQL();<br /> if (sql != INVALID_HANDLE)<br /> {<br /> sql = view_as&lt;DataBase&gt;(CloneHandle(sql));<br /> }<br /> delete sql;<br /> &lt;/pawn&gt;<br /> <br /> =Handle Types=<br /> The following is a list of some common Handle types provided by SourceMod and some documentation on each. Some Handles are exposed, by name, so that Extensions can create Handles of this type. An example:<br /> <br /> &lt;pawn&gt;HandleType_t g_DataPackType;<br /> <br /> handlesys-&gt;FindHandleType(&quot;DataPack&quot;, &amp;g_DataPackType);&lt;/pawn&gt;<br /> <br /> ==BitBuffers==<br /> {{HandleType|bf_read or bf_write|Only if explicitly stated|Only if it can also be closed|Core|bitbuffer.inc}}<br /> <br /> There are four types of BitBuffer Handles. They are separated into ''bf_write'' (writable buffer) and ''bf_read'' (readable buffer). These are directly abstracted from their Half-Life 2 counterpart. Internally, there are separate Handle types for each; certain functions will use BitBuffer handles that cannot be freed.<br /> <br /> ==ConVars==<br /> {{HandleType|ConVar|No|No|Core|convars.inc}}<br /> <br /> ConVar Handles are primarily used for getting and setting a console variable's value. They cannot be cloned nor deleted since they exist until SourceMod is shut down.<br /> <br /> ==DataPacks==<br /> {{HandleType|DataPack|Yes|Yes|Core|datapack.inc}}<br /> <br /> DataPack Handles are used to pack data into a sequential stream, for unpacking later. They are unidirectional, meaning that reading and writing affects the same position in the stream.<br /> <br /> The DataPack type is exposed for Extensions to use.<br /> <br /> ==Directories==<br /> {{HandleType|Directory|Yes|Yes|Core|files.inc}}<br /> <br /> Directory Handles are used for opening and enumerating the contents of a directory (folder) on the filesystem.<br /> <br /> ==Database Drivers==<br /> {{HandleType|DBDriver|Yes|No|Core|dbi.inc}}<br /> <br /> DBDriver Handles contain information about a database driver. They are static and cannot be closed.<br /> <br /> ==Database Queries==<br /> {{HandleType|IQuery|Yes|No|Core|dbi.inc}}<br /> {{HandleType|IPreparedQuery|Yes|No|Core|dbi.inc}}<br /> <br /> Database Queries wrap an &lt;tt&gt;IQuery&lt;/tt&gt; pointer for database queries. Closing a query frees its resources, including any prepared statement information and any result sets.<br /> <br /> ==Databases==<br /> {{HandleType|IDatabase|Yes|Yes|Core|dbi.inc}}<br /> <br /> Database Handles wrap an &lt;tt&gt;IDatabase&lt;/tt&gt; pointer for database connections. Closing these disconnects the database and frees any related resources.<br /> <br /> ==Events==<br /> {{HandleType|Event|No|No|Core|events.inc}}<br /> <br /> Event Handles are used for getting and setting data in Half-Life 2 game events as well as for firing them. They can only be closed using CancelCreatedEvent() if the event was not fired for some reason.<br /> <br /> ==Files==<br /> {{HandleType|File|Yes|Yes|Core|files.inc}}<br /> <br /> File Handles are used for opening, reading from, writing to, and creating to files on the file system.<br /> <br /> ==Forwards==<br /> {{HandleType|Forward|Yes|Only if explicitly stated|Core|functions.inc}}<br /> <br /> Forward Handles are primarily used when calling functions inside a forward container. There are two types of forwards: global and private. Only private forwards can be cloned.<br /> <br /> ==KeyValues==<br /> {{HandleType|KeyValues|Yes|No|Core|keyvalues.inc}}<br /> <br /> KeyValues Handles abstract the Valve data type &lt;tt&gt;KeyValues&lt;/tt&gt;, which are tree-based, recursive key to value mapping structures, often used to enumerate properties or configuration file directives.<br /> <br /> ==Plugins==<br /> {{HandleType|Plugin|No|No|Core|sourcemod.inc}}<br /> <br /> Plugin Handles are used for the unique identification of a Plugin. They are owned by Core and cannot be cloned or closed by any other plugin or extension. However, plugins can use Handles for certain natives which enumerate or retrieve information on plugins. <br /> <br /> Plugin Handles should not be cached globally, as plugins can become unloaded, and the Handle will be invalid.<br /> <br /> ==Plugin Iterators==<br /> {{HandleType|PluginIter|Yes|No|Core|sourcemod.inc}}<br /> <br /> Plugin Iterators allow you to walk over a list of plugins. They are intended for temporary use only.<br /> <br /> ==Protobuf==<br /> {{HandleType|protobuf|No|No|Core|protobuf.inc}}<br /> <br /> Protobuf Handles are currently used for usermessages in supported games. They directly reference protobuf Messages, which can be a usermessage or a Message field inside of a usermessage. They are owned and managed by Core and cannot be cloned or closed by a plugin.<br /> <br /> ==SMC Parsers==<br /> {{HandleType|SMC Parser|Yes|No|Core|textparse.inc}}<br /> <br /> SMC Parsers are Handles which contain a set of functions for hooking parse events in an SMC file. Since they directly reference functions in a plugin, they cannot be cloned.<br /> <br /> ==Timers==<br /> {{HandleType|Timer|Yes|No|Core|timers.inc}}<br /> <br /> Timers are temporary Handles which are automatically closed on any of the following events:<br /> *The timer ends (via Plugin_Stop or being a one-time timer that is finished)<br /> *The timer is killed via &lt;tt&gt;KillTimer&lt;/tt&gt;<br /> *The timer is closed via &lt;tt&gt;CloseHandle&lt;/tt&gt;<br /> *The timer's parent plugin unloads<br /> <br /> [[Category:SourceMod Scripting]]</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Handles_(SourceMod_Scripting)&diff=10173 2016-06-17T12:24:16Z

<p>Xerox8521: Updated to 1.7 Syntax</p> <hr /> <div>Handles are a special data type used in [[:Category:SourceMod Scripting|SourceMod Scripting]]. They represent a single internal and unique object. For example, there are &quot;File&quot; Handles for files, and &quot;Menu&quot; Handles for menus, but they are both encapsulated under the &quot;Handle&quot; [[Tags (SourceMod Scripting)|tag]].<br /> <br /> Handles are more than &quot;pointers&quot; from C or C++ because they have a ''reference count''. This means that the number of copies floating around in memory is tracked. The actual internal object is not destroyed until each copy is also destroyed.<br /> <br /> Since SourcePawn does not have [[Garbage Collection]], Handles are a special way of intelligently allowing plugins and SourceMod to manage their own memory.<br /> <br /> For more information on using Handles in the SourceMod API, see [[Handle API (SourceMod)]].<br /> <br /> =Opening Handles=<br /> Opening a Handle is usually done implicitly by a native function. For example, OpenDirectory opens a new Handle which is used in other Directory natives. This associates a ''type'' with the Handle. Trying to use a Directory Handle with any other non-Directory native will cause an error (HandleError_Type), because Handles are type checked.<br /> <br /> &lt;pawn&gt;Handle hndl = OpenDirectory(&quot;addons/sourcemod/configs&quot;);<br /> &lt;/pawn&gt;<br /> <br /> =Closing Handles=<br /> ==Basic operation==<br /> Closing a Handle means seeing if the internal object can be removed from memory. For example, if a plugin creates an SQL connection, closing the Handle means closing and destroying the connection. This is almost always done using the CloseHandle() native function.<br /> <br /> ==When to close==<br /> When a plugin unloads, all of its Handles are automatically destroyed. This does not mean, however, that closing Handles is optional. Consider the following code:<br /> <br /> &lt;pawn&gt;stock bool IsFileInFolder(const char[] path, const char[] file)<br /> {<br /> char path[PLATFORM_MAX_PATH];<br /> FileType type;<br /> <br /> Handle dir = OpenDirectory(path);<br /> if (dir == INVALID_HANDLE)<br /> {<br /> return false;<br /> }<br /> <br /> while (ReadDirEntry(dir, path, sizeof(path), type))<br /> {<br /> if (type == FileType_File &amp;&amp; StrEqual(path, file))<br /> {<br /> return true;<br /> }<br /> }<br /> <br /> delete dir;<br /> <br /> return false;<br /> }<br /> &lt;/pawn&gt;<br /> <br /> This function searches a directory for a single file. If this function were to omit the call to CloseHandle, it would [[Memory Leak|leak memory]] every time it was called, and eventually the script would fill up with a large number of lingering Handles that were left open.<br /> <br /> So, when do you close Handles? There are generally two rules of thumb to go by:<br /> *If the native uses terminology such as &quot;Opens a [...]&quot; or &quot;Creates a [...]&quot; or gives explicit directions for closing.<br /> *If the Handle represents a temporary object or piece of information, and you will no longer be using it.<br /> <br /> Most of the time, you will be closing Handles. Check the Handle Type documentation at the end of this page.<br /> <br /> ==When you can't close==<br /> There are a few Handle types that cannot be closed. The major one is the Handle which identifies a plugin. Plugins cannot unload themselves, and thus destroying their own Handles is not allowed.<br /> <br /> Furthermore, a script cannot close a Handle that is owned by another plugin. This is for protection against API mistakes and accidental errors. For example, if a Handle is shared between two plugins, one accidental free could invalidate a Handle unexpectedly. To allow the sharing of Handles, see [[#Cloning Handles|Cloning Handles]].<br /> <br /> ==Reference counters==<br /> Closing Handles does not always destroy the internal data. This is the case when Handles are [[#Cloning Handles|cloned]]. Each clone adds a ''reference count'' to the Handle, and closing each clone removes one reference count. The original object is only actually destroyed once the Handle has no more reference counters. <br /> <br /> =Cloning Handles=<br /> As briefly described earlier, there is a problem when scripts try to share Handles. Imagine this scenario:<br /> *Plugin 'A' creates a Handle.<br /> *Plugin 'B' received the Handle.<br /> *Plugin 'A' is unloaded, and the Handle is destroyed.<br /> *Plugin 'B' tries to use the Handle.<br /> <br /> To prevent this, the CloneHandle native is provided. This function returns a ''new'' Handle that is a &quot;copy&quot; of the original. While their values won't be equal, they contain the same internal data. The data itself will not be destroyed until each copy and the original are closed with CloseHandle. It does not matter what order they are freed in, however, each Handle can only be freed once.<br /> <br /> There are two ways of cloning. A plugin can either clone a Handle itself, and become the owner, or it can explicitly set a new owner. The difference is one of API design. Example of the former:<br /> &lt;pawn&gt;new Handle:g_hSQL;<br /> /**<br /> * The other plugin calling this function must pass his ID in,<br /> * but doesn't have to call CloneHandle()<br /> */<br /> public Handle:GetGlobalSQL(Handle:otherPlugin)<br /> {<br /> return CloneHandle(g_hSQL, otherPlugin);<br /> }<br /> <br /> /**<br /> * This code would appear in the other plugin<br /> */<br /> new Handle:sql = GetGlobalSQL(myself);<br /> /* ... */<br /> CloseHandle(sql);<br /> &lt;/pawn&gt;<br /> <br /> Example of the latter:<br /> &lt;pawn&gt;new Handle:g_hSQL;<br /> /**<br /> * The calling plugin must call CloneHandle() himself.<br /> */<br /> public Handle:GetGlobalSQL()<br /> {<br /> return g_hSQL;<br /> }<br /> <br /> /**<br /> * This code would appear in the other plugin<br /> */<br /> new Handle:sql = GetGlobalSQL();<br /> if (sql != INVALID_HANDLE)<br /> {<br /> sql = CloneHandle(sql);<br /> }<br /> CloseHandle(sql);<br /> &lt;/pawn&gt;<br /> <br /> =Handle Types=<br /> The following is a list of some common Handle types provided by SourceMod and some documentation on each. Some Handles are exposed, by name, so that Extensions can create Handles of this type. An example:<br /> <br /> &lt;pawn&gt;HandleType_t g_DataPackType;<br /> <br /> handlesys-&gt;FindHandleType(&quot;DataPack&quot;, &amp;g_DataPackType);&lt;/pawn&gt;<br /> <br /> ==BitBuffers==<br /> {{HandleType|bf_read or bf_write|Only if explicitly stated|Only if it can also be closed|Core|bitbuffer.inc}}<br /> <br /> There are four types of BitBuffer Handles. They are separated into ''bf_write'' (writable buffer) and ''bf_read'' (readable buffer). These are directly abstracted from their Half-Life 2 counterpart. Internally, there are separate Handle types for each; certain functions will use BitBuffer handles that cannot be freed.<br /> <br /> ==ConVars==<br /> {{HandleType|ConVar|No|No|Core|convars.inc}}<br /> <br /> ConVar Handles are primarily used for getting and setting a console variable's value. They cannot be cloned nor deleted since they exist until SourceMod is shut down.<br /> <br /> ==DataPacks==<br /> {{HandleType|DataPack|Yes|Yes|Core|datapack.inc}}<br /> <br /> DataPack Handles are used to pack data into a sequential stream, for unpacking later. They are unidirectional, meaning that reading and writing affects the same position in the stream.<br /> <br /> The DataPack type is exposed for Extensions to use.<br /> <br /> ==Directories==<br /> {{HandleType|Directory|Yes|Yes|Core|files.inc}}<br /> <br /> Directory Handles are used for opening and enumerating the contents of a directory (folder) on the filesystem.<br /> <br /> ==Database Drivers==<br /> {{HandleType|DBDriver|Yes|No|Core|dbi.inc}}<br /> <br /> DBDriver Handles contain information about a database driver. They are static and cannot be closed.<br /> <br /> ==Database Queries==<br /> {{HandleType|IQuery|Yes|No|Core|dbi.inc}}<br /> {{HandleType|IPreparedQuery|Yes|No|Core|dbi.inc}}<br /> <br /> Database Queries wrap an &lt;tt&gt;IQuery&lt;/tt&gt; pointer for database queries. Closing a query frees its resources, including any prepared statement information and any result sets.<br /> <br /> ==Databases==<br /> {{HandleType|IDatabase|Yes|Yes|Core|dbi.inc}}<br /> <br /> Database Handles wrap an &lt;tt&gt;IDatabase&lt;/tt&gt; pointer for database connections. Closing these disconnects the database and frees any related resources.<br /> <br /> ==Events==<br /> {{HandleType|Event|No|No|Core|events.inc}}<br /> <br /> Event Handles are used for getting and setting data in Half-Life 2 game events as well as for firing them. They can only be closed using CancelCreatedEvent() if the event was not fired for some reason.<br /> <br /> ==Files==<br /> {{HandleType|File|Yes|Yes|Core|files.inc}}<br /> <br /> File Handles are used for opening, reading from, writing to, and creating to files on the file system.<br /> <br /> ==Forwards==<br /> {{HandleType|Forward|Yes|Only if explicitly stated|Core|functions.inc}}<br /> <br /> Forward Handles are primarily used when calling functions inside a forward container. There are two types of forwards: global and private. Only private forwards can be cloned.<br /> <br /> ==KeyValues==<br /> {{HandleType|KeyValues|Yes|No|Core|keyvalues.inc}}<br /> <br /> KeyValues Handles abstract the Valve data type &lt;tt&gt;KeyValues&lt;/tt&gt;, which are tree-based, recursive key to value mapping structures, often used to enumerate properties or configuration file directives.<br /> <br /> ==Plugins==<br /> {{HandleType|Plugin|No|No|Core|sourcemod.inc}}<br /> <br /> Plugin Handles are used for the unique identification of a Plugin. They are owned by Core and cannot be cloned or closed by any other plugin or extension. However, plugins can use Handles for certain natives which enumerate or retrieve information on plugins. <br /> <br /> Plugin Handles should not be cached globally, as plugins can become unloaded, and the Handle will be invalid.<br /> <br /> ==Plugin Iterators==<br /> {{HandleType|PluginIter|Yes|No|Core|sourcemod.inc}}<br /> <br /> Plugin Iterators allow you to walk over a list of plugins. They are intended for temporary use only.<br /> <br /> ==Protobuf==<br /> {{HandleType|protobuf|No|No|Core|protobuf.inc}}<br /> <br /> Protobuf Handles are currently used for usermessages in supported games. They directly reference protobuf Messages, which can be a usermessage or a Message field inside of a usermessage. They are owned and managed by Core and cannot be cloned or closed by a plugin.<br /> <br /> ==SMC Parsers==<br /> {{HandleType|SMC Parser|Yes|No|Core|textparse.inc}}<br /> <br /> SMC Parsers are Handles which contain a set of functions for hooking parse events in an SMC file. Since they directly reference functions in a plugin, they cannot be cloned.<br /> <br /> ==Timers==<br /> {{HandleType|Timer|Yes|No|Core|timers.inc}}<br /> <br /> Timers are temporary Handles which are automatically closed on any of the following events:<br /> *The timer ends (via Plugin_Stop or being a one-time timer that is finished)<br /> *The timer is killed via &lt;tt&gt;KillTimer&lt;/tt&gt;<br /> *The timer is closed via &lt;tt&gt;CloseHandle&lt;/tt&gt;<br /> *The timer's parent plugin unloads<br /> <br /> [[Category:SourceMod Scripting]]</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Menus_Step_By_Step_(SourceMod_Scripting)&diff=10172 2016-06-17T12:19:02Z

<p>Xerox8521: Updated to 1.7 Syntax</p> <hr /> <div>The SourceMod [[Menu API (SourceMod)|Menu API]] is fairly useful for displaying an information panel, a menu, or a vote to users. This document talks specifically about menus and how to create one.<br /> <br /> == The working menu example ==<br /> <br /> This is the working code example that we'll be talking about in the upcoming sections. If you need to, you can come back and look at it as you read the rest of this page.<br /> <br /> We will be using PrintToServer to print text to the server console as we run through the events.<br /> <br /> Usage of the [[Translations (SourceMod Scripting)|Translations]] system is highly recommended and will be used in this example.<br /> <br /> &lt;pawn&gt;#define CHOICE1 &quot;#choice1&quot;<br /> #define CHOICE2 &quot;#choice2&quot;<br /> #define CHOICE3 &quot;#choice3&quot;<br /> <br /> public void OnPluginStart()<br /> {<br /> LoadTranslations(&quot;menu_test.phrases&quot;);<br /> RegConsoleCmd(&quot;menu_test1&quot;, Menu_Test1);<br /> }<br /> <br /> public int MenuHandler1(Menu menu, MenuAction action, int param1, int param2)<br /> {<br /> switch(action)<br /> {<br /> case MenuAction_Start:<br /> {<br /> PrintToServer(&quot;Displaying menu&quot;);<br /> }<br /> <br /> case MenuAction_Display:<br /> {<br /> char buffer[255];<br /> Format(buffer, sizeof(buffer), &quot;%T&quot;, &quot;Vote Nextmap&quot;, param1);<br /> <br /> Panel panel = view_as&lt;Panel&gt;(param2);<br /> panel.SetTitle(buffer);<br /> PrintToServer(&quot;Client %d was sent menu with panel %x&quot;, param1, param2);<br /> }<br /> <br /> case MenuAction_Select:<br /> {<br /> char info[32];<br /> menu.GetItem(param2, info, sizeof(info));<br /> if (StrEqual(info, CHOICE3))<br /> {<br /> PrintToServer(&quot;Client %d somehow selected %s despite it being disabled&quot;, param1, info);<br /> }<br /> else<br /> {<br /> PrintToServer(&quot;Client %d selected %s&quot;, param1, info);<br /> }<br /> }<br /> <br /> case MenuAction_Cancel:<br /> {<br /> PrintToServer(&quot;Client %d's menu was cancelled for reason %d&quot;, param1, param2);<br /> }<br /> <br /> case MenuAction_End:<br /> {<br /> delete menu;<br /> }<br /> <br /> case MenuAction_DrawItem:<br /> {<br /> int style;<br /> char info[32];<br /> menu.GetItem(param2, info, sizeof(info), style);<br /> <br /> if (StrEqual(info, CHOICE3))<br /> {<br /> return ITEMDRAW_DISABLED;<br /> }<br /> else<br /> {<br /> return style;<br /> }<br /> }<br /> <br /> case MenuAction_DisplayItem:<br /> {<br /> char info[32];<br /> menu.GetItem(param2, info, sizeof(info));<br /> <br /> char display[64];<br /> <br /> if (StrEqual(info, CHOICE3))<br /> {<br /> Format(display, sizeof(display), &quot;%T&quot;, &quot;Choice 3&quot;, param1);<br /> return RedrawMenuItem(display);<br /> }<br /> }<br /> }<br /> <br /> return 0;<br /> }<br /> <br /> public Action Menu_Test1(int client, int args)<br /> {<br /> Menu menu = new Menu(MenuHandler1, MENU_ACTIONS_ALL);<br /> menu.SetTitle(&quot;%T&quot;, &quot;Menu Title&quot;, LANG_SERVER);<br /> menu.AddItem(CHOICE1, &quot;Choice 1&quot;);<br /> menu.AddItem(CHOICE2, &quot;Choice 2&quot;);<br /> menu.AddItem(CHOICE3, &quot;Choice 3&quot;);<br /> menu.ExitButton = false;<br /> menu.Display(client, 20);<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> The translation file that goes with it... addons/sourcemod/translations/menu_test.phrases.txt<br /> <br /> &lt;pre&gt;&quot;Phrases&quot;<br /> {<br /> &quot;Choice 3&quot;<br /> {<br /> &quot;en&quot; &quot;Choice Translated&quot;<br /> }<br /> <br /> &quot;Menu Title&quot;<br /> {<br /> &quot;en&quot; &quot;Menu Title Translated&quot;<br /> }<br /> }&lt;/pre&gt;<br /> <br /> == Step by Step ==<br /> <br /> === OnPluginStart ===<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> LoadTranslations(&quot;menu_test.phrases&quot;);<br /> RegConsoleCmd(&quot;menu_test1&quot;, Menu_Test1);<br /> }&lt;/pawn&gt;<br /> <br /> This block is here to register the command /menu_test1 so that this menu can be tested.<br /> <br /> This block is beyond the scope of this page. See: [[Introduction to SourceMod Plugins#Plugin Structure|Plugin Structure]] for OnPluginStart, [[Translations (SourceMod Scripting)|Translations]] for LoadTranslations, and [[Commands_(SourceMod_Scripting)|Commands]] for RegConsoleCmd.<br /> <br /> === Menu_Test1 ===<br /> <br /> Menu_Test1 is a ConCmd, which is beyond the scope of this page. See: [[Commands (SourceMod Scripting)|Commands]] for more details on that. We're going to be talking about what's in it.<br /> <br /> ==== Menu ====<br /> <br /> &lt;pawn&gt; Menu menu = new Menu(MenuHandler1, MENU_ACTIONS_ALL);&lt;/pawn&gt;<br /> <br /> Menu takes two arguments.<br /> <br /> The first is a function that matches the [https://sm.alliedmods.net/new-api/menus/MenuHandler MenuHandler] callback signature.<br /> <br /> The second is a bitmask of which MenuAction events we are going to handle in our MenuHandler. There are 7 that apply to standard menus: <br /> * MenuAction_Start - Called once when a menu is displayed<br /> * MenuAction_Display - Called once for each client a menu is displayed to<br /> * MenuAction_Select - Called when a client makes a selection from the menu that isn't Previous, Next, Back, or Exit.<br /> * MenuAction_Cancel - Called when a client closes a menu or it is closed on them<br /> * MenuAction_End - Called once when all clients have closed the menu<br /> * MenuAction_DrawItem - Called once for each item for each user a menu is displayed to. Can change the menu item style.<br /> * MenuAction_DisplayIitem. - Called once for each item for each user a menu is displayed to. Can change the menu item text.<br /> <br /> These will be discussed in more detail in the MenuHandler1 section.<br /> <br /> Of those 7, 3 are called whether you specify them or not: MenuAction_Select, MenuAction_Cancel, and MenuAction_End.<br /> <br /> MENU_ACTIONS_DEFAULT sets just the 3 required fields, while MENU_ACTIONS_ALL specifies all 10 actions (including the 3 vote actions).<br /> <br /> To specify just a few of them, you can do this:<br /> <br /> &lt;pawn&gt; Menu menu = new Menu(MenuHandler1, MenuAction_Start|MenuAction_Select|MenuAction_Cancel|MenuAction_End);&lt;/pawn&gt;<br /> <br /> ==== menu.SetTitle ====<br /> &lt;pawn&gt; menu.SetTitle(&quot;%T&quot;, &quot;Menu Title&quot;, LANG_SERVER);&lt;/pawn&gt;<br /> <br /> Sets the menu's title. This example uses the translation system and the server's default language. This isn't strictly necessary as we will set the menu title again later.<br /> <br /> ==== menu.AddItem ====<br /> <br /> &lt;pawn&gt; menu.AddItem(CHOICE1, &quot;Choice 1&quot;);<br /> menu.AddItem(menu, CHOICE2, &quot;Choice 2&quot;);<br /> menu.AddItem(menu, CHOICE3, &quot;Choice 3&quot;);&lt;/pawn&gt;<br /> <br /> A menu isn't useful without something in it!<br /> menu.AddItem has 2 required arguments and one optional argument.<br /> <br /> The 3 required arguments are:<br /> <br /> The Menu handle, the Info string, and the Display string.<br /> <br /> The Info String is a string that is used to uniquely identify this menu item. It is never displayed to the user, but is used in various callbacks.<br /> <br /> The Display String is the default text to be used for this item on the menu. It can be changed via the menu's MenuAction_DisplayItem callback.<br /> <br /> The optional argument is the menu's item draw style. It can be one of these values:<br /> * ITEMDRAW_DEFAULT - Displays text as normal.<br /> * ITEMDRAW_DISABLED - Item is displayed and has a number, but can't be selected.<br /> * ITEMDRAW_RAWLINE - Item is displayed, but doesn't have a number assigned to it and thus can't be selected<br /> * ITEMDRAW_NOTEXT - Draws an item with no text. Not very useful.<br /> * ITEMDRAW_SPACER - Item is blank, but has a number. Can't be selected.<br /> * ITEMDRAW_IGNORE - Item is blank with no number. Can't be selected.<br /> * ITEMDRAW_CONTROL - Don't use this one. It's used for the items SourceMod automatically adds.<br /> <br /> Be aware that if your CreateMenu second argument includes MenuAction_DrawItem or MENU_ACTIONS_ALL and you don't actually implement the MenuAction_DrawItem callback (or implement it and don't return the current item's style if you don't change it), your style here will be completely ignored.<br /> <br /> ==== menu.ExitButton ====<br /> &lt;pawn&gt; menu.ExitButton = false;&lt;/pawn&gt;<br /> <br /> Defaults to true.<br /> <br /> It set to false, the menu won't have an exit button.<br /> <br /> ==== menu.ExitBackButton ====<br /> &lt;pawn&gt; menu.ExitBackButton = false;&lt;/pawn&gt;<br /> <br /> (This isn't in the code above, but it should be mentioned) <br /> <br /> Defaults to false.<br /> <br /> Should only be used if the menu is a submenu, with the menu set up to check the cancel reason to see if the ExitBack action was used.<br /> <br /> If set to true, replaces the Exit item with the Back item. The Back item still cancels the menu, but has a separate cancel reason.<br /> <br /> This can be used to dynamically set if a menu is being called as its own menu or as a submenu.<br /> <br /> ==== menu.Display ====<br /> &lt;pawn&gt; menu.Display(client, 20);&lt;/pawn&gt;<br /> <br /> DisplayMenu takes 2 arguments:<br /> <br /> A Menu handle, a client index, and the amount of time in seconds to show the menu.<br /> <br /> If you want the menu to show forever, pass MENU_TIME_FOREVER as the third argument.<br /> <br /> === MenuHandler1 ===<br /> &lt;pawn&gt;public int MenuHandler1(Menu menu, MenuAction action, int param1, int param2)&lt;/pawn&gt;<br /> <br /> MenuHandler1 is a function whose signature matches the MenuHandler callback. It can be named something other than MenuHandler1. It must always be public and it will always have these arguments: Handle, MenuAction, cell, and cell in that order.<br /> <br /> The Handle argument is always the menu that called the handler.<br /> <br /> The MenuAction argument is always one of 7 actions for a standard menu. They are: MenuAction_Start, MenuAction_Display, MenuAction_Select, MenuAction_Cancel, MenuAction_End, MenuAction_DrawItem, and MenuAction_DisplayIitem. We will discuss each of these as we reach their code.<br /> <br /> The two cell arguments meaning depend on the MenuAction argument. '''A common mistake is to assume param1 is the client.''' This is incorrect for MenuAction_Start, MenuAction_End, MenuAction_VoteEnd, MenuAction_VoteStart, and MenuAction_VoteCancel.<br /> <br /> ==== MenuAction_Start ====<br /> <br /> &lt;pawn&gt; case MenuAction_Start:<br /> {<br /> PrintToServer(&quot;Displaying menu&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> * param1: not set<br /> * param2: not set<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_Start doesn't set param1 and param2. It is fired when the menu is displayed to one or more users using DisplayMenu, DisplayMenuAtItem, VoteMenu, or VoteMenuToAll.<br /> <br /> ==== MenuAction_Display ====<br /> <br /> &lt;pawn&gt; case MenuAction_Display:<br /> {<br /> char buffer[255];<br /> Format(buffer, sizeof(buffer), &quot;%T&quot;, &quot;Vote Nextmap&quot;, param1);<br /> <br /> Panel panel = view_as&lt;Panel&gt;(param2);<br /> panel.SetTitle(buffer);<br /> PrintToServer(&quot;Client %d was sent menu with panel %x&quot;, param1, param2);<br /> }&lt;/pawn&gt;<br /> <br /> * param1: client index<br /> * param2: MenuPanel Handle<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_Display is called once for each user a menu is displayed to. param1 is the client, param2 is the MenuPanel handle.<br /> <br /> SetPanelTitle is used to change the menu's title based on the language of the user viewing it using the Translations system. Previous versions of this guide suggested using SetMenuTitle. This is a ''bad'' idea, as it changes the title globally.<br /> <br /> ==== MenuAction_Select ====<br /> &lt;pawn&gt; case MenuAction_Select:<br /> {<br /> char info[32];<br /> menu.GetInfo(param2, info, sizeof(info));<br /> if (StrEqual(info, CHOICE3))<br /> {<br /> PrintToServer(&quot;Client %d somehow selected %s despite it being disabled&quot;, param1, info);<br /> }<br /> else<br /> {<br /> PrintToServer(&quot;Client %d selected %s&quot;, param1, info);<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> * param1: client index<br /> * param2: item number for use with GetMenuItem<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_Select is called when a user selects a non-control item on the menu (something added using AddMenuItem). param1 is the client, param2 is the menu position of the item the client selected.<br /> <br /> Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.<br /> <br /> GetMenuItem is used here to fetch the info string.<br /> <br /> ==== MenuAction_Cancel ====<br /> <br /> case MenuAction_Cancel:<br /> {<br /> PrintToServer(&quot;Client %d's menu was cancelled for reason %d&quot;, param1, param2);<br /> }<br /> <br /> * param1: client index<br /> * param2: MenuCancel reason<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_Cancel is called whenever a user closes a menu or it is closed for them for another reason. param1 is the client, param2 is the close reason.<br /> <br /> The close reasons you can receive are:<br /> <br /> * MenuCancel_Disconnected - The client got disconnected from the server.<br /> * MenuCancel_Interrupted - Another menu opened, automatically closing our menu.<br /> * MenuCancel_Exit - The client selected Exit. Not called if SetMenuExitBack was set to true. Not called if SetMenuExit was set to false.<br /> * MenuCancel_NoDisplay - Our menu never displayed to the client for whatever reason.<br /> * MenuCancel_Timeout - The menu timed out. Not called if the menu time was MENU_TIME_FOREVER.<br /> * MenuCancel_ExitBack - The client selected Back. Only called if SetMenuExitBack has been called and set to true before the menu was sent. Not called if SetMenuExit was set to false.<br /> <br /> ==== MenuAction_End ====<br /> &lt;pawn&gt; case MenuAction_End:<br /> {<br /> delete menu;<br /> }&lt;/pawn&gt;<br /> <br /> * param1: MenuEnd reason<br /> * param2: If param1 is MenuEnd_Cancelled, the MenuCancel reason<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_End is called when ''all'' clients have closed a menu or vote. For menus that are not going to be redisplayed, it is required that you call CloseHandle on the menu here.<br /> <br /> The parameters are rarely used in MenuAction_End. param1 is the menu end reason. param2 depends on param1.<br /> <br /> The end reasons you can receive for normal menus are:<br /> <br /> * MenuEnd_Selected - The menu closed because an item was selected (MenuAction_Select was fired)<br /> * MenuEnd_Cancelled - The menu was cancelled (MenuAction_Cancel was fired), cancel reason is in param2; cancel reason can be any of the ones listed in MenuAction_Cancel except MenuCancel_Exit or MenuCancel_ExitBack<br /> * MenuEnd_Exit - The menu was exited via the Exit item (MenuAction_Cancel was fired with param2 set to MenuCancel_Exit)<br /> * MenuEnd_ExitBack - The menu was exited via the ExitBack item (MenuAction_Cancel was fired with param 2 set to MenuCancel_ExitBack)<br /> <br /> Note: You do '''not''' have the client index during this callback, so it's far too late to do anything useful with this information.<br /> <br /> ==== MenuAction_DrawItem ====<br /> &lt;pawn&gt; case MenuAction_DrawItem:<br /> {<br /> int style;<br /> char info[32];<br /> menu.GetItem(param2, info, sizeof(info), style);<br /> <br /> if (StrEqual(info, CHOICE3))<br /> {<br /> return ITEMDRAW_DISABLED;<br /> }<br /> else<br /> {<br /> return style;<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> * param1: client index<br /> * param2: item number for use with GetMenuItem<br /> * return: new ITEMDRAW properties or style from GetMenuItem. Since 0 is ITEMDRAW_DEFAULT, returning 0 clears all styles for this item.<br /> <br /> MenuAction_DrawItem is called once for each item on the menu for each user. You can manipulate its draw style here. param1 is the client, param2 is the menu position.<br /> <br /> Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.<br /> <br /> GetMenuItem is used here to fetch the info string and menu style.<br /> <br /> You should return the style you want the menu item to have. In our example, if client 1 is viewing the menu, we want CHOICE3 to be disabled.<br /> <br /> the return value is a bitfield, so to apply multiple styles, you do something like this:<br /> <br /> return ITEMDRAW_NOTEXT | ITEMDRAW_SPACER;<br /> <br /> '''Failing to return the current item's style if you don't change the style is a programmer error.'''<br /> <br /> ==== MenuAction_DisplayItem ====<br /> <br /> &lt;pawn&gt; case MenuAction_DisplayItem:<br /> {<br /> char info[32];<br /> menu.GetItem(param2, info, sizeof(info));<br /> <br /> char display[64];<br /> <br /> if (StrEqual(info, CHOICE3))<br /> {<br /> Format(display, sizeof(display), &quot;%T&quot;, &quot;Choice 3&quot;, param1);<br /> return RedrawMenuItem(display);<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> * param1: client index<br /> * param2: item number for use with GetMenuItem<br /> * return: return value from RedrawMenuItem or 0 for no change<br /> <br /> MenuAction_DrawItem is called once for each item on the menu for each user. You can manipulate its text here. param1 is the client, param2 is the menu position.<br /> <br /> This callback is intended for use with the Translation system.<br /> <br /> Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.<br /> <br /> GetMenuItem is used here to fetch the info string.<br /> <br /> Once we have the info string, we compare our item to it and apply the appropriate translation string.<br /> <br /> If we change an item, we have to call RedrawMenuItem and return the value it returns. If we do not change an item, we must return 0.<br /> <br /> ==== return ====<br /> &lt;pawn&gt; return 0;&lt;/pawn&gt;<br /> <br /> If you handle MenuAction_DrawItem or MenuAction_DisplayItem, you will get the following warning if you fail to return 0 after the switch block:<br /> <br /> &lt;code&gt;warning 209: function &quot;MenuHandler1&quot; should return a value&lt;/code&gt;<br /> <br /> This is because MenuAction_DrawItem and MenuAction_DisplayItem have return values, while the other actions only return 0.<br /> <br /> == The End ==<br /> Hopefully this walk through a simple menu helped you understand why each call is being made where. Menus have some options that we didn't explore here, such as disabling pagination (which is enabled by default). You may want to refer to the main Menu documentation for more details.</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Menus_Step_By_Step_(SourceMod_Scripting)&diff=10171 2016-06-17T12:14:56Z

<p>Xerox8521: /* Step by Step */</p> <hr /> <div>The SourceMod [[Menu API (SourceMod)|Menu API]] is fairly useful for displaying an information panel, a menu, or a vote to users. This document talks specifically about menus and how to create one.<br /> <br /> == The working menu example ==<br /> <br /> This is the working code example that we'll be talking about in the upcoming sections. If you need to, you can come back and look at it as you read the rest of this page.<br /> <br /> We will be using PrintToServer to print text to the server console as we run through the events.<br /> <br /> Usage of the [[Translations (SourceMod Scripting)|Translations]] system is highly recommended and will be used in this example.<br /> <br /> &lt;pawn&gt;#define CHOICE1 &quot;#choice1&quot;<br /> #define CHOICE2 &quot;#choice2&quot;<br /> #define CHOICE3 &quot;#choice3&quot;<br /> <br /> public void OnPluginStart()<br /> {<br /> LoadTranslations(&quot;menu_test.phrases&quot;);<br /> RegConsoleCmd(&quot;menu_test1&quot;, Menu_Test1);<br /> }<br /> <br /> public int MenuHandler1(Menu menu, MenuAction action, int param1, int param2)<br /> {<br /> switch(action)<br /> {<br /> case MenuAction_Start:<br /> {<br /> PrintToServer(&quot;Displaying menu&quot;);<br /> }<br /> <br /> case MenuAction_Display:<br /> {<br /> char buffer[255];<br /> Format(buffer, sizeof(buffer), &quot;%T&quot;, &quot;Vote Nextmap&quot;, param1);<br /> <br /> Panel panel = view_as&lt;Panel&gt;(param2);<br /> panel.SetTitle(buffer);<br /> PrintToServer(&quot;Client %d was sent menu with panel %x&quot;, param1, param2);<br /> }<br /> <br /> case MenuAction_Select:<br /> {<br /> char info[32];<br /> menu.GetItem(param2, info, sizeof(info));<br /> if (StrEqual(info, CHOICE3))<br /> {<br /> PrintToServer(&quot;Client %d somehow selected %s despite it being disabled&quot;, param1, info);<br /> }<br /> else<br /> {<br /> PrintToServer(&quot;Client %d selected %s&quot;, param1, info);<br /> }<br /> }<br /> <br /> case MenuAction_Cancel:<br /> {<br /> PrintToServer(&quot;Client %d's menu was cancelled for reason %d&quot;, param1, param2);<br /> }<br /> <br /> case MenuAction_End:<br /> {<br /> delete menu;<br /> }<br /> <br /> case MenuAction_DrawItem:<br /> {<br /> int style;<br /> char info[32];<br /> menu.GetItem(param2, info, sizeof(info), style);<br /> <br /> if (StrEqual(info, CHOICE3))<br /> {<br /> return ITEMDRAW_DISABLED;<br /> }<br /> else<br /> {<br /> return style;<br /> }<br /> }<br /> <br /> case MenuAction_DisplayItem:<br /> {<br /> char info[32];<br /> menu.GetItem(param2, info, sizeof(info));<br /> <br /> char display[64];<br /> <br /> if (StrEqual(info, CHOICE3))<br /> {<br /> Format(display, sizeof(display), &quot;%T&quot;, &quot;Choice 3&quot;, param1);<br /> return RedrawMenuItem(display);<br /> }<br /> }<br /> }<br /> <br /> return 0;<br /> }<br /> <br /> public Action Menu_Test1(int client, int args)<br /> {<br /> Menu menu = new Menu(MenuHandler1, MENU_ACTIONS_ALL);<br /> menu.SetTitle(&quot;%T&quot;, &quot;Menu Title&quot;, LANG_SERVER);<br /> menu.AddItem(CHOICE1, &quot;Choice 1&quot;);<br /> menu.AddItem(CHOICE2, &quot;Choice 2&quot;);<br /> menu.AddItem(CHOICE3, &quot;Choice 3&quot;);<br /> menu.ExitButton = false;<br /> menu.Display(client, 20);<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> The translation file that goes with it... addons/sourcemod/translations/menu_test.phrases.txt<br /> <br /> &lt;pre&gt;&quot;Phrases&quot;<br /> {<br /> &quot;Choice 3&quot;<br /> {<br /> &quot;en&quot; &quot;Choice Translated&quot;<br /> }<br /> <br /> &quot;Menu Title&quot;<br /> {<br /> &quot;en&quot; &quot;Menu Title Translated&quot;<br /> }<br /> }&lt;/pre&gt;<br /> <br /> == Step by Step ==<br /> <br /> === OnPluginStart ===<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> LoadTranslations(&quot;menu_test.phrases&quot;);<br /> RegConsoleCmd(&quot;menu_test1&quot;, Menu_Test1);<br /> }&lt;/pawn&gt;<br /> <br /> This block is here to register the command /menu_test1 so that this menu can be tested.<br /> <br /> This block is beyond the scope of this page. See: [[Introduction to SourceMod Plugins#Plugin Structure|Plugin Structure]] for OnPluginStart, [[Translations (SourceMod Scripting)|Translations]] for LoadTranslations, and [[Commands_(SourceMod_Scripting)|Commands]] for RegConsoleCmd.<br /> <br /> === Menu_Test1 ===<br /> <br /> Menu_Test1 is a ConCmd, which is beyond the scope of this page. See: [[Commands (SourceMod Scripting)|Commands]] for more details on that. We're going to be talking about what's in it.<br /> <br /> ==== CreateMenu ====<br /> <br /> &lt;pawn&gt; Menu menu = new Menu(MenuHandler1, MENU_ACTIONS_ALL);&lt;/pawn&gt;<br /> <br /> Menu takes two arguments.<br /> <br /> The first is a function that matches the [https://sm.alliedmods.net/new-api/menus/MenuHandler MenuHandler] callback signature.<br /> <br /> The second is a bitmask of which MenuAction events we are going to handle in our MenuHandler. There are 7 that apply to standard menus: <br /> * MenuAction_Start - Called once when a menu is displayed<br /> * MenuAction_Display - Called once for each client a menu is displayed to<br /> * MenuAction_Select - Called when a client makes a selection from the menu that isn't Previous, Next, Back, or Exit.<br /> * MenuAction_Cancel - Called when a client closes a menu or it is closed on them<br /> * MenuAction_End - Called once when all clients have closed the menu<br /> * MenuAction_DrawItem - Called once for each item for each user a menu is displayed to. Can change the menu item style.<br /> * MenuAction_DisplayIitem. - Called once for each item for each user a menu is displayed to. Can change the menu item text.<br /> <br /> These will be discussed in more detail in the MenuHandler1 section.<br /> <br /> Of those 7, 3 are called whether you specify them or not: MenuAction_Select, MenuAction_Cancel, and MenuAction_End.<br /> <br /> MENU_ACTIONS_DEFAULT sets just the 3 required fields, while MENU_ACTIONS_ALL specifies all 10 actions (including the 3 vote actions).<br /> <br /> To specify just a few of them, you can do this:<br /> <br /> &lt;pawn&gt; Menu menu = new Menu(MenuHandler1, MenuAction_Start|MenuAction_Select|MenuAction_Cancel|MenuAction_End);&lt;/pawn&gt;<br /> <br /> ==== menu.SetTitle ====<br /> &lt;pawn&gt; menu.SetTitle(&quot;%T&quot;, &quot;Menu Title&quot;, LANG_SERVER);&lt;/pawn&gt;<br /> <br /> Sets the menu's title. This example uses the translation system and the server's default language. This isn't strictly necessary as we will set the menu title again later.<br /> <br /> ==== menu.AddItem ====<br /> <br /> &lt;pawn&gt; menu.AddItem(CHOICE1, &quot;Choice 1&quot;);<br /> menu.AddItem(menu, CHOICE2, &quot;Choice 2&quot;);<br /> menu.AddItem(menu, CHOICE3, &quot;Choice 3&quot;);&lt;/pawn&gt;<br /> <br /> A menu isn't useful without something in it!<br /> menu.AddItem has 2 required arguments and one optional argument.<br /> <br /> The 3 required arguments are:<br /> <br /> The Menu handle, the Info string, and the Display string.<br /> <br /> The Info String is a string that is used to uniquely identify this menu item. It is never displayed to the user, but is used in various callbacks.<br /> <br /> The Display String is the default text to be used for this item on the menu. It can be changed via the menu's MenuAction_DisplayItem callback.<br /> <br /> The optional argument is the menu's item draw style. It can be one of these values:<br /> * ITEMDRAW_DEFAULT - Displays text as normal.<br /> * ITEMDRAW_DISABLED - Item is displayed and has a number, but can't be selected.<br /> * ITEMDRAW_RAWLINE - Item is displayed, but doesn't have a number assigned to it and thus can't be selected<br /> * ITEMDRAW_NOTEXT - Draws an item with no text. Not very useful.<br /> * ITEMDRAW_SPACER - Item is blank, but has a number. Can't be selected.<br /> * ITEMDRAW_IGNORE - Item is blank with no number. Can't be selected.<br /> * ITEMDRAW_CONTROL - Don't use this one. It's used for the items SourceMod automatically adds.<br /> <br /> Be aware that if your CreateMenu second argument includes MenuAction_DrawItem or MENU_ACTIONS_ALL and you don't actually implement the MenuAction_DrawItem callback (or implement it and don't return the current item's style if you don't change it), your style here will be completely ignored.<br /> <br /> ==== SetMenuExitButton ====<br /> &lt;pawn&gt; SetMenuExitButton(menu, false);&lt;/pawn&gt;<br /> <br /> Defaults to true.<br /> <br /> It set to false, the menu won't have an exit button.<br /> <br /> ==== SetMenuExitBackButton ====<br /> &lt;pawn&gt; SetMenuExitBackButton(menu, false);&lt;/pawn&gt;<br /> <br /> (This isn't in the code above, but it should be mentioned) <br /> <br /> Defaults to false.<br /> <br /> Should only be used if the menu is a submenu, with the menu set up to check the cancel reason to see if the ExitBack action was used.<br /> <br /> If set to true, replaces the Exit item with the Back item. The Back item still cancels the menu, but has a separate cancel reason.<br /> <br /> This can be used to dynamically set if a menu is being called as its own menu or as a submenu.<br /> <br /> ==== DisplayMenu ====<br /> &lt;pawn&gt; DisplayMenu(menu, client, 20);&lt;/pawn&gt;<br /> <br /> DisplayMenu takes 3 arguments:<br /> <br /> A Menu handle, a client index, and the amount of time in seconds to show the menu.<br /> <br /> If you want the menu to show forever, pass MENU_TIME_FOREVER as the third argument.<br /> <br /> === MenuHandler1 ===<br /> &lt;pawn&gt;public MenuHandler1(Handle:menu, MenuAction:action, param1, param2)&lt;/pawn&gt;<br /> <br /> MenuHandler1 is a function whose signature matches the MenuHandler callback. It can be named something other than MenuHandler1. It must always be public and it will always have these arguments: Handle, MenuAction, cell, and cell in that order.<br /> <br /> The Handle argument is always the menu that called the handler.<br /> <br /> The MenuAction argument is always one of 7 actions for a standard menu. They are: MenuAction_Start, MenuAction_Display, MenuAction_Select, MenuAction_Cancel, MenuAction_End, MenuAction_DrawItem, and MenuAction_DisplayIitem. We will discuss each of these as we reach their code.<br /> <br /> The two cell arguments meaning depend on the MenuAction argument. '''A common mistake is to assume param1 is the client.''' This is incorrect for MenuAction_Start, MenuAction_End, MenuAction_VoteEnd, MenuAction_VoteStart, and MenuAction_VoteCancel.<br /> <br /> ==== MenuAction_Start ====<br /> <br /> &lt;pawn&gt; case MenuAction_Start:<br /> {<br /> PrintToServer(&quot;Displaying menu&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> * param1: not set<br /> * param2: not set<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_Start doesn't set param1 and param2. It is fired when the menu is displayed to one or more users using DisplayMenu, DisplayMenuAtItem, VoteMenu, or VoteMenuToAll.<br /> <br /> ==== MenuAction_Display ====<br /> <br /> &lt;pawn&gt; case MenuAction_Display:<br /> {<br /> decl String:buffer[255];<br /> Format(buffer, sizeof(buffer), &quot;%T&quot;, &quot;Vote Nextmap&quot;, param1);<br /> <br /> new Handle:panel = Handle:param2;<br /> SetPanelTitle(panel, buffer);<br /> PrintToServer(&quot;Client %d was sent menu with panel %x&quot;, param1, param2);<br /> }&lt;/pawn&gt;<br /> <br /> * param1: client index<br /> * param2: MenuPanel Handle<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_Display is called once for each user a menu is displayed to. param1 is the client, param2 is the MenuPanel handle.<br /> <br /> SetPanelTitle is used to change the menu's title based on the language of the user viewing it using the Translations system. Previous versions of this guide suggested using SetMenuTitle. This is a ''bad'' idea, as it changes the title globally.<br /> <br /> ==== MenuAction_Select ====<br /> &lt;pawn&gt; case MenuAction_Select:<br /> {<br /> decl String:info[32];<br /> GetMenuItem(menu, param2, info, sizeof(info));<br /> if (StrEqual(info, CHOICE3))<br /> {<br /> PrintToServer(&quot;Client %d somehow selected %s despite it being disabled&quot;, param1, info);<br /> }<br /> else<br /> {<br /> PrintToServer(&quot;Client %d selected %s&quot;, param1, info);<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> * param1: client index<br /> * param2: item number for use with GetMenuItem<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_Select is called when a user selects a non-control item on the menu (something added using AddMenuItem). param1 is the client, param2 is the menu position of the item the client selected.<br /> <br /> Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.<br /> <br /> GetMenuItem is used here to fetch the info string.<br /> <br /> ==== MenuAction_Cancel ====<br /> <br /> case MenuAction_Cancel:<br /> {<br /> PrintToServer(&quot;Client %d's menu was cancelled for reason %d&quot;, param1, param2);<br /> }<br /> <br /> * param1: client index<br /> * param2: MenuCancel reason<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_Cancel is called whenever a user closes a menu or it is closed for them for another reason. param1 is the client, param2 is the close reason.<br /> <br /> The close reasons you can receive are:<br /> <br /> * MenuCancel_Disconnected - The client got disconnected from the server.<br /> * MenuCancel_Interrupted - Another menu opened, automatically closing our menu.<br /> * MenuCancel_Exit - The client selected Exit. Not called if SetMenuExitBack was set to true. Not called if SetMenuExit was set to false.<br /> * MenuCancel_NoDisplay - Our menu never displayed to the client for whatever reason.<br /> * MenuCancel_Timeout - The menu timed out. Not called if the menu time was MENU_TIME_FOREVER.<br /> * MenuCancel_ExitBack - The client selected Back. Only called if SetMenuExitBack has been called and set to true before the menu was sent. Not called if SetMenuExit was set to false.<br /> <br /> ==== MenuAction_End ====<br /> &lt;pawn&gt; case MenuAction_End:<br /> {<br /> CloseHandle(menu);<br /> }&lt;/pawn&gt;<br /> <br /> * param1: MenuEnd reason<br /> * param2: If param1 is MenuEnd_Cancelled, the MenuCancel reason<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_End is called when ''all'' clients have closed a menu or vote. For menus that are not going to be redisplayed, it is required that you call CloseHandle on the menu here.<br /> <br /> The parameters are rarely used in MenuAction_End. param1 is the menu end reason. param2 depends on param1.<br /> <br /> The end reasons you can receive for normal menus are:<br /> <br /> * MenuEnd_Selected - The menu closed because an item was selected (MenuAction_Select was fired)<br /> * MenuEnd_Cancelled - The menu was cancelled (MenuAction_Cancel was fired), cancel reason is in param2; cancel reason can be any of the ones listed in MenuAction_Cancel except MenuCancel_Exit or MenuCancel_ExitBack<br /> * MenuEnd_Exit - The menu was exited via the Exit item (MenuAction_Cancel was fired with param2 set to MenuCancel_Exit)<br /> * MenuEnd_ExitBack - The menu was exited via the ExitBack item (MenuAction_Cancel was fired with param 2 set to MenuCancel_ExitBack)<br /> <br /> Note: You do '''not''' have the client index during this callback, so it's far too late to do anything useful with this information.<br /> <br /> ==== MenuAction_DrawItem ====<br /> &lt;pawn&gt; case MenuAction_DrawItem:<br /> {<br /> new style;<br /> decl String:info[32];<br /> GetMenuItem(menu, param2, info, sizeof(info), style);<br /> <br /> if (StrEqual(info, CHOICE3))<br /> {<br /> return ITEMDRAW_DISABLED;<br /> }<br /> else<br /> {<br /> return style;<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> * param1: client index<br /> * param2: item number for use with GetMenuItem<br /> * return: new ITEMDRAW properties or style from GetMenuItem. Since 0 is ITEMDRAW_DEFAULT, returning 0 clears all styles for this item.<br /> <br /> MenuAction_DrawItem is called once for each item on the menu for each user. You can manipulate its draw style here. param1 is the client, param2 is the menu position.<br /> <br /> Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.<br /> <br /> GetMenuItem is used here to fetch the info string and menu style.<br /> <br /> You should return the style you want the menu item to have. In our example, if client 1 is viewing the menu, we want CHOICE3 to be disabled.<br /> <br /> the return value is a bitfield, so to apply multiple styles, you do something like this:<br /> <br /> return ITEMDRAW_NOTEXT | ITEMDRAW_SPACER;<br /> <br /> '''Failing to return the current item's style if you don't change the style is a programmer error.'''<br /> <br /> ==== MenuAction_DisplayItem ====<br /> <br /> &lt;pawn&gt; case MenuAction_DisplayItem:<br /> {<br /> decl String:info[32];<br /> GetMenuItem(menu, param2, info, sizeof(info));<br /> <br /> decl String:display[64];<br /> <br /> if (StrEqual(info, CHOICE3))<br /> {<br /> Format(display, sizeof(display), &quot;%T&quot;, &quot;Choice 3&quot;, param1);<br /> return RedrawMenuItem(display);<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> * param1: client index<br /> * param2: item number for use with GetMenuItem<br /> * return: return value from RedrawMenuItem or 0 for no change<br /> <br /> MenuAction_DrawItem is called once for each item on the menu for each user. You can manipulate its text here. param1 is the client, param2 is the menu position.<br /> <br /> This callback is intended for use with the Translation system.<br /> <br /> Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.<br /> <br /> GetMenuItem is used here to fetch the info string.<br /> <br /> Once we have the info string, we compare our item to it and apply the appropriate translation string.<br /> <br /> If we change an item, we have to call RedrawMenuItem and return the value it returns. If we do not change an item, we must return 0.<br /> <br /> ==== return ====<br /> &lt;pawn&gt; return 0;&lt;/pawn&gt;<br /> <br /> If you handle MenuAction_DrawItem or MenuAction_DisplayItem, you will get the following warning if you fail to return 0 after the switch block:<br /> <br /> &lt;code&gt;warning 209: function &quot;MenuHandler1&quot; should return a value&lt;/code&gt;<br /> <br /> This is because MenuAction_DrawItem and MenuAction_DisplayItem have return values, while the other actions only return 0.<br /> <br /> == The End ==<br /> Hopefully this walk through a simple menu helped you understand why each call is being made where. Menus have some options that we didn't explore here, such as disabling pagination (which is enabled by default). You may want to refer to the main Menu documentation for more details.</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Menus_Step_By_Step_(SourceMod_Scripting)&diff=10170 2016-06-17T12:11:15Z

<p>Xerox8521: /* OnPluginStart */</p> <hr /> <div>The SourceMod [[Menu API (SourceMod)|Menu API]] is fairly useful for displaying an information panel, a menu, or a vote to users. This document talks specifically about menus and how to create one.<br /> <br /> == The working menu example ==<br /> <br /> This is the working code example that we'll be talking about in the upcoming sections. If you need to, you can come back and look at it as you read the rest of this page.<br /> <br /> We will be using PrintToServer to print text to the server console as we run through the events.<br /> <br /> Usage of the [[Translations (SourceMod Scripting)|Translations]] system is highly recommended and will be used in this example.<br /> <br /> &lt;pawn&gt;#define CHOICE1 &quot;#choice1&quot;<br /> #define CHOICE2 &quot;#choice2&quot;<br /> #define CHOICE3 &quot;#choice3&quot;<br /> <br /> public void OnPluginStart()<br /> {<br /> LoadTranslations(&quot;menu_test.phrases&quot;);<br /> RegConsoleCmd(&quot;menu_test1&quot;, Menu_Test1);<br /> }<br /> <br /> public int MenuHandler1(Menu menu, MenuAction action, int param1, int param2)<br /> {<br /> switch(action)<br /> {<br /> case MenuAction_Start:<br /> {<br /> PrintToServer(&quot;Displaying menu&quot;);<br /> }<br /> <br /> case MenuAction_Display:<br /> {<br /> char buffer[255];<br /> Format(buffer, sizeof(buffer), &quot;%T&quot;, &quot;Vote Nextmap&quot;, param1);<br /> <br /> Panel panel = view_as&lt;Panel&gt;(param2);<br /> panel.SetTitle(buffer);<br /> PrintToServer(&quot;Client %d was sent menu with panel %x&quot;, param1, param2);<br /> }<br /> <br /> case MenuAction_Select:<br /> {<br /> char info[32];<br /> menu.GetItem(param2, info, sizeof(info));<br /> if (StrEqual(info, CHOICE3))<br /> {<br /> PrintToServer(&quot;Client %d somehow selected %s despite it being disabled&quot;, param1, info);<br /> }<br /> else<br /> {<br /> PrintToServer(&quot;Client %d selected %s&quot;, param1, info);<br /> }<br /> }<br /> <br /> case MenuAction_Cancel:<br /> {<br /> PrintToServer(&quot;Client %d's menu was cancelled for reason %d&quot;, param1, param2);<br /> }<br /> <br /> case MenuAction_End:<br /> {<br /> delete menu;<br /> }<br /> <br /> case MenuAction_DrawItem:<br /> {<br /> int style;<br /> char info[32];<br /> menu.GetItem(param2, info, sizeof(info), style);<br /> <br /> if (StrEqual(info, CHOICE3))<br /> {<br /> return ITEMDRAW_DISABLED;<br /> }<br /> else<br /> {<br /> return style;<br /> }<br /> }<br /> <br /> case MenuAction_DisplayItem:<br /> {<br /> char info[32];<br /> menu.GetItem(param2, info, sizeof(info));<br /> <br /> char display[64];<br /> <br /> if (StrEqual(info, CHOICE3))<br /> {<br /> Format(display, sizeof(display), &quot;%T&quot;, &quot;Choice 3&quot;, param1);<br /> return RedrawMenuItem(display);<br /> }<br /> }<br /> }<br /> <br /> return 0;<br /> }<br /> <br /> public Action Menu_Test1(int client, int args)<br /> {<br /> Menu menu = new Menu(MenuHandler1, MENU_ACTIONS_ALL);<br /> menu.SetTitle(&quot;%T&quot;, &quot;Menu Title&quot;, LANG_SERVER);<br /> menu.AddItem(CHOICE1, &quot;Choice 1&quot;);<br /> menu.AddItem(CHOICE2, &quot;Choice 2&quot;);<br /> menu.AddItem(CHOICE3, &quot;Choice 3&quot;);<br /> menu.ExitButton = false;<br /> menu.Display(client, 20);<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> The translation file that goes with it... addons/sourcemod/translations/menu_test.phrases.txt<br /> <br /> &lt;pre&gt;&quot;Phrases&quot;<br /> {<br /> &quot;Choice 3&quot;<br /> {<br /> &quot;en&quot; &quot;Choice Translated&quot;<br /> }<br /> <br /> &quot;Menu Title&quot;<br /> {<br /> &quot;en&quot; &quot;Menu Title Translated&quot;<br /> }<br /> }&lt;/pre&gt;<br /> <br /> == Step by Step ==<br /> <br /> === OnPluginStart ===<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> LoadTranslations(&quot;menu_test.phrases&quot;);<br /> RegConsoleCmd(&quot;menu_test1&quot;, Menu_Test1);<br /> }&lt;/pawn&gt;<br /> <br /> This block is here to register the command /menu_test1 so that this menu can be tested.<br /> <br /> This block is beyond the scope of this page. See: [[Introduction to SourceMod Plugins#Plugin Structure|Plugin Structure]] for OnPluginStart, [[Translations (SourceMod Scripting)|Translations]] for LoadTranslations, and [[Commands_(SourceMod_Scripting)|Commands]] for RegConsoleCmd.<br /> <br /> === Menu_Test1 ===<br /> <br /> Menu_Test1 is a ConCmd, which is beyond the scope of this page. See: [[Commands (SourceMod Scripting)|Commands]] for more details on that. We're going to be talking about what's in it.<br /> <br /> ==== CreateMenu ====<br /> <br /> &lt;pawn&gt; new Handle:menu = CreateMenu(MenuHandler1, MENU_ACTIONS_ALL);&lt;/pawn&gt;<br /> <br /> CreateMenu takes two arguments.<br /> <br /> The first is a function that matches the [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=768&amp; MenuHandler] callback signature.<br /> <br /> The second is a bitmask of which MenuAction events we are going to handle in our MenuHandler. There are 7 that apply to standard menus: <br /> * MenuAction_Start - Called once when a menu is displayed<br /> * MenuAction_Display - Called once for each client a menu is displayed to<br /> * MenuAction_Select - Called when a client makes a selection from the menu that isn't Previous, Next, Back, or Exit.<br /> * MenuAction_Cancel - Called when a client closes a menu or it is closed on them<br /> * MenuAction_End - Called once when all clients have closed the menu<br /> * MenuAction_DrawItem - Called once for each item for each user a menu is displayed to. Can change the menu item style.<br /> * MenuAction_DisplayIitem. - Called once for each item for each user a menu is displayed to. Can change the menu item text.<br /> <br /> These will be discussed in more detail in the MenuHandler1 section.<br /> <br /> Of those 7, 3 are called whether you specify them or not: MenuAction_Select, MenuAction_Cancel, and MenuAction_End.<br /> <br /> MENU_ACTIONS_DEFAULT sets just the 3 required fields, while MENU_ACTIONS_ALL specifies all 10 actions (including the 3 vote actions).<br /> <br /> To specify just a few of them, you can do this:<br /> <br /> &lt;pawn&gt; new Handle:menu = CreateMenu(MenuHandler1, MenuAction_Start|MenuAction_Select|MenuAction_Cancel|MenuAction_End);&lt;/pawn&gt;<br /> <br /> ==== SetMenuTitle ====<br /> &lt;pawn&gt; SetMenuTitle(menu, &quot;%T&quot;, &quot;Menu Title&quot;, LANG_SERVER);&lt;/pawn&gt;<br /> <br /> Sets the menu's title. This example uses the translation system and the server's default language. This isn't strictly necessary as we will set the menu title again later.<br /> <br /> ==== AddMenuItem ====<br /> <br /> &lt;pawn&gt; AddMenuItem(menu, CHOICE1, &quot;Choice 1&quot;);<br /> AddMenuItem(menu, CHOICE2, &quot;Choice 2&quot;);<br /> AddMenuItem(menu, CHOICE3, &quot;Choice 3&quot;);&lt;/pawn&gt;<br /> <br /> A menu isn't useful without something in it!<br /> AddMenuItem has 3 required arguments and one optional argument.<br /> <br /> The 3 required arguments are:<br /> <br /> The Menu handle, the Info string, and the Display string.<br /> <br /> The Info String is a string that is used to uniquely identify this menu item. It is never displayed to the user, but is used in various callbacks.<br /> <br /> The Display String is the default text to be used for this item on the menu. It can be changed via the menu's MenuAction_DisplayItem callback.<br /> <br /> The optional argument is the menu's item draw style. It can be one of these values:<br /> * ITEMDRAW_DEFAULT - Displays text as normal.<br /> * ITEMDRAW_DISABLED - Item is displayed and has a number, but can't be selected.<br /> * ITEMDRAW_RAWLINE - Item is displayed, but doesn't have a number assigned to it and thus can't be selected<br /> * ITEMDRAW_NOTEXT - Draws an item with no text. Not very useful.<br /> * ITEMDRAW_SPACER - Item is blank, but has a number. Can't be selected.<br /> * ITEMDRAW_IGNORE - Item is blank with no number. Can't be selected.<br /> * ITEMDRAW_CONTROL - Don't use this one. It's used for the items SourceMod automatically adds.<br /> <br /> Be aware that if your CreateMenu second argument includes MenuAction_DrawItem or MENU_ACTIONS_ALL and you don't actually implement the MenuAction_DrawItem callback (or implement it and don't return the current item's style if you don't change it), your style here will be completely ignored.<br /> <br /> ==== SetMenuExitButton ====<br /> &lt;pawn&gt; SetMenuExitButton(menu, false);&lt;/pawn&gt;<br /> <br /> Defaults to true.<br /> <br /> It set to false, the menu won't have an exit button.<br /> <br /> ==== SetMenuExitBackButton ====<br /> &lt;pawn&gt; SetMenuExitBackButton(menu, false);&lt;/pawn&gt;<br /> <br /> (This isn't in the code above, but it should be mentioned) <br /> <br /> Defaults to false.<br /> <br /> Should only be used if the menu is a submenu, with the menu set up to check the cancel reason to see if the ExitBack action was used.<br /> <br /> If set to true, replaces the Exit item with the Back item. The Back item still cancels the menu, but has a separate cancel reason.<br /> <br /> This can be used to dynamically set if a menu is being called as its own menu or as a submenu.<br /> <br /> ==== DisplayMenu ====<br /> &lt;pawn&gt; DisplayMenu(menu, client, 20);&lt;/pawn&gt;<br /> <br /> DisplayMenu takes 3 arguments:<br /> <br /> A Menu handle, a client index, and the amount of time in seconds to show the menu.<br /> <br /> If you want the menu to show forever, pass MENU_TIME_FOREVER as the third argument.<br /> <br /> === MenuHandler1 ===<br /> &lt;pawn&gt;public MenuHandler1(Handle:menu, MenuAction:action, param1, param2)&lt;/pawn&gt;<br /> <br /> MenuHandler1 is a function whose signature matches the MenuHandler callback. It can be named something other than MenuHandler1. It must always be public and it will always have these arguments: Handle, MenuAction, cell, and cell in that order.<br /> <br /> The Handle argument is always the menu that called the handler.<br /> <br /> The MenuAction argument is always one of 7 actions for a standard menu. They are: MenuAction_Start, MenuAction_Display, MenuAction_Select, MenuAction_Cancel, MenuAction_End, MenuAction_DrawItem, and MenuAction_DisplayIitem. We will discuss each of these as we reach their code.<br /> <br /> The two cell arguments meaning depend on the MenuAction argument. '''A common mistake is to assume param1 is the client.''' This is incorrect for MenuAction_Start, MenuAction_End, MenuAction_VoteEnd, MenuAction_VoteStart, and MenuAction_VoteCancel.<br /> <br /> ==== MenuAction_Start ====<br /> <br /> &lt;pawn&gt; case MenuAction_Start:<br /> {<br /> PrintToServer(&quot;Displaying menu&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> * param1: not set<br /> * param2: not set<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_Start doesn't set param1 and param2. It is fired when the menu is displayed to one or more users using DisplayMenu, DisplayMenuAtItem, VoteMenu, or VoteMenuToAll.<br /> <br /> ==== MenuAction_Display ====<br /> <br /> &lt;pawn&gt; case MenuAction_Display:<br /> {<br /> decl String:buffer[255];<br /> Format(buffer, sizeof(buffer), &quot;%T&quot;, &quot;Vote Nextmap&quot;, param1);<br /> <br /> new Handle:panel = Handle:param2;<br /> SetPanelTitle(panel, buffer);<br /> PrintToServer(&quot;Client %d was sent menu with panel %x&quot;, param1, param2);<br /> }&lt;/pawn&gt;<br /> <br /> * param1: client index<br /> * param2: MenuPanel Handle<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_Display is called once for each user a menu is displayed to. param1 is the client, param2 is the MenuPanel handle.<br /> <br /> SetPanelTitle is used to change the menu's title based on the language of the user viewing it using the Translations system. Previous versions of this guide suggested using SetMenuTitle. This is a ''bad'' idea, as it changes the title globally.<br /> <br /> ==== MenuAction_Select ====<br /> &lt;pawn&gt; case MenuAction_Select:<br /> {<br /> decl String:info[32];<br /> GetMenuItem(menu, param2, info, sizeof(info));<br /> if (StrEqual(info, CHOICE3))<br /> {<br /> PrintToServer(&quot;Client %d somehow selected %s despite it being disabled&quot;, param1, info);<br /> }<br /> else<br /> {<br /> PrintToServer(&quot;Client %d selected %s&quot;, param1, info);<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> * param1: client index<br /> * param2: item number for use with GetMenuItem<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_Select is called when a user selects a non-control item on the menu (something added using AddMenuItem). param1 is the client, param2 is the menu position of the item the client selected.<br /> <br /> Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.<br /> <br /> GetMenuItem is used here to fetch the info string.<br /> <br /> ==== MenuAction_Cancel ====<br /> <br /> case MenuAction_Cancel:<br /> {<br /> PrintToServer(&quot;Client %d's menu was cancelled for reason %d&quot;, param1, param2);<br /> }<br /> <br /> * param1: client index<br /> * param2: MenuCancel reason<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_Cancel is called whenever a user closes a menu or it is closed for them for another reason. param1 is the client, param2 is the close reason.<br /> <br /> The close reasons you can receive are:<br /> <br /> * MenuCancel_Disconnected - The client got disconnected from the server.<br /> * MenuCancel_Interrupted - Another menu opened, automatically closing our menu.<br /> * MenuCancel_Exit - The client selected Exit. Not called if SetMenuExitBack was set to true. Not called if SetMenuExit was set to false.<br /> * MenuCancel_NoDisplay - Our menu never displayed to the client for whatever reason.<br /> * MenuCancel_Timeout - The menu timed out. Not called if the menu time was MENU_TIME_FOREVER.<br /> * MenuCancel_ExitBack - The client selected Back. Only called if SetMenuExitBack has been called and set to true before the menu was sent. Not called if SetMenuExit was set to false.<br /> <br /> ==== MenuAction_End ====<br /> &lt;pawn&gt; case MenuAction_End:<br /> {<br /> CloseHandle(menu);<br /> }&lt;/pawn&gt;<br /> <br /> * param1: MenuEnd reason<br /> * param2: If param1 is MenuEnd_Cancelled, the MenuCancel reason<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_End is called when ''all'' clients have closed a menu or vote. For menus that are not going to be redisplayed, it is required that you call CloseHandle on the menu here.<br /> <br /> The parameters are rarely used in MenuAction_End. param1 is the menu end reason. param2 depends on param1.<br /> <br /> The end reasons you can receive for normal menus are:<br /> <br /> * MenuEnd_Selected - The menu closed because an item was selected (MenuAction_Select was fired)<br /> * MenuEnd_Cancelled - The menu was cancelled (MenuAction_Cancel was fired), cancel reason is in param2; cancel reason can be any of the ones listed in MenuAction_Cancel except MenuCancel_Exit or MenuCancel_ExitBack<br /> * MenuEnd_Exit - The menu was exited via the Exit item (MenuAction_Cancel was fired with param2 set to MenuCancel_Exit)<br /> * MenuEnd_ExitBack - The menu was exited via the ExitBack item (MenuAction_Cancel was fired with param 2 set to MenuCancel_ExitBack)<br /> <br /> Note: You do '''not''' have the client index during this callback, so it's far too late to do anything useful with this information.<br /> <br /> ==== MenuAction_DrawItem ====<br /> &lt;pawn&gt; case MenuAction_DrawItem:<br /> {<br /> new style;<br /> decl String:info[32];<br /> GetMenuItem(menu, param2, info, sizeof(info), style);<br /> <br /> if (StrEqual(info, CHOICE3))<br /> {<br /> return ITEMDRAW_DISABLED;<br /> }<br /> else<br /> {<br /> return style;<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> * param1: client index<br /> * param2: item number for use with GetMenuItem<br /> * return: new ITEMDRAW properties or style from GetMenuItem. Since 0 is ITEMDRAW_DEFAULT, returning 0 clears all styles for this item.<br /> <br /> MenuAction_DrawItem is called once for each item on the menu for each user. You can manipulate its draw style here. param1 is the client, param2 is the menu position.<br /> <br /> Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.<br /> <br /> GetMenuItem is used here to fetch the info string and menu style.<br /> <br /> You should return the style you want the menu item to have. In our example, if client 1 is viewing the menu, we want CHOICE3 to be disabled.<br /> <br /> the return value is a bitfield, so to apply multiple styles, you do something like this:<br /> <br /> return ITEMDRAW_NOTEXT | ITEMDRAW_SPACER;<br /> <br /> '''Failing to return the current item's style if you don't change the style is a programmer error.'''<br /> <br /> ==== MenuAction_DisplayItem ====<br /> <br /> &lt;pawn&gt; case MenuAction_DisplayItem:<br /> {<br /> decl String:info[32];<br /> GetMenuItem(menu, param2, info, sizeof(info));<br /> <br /> decl String:display[64];<br /> <br /> if (StrEqual(info, CHOICE3))<br /> {<br /> Format(display, sizeof(display), &quot;%T&quot;, &quot;Choice 3&quot;, param1);<br /> return RedrawMenuItem(display);<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> * param1: client index<br /> * param2: item number for use with GetMenuItem<br /> * return: return value from RedrawMenuItem or 0 for no change<br /> <br /> MenuAction_DrawItem is called once for each item on the menu for each user. You can manipulate its text here. param1 is the client, param2 is the menu position.<br /> <br /> This callback is intended for use with the Translation system.<br /> <br /> Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.<br /> <br /> GetMenuItem is used here to fetch the info string.<br /> <br /> Once we have the info string, we compare our item to it and apply the appropriate translation string.<br /> <br /> If we change an item, we have to call RedrawMenuItem and return the value it returns. If we do not change an item, we must return 0.<br /> <br /> ==== return ====<br /> &lt;pawn&gt; return 0;&lt;/pawn&gt;<br /> <br /> If you handle MenuAction_DrawItem or MenuAction_DisplayItem, you will get the following warning if you fail to return 0 after the switch block:<br /> <br /> &lt;code&gt;warning 209: function &quot;MenuHandler1&quot; should return a value&lt;/code&gt;<br /> <br /> This is because MenuAction_DrawItem and MenuAction_DisplayItem have return values, while the other actions only return 0.<br /> <br /> == The End ==<br /> Hopefully this walk through a simple menu helped you understand why each call is being made where. Menus have some options that we didn't explore here, such as disabling pagination (which is enabled by default). You may want to refer to the main Menu documentation for more details.</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Menus_Step_By_Step_(SourceMod_Scripting)&diff=10169 2016-06-17T12:10:45Z

<p>Xerox8521: Updated to 1.7 Syntax</p> <hr /> <div>The SourceMod [[Menu API (SourceMod)|Menu API]] is fairly useful for displaying an information panel, a menu, or a vote to users. This document talks specifically about menus and how to create one.<br /> <br /> == The working menu example ==<br /> <br /> This is the working code example that we'll be talking about in the upcoming sections. If you need to, you can come back and look at it as you read the rest of this page.<br /> <br /> We will be using PrintToServer to print text to the server console as we run through the events.<br /> <br /> Usage of the [[Translations (SourceMod Scripting)|Translations]] system is highly recommended and will be used in this example.<br /> <br /> &lt;pawn&gt;#define CHOICE1 &quot;#choice1&quot;<br /> #define CHOICE2 &quot;#choice2&quot;<br /> #define CHOICE3 &quot;#choice3&quot;<br /> <br /> public void OnPluginStart()<br /> {<br /> LoadTranslations(&quot;menu_test.phrases&quot;);<br /> RegConsoleCmd(&quot;menu_test1&quot;, Menu_Test1);<br /> }<br /> <br /> public int MenuHandler1(Menu menu, MenuAction action, int param1, int param2)<br /> {<br /> switch(action)<br /> {<br /> case MenuAction_Start:<br /> {<br /> PrintToServer(&quot;Displaying menu&quot;);<br /> }<br /> <br /> case MenuAction_Display:<br /> {<br /> char buffer[255];<br /> Format(buffer, sizeof(buffer), &quot;%T&quot;, &quot;Vote Nextmap&quot;, param1);<br /> <br /> Panel panel = view_as&lt;Panel&gt;(param2);<br /> panel.SetTitle(buffer);<br /> PrintToServer(&quot;Client %d was sent menu with panel %x&quot;, param1, param2);<br /> }<br /> <br /> case MenuAction_Select:<br /> {<br /> char info[32];<br /> menu.GetItem(param2, info, sizeof(info));<br /> if (StrEqual(info, CHOICE3))<br /> {<br /> PrintToServer(&quot;Client %d somehow selected %s despite it being disabled&quot;, param1, info);<br /> }<br /> else<br /> {<br /> PrintToServer(&quot;Client %d selected %s&quot;, param1, info);<br /> }<br /> }<br /> <br /> case MenuAction_Cancel:<br /> {<br /> PrintToServer(&quot;Client %d's menu was cancelled for reason %d&quot;, param1, param2);<br /> }<br /> <br /> case MenuAction_End:<br /> {<br /> delete menu;<br /> }<br /> <br /> case MenuAction_DrawItem:<br /> {<br /> int style;<br /> char info[32];<br /> menu.GetItem(param2, info, sizeof(info), style);<br /> <br /> if (StrEqual(info, CHOICE3))<br /> {<br /> return ITEMDRAW_DISABLED;<br /> }<br /> else<br /> {<br /> return style;<br /> }<br /> }<br /> <br /> case MenuAction_DisplayItem:<br /> {<br /> char info[32];<br /> menu.GetItem(param2, info, sizeof(info));<br /> <br /> char display[64];<br /> <br /> if (StrEqual(info, CHOICE3))<br /> {<br /> Format(display, sizeof(display), &quot;%T&quot;, &quot;Choice 3&quot;, param1);<br /> return RedrawMenuItem(display);<br /> }<br /> }<br /> }<br /> <br /> return 0;<br /> }<br /> <br /> public Action Menu_Test1(int client, int args)<br /> {<br /> Menu menu = new Menu(MenuHandler1, MENU_ACTIONS_ALL);<br /> menu.SetTitle(&quot;%T&quot;, &quot;Menu Title&quot;, LANG_SERVER);<br /> menu.AddItem(CHOICE1, &quot;Choice 1&quot;);<br /> menu.AddItem(CHOICE2, &quot;Choice 2&quot;);<br /> menu.AddItem(CHOICE3, &quot;Choice 3&quot;);<br /> menu.ExitButton = false;<br /> menu.Display(client, 20);<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> The translation file that goes with it... addons/sourcemod/translations/menu_test.phrases.txt<br /> <br /> &lt;pre&gt;&quot;Phrases&quot;<br /> {<br /> &quot;Choice 3&quot;<br /> {<br /> &quot;en&quot; &quot;Choice Translated&quot;<br /> }<br /> <br /> &quot;Menu Title&quot;<br /> {<br /> &quot;en&quot; &quot;Menu Title Translated&quot;<br /> }<br /> }&lt;/pre&gt;<br /> <br /> == Step by Step ==<br /> <br /> === OnPluginStart ===<br /> <br /> &lt;pawn&gt;public OnPluginStart()<br /> {<br /> LoadTranslations(&quot;menu_test.phrases&quot;);<br /> RegConsoleCmd(&quot;menu_test1&quot;, Menu_Test1);<br /> }&lt;/pawn&gt;<br /> <br /> This block is here to register the command /menu_test1 so that this menu can be tested.<br /> <br /> This block is beyond the scope of this page. See: [[Introduction to SourceMod Plugins#Plugin Structure|Plugin Structure]] for OnPluginStart, [[Translations (SourceMod Scripting)|Translations]] for LoadTranslations, and [[Commands_(SourceMod_Scripting)|Commands]] for RegConsoleCmd.<br /> <br /> === Menu_Test1 ===<br /> <br /> Menu_Test1 is a ConCmd, which is beyond the scope of this page. See: [[Commands (SourceMod Scripting)|Commands]] for more details on that. We're going to be talking about what's in it.<br /> <br /> ==== CreateMenu ====<br /> <br /> &lt;pawn&gt; new Handle:menu = CreateMenu(MenuHandler1, MENU_ACTIONS_ALL);&lt;/pawn&gt;<br /> <br /> CreateMenu takes two arguments.<br /> <br /> The first is a function that matches the [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=768&amp; MenuHandler] callback signature.<br /> <br /> The second is a bitmask of which MenuAction events we are going to handle in our MenuHandler. There are 7 that apply to standard menus: <br /> * MenuAction_Start - Called once when a menu is displayed<br /> * MenuAction_Display - Called once for each client a menu is displayed to<br /> * MenuAction_Select - Called when a client makes a selection from the menu that isn't Previous, Next, Back, or Exit.<br /> * MenuAction_Cancel - Called when a client closes a menu or it is closed on them<br /> * MenuAction_End - Called once when all clients have closed the menu<br /> * MenuAction_DrawItem - Called once for each item for each user a menu is displayed to. Can change the menu item style.<br /> * MenuAction_DisplayIitem. - Called once for each item for each user a menu is displayed to. Can change the menu item text.<br /> <br /> These will be discussed in more detail in the MenuHandler1 section.<br /> <br /> Of those 7, 3 are called whether you specify them or not: MenuAction_Select, MenuAction_Cancel, and MenuAction_End.<br /> <br /> MENU_ACTIONS_DEFAULT sets just the 3 required fields, while MENU_ACTIONS_ALL specifies all 10 actions (including the 3 vote actions).<br /> <br /> To specify just a few of them, you can do this:<br /> <br /> &lt;pawn&gt; new Handle:menu = CreateMenu(MenuHandler1, MenuAction_Start|MenuAction_Select|MenuAction_Cancel|MenuAction_End);&lt;/pawn&gt;<br /> <br /> ==== SetMenuTitle ====<br /> &lt;pawn&gt; SetMenuTitle(menu, &quot;%T&quot;, &quot;Menu Title&quot;, LANG_SERVER);&lt;/pawn&gt;<br /> <br /> Sets the menu's title. This example uses the translation system and the server's default language. This isn't strictly necessary as we will set the menu title again later.<br /> <br /> ==== AddMenuItem ====<br /> <br /> &lt;pawn&gt; AddMenuItem(menu, CHOICE1, &quot;Choice 1&quot;);<br /> AddMenuItem(menu, CHOICE2, &quot;Choice 2&quot;);<br /> AddMenuItem(menu, CHOICE3, &quot;Choice 3&quot;);&lt;/pawn&gt;<br /> <br /> A menu isn't useful without something in it!<br /> AddMenuItem has 3 required arguments and one optional argument.<br /> <br /> The 3 required arguments are:<br /> <br /> The Menu handle, the Info string, and the Display string.<br /> <br /> The Info String is a string that is used to uniquely identify this menu item. It is never displayed to the user, but is used in various callbacks.<br /> <br /> The Display String is the default text to be used for this item on the menu. It can be changed via the menu's MenuAction_DisplayItem callback.<br /> <br /> The optional argument is the menu's item draw style. It can be one of these values:<br /> * ITEMDRAW_DEFAULT - Displays text as normal.<br /> * ITEMDRAW_DISABLED - Item is displayed and has a number, but can't be selected.<br /> * ITEMDRAW_RAWLINE - Item is displayed, but doesn't have a number assigned to it and thus can't be selected<br /> * ITEMDRAW_NOTEXT - Draws an item with no text. Not very useful.<br /> * ITEMDRAW_SPACER - Item is blank, but has a number. Can't be selected.<br /> * ITEMDRAW_IGNORE - Item is blank with no number. Can't be selected.<br /> * ITEMDRAW_CONTROL - Don't use this one. It's used for the items SourceMod automatically adds.<br /> <br /> Be aware that if your CreateMenu second argument includes MenuAction_DrawItem or MENU_ACTIONS_ALL and you don't actually implement the MenuAction_DrawItem callback (or implement it and don't return the current item's style if you don't change it), your style here will be completely ignored.<br /> <br /> ==== SetMenuExitButton ====<br /> &lt;pawn&gt; SetMenuExitButton(menu, false);&lt;/pawn&gt;<br /> <br /> Defaults to true.<br /> <br /> It set to false, the menu won't have an exit button.<br /> <br /> ==== SetMenuExitBackButton ====<br /> &lt;pawn&gt; SetMenuExitBackButton(menu, false);&lt;/pawn&gt;<br /> <br /> (This isn't in the code above, but it should be mentioned) <br /> <br /> Defaults to false.<br /> <br /> Should only be used if the menu is a submenu, with the menu set up to check the cancel reason to see if the ExitBack action was used.<br /> <br /> If set to true, replaces the Exit item with the Back item. The Back item still cancels the menu, but has a separate cancel reason.<br /> <br /> This can be used to dynamically set if a menu is being called as its own menu or as a submenu.<br /> <br /> ==== DisplayMenu ====<br /> &lt;pawn&gt; DisplayMenu(menu, client, 20);&lt;/pawn&gt;<br /> <br /> DisplayMenu takes 3 arguments:<br /> <br /> A Menu handle, a client index, and the amount of time in seconds to show the menu.<br /> <br /> If you want the menu to show forever, pass MENU_TIME_FOREVER as the third argument.<br /> <br /> === MenuHandler1 ===<br /> &lt;pawn&gt;public MenuHandler1(Handle:menu, MenuAction:action, param1, param2)&lt;/pawn&gt;<br /> <br /> MenuHandler1 is a function whose signature matches the MenuHandler callback. It can be named something other than MenuHandler1. It must always be public and it will always have these arguments: Handle, MenuAction, cell, and cell in that order.<br /> <br /> The Handle argument is always the menu that called the handler.<br /> <br /> The MenuAction argument is always one of 7 actions for a standard menu. They are: MenuAction_Start, MenuAction_Display, MenuAction_Select, MenuAction_Cancel, MenuAction_End, MenuAction_DrawItem, and MenuAction_DisplayIitem. We will discuss each of these as we reach their code.<br /> <br /> The two cell arguments meaning depend on the MenuAction argument. '''A common mistake is to assume param1 is the client.''' This is incorrect for MenuAction_Start, MenuAction_End, MenuAction_VoteEnd, MenuAction_VoteStart, and MenuAction_VoteCancel.<br /> <br /> ==== MenuAction_Start ====<br /> <br /> &lt;pawn&gt; case MenuAction_Start:<br /> {<br /> PrintToServer(&quot;Displaying menu&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> * param1: not set<br /> * param2: not set<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_Start doesn't set param1 and param2. It is fired when the menu is displayed to one or more users using DisplayMenu, DisplayMenuAtItem, VoteMenu, or VoteMenuToAll.<br /> <br /> ==== MenuAction_Display ====<br /> <br /> &lt;pawn&gt; case MenuAction_Display:<br /> {<br /> decl String:buffer[255];<br /> Format(buffer, sizeof(buffer), &quot;%T&quot;, &quot;Vote Nextmap&quot;, param1);<br /> <br /> new Handle:panel = Handle:param2;<br /> SetPanelTitle(panel, buffer);<br /> PrintToServer(&quot;Client %d was sent menu with panel %x&quot;, param1, param2);<br /> }&lt;/pawn&gt;<br /> <br /> * param1: client index<br /> * param2: MenuPanel Handle<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_Display is called once for each user a menu is displayed to. param1 is the client, param2 is the MenuPanel handle.<br /> <br /> SetPanelTitle is used to change the menu's title based on the language of the user viewing it using the Translations system. Previous versions of this guide suggested using SetMenuTitle. This is a ''bad'' idea, as it changes the title globally.<br /> <br /> ==== MenuAction_Select ====<br /> &lt;pawn&gt; case MenuAction_Select:<br /> {<br /> decl String:info[32];<br /> GetMenuItem(menu, param2, info, sizeof(info));<br /> if (StrEqual(info, CHOICE3))<br /> {<br /> PrintToServer(&quot;Client %d somehow selected %s despite it being disabled&quot;, param1, info);<br /> }<br /> else<br /> {<br /> PrintToServer(&quot;Client %d selected %s&quot;, param1, info);<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> * param1: client index<br /> * param2: item number for use with GetMenuItem<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_Select is called when a user selects a non-control item on the menu (something added using AddMenuItem). param1 is the client, param2 is the menu position of the item the client selected.<br /> <br /> Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.<br /> <br /> GetMenuItem is used here to fetch the info string.<br /> <br /> ==== MenuAction_Cancel ====<br /> <br /> case MenuAction_Cancel:<br /> {<br /> PrintToServer(&quot;Client %d's menu was cancelled for reason %d&quot;, param1, param2);<br /> }<br /> <br /> * param1: client index<br /> * param2: MenuCancel reason<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_Cancel is called whenever a user closes a menu or it is closed for them for another reason. param1 is the client, param2 is the close reason.<br /> <br /> The close reasons you can receive are:<br /> <br /> * MenuCancel_Disconnected - The client got disconnected from the server.<br /> * MenuCancel_Interrupted - Another menu opened, automatically closing our menu.<br /> * MenuCancel_Exit - The client selected Exit. Not called if SetMenuExitBack was set to true. Not called if SetMenuExit was set to false.<br /> * MenuCancel_NoDisplay - Our menu never displayed to the client for whatever reason.<br /> * MenuCancel_Timeout - The menu timed out. Not called if the menu time was MENU_TIME_FOREVER.<br /> * MenuCancel_ExitBack - The client selected Back. Only called if SetMenuExitBack has been called and set to true before the menu was sent. Not called if SetMenuExit was set to false.<br /> <br /> ==== MenuAction_End ====<br /> &lt;pawn&gt; case MenuAction_End:<br /> {<br /> CloseHandle(menu);<br /> }&lt;/pawn&gt;<br /> <br /> * param1: MenuEnd reason<br /> * param2: If param1 is MenuEnd_Cancelled, the MenuCancel reason<br /> * return: 0 (or don't return)<br /> <br /> MenuAction_End is called when ''all'' clients have closed a menu or vote. For menus that are not going to be redisplayed, it is required that you call CloseHandle on the menu here.<br /> <br /> The parameters are rarely used in MenuAction_End. param1 is the menu end reason. param2 depends on param1.<br /> <br /> The end reasons you can receive for normal menus are:<br /> <br /> * MenuEnd_Selected - The menu closed because an item was selected (MenuAction_Select was fired)<br /> * MenuEnd_Cancelled - The menu was cancelled (MenuAction_Cancel was fired), cancel reason is in param2; cancel reason can be any of the ones listed in MenuAction_Cancel except MenuCancel_Exit or MenuCancel_ExitBack<br /> * MenuEnd_Exit - The menu was exited via the Exit item (MenuAction_Cancel was fired with param2 set to MenuCancel_Exit)<br /> * MenuEnd_ExitBack - The menu was exited via the ExitBack item (MenuAction_Cancel was fired with param 2 set to MenuCancel_ExitBack)<br /> <br /> Note: You do '''not''' have the client index during this callback, so it's far too late to do anything useful with this information.<br /> <br /> ==== MenuAction_DrawItem ====<br /> &lt;pawn&gt; case MenuAction_DrawItem:<br /> {<br /> new style;<br /> decl String:info[32];<br /> GetMenuItem(menu, param2, info, sizeof(info), style);<br /> <br /> if (StrEqual(info, CHOICE3))<br /> {<br /> return ITEMDRAW_DISABLED;<br /> }<br /> else<br /> {<br /> return style;<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> * param1: client index<br /> * param2: item number for use with GetMenuItem<br /> * return: new ITEMDRAW properties or style from GetMenuItem. Since 0 is ITEMDRAW_DEFAULT, returning 0 clears all styles for this item.<br /> <br /> MenuAction_DrawItem is called once for each item on the menu for each user. You can manipulate its draw style here. param1 is the client, param2 is the menu position.<br /> <br /> Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.<br /> <br /> GetMenuItem is used here to fetch the info string and menu style.<br /> <br /> You should return the style you want the menu item to have. In our example, if client 1 is viewing the menu, we want CHOICE3 to be disabled.<br /> <br /> the return value is a bitfield, so to apply multiple styles, you do something like this:<br /> <br /> return ITEMDRAW_NOTEXT | ITEMDRAW_SPACER;<br /> <br /> '''Failing to return the current item's style if you don't change the style is a programmer error.'''<br /> <br /> ==== MenuAction_DisplayItem ====<br /> <br /> &lt;pawn&gt; case MenuAction_DisplayItem:<br /> {<br /> decl String:info[32];<br /> GetMenuItem(menu, param2, info, sizeof(info));<br /> <br /> decl String:display[64];<br /> <br /> if (StrEqual(info, CHOICE3))<br /> {<br /> Format(display, sizeof(display), &quot;%T&quot;, &quot;Choice 3&quot;, param1);<br /> return RedrawMenuItem(display);<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> * param1: client index<br /> * param2: item number for use with GetMenuItem<br /> * return: return value from RedrawMenuItem or 0 for no change<br /> <br /> MenuAction_DrawItem is called once for each item on the menu for each user. You can manipulate its text here. param1 is the client, param2 is the menu position.<br /> <br /> This callback is intended for use with the Translation system.<br /> <br /> Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.<br /> <br /> GetMenuItem is used here to fetch the info string.<br /> <br /> Once we have the info string, we compare our item to it and apply the appropriate translation string.<br /> <br /> If we change an item, we have to call RedrawMenuItem and return the value it returns. If we do not change an item, we must return 0.<br /> <br /> ==== return ====<br /> &lt;pawn&gt; return 0;&lt;/pawn&gt;<br /> <br /> If you handle MenuAction_DrawItem or MenuAction_DisplayItem, you will get the following warning if you fail to return 0 after the switch block:<br /> <br /> &lt;code&gt;warning 209: function &quot;MenuHandler1&quot; should return a value&lt;/code&gt;<br /> <br /> This is because MenuAction_DrawItem and MenuAction_DisplayItem have return values, while the other actions only return 0.<br /> <br /> == The End ==<br /> Hopefully this walk through a simple menu helped you understand why each call is being made where. Menus have some options that we didn't explore here, such as disabling pagination (which is enabled by default). You may want to refer to the main Menu documentation for more details.</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=CHL2MP_Player_Offset_List_(Zombie_Panic:_Source)&diff=10121 2016-03-25T11:26:04Z

<p>Xerox8521: </p> <hr /> <div>Also for use when using [[Virtual Offsets (Source Mods)|virtual offsets]].<br /> <br /> These are the &lt;b&gt;Linux&lt;/b&gt; offsets. &lt;b&gt;Windows offsets are 1 smaller.&lt;/b&gt;<br /> <br /> == The List ==<br /> This comes from the symbol tables, so you'll have to look in the SDK for return types.<br /> <br /> &lt;b&gt;Last Updated Mar 25th 2016&lt;/b&gt;<br /> <br /> &lt;pre&gt;<br /> // Auto reconstructed from vtable block @ 0x012B7420<br /> // from &quot;server_i486.so&quot;, by ida_vtables.idc<br /> 0 CHL2MP_Player::~CHL2MP_Player()<br /> 1 CHL2MP_Player::~CHL2MP_Player()<br /> 2 CBaseEntity::SetRefEHandle(CBaseHandle const&amp;)<br /> 3 CBaseEntity::GetRefEHandle(void)const<br /> 4 CBaseEntity::GetCollideable(void)<br /> 5 CBaseEntity::GetNetworkable(void)<br /> 6 CBaseEntity::GetBaseEntity(void)<br /> 7 CBaseEntity::GetModelIndex(void)const<br /> 8 CBaseEntity::GetModelName(void)const<br /> 9 CBaseEntity::SetModelIndex(int)<br /> 10 CHL2MP_Player::GetServerClass(void)<br /> 11 CHL2MP_Player::YouForgotToImplementOrDeclareServerClass(void)<br /> 12 CHL2MP_Player::GetDataDescMap(void)<br /> 13 CBaseAnimating::TestCollision(Ray_t const&amp;,unsigned int,CGameTrace &amp;)<br /> 14 CHL2_Player::TestHitboxes(Ray_t const&amp;,unsigned int,CGameTrace &amp;)<br /> 15 CBaseEntity::ComputeWorldSpaceSurroundingBox(Vector *,Vector *)<br /> 16 CHL2MP_Player::ShouldCollide(int,int)const<br /> 17 CBaseEntity::SetOwnerEntity(CBaseEntity*)<br /> 18 CBasePlayer::ShouldTransmit(CCheckTransmitInfo const*)<br /> 19 CBasePlayer::UpdateTransmitState(void)<br /> 20 CBaseCombatCharacter::SetTransmit(CCheckTransmitInfo *,bool)<br /> 21 CBasePlayer::GetTracerType(void)<br /> 22 CHL2MP_Player::Spawn(void)<br /> 23 CBaseEntity::ZPASpawn(void)<br /> 24 CHL2MP_Player::Precache(void)<br /> 25 CBasePlayer::SetModel(char const*)<br /> 26 CBaseEntity::PostConstructor(char const*)<br /> 27 CBaseEntity::PostClientActive(void)<br /> 28 CBaseEntity::ParseMapData(CEntityMapData *)<br /> 29 CBaseEntity::KeyValue(char const*,char const*)<br /> 30 CBaseEntity::KeyValue(char const*,float)<br /> 31 CBaseEntity::KeyValue(char const*,Vector const&amp;)<br /> 32 CBaseEntity::GetKeyValue(char const*,char *,int)<br /> 33 CHL2_Player::Activate(void)<br /> 34 CBaseEntity::SetParent(CBaseEntity*,int)<br /> 35 CBasePlayer::ObjectCaps(void)<br /> 36 CBaseEntity::AcceptInput(char const*,CBaseEntity*,CBaseEntity*,variant_t,int)<br /> 37 CBaseAnimating::GetInputDispatchEffectPosition(char const*,Vector &amp;,QAngle &amp;)<br /> 38 CHL2_Player::DrawDebugGeometryOverlays(void)<br /> 39 CBaseAnimating::DrawDebugTextOverlays(void)<br /> 40 CBasePlayer::Save(ISave &amp;)<br /> 41 CBasePlayer::Restore(IRestore &amp;)<br /> 42 CBasePlayer::ShouldSavePhysics(void)<br /> 43 CBaseEntity::OnSave(IEntitySaveUtils *)<br /> 44 CHL2_Player::OnRestore(void)<br /> 45 CBasePlayer::RequiredEdictIndex(void)<br /> 46 CBaseEntity::MoveDone(void)<br /> 47 CBaseEntity::Think(void)<br /> 48 CBasePlayer::NetworkStateChanged_m_nNextThinkTick(void)<br /> 49 CBasePlayer::NetworkStateChanged_m_nNextThinkTick(void *)<br /> 50 CBaseAnimating::GetBaseAnimating(void)<br /> 51 CBaseEntity::GetResponseSystem(void)<br /> 52 CBaseEntity::DispatchResponse(char const*)<br /> 53 CHL2_Player::Classify(void)<br /> 54 CBaseEntity::DeathNotice(CBaseEntity*)<br /> 55 CBaseEntity::ShouldAttractAutoAim(CBaseEntity*)<br /> 56 CBaseEntity::GetAutoAimRadius(void)<br /> 57 CBaseEntity::GetAutoAimCenter(void)<br /> 58 CBaseEntity::GetBeamTraceFilter(void)<br /> 59 CHL2_Player::PassesDamageFilter(CTakeDamageInfo const&amp;)<br /> 60 CBasePlayer::TraceAttack(CTakeDamageInfo const&amp;,Vector const&amp;,CGameTrace *)<br /> 61 CBaseEntity::CanBeHitByMeleeAttack(CBaseEntity*)<br /> 62 CHL2MP_Player::OnTakeDamage(CTakeDamageInfo const&amp;)<br /> 63 CHL2MP_Player::TakeHealth(float,int)<br /> 64 CBaseEntity::IsAlive(void)<br /> 65 CHL2MP_Player::Event_Killed(CTakeDamageInfo const&amp;)<br /> 66 CHL2_Player::Event_KilledOther(CBaseEntity *,CTakeDamageInfo const&amp;)<br /> 67 CBaseCombatCharacter::BloodColor(void)<br /> 68 CBaseEntity::IsTriggered(CBaseEntity*)<br /> 69 CBaseEntity::IsNPC(void)const<br /> 70 CBaseCombatCharacter::MyCombatCharacterPointer(void)<br /> 71 CBaseEntity::GetDelay(void)<br /> 72 CBaseEntity::IsMoving(void)<br /> 73 CBaseEntity::DamageDecal(int,int)<br /> 74 CBaseEntity::DecalTrace(CGameTrace *,char const*)<br /> 75 CBaseEntity::ImpactTrace(CGameTrace *,int,char *)<br /> 76 CBaseEntity::OnControls(CBaseEntity*)<br /> 77 CBaseEntity::HasTarget(string_t)<br /> 78 CBasePlayer::IsPlayer(void)const<br /> 79 CBasePlayer::IsNetClient(void)const<br /> 80 CBaseEntity::IsTemplate(void)<br /> 81 CBaseEntity::IsBaseObject(void)const<br /> 82 CBaseEntity::IsBaseTrain(void)const<br /> 83 CBaseEntity::IsPlayerUsableItem(void)<br /> 84 CBaseEntity::GetItemTypeID(void)<br /> 85 CBaseEntity::GetServerVehicle(void)<br /> 86 CBaseEntity::IsViewable(void)<br /> 87 CBasePlayer::GetZPMTeam(void)const<br /> 88 CHL2MP_Player::ChangeTeam(int)<br /> 89 CBaseEntity::OnEntityEvent(EntityEvent_t,void *)<br /> 90 CBaseEntity::CanStandOn(CBaseEntity*)const<br /> 91 CBaseEntity::CanStandOn(edict_t *)const<br /> 92 CBaseEntity::GetEnemy(void)<br /> 93 CBaseEntity::GetEnemy(void)const<br /> 94 CBaseEntity::Use(CBaseEntity*,CBaseEntity*,USE_TYPE,float)<br /> 95 CBaseEntity::StartTouch(CBaseEntity*)<br /> 96 CBasePlayer::Touch(CBaseEntity *)<br /> 97 CBaseEntity::EndTouch(CBaseEntity*)<br /> 98 CBaseEntity::StartBlocked(CBaseEntity*)<br /> 99 CBaseEntity::Blocked(CBaseEntity*)<br /> 100 CBaseEntity::EndBlocked(void)<br /> 101 CBasePlayer::PhysicsSimulate(void)<br /> 102 CHL2MP_Player::UpdateOnRemove(void)<br /> 103 CHL2_Player::StopLoopingSounds(void)<br /> 104 CBaseEntity::SUB_AllowedToFade(void)<br /> 105 CBaseFlex::Teleport(Vector const*,QAngle const*,Vector const*)<br /> 106 CBaseEntity::NotifySystemEvent(CBaseEntity*,notify_system_event_t,notify_system_event_params_t const&amp;)<br /> 107 CBasePlayer::MakeTracer(Vector const&amp;,CGameTrace const&amp;,int)<br /> 108 CBaseEntity::GetTracerAttachment(void)<br /> 109 CHL2MP_Player::FireBullets(FireBulletsInfo_t const&amp;)<br /> 110 CBasePlayer::DoImpactEffect(CGameTrace &amp;,int)<br /> 111 CBaseEntity::Respawn(void)<br /> 112 CBaseEntity::IsLockedByMaster(void)<br /> 113 CBaseAnimating::ModifyOrAppendCriteria(AI_CriteriaSet &amp;)<br /> 114 CBaseEntity::NetworkStateChanged_m_iMaxHealth(void)<br /> 115 CBaseEntity::NetworkStateChanged_m_iMaxHealth(void *)<br /> 116 CBasePlayer::NetworkStateChanged_m_iHealth(void)<br /> 117 CBasePlayer::NetworkStateChanged_m_iHealth(void *)<br /> 118 CBasePlayer::NetworkStateChanged_m_lifeState(void)<br /> 119 CBasePlayer::NetworkStateChanged_m_lifeState(void *)<br /> 120 CBaseEntity::NetworkStateChanged_m_takedamage(void)<br /> 121 CBaseEntity::NetworkStateChanged_m_takedamage(void *)<br /> 122 CBaseEntity::GetDamageType(void)const<br /> 123 CBaseEntity::GetDamage(void)<br /> 124 CBaseEntity::SetDamage(float)<br /> 125 CBasePlayer::EyePosition(void)<br /> 126 CBasePlayer::EyeAngles(void)<br /> 127 CBasePlayer::LocalEyeAngles(void)<br /> 128 CBaseEntity::EarPosition(void)<br /> 129 CBasePlayer::BodyTarget(Vector const&amp;,bool)<br /> 130 CBaseEntity::HeadTarget(Vector const&amp;)<br /> 131 CBaseEntity::GetVectors(Vector *,Vector *,Vector *)const<br /> 132 CBaseEntity::GetViewOffset(void)<br /> 133 CBasePlayer::GetSmoothedVelocity(void)<br /> 134 CBaseAnimating::GetVelocity(Vector *,Vector *)<br /> 135 CBaseCombatCharacter::FVisible(CBaseEntity *,int,CBaseEntity **)<br /> 136 CBaseCombatCharacter::FVisible(Vector const&amp;,int,CBaseEntity **)<br /> 137 CBaseEntity::CanBeSeenBy(CAI_BaseNPC *)<br /> 138 CBaseEntity::GetAttackDamageScale(CBaseEntity*)<br /> 139 CBaseEntity::GetReceivedDamageScale(CBaseEntity*)<br /> 140 CBasePlayer::SetGroundEntity(CBaseEntity *)<br /> 141 CBaseEntity::GetGroundEntity(void)<br /> 142 CBaseEntity::GetGroundVelocityToApply(Vector &amp;)<br /> 143 CBaseEntity::PhysicsSplash(Vector const&amp;,Vector const&amp;,float,float)<br /> 144 CHL2_Player::Splash(void)<br /> 145 CBaseEntity::WorldSpaceCenter(void)const<br /> 146 CBaseEntity::GetSoundEmissionOrigin(void)const<br /> 147 CBaseEntity::CreateVPhysics(void)<br /> 148 CBaseEntity::ForceVPhysicsCollide(CBaseEntity*)<br /> 149 CBasePlayer::VPhysicsDestroyObject(void)<br /> 150 CBasePlayer::VPhysicsUpdate(IPhysicsObject *)<br /> 151 CBaseEntity::VPhysicsTakeDamage(CTakeDamageInfo const&amp;)<br /> 152 CBaseCombatCharacter::VPhysicsShadowCollision(int,gamevcollisionevent_t *)<br /> 153 CBasePlayer::VPhysicsShadowUpdate(IPhysicsObject *)<br /> 154 CBasePlayer::VPhysicsCollision(int,gamevcollisionevent_t *)<br /> 155 CBaseEntity::VPhysicsFriction(IPhysicsObject *,float,int,int)<br /> 156 CBaseEntity::UpdatePhysicsShadowToCurrentPosition(float)<br /> 157 CBaseEntity::VPhysicsGetObjectList(IPhysicsObject **,int)<br /> 158 CBaseEntity::VPhysicsIsFlesh(void)<br /> 159 CBaseEntity::HasPhysicsAttacker(float)<br /> 160 CBasePlayer::PhysicsSolidMaskForEntity(void)const<br /> 161 CBaseEntity::ResolveFlyCollisionCustom(CGameTrace &amp;,Vector &amp;)<br /> 162 CBaseEntity::PerformCustomPhysics(Vector *,Vector *,QAngle *,QAngle *)<br /> 163 CBaseAnimating::GetStepOrigin(void)const<br /> 164 CBaseAnimating::GetStepAngles(void)const<br /> 165 CBaseEntity::ShouldDrawWaterImpacts(void)<br /> 166 CBasePlayer::NetworkStateChanged_m_fFlags(void)<br /> 167 CBasePlayer::NetworkStateChanged_m_fFlags(void *)<br /> 168 CBasePlayer::NetworkStateChanged_m_nWaterLevel(void)<br /> 169 CBasePlayer::NetworkStateChanged_m_nWaterLevel(void *)<br /> 170 CBasePlayer::NetworkStateChanged_m_hGroundEntity(void)<br /> 171 CBasePlayer::NetworkStateChanged_m_hGroundEntity(void *)<br /> 172 CBasePlayer::NetworkStateChanged_m_vecBaseVelocity(void)<br /> 173 CBasePlayer::NetworkStateChanged_m_vecBaseVelocity(void *)<br /> 174 CBasePlayer::NetworkStateChanged_m_flFriction(void)<br /> 175 CBasePlayer::NetworkStateChanged_m_flFriction(void *)<br /> 176 CBasePlayer::NetworkStateChanged_m_vecVelocity(void)<br /> 177 CBasePlayer::NetworkStateChanged_m_vecVelocity(void *)<br /> 178 CBasePlayer::NetworkStateChanged_m_vecViewOffset(void)<br /> 179 CBasePlayer::NetworkStateChanged_m_vecViewOffset(void *)<br /> 180 CBaseAnimating::Hide(void)<br /> 181 CBaseAnimating::GetIdealSpeed(void)const<br /> 182 CBaseAnimating::GetIdealAccel(void)const<br /> 183 CBaseAnimatingOverlay::StudioFrameAdvance(void)<br /> 184 CBaseAnimating::IsActivityFinished(void)<br /> 185 CBaseAnimating::GetSequenceGroundSpeed(CStudioHdr *,int)<br /> 186 CBaseAnimating::ClampRagdollForce(Vector const&amp;,Vector*)<br /> 187 CHL2MP_Player::BecomeRagdollOnClient(Vector const&amp;)<br /> 188 CBaseAnimating::IsRagdoll(void)<br /> 189 CBaseAnimating::CanBecomeRagdoll(void)<br /> 190 CBaseAnimatingOverlay::GetSkeleton(CStudioHdr *,Vector *,Quaternion *,int)<br /> 191 CBaseAnimating::GetBoneTransform(int,matrix3x4_t &amp;)<br /> 192 CBaseAnimating::SetupBones(matrix3x4_t *,int)<br /> 193 CBaseAnimating::CalculateIKLocks(float)<br /> 194 CBaseAnimatingOverlay::DispatchAnimEvents(CBaseAnimating *)<br /> 195 CBasePlayer::HandleAnimEvent(animevent_t *)<br /> 196 CBaseAnimating::PopulatePoseParameters(void)<br /> 197 CBaseAnimating::GetAttachment(int,matrix3x4_t &amp;)<br /> 198 CBaseAnimating::InitBoneControllers(void)<br /> 199 CBaseAnimating::GetGroundSpeedVelocity(void)<br /> 200 CBaseAnimating::Ignite(float,bool,float,bool)<br /> 201 CBaseAnimating::IgniteLifetime(float)<br /> 202 CBaseAnimating::IgniteNumHitboxFires(int)<br /> 203 CBaseAnimating::IgniteHitboxFireScale(float)<br /> 204 CBaseAnimating::Extinguish(void)<br /> 205 CBaseCombatCharacter::SetLightingOriginRelative(CBaseEntity *)<br /> 206 CBaseAnimating::SetLightingOrigin(CBaseEntity *)<br /> 207 CBaseFlex::SetViewtarget(Vector const&amp;)<br /> 208 CBaseFlex::StartSceneEvent(CSceneEventInfo *,CChoreoScene *,CChoreoEvent *,CChoreoActor *,CBaseEntity *)<br /> 209 CBaseFlex::ProcessSceneEvents(void)<br /> 210 CBaseFlex::ProcessSceneEvent(CSceneEventInfo *,CChoreoScene *,CChoreoEvent *)<br /> 211 CBaseFlex::ClearSceneEvent(CSceneEventInfo *,bool,bool)<br /> 212 CBaseFlex::CheckSceneEventCompletion(CSceneEventInfo *,float,CChoreoScene *,CChoreoEvent *)<br /> 213 CBaseFlex::PlayScene(char const*,float,AI_Response *,IRecipientFilter *)<br /> 214 CBaseFlex::PlayAutoGeneratedSoundScene(char const*)<br /> 215 CHL2_Player::GetPhysicsImpactDamageTable(void)<br /> 216 CBaseCombatCharacter::FInViewCone(CBaseEntity *)<br /> 217 CBaseCombatCharacter::FInViewCone(Vector const&amp;)<br /> 218 CBaseCombatCharacter::FInAimCone(CBaseEntity *)<br /> 219 CBaseCombatCharacter::FInAimCone(Vector const&amp;)<br /> 220 CHL2_Player::ShouldShootMissTarget(CBaseCombatCharacter *)<br /> 221 CBaseCombatCharacter::FindMissTarget(void)<br /> 222 CHL2_Player::HandleInteraction(int,void *,CBaseCombatCharacter *)<br /> 223 CBasePlayer::BodyAngles(void)<br /> 224 CBaseCombatCharacter::BodyDirection2D(void)<br /> 225 CBaseCombatCharacter::BodyDirection3D(void)<br /> 226 CBaseCombatCharacter::HeadDirection2D(void)<br /> 227 CBaseCombatCharacter::HeadDirection3D(void)<br /> 228 CHL2_Player::EyeDirection2D(void)<br /> 229 CHL2_Player::EyeDirection3D(void)<br /> 230 CHL2MP_Player::GiveAmmo(int,int,bool)<br /> 231 CBaseCombatCharacter::NPC_TranslateActivity(Activity)<br /> 232 CBaseCombatCharacter::Weapon_TranslateActivity(Activity,bool *)<br /> 233 CBaseCombatCharacter::Weapon_FrameUpdate(void)<br /> 234 CBaseCombatCharacter::Weapon_HandleAnimEvent(animevent_t *)<br /> 235 CHL2_Player::Weapon_CanUse(CBaseCombatWeapon *)<br /> 236 CHL2_Player::Weapon_Equip(CBaseCombatWeapon *)<br /> 237 CBaseCombatCharacter::Weapon_EquipAmmoOnly(CBaseCombatWeapon *)<br /> 238 CHL2MP_Player::Weapon_Drop(CBaseCombatWeapon *,Vector const*,Vector const*)<br /> 239 CHL2MP_Player::Weapon_Switch(CBaseCombatWeapon *,int,bool)<br /> 240 CBasePlayer::Weapon_ShootPosition(void)<br /> 241 CHL2_Player::Weapon_CanSwitchTo(CBaseCombatWeapon *)<br /> 242 CBaseCombatCharacter::Weapon_SlotOccupied(CBaseCombatWeapon *)<br /> 243 CBaseCombatCharacter::Weapon_GetSlot(int)const<br /> 244 CBaseCombatCharacter::Weapon_SetSlot(int,CBaseCombatWeapon *)<br /> 245 CBaseCombatCharacter::Weapon_CleanupSlot(int)<br /> 246 CBaseCombatCharacter::Weapon_DeleteSlot(int)<br /> 247 CBaseCombatCharacter::AddPlayerItem(CBaseCombatWeapon *)<br /> 248 CBasePlayer::RemovePlayerItem(CBaseCombatWeapon *)<br /> 249 CBaseCombatCharacter::CanBecomeServerRagdoll(void)<br /> 250 CHL2_Player::OnTakeDamage_Alive(CTakeDamageInfo const&amp;)<br /> 251 CBaseCombatCharacter::OnTakeDamage_Dying(CTakeDamageInfo const&amp;)<br /> 252 CBaseCombatCharacter::OnTakeDamage_Dead(CTakeDamageInfo const&amp;)<br /> 253 CBaseCombatCharacter::OnFriendDamaged(CBaseCombatCharacter*,CBaseEntity *)<br /> 254 CHL2_Player::NotifyFriendsOfDamage(CBaseEntity *)<br /> 255 CBaseCombatCharacter::OnPlayerKilledOther(CBaseEntity *,CTakeDamageInfo const&amp;)<br /> 256 CBaseCombatCharacter::GetDeathActivity(void)<br /> 257 CBaseCombatCharacter::CorpseGib(CTakeDamageInfo const&amp;)<br /> 258 CBaseCombatCharacter::CorpseFade(void)<br /> 259 CBaseCombatCharacter::HasHumanGibs(void)<br /> 260 CBaseCombatCharacter::HasAlienGibs(void)<br /> 261 CHL2MP_Player::ShouldGib(CTakeDamageInfo const&amp;)<br /> 262 CBaseCombatCharacter::OnKilledNPC(CBaseCombatCharacter*)<br /> 263 CBaseCombatCharacter::Event_Gibbed(CTakeDamageInfo const&amp;)<br /> 264 CBasePlayer::Event_Dying(void)<br /> 265 CBaseCombatCharacter::BecomeRagdoll(CTakeDamageInfo const&amp;,Vector const&amp;)<br /> 266 CBaseCombatCharacter::FixupBurningServerRagdoll(CBaseEntity *)<br /> 267 CBaseCombatCharacter::BecomeRagdollBoogie(CBaseEntity *,Vector const&amp;,float,int)<br /> 268 CBaseCombatCharacter::CheckTraceHullAttack(float,Vector const&amp;,Vector const&amp;,int,int,float,bool)<br /> 269 CBaseCombatCharacter::CheckTraceHullAttack(Vector const&amp;,Vector const&amp;,Vector const&amp;,Vector const&amp;,int,int,float,bool)<br /> 270 CBaseCombatCharacter::PushawayTouch(CBaseEntity *)<br /> 271 CBaseCombatCharacter::IRelationType(CBaseEntity *)<br /> 272 CBaseCombatCharacter::IRelationPriority(CBaseEntity *)<br /> 273 CBasePlayer::IsInAVehicle(void)const<br /> 274 CBasePlayer::GetVehicle(void)<br /> 275 CBasePlayer::GetVehicleEntity(void)<br /> 276 CBaseCombatCharacter::ExitVehicle(void)<br /> 277 CHL2_Player::CalcWeaponProficiency(CBaseCombatWeapon *)<br /> 278 CBaseCombatCharacter::GetAttackSpread(CBaseCombatWeapon *,CBaseEntity *)<br /> 279 CBaseCombatCharacter::GetSpreadBias(CBaseCombatWeapon *,CBaseEntity *)<br /> 280 CBasePlayer::DoMuzzleFlash(void)<br /> 281 CBaseCombatCharacter::AddEntityRelationship(CBaseEntity *,Disposition_t,int)<br /> 282 CBaseCombatCharacter::RemoveEntityRelationship(CBaseEntity *)<br /> 283 CBaseCombatCharacter::AddClassRelationship(Class_T,Disposition_t,int)<br /> 284 CBaseCombatCharacter::OnChangeActiveWeapon(CBaseCombatWeapon *,CBaseCombatWeapon *)<br /> 285 CHL2MP_Player::CreateViewModel(int)<br /> 286 CHL2_Player::SetupVisibility(CBaseEntity *,unsigned char *,int)<br /> 287 CHL2MP_Player::WantsLagCompensationOnEntity(CBasePlayer const*,CUserCmd const*,CBitVec&lt;2048&gt; const*)const<br /> 288 CHL2MP_Player::SharedSpawn(void)<br /> 289 CBasePlayer::ForceRespawn(void)<br /> 290 CHL2MP_Player::InitialSpawn(void)<br /> 291 CBasePlayer::InitHUD(void)<br /> 292 CBasePlayer::ShowViewPortPanel(char const*,bool,KeyValues *)<br /> 293 CHL2MP_Player::PlayerDeathThink(void)<br /> 294 CHL2MP_Player::Jump(void)<br /> 295 CBasePlayer::Duck(void)<br /> 296 CHL2MP_Player::PreThink(void)<br /> 297 CHL2MP_Player::PostThink(void)<br /> 298 CHL2MP_Player::DamageEffect(float,int)<br /> 299 CHL2_Player::OnDamagedByExplosion(CTakeDamageInfo const&amp;)<br /> 300 CBasePlayer::ShouldFadeOnDeath(void)<br /> 301 CBasePlayer::IsFakeClient(void)const<br /> 302 CBasePlayer::GetPlayerMins(void)const<br /> 303 CBasePlayer::GetPlayerMaxs(void)const<br /> 304 CBasePlayer::CalcRoll(QAngle const&amp;,Vector const&amp;,float,float)<br /> 305 CBasePlayer::PackDeadPlayerItems(void)<br /> 306 CBasePlayer::RemoveAllItems(bool)<br /> 307 CBasePlayer::Weapon_SetLast(CBaseCombatWeapon *)<br /> 308 CBasePlayer::Weapon_ShouldSetLast(CBaseCombatWeapon *,CBaseCombatWeapon *)<br /> 309 CBasePlayer::Weapon_ShouldSelectItem(CBaseCombatWeapon *)<br /> 310 CHL2_Player::UpdateClientData(void)<br /> 311 CHL2_Player::ExitLadder(void)<br /> 312 CHL2_Player::GetLadderSurface(Vector const&amp;)<br /> 313 CHL2_Player::SetFlashlightEnabled(bool)<br /> 314 CHL2MP_Player::FlashlightIsOn(void)<br /> 315 CHL2MP_Player::FlashlightTurnOn(void)<br /> 316 CHL2MP_Player::FlashlightTurnOff(void)<br /> 317 CHL2_Player::IsIlluminatedByFlashlight(CBaseEntity *,float *)<br /> 318 CBasePlayer::UpdateStepSound(surfacedata_t *,Vector const&amp;,Vector const&amp;)<br /> 319 CHL2MP_Player::PlayStepSound(Vector &amp;,surfacedata_t *,float,bool)<br /> 320 CBasePlayer::GetStepSoundVelocities(float *,float *)<br /> 321 CBasePlayer::SetStepSoundTime(stepsoundtimes_t,bool)<br /> 322 CHL2MP_Player::DeathSound(CTakeDamageInfo const&amp;)<br /> 323 CHL2MP_Player::SetAnimation(PLAYER_ANIM)<br /> 324 CBasePlayer::ImpulseCommands(void)<br /> 325 CHL2_Player::CheatImpulseCommands(int)<br /> 326 CHL2MP_Player::ClientCommand(CCommand const&amp;)<br /> 327 CHL2MP_Player::StartObserverMode(int)<br /> 328 CHL2MP_Player::StopObserverMode(void)<br /> 329 CBasePlayer::ModeWantsSpectatorGUI(int)<br /> 330 CBasePlayer::SetObserverMode(int)<br /> 331 CBasePlayer::GetObserverMode(void)<br /> 332 CBasePlayer::SetObserverTarget(CBaseEntity *)<br /> 333 CBasePlayer::ObserverUse(bool)<br /> 334 CBasePlayer::GetObserverTarget(void)<br /> 335 CBasePlayer::FindNextObserverTarget(bool)<br /> 336 CBasePlayer::GetNextObserverSearchStartPoint(bool)<br /> 337 CBasePlayer::IsValidObserverTarget(CBaseEntity *)<br /> 338 CBasePlayer::CheckObserverSettings(void)<br /> 339 CBasePlayer::JumptoPosition(Vector const&amp;,QAngle const&amp;)<br /> 340 CBasePlayer::ForceObserverMode(int)<br /> 341 CBasePlayer::ResetObserverMode(void)<br /> 342 CBasePlayer::ValidateCurrentObserverTarget(void)<br /> 343 CBasePlayer::AttemptToExitFreezeCam(void)<br /> 344 CBasePlayer::StartReplayMode(float,float,int)<br /> 345 CBasePlayer::StopReplayMode(void)<br /> 346 CBasePlayer::GetDelayTicks(void)<br /> 347 CBasePlayer::GetReplayEntity(void)<br /> 348 CHL2_Player::CreateCorpse(void)<br /> 349 CHL2MP_Player::EntSelectSpawnPoint(void)<br /> 350 CBasePlayer::GetInVehicle(IServerVehicle *,int)<br /> 351 CBasePlayer::LeaveVehicle(Vector const&amp;,QAngle const&amp;)<br /> 352 CBasePlayer::OnVehicleStart(void)<br /> 353 CBasePlayer::OnVehicleEnd(Vector &amp;)<br /> 354 CBasePlayer::BumpWeapon(CBaseCombatWeapon *)<br /> 355 CBasePlayer::SelectLastItem(void)<br /> 356 CBasePlayer::SelectItem(char const*,int)<br /> 357 CBasePlayer::SelectItem(int,int)<br /> 358 CHL2MP_Player::ItemPostFrame(void)<br /> 359 CBasePlayer::GiveNamedItem(char const*,int)<br /> 360 CBasePlayer::CheckTrainUpdate(void)<br /> 361 CHL2_Player::SetPlayerUnderwater(bool)<br /> 362 CHL2MP_Player::CanBreatheUnderwater(void)const<br /> 363 CHL2MP_Player::PlayerUse(void)<br /> 364 CHL2_Player::PlayUseDenySound(void)<br /> 365 CBasePlayer::FindUseEntity(void)<br /> 366 CBasePlayer::IsUseableEntity(CBaseEntity *,unsigned int)<br /> 367 CHL2MP_Player::PickupObject(CBaseEntity *,bool)<br /> 368 CHL2_Player::ForceDropOfCarriedPhysObjects(CBaseEntity *)<br /> 369 CHL2_Player::GetHeldObjectMass(IPhysicsObject *)<br /> 370 CHL2_Player::GetHeldObject(void)<br /> 371 CBasePlayer::UpdateGeigerCounter(void)<br /> 372 CBasePlayer::GetAutoaimVector(float)<br /> 373 CBasePlayer::GetAutoaimVector(float,float)<br /> 374 CHL2_Player::GetAutoaimVector(autoaim_params_t &amp;)<br /> 375 CBasePlayer::ShouldAutoaim(void)<br /> 376 CBasePlayer::ForceClientDllUpdate(void)<br /> 377 CBasePlayer::ProcessUsercmds(CUserCmd *,int,int,int,bool)<br /> 378 CHL2MP_Player::PlayerRunCommand(CUserCmd *,IMoveHelper *)<br /> 379 CHL2MP_Player::CanHearAndReadChatFrom(CBasePlayer *)<br /> 380 CHL2MP_Player::CanSpeak(void)<br /> 381 CHL2MP_Player::PlayCharacterSound(char const*)<br /> 382 CHL2_Player::ModifyOrAppendPlayerCriteria(AI_CriteriaSet &amp;)<br /> 383 CHL2MP_Player::CheckChatText(char *,int)<br /> 384 CHL2MP_Player::CreateRagdollEntity(void)<br /> 385 CBasePlayer::ShouldAnnounceAchievement(void)<br /> 386 CHL2_Player::OnDoneDamage(void)<br /> 387 CHL2_Player::IsWalking(void)<br /> 388 CHL2MP_Player::IsPracticallyZombie(void)const<br /> 389 CHL2MP_Player::IsInfectionKnown(void)const<br /> 390 CHL2MP_Player::DidZombieJustTurn(void)const<br /> 391 CHL2MP_Player::InfectPlayer(float)<br /> 392 CHL2MP_Player::DisinfectPlayer(void)<br /> 393 CHL2_Player::IsFollowingPhysics(void)<br /> 394 CHL2_Player::InitVCollision(Vector const&amp;,Vector const&amp;)<br /> 395 CBasePlayer::UpdatePhysicsShadowToCurrentPosition(void)<br /> 396 CBasePlayer::Hints(void)<br /> 397 CBasePlayer::IsReadyToPlay(void)<br /> 398 CBasePlayer::IsReadyToSpawn(void)<br /> 399 CBasePlayer::ShouldGainInstantSpawn(void)<br /> 400 CBasePlayer::ResetPerRoundStats(void)<br /> 401 CBasePlayer::ResetScores(void)<br /> 402 CBasePlayer::SpawnArmorValue(void)<br /> 403 CHL2_Player::EquipSuit(bool)<br /> 404 CHL2_Player::RemoveSuit(void)<br /> 405 CHL2MP_Player::CommitSuicide(bool,bool)<br /> 406 CHL2MP_Player::CommitSuicide(Vector const&amp;,bool,bool)<br /> 407 CBasePlayer::IsBot(void)const<br /> 408 CHL2MP_Player::NotePlayerTalked(void)<br /> 409 CBasePlayer::GetExpresser(void)<br /> 410 CBasePlayer::NetworkStateChanged_m_iAmmo(void)<br /> 411 CBasePlayer::NetworkStateChanged_m_iAmmo(void *)<br /> 412 CHL2_Player::SuspendUse(float)<br /> 413 CHL2_Player::CommanderMode(void)<br /> 414 CHL2MP_Player::StartSprinting(void)<br /> 415 CHL2_Player::GetIdleTime(void)const<br /> 416 CHL2_Player::GetMoveTime(void)const<br /> 417 CHL2_Player::GetLastDamageTime(void)const<br /> 418 CHL2_Player::IsDucking(void)const<br /> 419 CHL2_Player::Weapon_Lower(void)<br /> 420 CHL2_Player::Weapon_Ready(void)<br /> 421 CHL2_Player::IsHoldingEntity(CBaseEntity *)<br /> 422 CHL2_Player::UpdateWeaponPosture(void)<br /> 423 CHL2_Player::NetworkStateChanged_m_fIsWalking(void)<br /> 424 CHL2_Player::NetworkStateChanged_m_fIsWalking(void *)<br /> 425 CHL2MP_Player::GhostSpawn(void)<br /> 426 CHL2MP_Player::WaitSpawn(void)<br /> 427 CHL2MP_Player::ObserverSpawn(void)<br /> 428 CHL2MP_Player::HandleCommand_JoinTeam(int)<br /> 429 CHL2MP_Player::CanHearChatFrom(CBasePlayer *)<br /> 430 CHL2MP_Player::RemoveWeight(float)<br /> 431 CHL2MP_Player::RemoveAllItems(void)<br /> 432 CHL2MP_Player::ItemReticleSearch(void)<br /> 433 CHL2MP_Player::EnterPhoneTrigger(CPhoneTrigger *)<br /> 434 CHL2MP_Player::LeavePhoneTrigger(CPhoneTrigger *)<br /> 435 CHL2MP_Player::ActivatePhoneTriggers(void)<br /> 436 CHL2MP_Player::InPhoneTrigger(void)<br /> 437 CHL2MP_Player::InventoryStatus(void)<br /> 438 CHL2MP_Player::GiveNamedItem(char const*)<br /> 439 CHL2MP_Player::PlayerWeaponPickup(CBaseCombatWeapon *)<br /> 440 CHL2MP_Player::GiveEmptyHands(void)<br /> 441 CHL2MP_Player::GivePhone(void)<br /> 442 CHL2MP_Player::SetPlayerTeamModel(int)<br /> 443 CHL2MP_Player::GiveDefaultGear(void)<br /> 444 CHL2MP_Player::GetPlayerModelSoundPrefix(void)<br /> 445 CHL2MP_Player::GetPlayerModelType(void)<br /> 446 CHL2MP_Player::DefuseIEDs(CTakeDamageInfo const&amp;)<br /> 447 CHL2MP_Player::ShowBriefingMenu(void)<br /> 448 CHL2MP_Player::HideBriefingMenu(void)<br /> 449 CHL2MP_Player::CreateAmmo(char const*)<br /> 450 CHL2MP_Player::PrepWeaponForDrop(CBaseCombatWeapon *)<br /> 451 CHL2MP_Player::ScootInventory(void)<br /> 452 CHL2MP_Player::PlayerDropWeapon(void)<br /> 453 CHL2MP_Player::PlayerUnloadWeapon(void)<br /> 454 CHL2MP_Player::PlayerCycleAmmoType(void)<br /> 455 CHL2MP_Player::PlayerCycleDropAmount(void)<br /> 456 CHL2MP_Player::PrepAmmoForDrop(CItem *)<br /> 457 CHL2MP_Player::PlayerDropAmmo(void)<br /> 458 CHL2MP_Player::PlayerDropUnusedAmmo(void)<br /> 459 CHL2MP_Player::GiveAmmoToPlayer(void)<br /> 460 CHL2MP_Player::ResetTeamSwitch(void)<br /> 461 CHL2MP_Player::Panic(bool)<br /> 462 CHL2MP_Player::Melee(bool)<br /> 463 CHL2MP_Player::VoiceMenu(char const*,char const*)<br /> 464 CHL2MP_Player::VoiceMenuText(char const*)<br /> 465 CHL2MP_Player::Taunt(bool)<br /> 466 CHL2MP_Player::KillTaunt(bool)<br /> 467 CHL2MP_Player::Berzerk(void)<br /> 468 CHL2MP_Player::Go(void)<br /> 469 CHL2MP_Player::Roar(void)<br /> 470 CHL2MP_Player::Camp(void)<br /> 471 CHL2MP_Player::PickedAsCarrier(void)<br /> 472 CHL2MP_Player::ResetCarrier(void)<br /> 473 CHL2MP_Player::IsCarrier(void)<br /> 474 CHL2MP_Player::HolsterWeapon(void)<br /> 475 CHL2MP_Player::SwitchToPhone(void)<br /> 476 CHL2MP_Player::Trace(void)<br /> 477 CHL2MP_Player::IsOnATeam(void)<br /> &lt;/pre&gt;</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Scripting_FAQ_(SourceMod)&diff=10117 2016-02-16T21:22:22Z

<p>Xerox8521: /* Why is Source telling me my command is an &quot;Unknown command&quot;? */</p> <hr /> <div>[[Image:Yak.gif]]<br /> yak wuz heer<br /> <br /> =How do I learn SourcePawn?=<br /> A good start is on the [[Introduction_to_SourcePawn_1.7]] page, which will teach you the SourcePawn language. Then go through the [[Introduction to SourceMod Plugins]], which will teach you how to write your first plug-in.<br /> <br /> =Where can I find all the SourcePawn functions and other information?=<br /> All SourceMod plug-ins have this line:<br /> <br /> &lt;pawn&gt;#include &lt;sourcemod&gt;&lt;/pawn&gt;<br /> <br /> This line instructs the compiler to retrieve the file &lt;tt&gt;sourcemod.inc&lt;/tt&gt; from the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder. Every function, variable, and definition can be found in the &lt;tt&gt;.inc&lt;/tt&gt; files inside the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder.<br /> <br /> But searching through all those files can be quite tedious. Thankfully, the honourable [https://forums.alliedmods.net/member.php?u=9443 Nican] created an API reference viewable on the web, complete with searching and commenting: [https://sm.alliedmods.net/new-api/ https://sm.alliedmods.net/new-api/]<br /> <br /> Also, if you are in the SourceMod IRC channel ([irc://irc.gamesurge.net/sourcemod #sourcemod on GameSurge]), you can use the &lt;tt&gt;!api&lt;/tt&gt; command to search [https://forums.alliedmods.net/member.php?u=9443 Nican's] API reference:<br /> &lt;pre&gt;&lt;theY4Kman&gt; !api Netclass<br /> &lt;yakbot&gt; theY4Kman: bool GetEntityNetClass(int edict, char[] clsname, int maxlength): Retrieves an entity's networkable serverclass name. This is not the same as the classname and is used for networkable state changes. (https://sm.alliedmods.net/new-api/entity/GetEntityNetClass)&lt;/pre&gt;<br /> <br /> =How do I find the classname of an entity? (e.g., &quot;&lt;tt&gt;weapon_knife&lt;/tt&gt;&quot; or &quot;&lt;tt&gt;prop_physics&lt;/tt&gt;&quot;)=<br /> The classname of an entity (not to be confused with a netclass such as &lt;tt&gt;CCSPlayer&lt;/tt&gt;) is a unique identifier. It's the most well known of entity names. To find it, use the function [https://sm.alliedmods.net/new-api/entity/GetEdictClassname GetEdictClassname()]:<br /> <br /> &lt;pawn&gt;char classname[128];<br /> GetEdictClassname(myentity, classname, sizeof(classname));<br /> <br /> PrintToServer(&quot;myentity classname: %s&quot;, classname);<br /> // myentity classname: weapon_knife&lt;/pawn&gt;<br /> <br /> =How do I block regular commands, such as &lt;tt&gt;kill&lt;/tt&gt; and &lt;tt&gt;say&lt;/tt&gt;?=<br /> As of version 1.3, the recommended way to hook and block commands is with [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()]. Previously, using [https://sm.alliedmods.net/new-api/console/RegConsoleCmd RegConsoleCmd()] with the command name was the only way to hook commands, but this creates a whole new command for the command dispatch to check every time any command is executed. [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] creates only a lightweight hook, processed only when the specific command is executed.<br /> <br /> Here's how to use it to block the &lt;tt&gt;say&lt;/tt&gt; command:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> AddCommandListener(SayCallback, &quot;say&quot;);<br /> }<br /> <br /> public Action SayCallback(int client, const char[] command, int argc)<br /> {<br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I hook +commands, such as &lt;tt&gt;+zoom&lt;/tt&gt; and &lt;tt&gt;+attack&lt;/tt&gt;?=<br /> Unlike regular commands, &lt;tt&gt;+commands&lt;/tt&gt; are handled on the client's computer, then sent to the server in a more compressed fashion. This means [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] cannot be used to hook &lt;tt&gt;+commands&lt;/tt&gt;. As of version 1.3, the recommended solution is to use the global forward [https://sm.alliedmods.net/new-api/sdktools_hooks/OnPlayerRunCmd OnPlayerRunCmd()]. This forward is fired every time a player uses a movement button. To detect or block a &lt;tt&gt;+command&lt;/tt&gt;, you'll first have to find out its proper &lt;tt&gt;IN_&lt;/tt&gt; constant (see &lt;tt&gt;[https://sm.alliedmods.net/new-api/entity_prop_stocks/__raw entity_prop_stocks.inc]&lt;/tt&gt;).<br /> <br /> Here's how to use it to block crouching when attacking:<br /> <br /> &lt;pawn&gt;public Action OnPlayerRunCmd(int client, int &amp;buttons, int &amp;impulse, float vel[3], float angles[3], int &amp;weapon)<br /> {<br /> // Check if the player is attacking (+attack)<br /> if ((buttons &amp; IN_ATTACK) == IN_ATTACK)<br /> {<br /> // If so, block their crouching (+duck)<br /> buttons &amp;= ~IN_DUCK;<br /> }<br /> <br /> // We must return Plugin_Continue to let the changes be processed.<br /> // Otherwise, we can return Plugin_Handled to block the commands<br /> return Plugin_Continue;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of loose indentation warnings?=<br /> &lt;pre&gt;myplugin.sp(#) : warning 217: loose indentation&lt;/pre&gt;<br /> <br /> Loose indentation warnings arise when indentation in your code is inconsistent. This usually means using both tabs and spaces as indentation. However, it can also mean a different amount of spaces or tabs are being used. Therefore, to correct it, use just one type of indentation. Because different editors have different settings for the size of tab stops, it is recommended you use 4 spaces to indent.<br /> <br /> Good:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> int myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> Bad:<br /> <br /> &lt;pawn&gt;public voidOnPluginStart()<br /> {<br /> int myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of tag mismatch warnings?=<br /> Though every variable in SourcePawn is one cell (4 bytes), with the exception of strings, there are many different ways to interpret what's inside a cell. To signify a cell's contents, tags are used. The most common are &lt;tt&gt;_&lt;/tt&gt; (the default tag: a vanilla cell. This tag is implied when no other tag is specified.), &lt;tt&gt;float&lt;/tt&gt;, &lt;tt&gt;bool&lt;/tt&gt;, and &lt;tt&gt;char&lt;/tt&gt;. See [[Introduction_to_SourcePawn_1.7#Variables_2]] for more information.<br /> <br /> Functions wear these tags on their parameters so you can tell what needs to be passed to the function:<br /> &lt;pawn&gt;native int SetEntPropFloat(int entity, PropType type, const char[] prop, float value, int element)&lt;/pawn&gt;<br /> <br /> This function calls for '''&lt;tt&gt;entity&lt;/tt&gt;''', a cell with the implied tag '''''&lt;tt&gt;int&lt;/tt&gt;'''''; '''&lt;tt&gt;type&lt;/tt&gt;''', with the developer-defined tag '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; '''&lt;tt&gt;prop&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;char&lt;/tt&gt;'''''; and '''&lt;tt&gt;value&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;float&lt;/tt&gt;'''''.<br /> To call this function, then, you must pass values with the specified tags. For example:<br /> &lt;pawn&gt;SetEntPropFloat(1234, Prop_Send, &quot;m_fNumber&quot;, 1.0);&lt;/pawn&gt;<br /> <br /> This calls the function correctly: &lt;tt&gt;1234&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''), &lt;tt&gt;Prop_Send&lt;/tt&gt; is a variable defined in the enum '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [https://sm.alliedmods.net/new-api/entity/__raw entity.inc], &lt;tt&gt;&quot;m_fNumber&quot;&lt;/tt&gt; is a '''''&lt;tt&gt;char&lt;/tt&gt;''''', and &lt;tt&gt;1.0&lt;/tt&gt; is a '''''&lt;tt&gt;float&lt;/tt&gt;'''''. For a nonexample:<br /> &lt;pawn&gt;SetEntPropFloat(1234.0, 1, &quot;m_fNumber&quot;, 1337);&lt;/pawn&gt;<br /> <br /> This is incorrect! &lt;tt&gt;1234.0&lt;/tt&gt; is a '''''&lt;tt&gt;float&lt;/tt&gt;''''' that should be a regular cell ('''''&lt;tt&gt;int&lt;/tt&gt;'''''); &lt;tt&gt;1&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;int&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; and &lt;tt&gt;1337&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;int&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;float&lt;/tt&gt;'''''. This call will generate a tag mismatch warning. To correct it, simply use a value with the correct tag. Most of the time, tags that are not built-in (such as '''''&lt;tt&gt;PropType&lt;/tt&gt;''''') can be found in the same file where a function uses them (you can find '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [https://sm.alliedmods.net/new-api/entity/__raw entity.inc]).<br /> <br /> =How do I add color to my messages?=<br /> Though the actual colors will vary depending on the mod, you can add color to any chat message using the characters &lt;tt&gt;0x01&lt;/tt&gt; to &lt;tt&gt;0x08&lt;/tt&gt;. For example:<br /> &lt;pawn&gt;PrintToChatAll (&quot;\x01 1 .. \x02 2 .. \x03 3 .. \x04 4 .. \x05 5 .. \x06 6 .. \x07 7 .. \x08 8&quot;);&lt;/pawn&gt;<br /> <br /> Example output from Left 4 Dead:<br /> <br /> [[Image:Left_4_Dead_Colors.png]]<br /> <br /> With a little experimenting, you can learn the colors for a mod. However, the meaning behind the colors is generally as follows:<br /> <br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x01&lt;/tt&gt; = Normal color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x02&lt;/tt&gt; = Use team color to the end of a player's name. When used, it can be the only color used, and it must be at the start of the message.<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x03&lt;/tt&gt; = Team color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x04&lt;/tt&gt; = Location color<br /> <br /> This data comes from Counter-Strike: Source.<br /> <br /> For CS:GO, here are some colors:<br /> &lt;pawn&gt;PrintToChat(&quot;\x011\x022\x033\x044\x055\x066\x077\x088\x099\x0AA\x0BB\x0CC\x0DD\x0EE\x0FF&quot;);&lt;/pawn&gt;<br /> <br /> Unfortunately, to use players' team colors, you must use UserMessages, because there is no way for the current SourceMod functions to know which team color to use. Here's an example:<br /> <br /> &lt;pawn&gt;Handle hBf;<br /> hBf = StartMessageOne(&quot;SayText2&quot;, player_to); // To send the message to all players, use StartMessageAll(&quot;SayText2&quot;);<br /> if (hBf != null)<br /> {<br /> BfWriteByte(hBf, player_from); <br /> BfWriteByte(hBf, 0); <br /> BfWriteString(hBf, &quot;&lt;\x03player_from team color\x01&gt; My message&quot;);<br /> EndMessage();<br /> }&lt;/pawn&gt;<br /> <br /> &lt;tt&gt;player_to&lt;/tt&gt; is the client index to send the message to (or use [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=132&amp; StartMessageAll()] instead of [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=133&amp; StartMessageOne()] to send the message to all players). &lt;tt&gt;player_from&lt;/tt&gt; is the client index of the player whose team color will be utilized in the message. The message will now look like this (assuming &lt;tt&gt;player_from&lt;/tt&gt; is on the RED team):<br /> <br /> &lt;span style=&quot;color:#AA0&quot;&gt;&amp;lt;&lt;/span&gt;&lt;span style=&quot;color:#F00&quot;&gt;player_from team color&lt;/span&gt;&lt;span style=&quot;color:#AA0&quot;&gt;&amp;gt; My message&lt;/span&gt;<br /> <br /> There's another catch, however: this is only known to work in CS:S and TF2. For other mods, your mileage may vary.<br /> <br /> ==Color Libraries==<br /> There are a few libraries that can handle colors for you, so you don't have to muck with UserMessages:<br /> <br /> ===exvel's Colors===<br /> This is a simple include file, allowing easy control over chat coloring. You can grab it [http://forums.alliedmods.net/showthread.php?t=96831 on the forums]. Instead of hex codes, colors are denoted with tags, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{default}&lt;/tt&gt;&lt;/span&gt;, &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;, or &lt;span style=&quot;color: #00F;&quot;&gt;&lt;tt&gt;{blue}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> Here's some example usage. Note that this code assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;colors&gt;<br /> <br /> public void OnPluginStart()<br /> {<br /> CPrintToChatAll(&quot;{green}Hello {red}World! {default}Test 1 concluded.&quot;);<br /> <br /> int client_on_blu_team = 1;<br /> CPrintToChatAllEx(client_on_blu_team, &quot;{teamcolor}BLU team {default}says {green}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> Note that to use a team color, there needs to be at least one player on that team. Otherwise, it will default to &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> ===SMLib===<br /> [http://forums.alliedmods.net/showthread.php?p=1398699 SMLib] is a huge collection of stock functions to keep plug-in developers from reinventing the wheel. It includes a [http://forums.alliedmods.net/showthread.php?p=1398702#post1398702 colors API] very similar to [[#exvel's Colors|exvel's]]. The benefits of SMLib are it supports shorthand color names, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{N}&lt;/tt&gt;&lt;/span&gt; and &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{G}&lt;/tt&gt;&lt;/span&gt;, and all colors are supported in its &lt;tt&gt;Client_PrintToChat()&lt;/tt&gt; function.<br /> <br /> Here's how to print the same thing as the above example with SMLib. Note that this code also assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;smlib&gt;<br /> <br /> public void OnPluginStart()<br /> {<br /> Client_PrintToChatAll(&quot;{G}Hello {R}World! {N}Test 1 concluded.&quot;);<br /> <br /> int client_on_blu_team = 1;<br /> Client_PrintToChatAll(client_on_blu_team, &quot;{T}BLU team {N}says {G}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> =Why do I get an &quot;unknown symbol&quot; error when using an SDKTools native?=<br /> None of SourceMod's or SDKTools's functions are built into SourcePawn. Therefore, every time you use one of their functions, SourcePawn needs to know how to call the function. Normally, this is done using includes. Just like you would #include &lt;sourcemod&gt; to use SourceMod's functions, you need to:<br /> &lt;pawn&gt;#include &lt;sdktools&gt;&lt;/pawn&gt;<br /> to use an SDKTools native.<br /> <br /> =Why is Source telling me my command is an &quot;Unknown command&quot;?=<br /> This is because you're not returning &lt;tt&gt;Plugin_Handled&lt;/tt&gt; in your callback. If you don't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so.<br /> <br /> &lt;pawn&gt;public Action MyCommand(int client, int args)<br /> {<br /> // Do something...<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Scripting_FAQ_(SourceMod)&diff=10116 2016-02-16T21:22:02Z

<p>Xerox8521: /* Color Libraries */</p> <hr /> <div>[[Image:Yak.gif]]<br /> yak wuz heer<br /> <br /> =How do I learn SourcePawn?=<br /> A good start is on the [[Introduction_to_SourcePawn_1.7]] page, which will teach you the SourcePawn language. Then go through the [[Introduction to SourceMod Plugins]], which will teach you how to write your first plug-in.<br /> <br /> =Where can I find all the SourcePawn functions and other information?=<br /> All SourceMod plug-ins have this line:<br /> <br /> &lt;pawn&gt;#include &lt;sourcemod&gt;&lt;/pawn&gt;<br /> <br /> This line instructs the compiler to retrieve the file &lt;tt&gt;sourcemod.inc&lt;/tt&gt; from the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder. Every function, variable, and definition can be found in the &lt;tt&gt;.inc&lt;/tt&gt; files inside the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder.<br /> <br /> But searching through all those files can be quite tedious. Thankfully, the honourable [https://forums.alliedmods.net/member.php?u=9443 Nican] created an API reference viewable on the web, complete with searching and commenting: [https://sm.alliedmods.net/new-api/ https://sm.alliedmods.net/new-api/]<br /> <br /> Also, if you are in the SourceMod IRC channel ([irc://irc.gamesurge.net/sourcemod #sourcemod on GameSurge]), you can use the &lt;tt&gt;!api&lt;/tt&gt; command to search [https://forums.alliedmods.net/member.php?u=9443 Nican's] API reference:<br /> &lt;pre&gt;&lt;theY4Kman&gt; !api Netclass<br /> &lt;yakbot&gt; theY4Kman: bool GetEntityNetClass(int edict, char[] clsname, int maxlength): Retrieves an entity's networkable serverclass name. This is not the same as the classname and is used for networkable state changes. (https://sm.alliedmods.net/new-api/entity/GetEntityNetClass)&lt;/pre&gt;<br /> <br /> =How do I find the classname of an entity? (e.g., &quot;&lt;tt&gt;weapon_knife&lt;/tt&gt;&quot; or &quot;&lt;tt&gt;prop_physics&lt;/tt&gt;&quot;)=<br /> The classname of an entity (not to be confused with a netclass such as &lt;tt&gt;CCSPlayer&lt;/tt&gt;) is a unique identifier. It's the most well known of entity names. To find it, use the function [https://sm.alliedmods.net/new-api/entity/GetEdictClassname GetEdictClassname()]:<br /> <br /> &lt;pawn&gt;char classname[128];<br /> GetEdictClassname(myentity, classname, sizeof(classname));<br /> <br /> PrintToServer(&quot;myentity classname: %s&quot;, classname);<br /> // myentity classname: weapon_knife&lt;/pawn&gt;<br /> <br /> =How do I block regular commands, such as &lt;tt&gt;kill&lt;/tt&gt; and &lt;tt&gt;say&lt;/tt&gt;?=<br /> As of version 1.3, the recommended way to hook and block commands is with [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()]. Previously, using [https://sm.alliedmods.net/new-api/console/RegConsoleCmd RegConsoleCmd()] with the command name was the only way to hook commands, but this creates a whole new command for the command dispatch to check every time any command is executed. [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] creates only a lightweight hook, processed only when the specific command is executed.<br /> <br /> Here's how to use it to block the &lt;tt&gt;say&lt;/tt&gt; command:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> AddCommandListener(SayCallback, &quot;say&quot;);<br /> }<br /> <br /> public Action SayCallback(int client, const char[] command, int argc)<br /> {<br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I hook +commands, such as &lt;tt&gt;+zoom&lt;/tt&gt; and &lt;tt&gt;+attack&lt;/tt&gt;?=<br /> Unlike regular commands, &lt;tt&gt;+commands&lt;/tt&gt; are handled on the client's computer, then sent to the server in a more compressed fashion. This means [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] cannot be used to hook &lt;tt&gt;+commands&lt;/tt&gt;. As of version 1.3, the recommended solution is to use the global forward [https://sm.alliedmods.net/new-api/sdktools_hooks/OnPlayerRunCmd OnPlayerRunCmd()]. This forward is fired every time a player uses a movement button. To detect or block a &lt;tt&gt;+command&lt;/tt&gt;, you'll first have to find out its proper &lt;tt&gt;IN_&lt;/tt&gt; constant (see &lt;tt&gt;[https://sm.alliedmods.net/new-api/entity_prop_stocks/__raw entity_prop_stocks.inc]&lt;/tt&gt;).<br /> <br /> Here's how to use it to block crouching when attacking:<br /> <br /> &lt;pawn&gt;public Action OnPlayerRunCmd(int client, int &amp;buttons, int &amp;impulse, float vel[3], float angles[3], int &amp;weapon)<br /> {<br /> // Check if the player is attacking (+attack)<br /> if ((buttons &amp; IN_ATTACK) == IN_ATTACK)<br /> {<br /> // If so, block their crouching (+duck)<br /> buttons &amp;= ~IN_DUCK;<br /> }<br /> <br /> // We must return Plugin_Continue to let the changes be processed.<br /> // Otherwise, we can return Plugin_Handled to block the commands<br /> return Plugin_Continue;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of loose indentation warnings?=<br /> &lt;pre&gt;myplugin.sp(#) : warning 217: loose indentation&lt;/pre&gt;<br /> <br /> Loose indentation warnings arise when indentation in your code is inconsistent. This usually means using both tabs and spaces as indentation. However, it can also mean a different amount of spaces or tabs are being used. Therefore, to correct it, use just one type of indentation. Because different editors have different settings for the size of tab stops, it is recommended you use 4 spaces to indent.<br /> <br /> Good:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> int myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> Bad:<br /> <br /> &lt;pawn&gt;public voidOnPluginStart()<br /> {<br /> int myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of tag mismatch warnings?=<br /> Though every variable in SourcePawn is one cell (4 bytes), with the exception of strings, there are many different ways to interpret what's inside a cell. To signify a cell's contents, tags are used. The most common are &lt;tt&gt;_&lt;/tt&gt; (the default tag: a vanilla cell. This tag is implied when no other tag is specified.), &lt;tt&gt;float&lt;/tt&gt;, &lt;tt&gt;bool&lt;/tt&gt;, and &lt;tt&gt;char&lt;/tt&gt;. See [[Introduction_to_SourcePawn_1.7#Variables_2]] for more information.<br /> <br /> Functions wear these tags on their parameters so you can tell what needs to be passed to the function:<br /> &lt;pawn&gt;native int SetEntPropFloat(int entity, PropType type, const char[] prop, float value, int element)&lt;/pawn&gt;<br /> <br /> This function calls for '''&lt;tt&gt;entity&lt;/tt&gt;''', a cell with the implied tag '''''&lt;tt&gt;int&lt;/tt&gt;'''''; '''&lt;tt&gt;type&lt;/tt&gt;''', with the developer-defined tag '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; '''&lt;tt&gt;prop&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;char&lt;/tt&gt;'''''; and '''&lt;tt&gt;value&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;float&lt;/tt&gt;'''''.<br /> To call this function, then, you must pass values with the specified tags. For example:<br /> &lt;pawn&gt;SetEntPropFloat(1234, Prop_Send, &quot;m_fNumber&quot;, 1.0);&lt;/pawn&gt;<br /> <br /> This calls the function correctly: &lt;tt&gt;1234&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''), &lt;tt&gt;Prop_Send&lt;/tt&gt; is a variable defined in the enum '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [https://sm.alliedmods.net/new-api/entity/__raw entity.inc], &lt;tt&gt;&quot;m_fNumber&quot;&lt;/tt&gt; is a '''''&lt;tt&gt;char&lt;/tt&gt;''''', and &lt;tt&gt;1.0&lt;/tt&gt; is a '''''&lt;tt&gt;float&lt;/tt&gt;'''''. For a nonexample:<br /> &lt;pawn&gt;SetEntPropFloat(1234.0, 1, &quot;m_fNumber&quot;, 1337);&lt;/pawn&gt;<br /> <br /> This is incorrect! &lt;tt&gt;1234.0&lt;/tt&gt; is a '''''&lt;tt&gt;float&lt;/tt&gt;''''' that should be a regular cell ('''''&lt;tt&gt;int&lt;/tt&gt;'''''); &lt;tt&gt;1&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;int&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; and &lt;tt&gt;1337&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;int&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;float&lt;/tt&gt;'''''. This call will generate a tag mismatch warning. To correct it, simply use a value with the correct tag. Most of the time, tags that are not built-in (such as '''''&lt;tt&gt;PropType&lt;/tt&gt;''''') can be found in the same file where a function uses them (you can find '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [https://sm.alliedmods.net/new-api/entity/__raw entity.inc]).<br /> <br /> =How do I add color to my messages?=<br /> Though the actual colors will vary depending on the mod, you can add color to any chat message using the characters &lt;tt&gt;0x01&lt;/tt&gt; to &lt;tt&gt;0x08&lt;/tt&gt;. For example:<br /> &lt;pawn&gt;PrintToChatAll (&quot;\x01 1 .. \x02 2 .. \x03 3 .. \x04 4 .. \x05 5 .. \x06 6 .. \x07 7 .. \x08 8&quot;);&lt;/pawn&gt;<br /> <br /> Example output from Left 4 Dead:<br /> <br /> [[Image:Left_4_Dead_Colors.png]]<br /> <br /> With a little experimenting, you can learn the colors for a mod. However, the meaning behind the colors is generally as follows:<br /> <br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x01&lt;/tt&gt; = Normal color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x02&lt;/tt&gt; = Use team color to the end of a player's name. When used, it can be the only color used, and it must be at the start of the message.<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x03&lt;/tt&gt; = Team color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x04&lt;/tt&gt; = Location color<br /> <br /> This data comes from Counter-Strike: Source.<br /> <br /> For CS:GO, here are some colors:<br /> &lt;pawn&gt;PrintToChat(&quot;\x011\x022\x033\x044\x055\x066\x077\x088\x099\x0AA\x0BB\x0CC\x0DD\x0EE\x0FF&quot;);&lt;/pawn&gt;<br /> <br /> Unfortunately, to use players' team colors, you must use UserMessages, because there is no way for the current SourceMod functions to know which team color to use. Here's an example:<br /> <br /> &lt;pawn&gt;Handle hBf;<br /> hBf = StartMessageOne(&quot;SayText2&quot;, player_to); // To send the message to all players, use StartMessageAll(&quot;SayText2&quot;);<br /> if (hBf != null)<br /> {<br /> BfWriteByte(hBf, player_from); <br /> BfWriteByte(hBf, 0); <br /> BfWriteString(hBf, &quot;&lt;\x03player_from team color\x01&gt; My message&quot;);<br /> EndMessage();<br /> }&lt;/pawn&gt;<br /> <br /> &lt;tt&gt;player_to&lt;/tt&gt; is the client index to send the message to (or use [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=132&amp; StartMessageAll()] instead of [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=133&amp; StartMessageOne()] to send the message to all players). &lt;tt&gt;player_from&lt;/tt&gt; is the client index of the player whose team color will be utilized in the message. The message will now look like this (assuming &lt;tt&gt;player_from&lt;/tt&gt; is on the RED team):<br /> <br /> &lt;span style=&quot;color:#AA0&quot;&gt;&amp;lt;&lt;/span&gt;&lt;span style=&quot;color:#F00&quot;&gt;player_from team color&lt;/span&gt;&lt;span style=&quot;color:#AA0&quot;&gt;&amp;gt; My message&lt;/span&gt;<br /> <br /> There's another catch, however: this is only known to work in CS:S and TF2. For other mods, your mileage may vary.<br /> <br /> ==Color Libraries==<br /> There are a few libraries that can handle colors for you, so you don't have to muck with UserMessages:<br /> <br /> ===exvel's Colors===<br /> This is a simple include file, allowing easy control over chat coloring. You can grab it [http://forums.alliedmods.net/showthread.php?t=96831 on the forums]. Instead of hex codes, colors are denoted with tags, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{default}&lt;/tt&gt;&lt;/span&gt;, &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;, or &lt;span style=&quot;color: #00F;&quot;&gt;&lt;tt&gt;{blue}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> Here's some example usage. Note that this code assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;colors&gt;<br /> <br /> public void OnPluginStart()<br /> {<br /> CPrintToChatAll(&quot;{green}Hello {red}World! {default}Test 1 concluded.&quot;);<br /> <br /> int client_on_blu_team = 1;<br /> CPrintToChatAllEx(client_on_blu_team, &quot;{teamcolor}BLU team {default}says {green}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> Note that to use a team color, there needs to be at least one player on that team. Otherwise, it will default to &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> ===SMLib===<br /> [http://forums.alliedmods.net/showthread.php?p=1398699 SMLib] is a huge collection of stock functions to keep plug-in developers from reinventing the wheel. It includes a [http://forums.alliedmods.net/showthread.php?p=1398702#post1398702 colors API] very similar to [[#exvel's Colors|exvel's]]. The benefits of SMLib are it supports shorthand color names, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{N}&lt;/tt&gt;&lt;/span&gt; and &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{G}&lt;/tt&gt;&lt;/span&gt;, and all colors are supported in its &lt;tt&gt;Client_PrintToChat()&lt;/tt&gt; function.<br /> <br /> Here's how to print the same thing as the above example with SMLib. Note that this code also assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;smlib&gt;<br /> <br /> public void OnPluginStart()<br /> {<br /> Client_PrintToChatAll(&quot;{G}Hello {R}World! {N}Test 1 concluded.&quot;);<br /> <br /> int client_on_blu_team = 1;<br /> Client_PrintToChatAll(client_on_blu_team, &quot;{T}BLU team {N}says {G}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> =Why do I get an &quot;unknown symbol&quot; error when using an SDKTools native?=<br /> None of SourceMod's or SDKTools's functions are built into SourcePawn. Therefore, every time you use one of their functions, SourcePawn needs to know how to call the function. Normally, this is done using includes. Just like you would #include &lt;sourcemod&gt; to use SourceMod's functions, you need to:<br /> &lt;pawn&gt;#include &lt;sdktools&gt;&lt;/pawn&gt;<br /> to use an SDKTools native.<br /> <br /> =Why is Source telling me my command is an &quot;Unknown command&quot;?=<br /> This is because you're not returning &lt;tt&gt;Plugin_Handled&lt;/tt&gt; in your callback. If you don't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so.<br /> <br /> &lt;pawn&gt;public Action:MyCommand(client, args)<br /> {<br /> // Do something...<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Scripting_FAQ_(SourceMod)&diff=10115 2016-02-16T21:21:17Z

<p>Xerox8521: /* How do I add color to my messages? */</p> <hr /> <div>[[Image:Yak.gif]]<br /> yak wuz heer<br /> <br /> =How do I learn SourcePawn?=<br /> A good start is on the [[Introduction_to_SourcePawn_1.7]] page, which will teach you the SourcePawn language. Then go through the [[Introduction to SourceMod Plugins]], which will teach you how to write your first plug-in.<br /> <br /> =Where can I find all the SourcePawn functions and other information?=<br /> All SourceMod plug-ins have this line:<br /> <br /> &lt;pawn&gt;#include &lt;sourcemod&gt;&lt;/pawn&gt;<br /> <br /> This line instructs the compiler to retrieve the file &lt;tt&gt;sourcemod.inc&lt;/tt&gt; from the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder. Every function, variable, and definition can be found in the &lt;tt&gt;.inc&lt;/tt&gt; files inside the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder.<br /> <br /> But searching through all those files can be quite tedious. Thankfully, the honourable [https://forums.alliedmods.net/member.php?u=9443 Nican] created an API reference viewable on the web, complete with searching and commenting: [https://sm.alliedmods.net/new-api/ https://sm.alliedmods.net/new-api/]<br /> <br /> Also, if you are in the SourceMod IRC channel ([irc://irc.gamesurge.net/sourcemod #sourcemod on GameSurge]), you can use the &lt;tt&gt;!api&lt;/tt&gt; command to search [https://forums.alliedmods.net/member.php?u=9443 Nican's] API reference:<br /> &lt;pre&gt;&lt;theY4Kman&gt; !api Netclass<br /> &lt;yakbot&gt; theY4Kman: bool GetEntityNetClass(int edict, char[] clsname, int maxlength): Retrieves an entity's networkable serverclass name. This is not the same as the classname and is used for networkable state changes. (https://sm.alliedmods.net/new-api/entity/GetEntityNetClass)&lt;/pre&gt;<br /> <br /> =How do I find the classname of an entity? (e.g., &quot;&lt;tt&gt;weapon_knife&lt;/tt&gt;&quot; or &quot;&lt;tt&gt;prop_physics&lt;/tt&gt;&quot;)=<br /> The classname of an entity (not to be confused with a netclass such as &lt;tt&gt;CCSPlayer&lt;/tt&gt;) is a unique identifier. It's the most well known of entity names. To find it, use the function [https://sm.alliedmods.net/new-api/entity/GetEdictClassname GetEdictClassname()]:<br /> <br /> &lt;pawn&gt;char classname[128];<br /> GetEdictClassname(myentity, classname, sizeof(classname));<br /> <br /> PrintToServer(&quot;myentity classname: %s&quot;, classname);<br /> // myentity classname: weapon_knife&lt;/pawn&gt;<br /> <br /> =How do I block regular commands, such as &lt;tt&gt;kill&lt;/tt&gt; and &lt;tt&gt;say&lt;/tt&gt;?=<br /> As of version 1.3, the recommended way to hook and block commands is with [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()]. Previously, using [https://sm.alliedmods.net/new-api/console/RegConsoleCmd RegConsoleCmd()] with the command name was the only way to hook commands, but this creates a whole new command for the command dispatch to check every time any command is executed. [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] creates only a lightweight hook, processed only when the specific command is executed.<br /> <br /> Here's how to use it to block the &lt;tt&gt;say&lt;/tt&gt; command:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> AddCommandListener(SayCallback, &quot;say&quot;);<br /> }<br /> <br /> public Action SayCallback(int client, const char[] command, int argc)<br /> {<br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I hook +commands, such as &lt;tt&gt;+zoom&lt;/tt&gt; and &lt;tt&gt;+attack&lt;/tt&gt;?=<br /> Unlike regular commands, &lt;tt&gt;+commands&lt;/tt&gt; are handled on the client's computer, then sent to the server in a more compressed fashion. This means [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] cannot be used to hook &lt;tt&gt;+commands&lt;/tt&gt;. As of version 1.3, the recommended solution is to use the global forward [https://sm.alliedmods.net/new-api/sdktools_hooks/OnPlayerRunCmd OnPlayerRunCmd()]. This forward is fired every time a player uses a movement button. To detect or block a &lt;tt&gt;+command&lt;/tt&gt;, you'll first have to find out its proper &lt;tt&gt;IN_&lt;/tt&gt; constant (see &lt;tt&gt;[https://sm.alliedmods.net/new-api/entity_prop_stocks/__raw entity_prop_stocks.inc]&lt;/tt&gt;).<br /> <br /> Here's how to use it to block crouching when attacking:<br /> <br /> &lt;pawn&gt;public Action OnPlayerRunCmd(int client, int &amp;buttons, int &amp;impulse, float vel[3], float angles[3], int &amp;weapon)<br /> {<br /> // Check if the player is attacking (+attack)<br /> if ((buttons &amp; IN_ATTACK) == IN_ATTACK)<br /> {<br /> // If so, block their crouching (+duck)<br /> buttons &amp;= ~IN_DUCK;<br /> }<br /> <br /> // We must return Plugin_Continue to let the changes be processed.<br /> // Otherwise, we can return Plugin_Handled to block the commands<br /> return Plugin_Continue;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of loose indentation warnings?=<br /> &lt;pre&gt;myplugin.sp(#) : warning 217: loose indentation&lt;/pre&gt;<br /> <br /> Loose indentation warnings arise when indentation in your code is inconsistent. This usually means using both tabs and spaces as indentation. However, it can also mean a different amount of spaces or tabs are being used. Therefore, to correct it, use just one type of indentation. Because different editors have different settings for the size of tab stops, it is recommended you use 4 spaces to indent.<br /> <br /> Good:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> int myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> Bad:<br /> <br /> &lt;pawn&gt;public voidOnPluginStart()<br /> {<br /> int myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of tag mismatch warnings?=<br /> Though every variable in SourcePawn is one cell (4 bytes), with the exception of strings, there are many different ways to interpret what's inside a cell. To signify a cell's contents, tags are used. The most common are &lt;tt&gt;_&lt;/tt&gt; (the default tag: a vanilla cell. This tag is implied when no other tag is specified.), &lt;tt&gt;float&lt;/tt&gt;, &lt;tt&gt;bool&lt;/tt&gt;, and &lt;tt&gt;char&lt;/tt&gt;. See [[Introduction_to_SourcePawn_1.7#Variables_2]] for more information.<br /> <br /> Functions wear these tags on their parameters so you can tell what needs to be passed to the function:<br /> &lt;pawn&gt;native int SetEntPropFloat(int entity, PropType type, const char[] prop, float value, int element)&lt;/pawn&gt;<br /> <br /> This function calls for '''&lt;tt&gt;entity&lt;/tt&gt;''', a cell with the implied tag '''''&lt;tt&gt;int&lt;/tt&gt;'''''; '''&lt;tt&gt;type&lt;/tt&gt;''', with the developer-defined tag '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; '''&lt;tt&gt;prop&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;char&lt;/tt&gt;'''''; and '''&lt;tt&gt;value&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;float&lt;/tt&gt;'''''.<br /> To call this function, then, you must pass values with the specified tags. For example:<br /> &lt;pawn&gt;SetEntPropFloat(1234, Prop_Send, &quot;m_fNumber&quot;, 1.0);&lt;/pawn&gt;<br /> <br /> This calls the function correctly: &lt;tt&gt;1234&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''), &lt;tt&gt;Prop_Send&lt;/tt&gt; is a variable defined in the enum '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [https://sm.alliedmods.net/new-api/entity/__raw entity.inc], &lt;tt&gt;&quot;m_fNumber&quot;&lt;/tt&gt; is a '''''&lt;tt&gt;char&lt;/tt&gt;''''', and &lt;tt&gt;1.0&lt;/tt&gt; is a '''''&lt;tt&gt;float&lt;/tt&gt;'''''. For a nonexample:<br /> &lt;pawn&gt;SetEntPropFloat(1234.0, 1, &quot;m_fNumber&quot;, 1337);&lt;/pawn&gt;<br /> <br /> This is incorrect! &lt;tt&gt;1234.0&lt;/tt&gt; is a '''''&lt;tt&gt;float&lt;/tt&gt;''''' that should be a regular cell ('''''&lt;tt&gt;int&lt;/tt&gt;'''''); &lt;tt&gt;1&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;int&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; and &lt;tt&gt;1337&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;int&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;float&lt;/tt&gt;'''''. This call will generate a tag mismatch warning. To correct it, simply use a value with the correct tag. Most of the time, tags that are not built-in (such as '''''&lt;tt&gt;PropType&lt;/tt&gt;''''') can be found in the same file where a function uses them (you can find '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [https://sm.alliedmods.net/new-api/entity/__raw entity.inc]).<br /> <br /> =How do I add color to my messages?=<br /> Though the actual colors will vary depending on the mod, you can add color to any chat message using the characters &lt;tt&gt;0x01&lt;/tt&gt; to &lt;tt&gt;0x08&lt;/tt&gt;. For example:<br /> &lt;pawn&gt;PrintToChatAll (&quot;\x01 1 .. \x02 2 .. \x03 3 .. \x04 4 .. \x05 5 .. \x06 6 .. \x07 7 .. \x08 8&quot;);&lt;/pawn&gt;<br /> <br /> Example output from Left 4 Dead:<br /> <br /> [[Image:Left_4_Dead_Colors.png]]<br /> <br /> With a little experimenting, you can learn the colors for a mod. However, the meaning behind the colors is generally as follows:<br /> <br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x01&lt;/tt&gt; = Normal color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x02&lt;/tt&gt; = Use team color to the end of a player's name. When used, it can be the only color used, and it must be at the start of the message.<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x03&lt;/tt&gt; = Team color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x04&lt;/tt&gt; = Location color<br /> <br /> This data comes from Counter-Strike: Source.<br /> <br /> For CS:GO, here are some colors:<br /> &lt;pawn&gt;PrintToChat(&quot;\x011\x022\x033\x044\x055\x066\x077\x088\x099\x0AA\x0BB\x0CC\x0DD\x0EE\x0FF&quot;);&lt;/pawn&gt;<br /> <br /> Unfortunately, to use players' team colors, you must use UserMessages, because there is no way for the current SourceMod functions to know which team color to use. Here's an example:<br /> <br /> &lt;pawn&gt;Handle hBf;<br /> hBf = StartMessageOne(&quot;SayText2&quot;, player_to); // To send the message to all players, use StartMessageAll(&quot;SayText2&quot;);<br /> if (hBf != null)<br /> {<br /> BfWriteByte(hBf, player_from); <br /> BfWriteByte(hBf, 0); <br /> BfWriteString(hBf, &quot;&lt;\x03player_from team color\x01&gt; My message&quot;);<br /> EndMessage();<br /> }&lt;/pawn&gt;<br /> <br /> &lt;tt&gt;player_to&lt;/tt&gt; is the client index to send the message to (or use [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=132&amp; StartMessageAll()] instead of [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=133&amp; StartMessageOne()] to send the message to all players). &lt;tt&gt;player_from&lt;/tt&gt; is the client index of the player whose team color will be utilized in the message. The message will now look like this (assuming &lt;tt&gt;player_from&lt;/tt&gt; is on the RED team):<br /> <br /> &lt;span style=&quot;color:#AA0&quot;&gt;&amp;lt;&lt;/span&gt;&lt;span style=&quot;color:#F00&quot;&gt;player_from team color&lt;/span&gt;&lt;span style=&quot;color:#AA0&quot;&gt;&amp;gt; My message&lt;/span&gt;<br /> <br /> There's another catch, however: this is only known to work in CS:S and TF2. For other mods, your mileage may vary.<br /> <br /> ==Color Libraries==<br /> There are a few libraries that can handle colors for you, so you don't have to muck with UserMessages:<br /> <br /> ===exvel's Colors===<br /> This is a simple include file, allowing easy control over chat coloring. You can grab it [http://forums.alliedmods.net/showthread.php?t=96831 on the forums]. Instead of hex codes, colors are denoted with tags, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{default}&lt;/tt&gt;&lt;/span&gt;, &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;, or &lt;span style=&quot;color: #00F;&quot;&gt;&lt;tt&gt;{blue}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> Here's some example usage. Note that this code assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;colors&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> CPrintToChatAll(&quot;{green}Hello {red}World! {default}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> CPrintToChatAllEx(client_on_blu_team, &quot;{teamcolor}BLU team {default}says {green}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> Note that to use a team color, there needs to be at least one player on that team. Otherwise, it will default to &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> ===SMLib===<br /> [http://forums.alliedmods.net/showthread.php?p=1398699 SMLib] is a huge collection of stock functions to keep plug-in developers from reinventing the wheel. It includes a [http://forums.alliedmods.net/showthread.php?p=1398702#post1398702 colors API] very similar to [[#exvel's Colors|exvel's]]. The benefits of SMLib are it supports shorthand color names, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{N}&lt;/tt&gt;&lt;/span&gt; and &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{G}&lt;/tt&gt;&lt;/span&gt;, and all colors are supported in its &lt;tt&gt;Client_PrintToChat()&lt;/tt&gt; function.<br /> <br /> Here's how to print the same thing as the above example with SMLib. Note that this code also assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;smlib&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> Client_PrintToChatAll(&quot;{G}Hello {R}World! {N}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> Client_PrintToChatAll(client_on_blu_team, &quot;{T}BLU team {N}says {G}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> =Why do I get an &quot;unknown symbol&quot; error when using an SDKTools native?=<br /> None of SourceMod's or SDKTools's functions are built into SourcePawn. Therefore, every time you use one of their functions, SourcePawn needs to know how to call the function. Normally, this is done using includes. Just like you would #include &lt;sourcemod&gt; to use SourceMod's functions, you need to:<br /> &lt;pawn&gt;#include &lt;sdktools&gt;&lt;/pawn&gt;<br /> to use an SDKTools native.<br /> <br /> =Why is Source telling me my command is an &quot;Unknown command&quot;?=<br /> This is because you're not returning &lt;tt&gt;Plugin_Handled&lt;/tt&gt; in your callback. If you don't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so.<br /> <br /> &lt;pawn&gt;public Action:MyCommand(client, args)<br /> {<br /> // Do something...<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Scripting_FAQ_(SourceMod)&diff=10114 2016-02-16T21:20:41Z

<p>Xerox8521: /* How do I get rid of tag mismatch warnings? */</p> <hr /> <div>[[Image:Yak.gif]]<br /> yak wuz heer<br /> <br /> =How do I learn SourcePawn?=<br /> A good start is on the [[Introduction_to_SourcePawn_1.7]] page, which will teach you the SourcePawn language. Then go through the [[Introduction to SourceMod Plugins]], which will teach you how to write your first plug-in.<br /> <br /> =Where can I find all the SourcePawn functions and other information?=<br /> All SourceMod plug-ins have this line:<br /> <br /> &lt;pawn&gt;#include &lt;sourcemod&gt;&lt;/pawn&gt;<br /> <br /> This line instructs the compiler to retrieve the file &lt;tt&gt;sourcemod.inc&lt;/tt&gt; from the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder. Every function, variable, and definition can be found in the &lt;tt&gt;.inc&lt;/tt&gt; files inside the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder.<br /> <br /> But searching through all those files can be quite tedious. Thankfully, the honourable [https://forums.alliedmods.net/member.php?u=9443 Nican] created an API reference viewable on the web, complete with searching and commenting: [https://sm.alliedmods.net/new-api/ https://sm.alliedmods.net/new-api/]<br /> <br /> Also, if you are in the SourceMod IRC channel ([irc://irc.gamesurge.net/sourcemod #sourcemod on GameSurge]), you can use the &lt;tt&gt;!api&lt;/tt&gt; command to search [https://forums.alliedmods.net/member.php?u=9443 Nican's] API reference:<br /> &lt;pre&gt;&lt;theY4Kman&gt; !api Netclass<br /> &lt;yakbot&gt; theY4Kman: bool GetEntityNetClass(int edict, char[] clsname, int maxlength): Retrieves an entity's networkable serverclass name. This is not the same as the classname and is used for networkable state changes. (https://sm.alliedmods.net/new-api/entity/GetEntityNetClass)&lt;/pre&gt;<br /> <br /> =How do I find the classname of an entity? (e.g., &quot;&lt;tt&gt;weapon_knife&lt;/tt&gt;&quot; or &quot;&lt;tt&gt;prop_physics&lt;/tt&gt;&quot;)=<br /> The classname of an entity (not to be confused with a netclass such as &lt;tt&gt;CCSPlayer&lt;/tt&gt;) is a unique identifier. It's the most well known of entity names. To find it, use the function [https://sm.alliedmods.net/new-api/entity/GetEdictClassname GetEdictClassname()]:<br /> <br /> &lt;pawn&gt;char classname[128];<br /> GetEdictClassname(myentity, classname, sizeof(classname));<br /> <br /> PrintToServer(&quot;myentity classname: %s&quot;, classname);<br /> // myentity classname: weapon_knife&lt;/pawn&gt;<br /> <br /> =How do I block regular commands, such as &lt;tt&gt;kill&lt;/tt&gt; and &lt;tt&gt;say&lt;/tt&gt;?=<br /> As of version 1.3, the recommended way to hook and block commands is with [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()]. Previously, using [https://sm.alliedmods.net/new-api/console/RegConsoleCmd RegConsoleCmd()] with the command name was the only way to hook commands, but this creates a whole new command for the command dispatch to check every time any command is executed. [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] creates only a lightweight hook, processed only when the specific command is executed.<br /> <br /> Here's how to use it to block the &lt;tt&gt;say&lt;/tt&gt; command:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> AddCommandListener(SayCallback, &quot;say&quot;);<br /> }<br /> <br /> public Action SayCallback(int client, const char[] command, int argc)<br /> {<br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I hook +commands, such as &lt;tt&gt;+zoom&lt;/tt&gt; and &lt;tt&gt;+attack&lt;/tt&gt;?=<br /> Unlike regular commands, &lt;tt&gt;+commands&lt;/tt&gt; are handled on the client's computer, then sent to the server in a more compressed fashion. This means [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] cannot be used to hook &lt;tt&gt;+commands&lt;/tt&gt;. As of version 1.3, the recommended solution is to use the global forward [https://sm.alliedmods.net/new-api/sdktools_hooks/OnPlayerRunCmd OnPlayerRunCmd()]. This forward is fired every time a player uses a movement button. To detect or block a &lt;tt&gt;+command&lt;/tt&gt;, you'll first have to find out its proper &lt;tt&gt;IN_&lt;/tt&gt; constant (see &lt;tt&gt;[https://sm.alliedmods.net/new-api/entity_prop_stocks/__raw entity_prop_stocks.inc]&lt;/tt&gt;).<br /> <br /> Here's how to use it to block crouching when attacking:<br /> <br /> &lt;pawn&gt;public Action OnPlayerRunCmd(int client, int &amp;buttons, int &amp;impulse, float vel[3], float angles[3], int &amp;weapon)<br /> {<br /> // Check if the player is attacking (+attack)<br /> if ((buttons &amp; IN_ATTACK) == IN_ATTACK)<br /> {<br /> // If so, block their crouching (+duck)<br /> buttons &amp;= ~IN_DUCK;<br /> }<br /> <br /> // We must return Plugin_Continue to let the changes be processed.<br /> // Otherwise, we can return Plugin_Handled to block the commands<br /> return Plugin_Continue;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of loose indentation warnings?=<br /> &lt;pre&gt;myplugin.sp(#) : warning 217: loose indentation&lt;/pre&gt;<br /> <br /> Loose indentation warnings arise when indentation in your code is inconsistent. This usually means using both tabs and spaces as indentation. However, it can also mean a different amount of spaces or tabs are being used. Therefore, to correct it, use just one type of indentation. Because different editors have different settings for the size of tab stops, it is recommended you use 4 spaces to indent.<br /> <br /> Good:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> int myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> Bad:<br /> <br /> &lt;pawn&gt;public voidOnPluginStart()<br /> {<br /> int myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of tag mismatch warnings?=<br /> Though every variable in SourcePawn is one cell (4 bytes), with the exception of strings, there are many different ways to interpret what's inside a cell. To signify a cell's contents, tags are used. The most common are &lt;tt&gt;_&lt;/tt&gt; (the default tag: a vanilla cell. This tag is implied when no other tag is specified.), &lt;tt&gt;float&lt;/tt&gt;, &lt;tt&gt;bool&lt;/tt&gt;, and &lt;tt&gt;char&lt;/tt&gt;. See [[Introduction_to_SourcePawn_1.7#Variables_2]] for more information.<br /> <br /> Functions wear these tags on their parameters so you can tell what needs to be passed to the function:<br /> &lt;pawn&gt;native int SetEntPropFloat(int entity, PropType type, const char[] prop, float value, int element)&lt;/pawn&gt;<br /> <br /> This function calls for '''&lt;tt&gt;entity&lt;/tt&gt;''', a cell with the implied tag '''''&lt;tt&gt;int&lt;/tt&gt;'''''; '''&lt;tt&gt;type&lt;/tt&gt;''', with the developer-defined tag '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; '''&lt;tt&gt;prop&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;char&lt;/tt&gt;'''''; and '''&lt;tt&gt;value&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;float&lt;/tt&gt;'''''.<br /> To call this function, then, you must pass values with the specified tags. For example:<br /> &lt;pawn&gt;SetEntPropFloat(1234, Prop_Send, &quot;m_fNumber&quot;, 1.0);&lt;/pawn&gt;<br /> <br /> This calls the function correctly: &lt;tt&gt;1234&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''), &lt;tt&gt;Prop_Send&lt;/tt&gt; is a variable defined in the enum '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [https://sm.alliedmods.net/new-api/entity/__raw entity.inc], &lt;tt&gt;&quot;m_fNumber&quot;&lt;/tt&gt; is a '''''&lt;tt&gt;char&lt;/tt&gt;''''', and &lt;tt&gt;1.0&lt;/tt&gt; is a '''''&lt;tt&gt;float&lt;/tt&gt;'''''. For a nonexample:<br /> &lt;pawn&gt;SetEntPropFloat(1234.0, 1, &quot;m_fNumber&quot;, 1337);&lt;/pawn&gt;<br /> <br /> This is incorrect! &lt;tt&gt;1234.0&lt;/tt&gt; is a '''''&lt;tt&gt;float&lt;/tt&gt;''''' that should be a regular cell ('''''&lt;tt&gt;int&lt;/tt&gt;'''''); &lt;tt&gt;1&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;int&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; and &lt;tt&gt;1337&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;int&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;float&lt;/tt&gt;'''''. This call will generate a tag mismatch warning. To correct it, simply use a value with the correct tag. Most of the time, tags that are not built-in (such as '''''&lt;tt&gt;PropType&lt;/tt&gt;''''') can be found in the same file where a function uses them (you can find '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [https://sm.alliedmods.net/new-api/entity/__raw entity.inc]).<br /> <br /> =How do I add color to my messages?=<br /> Though the actual colors will vary depending on the mod, you can add color to any chat message using the characters &lt;tt&gt;0x01&lt;/tt&gt; to &lt;tt&gt;0x08&lt;/tt&gt;. For example:<br /> &lt;pawn&gt;PrintToChatAll (&quot;\x01 1 .. \x02 2 .. \x03 3 .. \x04 4 .. \x05 5 .. \x06 6 .. \x07 7 .. \x08 8&quot;);&lt;/pawn&gt;<br /> <br /> Example output from Left 4 Dead:<br /> <br /> [[Image:Left_4_Dead_Colors.png]]<br /> <br /> With a little experimenting, you can learn the colors for a mod. However, the meaning behind the colors is generally as follows:<br /> <br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x01&lt;/tt&gt; = Normal color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x02&lt;/tt&gt; = Use team color to the end of a player's name. When used, it can be the only color used, and it must be at the start of the message.<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x03&lt;/tt&gt; = Team color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x04&lt;/tt&gt; = Location color<br /> <br /> This data comes from Counter-Strike: Source.<br /> <br /> For CS:GO, here are some colors:<br /> &lt;pawn&gt;PrintToChat(&quot;\x011\x022\x033\x044\x055\x066\x077\x088\x099\x0AA\x0BB\x0CC\x0DD\x0EE\x0FF&quot;);&lt;/pawn&gt;<br /> <br /> Unfortunately, to use players' team colors, you must use UserMessages, because there is no way for the current SourceMod functions to know which team color to use. Here's an example:<br /> <br /> &lt;pawn&gt;new Handle:hBf;<br /> hBf = StartMessageOne(&quot;SayText2&quot;, player_to); // To send the message to all players, use StartMessageAll(&quot;SayText2&quot;);<br /> if (hBf != INVALID_HANDLE)<br /> {<br /> BfWriteByte(hBf, player_from); <br /> BfWriteByte(hBf, 0); <br /> BfWriteString(hBf, &quot;&lt;\x03player_from team color\x01&gt; My message&quot;);<br /> EndMessage();<br /> }&lt;/pawn&gt;<br /> <br /> &lt;tt&gt;player_to&lt;/tt&gt; is the client index to send the message to (or use [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=132&amp; StartMessageAll()] instead of [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=133&amp; StartMessageOne()] to send the message to all players). &lt;tt&gt;player_from&lt;/tt&gt; is the client index of the player whose team color will be utilized in the message. The message will now look like this (assuming &lt;tt&gt;player_from&lt;/tt&gt; is on the RED team):<br /> <br /> &lt;span style=&quot;color:#AA0&quot;&gt;&amp;lt;&lt;/span&gt;&lt;span style=&quot;color:#F00&quot;&gt;player_from team color&lt;/span&gt;&lt;span style=&quot;color:#AA0&quot;&gt;&amp;gt; My message&lt;/span&gt;<br /> <br /> There's another catch, however: this is only known to work in CS:S and TF2. For other mods, your mileage may vary.<br /> <br /> ==Color Libraries==<br /> There are a few libraries that can handle colors for you, so you don't have to muck with UserMessages:<br /> <br /> ===exvel's Colors===<br /> This is a simple include file, allowing easy control over chat coloring. You can grab it [http://forums.alliedmods.net/showthread.php?t=96831 on the forums]. Instead of hex codes, colors are denoted with tags, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{default}&lt;/tt&gt;&lt;/span&gt;, &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;, or &lt;span style=&quot;color: #00F;&quot;&gt;&lt;tt&gt;{blue}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> Here's some example usage. Note that this code assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;colors&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> CPrintToChatAll(&quot;{green}Hello {red}World! {default}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> CPrintToChatAllEx(client_on_blu_team, &quot;{teamcolor}BLU team {default}says {green}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> Note that to use a team color, there needs to be at least one player on that team. Otherwise, it will default to &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> ===SMLib===<br /> [http://forums.alliedmods.net/showthread.php?p=1398699 SMLib] is a huge collection of stock functions to keep plug-in developers from reinventing the wheel. It includes a [http://forums.alliedmods.net/showthread.php?p=1398702#post1398702 colors API] very similar to [[#exvel's Colors|exvel's]]. The benefits of SMLib are it supports shorthand color names, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{N}&lt;/tt&gt;&lt;/span&gt; and &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{G}&lt;/tt&gt;&lt;/span&gt;, and all colors are supported in its &lt;tt&gt;Client_PrintToChat()&lt;/tt&gt; function.<br /> <br /> Here's how to print the same thing as the above example with SMLib. Note that this code also assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;smlib&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> Client_PrintToChatAll(&quot;{G}Hello {R}World! {N}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> Client_PrintToChatAll(client_on_blu_team, &quot;{T}BLU team {N}says {G}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> =Why do I get an &quot;unknown symbol&quot; error when using an SDKTools native?=<br /> None of SourceMod's or SDKTools's functions are built into SourcePawn. Therefore, every time you use one of their functions, SourcePawn needs to know how to call the function. Normally, this is done using includes. Just like you would #include &lt;sourcemod&gt; to use SourceMod's functions, you need to:<br /> &lt;pawn&gt;#include &lt;sdktools&gt;&lt;/pawn&gt;<br /> to use an SDKTools native.<br /> <br /> =Why is Source telling me my command is an &quot;Unknown command&quot;?=<br /> This is because you're not returning &lt;tt&gt;Plugin_Handled&lt;/tt&gt; in your callback. If you don't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so.<br /> <br /> &lt;pawn&gt;public Action:MyCommand(client, args)<br /> {<br /> // Do something...<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Scripting_FAQ_(SourceMod)&diff=10113 2016-02-16T21:16:17Z

<p>Xerox8521: /* Where can I find all the SourcePawn functions and other information? */</p> <hr /> <div>[[Image:Yak.gif]]<br /> yak wuz heer<br /> <br /> =How do I learn SourcePawn?=<br /> A good start is on the [[Introduction_to_SourcePawn_1.7]] page, which will teach you the SourcePawn language. Then go through the [[Introduction to SourceMod Plugins]], which will teach you how to write your first plug-in.<br /> <br /> =Where can I find all the SourcePawn functions and other information?=<br /> All SourceMod plug-ins have this line:<br /> <br /> &lt;pawn&gt;#include &lt;sourcemod&gt;&lt;/pawn&gt;<br /> <br /> This line instructs the compiler to retrieve the file &lt;tt&gt;sourcemod.inc&lt;/tt&gt; from the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder. Every function, variable, and definition can be found in the &lt;tt&gt;.inc&lt;/tt&gt; files inside the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder.<br /> <br /> But searching through all those files can be quite tedious. Thankfully, the honourable [https://forums.alliedmods.net/member.php?u=9443 Nican] created an API reference viewable on the web, complete with searching and commenting: [https://sm.alliedmods.net/new-api/ https://sm.alliedmods.net/new-api/]<br /> <br /> Also, if you are in the SourceMod IRC channel ([irc://irc.gamesurge.net/sourcemod #sourcemod on GameSurge]), you can use the &lt;tt&gt;!api&lt;/tt&gt; command to search [https://forums.alliedmods.net/member.php?u=9443 Nican's] API reference:<br /> &lt;pre&gt;&lt;theY4Kman&gt; !api Netclass<br /> &lt;yakbot&gt; theY4Kman: bool GetEntityNetClass(int edict, char[] clsname, int maxlength): Retrieves an entity's networkable serverclass name. This is not the same as the classname and is used for networkable state changes. (https://sm.alliedmods.net/new-api/entity/GetEntityNetClass)&lt;/pre&gt;<br /> <br /> =How do I find the classname of an entity? (e.g., &quot;&lt;tt&gt;weapon_knife&lt;/tt&gt;&quot; or &quot;&lt;tt&gt;prop_physics&lt;/tt&gt;&quot;)=<br /> The classname of an entity (not to be confused with a netclass such as &lt;tt&gt;CCSPlayer&lt;/tt&gt;) is a unique identifier. It's the most well known of entity names. To find it, use the function [https://sm.alliedmods.net/new-api/entity/GetEdictClassname GetEdictClassname()]:<br /> <br /> &lt;pawn&gt;char classname[128];<br /> GetEdictClassname(myentity, classname, sizeof(classname));<br /> <br /> PrintToServer(&quot;myentity classname: %s&quot;, classname);<br /> // myentity classname: weapon_knife&lt;/pawn&gt;<br /> <br /> =How do I block regular commands, such as &lt;tt&gt;kill&lt;/tt&gt; and &lt;tt&gt;say&lt;/tt&gt;?=<br /> As of version 1.3, the recommended way to hook and block commands is with [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()]. Previously, using [https://sm.alliedmods.net/new-api/console/RegConsoleCmd RegConsoleCmd()] with the command name was the only way to hook commands, but this creates a whole new command for the command dispatch to check every time any command is executed. [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] creates only a lightweight hook, processed only when the specific command is executed.<br /> <br /> Here's how to use it to block the &lt;tt&gt;say&lt;/tt&gt; command:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> AddCommandListener(SayCallback, &quot;say&quot;);<br /> }<br /> <br /> public Action SayCallback(int client, const char[] command, int argc)<br /> {<br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I hook +commands, such as &lt;tt&gt;+zoom&lt;/tt&gt; and &lt;tt&gt;+attack&lt;/tt&gt;?=<br /> Unlike regular commands, &lt;tt&gt;+commands&lt;/tt&gt; are handled on the client's computer, then sent to the server in a more compressed fashion. This means [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] cannot be used to hook &lt;tt&gt;+commands&lt;/tt&gt;. As of version 1.3, the recommended solution is to use the global forward [https://sm.alliedmods.net/new-api/sdktools_hooks/OnPlayerRunCmd OnPlayerRunCmd()]. This forward is fired every time a player uses a movement button. To detect or block a &lt;tt&gt;+command&lt;/tt&gt;, you'll first have to find out its proper &lt;tt&gt;IN_&lt;/tt&gt; constant (see &lt;tt&gt;[https://sm.alliedmods.net/new-api/entity_prop_stocks/__raw entity_prop_stocks.inc]&lt;/tt&gt;).<br /> <br /> Here's how to use it to block crouching when attacking:<br /> <br /> &lt;pawn&gt;public Action OnPlayerRunCmd(int client, int &amp;buttons, int &amp;impulse, float vel[3], float angles[3], int &amp;weapon)<br /> {<br /> // Check if the player is attacking (+attack)<br /> if ((buttons &amp; IN_ATTACK) == IN_ATTACK)<br /> {<br /> // If so, block their crouching (+duck)<br /> buttons &amp;= ~IN_DUCK;<br /> }<br /> <br /> // We must return Plugin_Continue to let the changes be processed.<br /> // Otherwise, we can return Plugin_Handled to block the commands<br /> return Plugin_Continue;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of loose indentation warnings?=<br /> &lt;pre&gt;myplugin.sp(#) : warning 217: loose indentation&lt;/pre&gt;<br /> <br /> Loose indentation warnings arise when indentation in your code is inconsistent. This usually means using both tabs and spaces as indentation. However, it can also mean a different amount of spaces or tabs are being used. Therefore, to correct it, use just one type of indentation. Because different editors have different settings for the size of tab stops, it is recommended you use 4 spaces to indent.<br /> <br /> Good:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> int myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> Bad:<br /> <br /> &lt;pawn&gt;public voidOnPluginStart()<br /> {<br /> int myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of tag mismatch warnings?=<br /> Though every variable in SourcePawn is one cell (4 bytes), with the exception of strings, there are many different ways to interpret what's inside a cell. To signify a cell's contents, tags are used. The most common are &lt;tt&gt;_&lt;/tt&gt; (the default tag: a vanilla cell. This tag is implied when no other tag is specified.), &lt;tt&gt;Float&lt;/tt&gt;, &lt;tt&gt;bool&lt;/tt&gt;, and &lt;tt&gt;String&lt;/tt&gt;. See [[Introduction to SourcePawn#Variables_2]] for more information.<br /> <br /> Functions wear these tags on their parameters so you can tell what needs to be passed to the function:<br /> &lt;pawn&gt;native SetEntPropFloat(entity, PropType:type, const String:prop[], Float:value);&lt;/pawn&gt;<br /> <br /> This function calls for '''&lt;tt&gt;entity&lt;/tt&gt;''', a cell with the implied tag '''''&lt;tt&gt;_&lt;/tt&gt;'''''; '''&lt;tt&gt;type&lt;/tt&gt;''', with the developer-defined tag '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; '''&lt;tt&gt;prop&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;String&lt;/tt&gt;'''''; and '''&lt;tt&gt;value&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;Float&lt;/tt&gt;'''''.<br /> To call this function, then, you must pass values with the specified tags. For example:<br /> &lt;pawn&gt;SetEntPropFloat(1234, Prop_Send, &quot;m_fNumber&quot;, 1.0);&lt;/pawn&gt;<br /> <br /> This calls the function correctly: &lt;tt&gt;1234&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''), &lt;tt&gt;Prop_Send&lt;/tt&gt; is a variable defined in the enum '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [http://docs.sourcemod.net/api/index.php?fastload=file&amp;id=4&amp;file=&amp; entity.inc], &lt;tt&gt;&quot;m_fNumber&quot;&lt;/tt&gt; is a '''''&lt;tt&gt;String&lt;/tt&gt;''''', and &lt;tt&gt;1.0&lt;/tt&gt; is a '''''&lt;tt&gt;Float&lt;/tt&gt;'''''. For a nonexample:<br /> &lt;pawn&gt;SetEntPropFloat(1234.0, 1, &quot;m_fNumber&quot;, 1337);&lt;/pawn&gt;<br /> <br /> This is incorrect! &lt;tt&gt;1234.0&lt;/tt&gt; is a '''''&lt;tt&gt;Float&lt;/tt&gt;''''' that should be a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''); &lt;tt&gt;1&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; and &lt;tt&gt;1337&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;Float&lt;/tt&gt;'''''. This call will generate a tag mismatch warning. To correct it, simply use a value with the correct tag. Most of the time, tags that are not built-in (such as '''''&lt;tt&gt;PropType&lt;/tt&gt;''''') can be found in the same file where a function uses them (you can find '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [http://docs.sourcemod.net/api/index.php?fastload=file&amp;id=4&amp;file=&amp; entity.inc]).<br /> <br /> =How do I add color to my messages?=<br /> Though the actual colors will vary depending on the mod, you can add color to any chat message using the characters &lt;tt&gt;0x01&lt;/tt&gt; to &lt;tt&gt;0x08&lt;/tt&gt;. For example:<br /> &lt;pawn&gt;PrintToChatAll (&quot;\x01 1 .. \x02 2 .. \x03 3 .. \x04 4 .. \x05 5 .. \x06 6 .. \x07 7 .. \x08 8&quot;);&lt;/pawn&gt;<br /> <br /> Example output from Left 4 Dead:<br /> <br /> [[Image:Left_4_Dead_Colors.png]]<br /> <br /> With a little experimenting, you can learn the colors for a mod. However, the meaning behind the colors is generally as follows:<br /> <br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x01&lt;/tt&gt; = Normal color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x02&lt;/tt&gt; = Use team color to the end of a player's name. When used, it can be the only color used, and it must be at the start of the message.<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x03&lt;/tt&gt; = Team color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x04&lt;/tt&gt; = Location color<br /> <br /> This data comes from Counter-Strike: Source.<br /> <br /> For CS:GO, here are some colors:<br /> &lt;pawn&gt;PrintToChat(&quot;\x011\x022\x033\x044\x055\x066\x077\x088\x099\x0AA\x0BB\x0CC\x0DD\x0EE\x0FF&quot;);&lt;/pawn&gt;<br /> <br /> Unfortunately, to use players' team colors, you must use UserMessages, because there is no way for the current SourceMod functions to know which team color to use. Here's an example:<br /> <br /> &lt;pawn&gt;new Handle:hBf;<br /> hBf = StartMessageOne(&quot;SayText2&quot;, player_to); // To send the message to all players, use StartMessageAll(&quot;SayText2&quot;);<br /> if (hBf != INVALID_HANDLE)<br /> {<br /> BfWriteByte(hBf, player_from); <br /> BfWriteByte(hBf, 0); <br /> BfWriteString(hBf, &quot;&lt;\x03player_from team color\x01&gt; My message&quot;);<br /> EndMessage();<br /> }&lt;/pawn&gt;<br /> <br /> &lt;tt&gt;player_to&lt;/tt&gt; is the client index to send the message to (or use [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=132&amp; StartMessageAll()] instead of [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=133&amp; StartMessageOne()] to send the message to all players). &lt;tt&gt;player_from&lt;/tt&gt; is the client index of the player whose team color will be utilized in the message. The message will now look like this (assuming &lt;tt&gt;player_from&lt;/tt&gt; is on the RED team):<br /> <br /> &lt;span style=&quot;color:#AA0&quot;&gt;&amp;lt;&lt;/span&gt;&lt;span style=&quot;color:#F00&quot;&gt;player_from team color&lt;/span&gt;&lt;span style=&quot;color:#AA0&quot;&gt;&amp;gt; My message&lt;/span&gt;<br /> <br /> There's another catch, however: this is only known to work in CS:S and TF2. For other mods, your mileage may vary.<br /> <br /> ==Color Libraries==<br /> There are a few libraries that can handle colors for you, so you don't have to muck with UserMessages:<br /> <br /> ===exvel's Colors===<br /> This is a simple include file, allowing easy control over chat coloring. You can grab it [http://forums.alliedmods.net/showthread.php?t=96831 on the forums]. Instead of hex codes, colors are denoted with tags, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{default}&lt;/tt&gt;&lt;/span&gt;, &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;, or &lt;span style=&quot;color: #00F;&quot;&gt;&lt;tt&gt;{blue}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> Here's some example usage. Note that this code assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;colors&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> CPrintToChatAll(&quot;{green}Hello {red}World! {default}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> CPrintToChatAllEx(client_on_blu_team, &quot;{teamcolor}BLU team {default}says {green}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> Note that to use a team color, there needs to be at least one player on that team. Otherwise, it will default to &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> ===SMLib===<br /> [http://forums.alliedmods.net/showthread.php?p=1398699 SMLib] is a huge collection of stock functions to keep plug-in developers from reinventing the wheel. It includes a [http://forums.alliedmods.net/showthread.php?p=1398702#post1398702 colors API] very similar to [[#exvel's Colors|exvel's]]. The benefits of SMLib are it supports shorthand color names, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{N}&lt;/tt&gt;&lt;/span&gt; and &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{G}&lt;/tt&gt;&lt;/span&gt;, and all colors are supported in its &lt;tt&gt;Client_PrintToChat()&lt;/tt&gt; function.<br /> <br /> Here's how to print the same thing as the above example with SMLib. Note that this code also assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;smlib&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> Client_PrintToChatAll(&quot;{G}Hello {R}World! {N}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> Client_PrintToChatAll(client_on_blu_team, &quot;{T}BLU team {N}says {G}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> =Why do I get an &quot;unknown symbol&quot; error when using an SDKTools native?=<br /> None of SourceMod's or SDKTools's functions are built into SourcePawn. Therefore, every time you use one of their functions, SourcePawn needs to know how to call the function. Normally, this is done using includes. Just like you would #include &lt;sourcemod&gt; to use SourceMod's functions, you need to:<br /> &lt;pawn&gt;#include &lt;sdktools&gt;&lt;/pawn&gt;<br /> to use an SDKTools native.<br /> <br /> =Why is Source telling me my command is an &quot;Unknown command&quot;?=<br /> This is because you're not returning &lt;tt&gt;Plugin_Handled&lt;/tt&gt; in your callback. If you don't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so.<br /> <br /> &lt;pawn&gt;public Action:MyCommand(client, args)<br /> {<br /> // Do something...<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Scripting_FAQ_(SourceMod)&diff=10112 2016-02-16T21:14:34Z

<p>Xerox8521: /* How do I learn SourcePawn? */</p> <hr /> <div>[[Image:Yak.gif]]<br /> yak wuz heer<br /> <br /> =How do I learn SourcePawn?=<br /> A good start is on the [[Introduction_to_SourcePawn_1.7]] page, which will teach you the SourcePawn language. Then go through the [[Introduction to SourceMod Plugins]], which will teach you how to write your first plug-in.<br /> <br /> =Where can I find all the SourcePawn functions and other information?=<br /> All SourceMod plug-ins have this line:<br /> <br /> &lt;pawn&gt;#include &lt;sourcemod&gt;&lt;/pawn&gt;<br /> <br /> This line instructs the compiler to retrieve the file &lt;tt&gt;sourcemod.inc&lt;/tt&gt; from the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder. Every function, variable, and definition can be found in the &lt;tt&gt;.inc&lt;/tt&gt; files inside the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder.<br /> <br /> But searching through all those files can be quite tedious. Thankfully, the honourable [https://forums.alliedmods.net/member.php?u=9443 Nican] created an API reference viewable on the web, complete with searching and commenting: [http://docs.sourcemod.net/api/ http://docs.sourcemod.net/api/]<br /> <br /> Also, if you are in the SourceMod IRC channel ([irc://irc.gamesurge.net/sourcemod #sourcemod on GameSurge]), you can use the &lt;tt&gt;!api&lt;/tt&gt; command to search [https://forums.alliedmods.net/member.php?u=9443 Nican's] API reference:<br /> &lt;pre&gt;&lt;theY4Kman&gt; !api Netclass<br /> &lt;yakbot&gt; theY4Kman: GetEntityNetClass(edict, String:clsname[], maxlength): Retrieves an entity's networkable serverclass name. This is not the same as the classname and is used for networkable state changes. (http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=66)&lt;/pre&gt;<br /> <br /> =How do I find the classname of an entity? (e.g., &quot;&lt;tt&gt;weapon_knife&lt;/tt&gt;&quot; or &quot;&lt;tt&gt;prop_physics&lt;/tt&gt;&quot;)=<br /> The classname of an entity (not to be confused with a netclass such as &lt;tt&gt;CCSPlayer&lt;/tt&gt;) is a unique identifier. It's the most well known of entity names. To find it, use the function [https://sm.alliedmods.net/new-api/entity/GetEdictClassname GetEdictClassname()]:<br /> <br /> &lt;pawn&gt;char classname[128];<br /> GetEdictClassname(myentity, classname, sizeof(classname));<br /> <br /> PrintToServer(&quot;myentity classname: %s&quot;, classname);<br /> // myentity classname: weapon_knife&lt;/pawn&gt;<br /> <br /> =How do I block regular commands, such as &lt;tt&gt;kill&lt;/tt&gt; and &lt;tt&gt;say&lt;/tt&gt;?=<br /> As of version 1.3, the recommended way to hook and block commands is with [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()]. Previously, using [https://sm.alliedmods.net/new-api/console/RegConsoleCmd RegConsoleCmd()] with the command name was the only way to hook commands, but this creates a whole new command for the command dispatch to check every time any command is executed. [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] creates only a lightweight hook, processed only when the specific command is executed.<br /> <br /> Here's how to use it to block the &lt;tt&gt;say&lt;/tt&gt; command:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> AddCommandListener(SayCallback, &quot;say&quot;);<br /> }<br /> <br /> public Action SayCallback(int client, const char[] command, int argc)<br /> {<br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I hook +commands, such as &lt;tt&gt;+zoom&lt;/tt&gt; and &lt;tt&gt;+attack&lt;/tt&gt;?=<br /> Unlike regular commands, &lt;tt&gt;+commands&lt;/tt&gt; are handled on the client's computer, then sent to the server in a more compressed fashion. This means [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] cannot be used to hook &lt;tt&gt;+commands&lt;/tt&gt;. As of version 1.3, the recommended solution is to use the global forward [https://sm.alliedmods.net/new-api/sdktools_hooks/OnPlayerRunCmd OnPlayerRunCmd()]. This forward is fired every time a player uses a movement button. To detect or block a &lt;tt&gt;+command&lt;/tt&gt;, you'll first have to find out its proper &lt;tt&gt;IN_&lt;/tt&gt; constant (see &lt;tt&gt;[https://sm.alliedmods.net/new-api/entity_prop_stocks/__raw entity_prop_stocks.inc]&lt;/tt&gt;).<br /> <br /> Here's how to use it to block crouching when attacking:<br /> <br /> &lt;pawn&gt;public Action OnPlayerRunCmd(int client, int &amp;buttons, int &amp;impulse, float vel[3], float angles[3], int &amp;weapon)<br /> {<br /> // Check if the player is attacking (+attack)<br /> if ((buttons &amp; IN_ATTACK) == IN_ATTACK)<br /> {<br /> // If so, block their crouching (+duck)<br /> buttons &amp;= ~IN_DUCK;<br /> }<br /> <br /> // We must return Plugin_Continue to let the changes be processed.<br /> // Otherwise, we can return Plugin_Handled to block the commands<br /> return Plugin_Continue;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of loose indentation warnings?=<br /> &lt;pre&gt;myplugin.sp(#) : warning 217: loose indentation&lt;/pre&gt;<br /> <br /> Loose indentation warnings arise when indentation in your code is inconsistent. This usually means using both tabs and spaces as indentation. However, it can also mean a different amount of spaces or tabs are being used. Therefore, to correct it, use just one type of indentation. Because different editors have different settings for the size of tab stops, it is recommended you use 4 spaces to indent.<br /> <br /> Good:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> int myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> Bad:<br /> <br /> &lt;pawn&gt;public voidOnPluginStart()<br /> {<br /> int myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of tag mismatch warnings?=<br /> Though every variable in SourcePawn is one cell (4 bytes), with the exception of strings, there are many different ways to interpret what's inside a cell. To signify a cell's contents, tags are used. The most common are &lt;tt&gt;_&lt;/tt&gt; (the default tag: a vanilla cell. This tag is implied when no other tag is specified.), &lt;tt&gt;Float&lt;/tt&gt;, &lt;tt&gt;bool&lt;/tt&gt;, and &lt;tt&gt;String&lt;/tt&gt;. See [[Introduction to SourcePawn#Variables_2]] for more information.<br /> <br /> Functions wear these tags on their parameters so you can tell what needs to be passed to the function:<br /> &lt;pawn&gt;native SetEntPropFloat(entity, PropType:type, const String:prop[], Float:value);&lt;/pawn&gt;<br /> <br /> This function calls for '''&lt;tt&gt;entity&lt;/tt&gt;''', a cell with the implied tag '''''&lt;tt&gt;_&lt;/tt&gt;'''''; '''&lt;tt&gt;type&lt;/tt&gt;''', with the developer-defined tag '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; '''&lt;tt&gt;prop&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;String&lt;/tt&gt;'''''; and '''&lt;tt&gt;value&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;Float&lt;/tt&gt;'''''.<br /> To call this function, then, you must pass values with the specified tags. For example:<br /> &lt;pawn&gt;SetEntPropFloat(1234, Prop_Send, &quot;m_fNumber&quot;, 1.0);&lt;/pawn&gt;<br /> <br /> This calls the function correctly: &lt;tt&gt;1234&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''), &lt;tt&gt;Prop_Send&lt;/tt&gt; is a variable defined in the enum '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [http://docs.sourcemod.net/api/index.php?fastload=file&amp;id=4&amp;file=&amp; entity.inc], &lt;tt&gt;&quot;m_fNumber&quot;&lt;/tt&gt; is a '''''&lt;tt&gt;String&lt;/tt&gt;''''', and &lt;tt&gt;1.0&lt;/tt&gt; is a '''''&lt;tt&gt;Float&lt;/tt&gt;'''''. For a nonexample:<br /> &lt;pawn&gt;SetEntPropFloat(1234.0, 1, &quot;m_fNumber&quot;, 1337);&lt;/pawn&gt;<br /> <br /> This is incorrect! &lt;tt&gt;1234.0&lt;/tt&gt; is a '''''&lt;tt&gt;Float&lt;/tt&gt;''''' that should be a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''); &lt;tt&gt;1&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; and &lt;tt&gt;1337&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;Float&lt;/tt&gt;'''''. This call will generate a tag mismatch warning. To correct it, simply use a value with the correct tag. Most of the time, tags that are not built-in (such as '''''&lt;tt&gt;PropType&lt;/tt&gt;''''') can be found in the same file where a function uses them (you can find '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [http://docs.sourcemod.net/api/index.php?fastload=file&amp;id=4&amp;file=&amp; entity.inc]).<br /> <br /> =How do I add color to my messages?=<br /> Though the actual colors will vary depending on the mod, you can add color to any chat message using the characters &lt;tt&gt;0x01&lt;/tt&gt; to &lt;tt&gt;0x08&lt;/tt&gt;. For example:<br /> &lt;pawn&gt;PrintToChatAll (&quot;\x01 1 .. \x02 2 .. \x03 3 .. \x04 4 .. \x05 5 .. \x06 6 .. \x07 7 .. \x08 8&quot;);&lt;/pawn&gt;<br /> <br /> Example output from Left 4 Dead:<br /> <br /> [[Image:Left_4_Dead_Colors.png]]<br /> <br /> With a little experimenting, you can learn the colors for a mod. However, the meaning behind the colors is generally as follows:<br /> <br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x01&lt;/tt&gt; = Normal color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x02&lt;/tt&gt; = Use team color to the end of a player's name. When used, it can be the only color used, and it must be at the start of the message.<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x03&lt;/tt&gt; = Team color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x04&lt;/tt&gt; = Location color<br /> <br /> This data comes from Counter-Strike: Source.<br /> <br /> For CS:GO, here are some colors:<br /> &lt;pawn&gt;PrintToChat(&quot;\x011\x022\x033\x044\x055\x066\x077\x088\x099\x0AA\x0BB\x0CC\x0DD\x0EE\x0FF&quot;);&lt;/pawn&gt;<br /> <br /> Unfortunately, to use players' team colors, you must use UserMessages, because there is no way for the current SourceMod functions to know which team color to use. Here's an example:<br /> <br /> &lt;pawn&gt;new Handle:hBf;<br /> hBf = StartMessageOne(&quot;SayText2&quot;, player_to); // To send the message to all players, use StartMessageAll(&quot;SayText2&quot;);<br /> if (hBf != INVALID_HANDLE)<br /> {<br /> BfWriteByte(hBf, player_from); <br /> BfWriteByte(hBf, 0); <br /> BfWriteString(hBf, &quot;&lt;\x03player_from team color\x01&gt; My message&quot;);<br /> EndMessage();<br /> }&lt;/pawn&gt;<br /> <br /> &lt;tt&gt;player_to&lt;/tt&gt; is the client index to send the message to (or use [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=132&amp; StartMessageAll()] instead of [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=133&amp; StartMessageOne()] to send the message to all players). &lt;tt&gt;player_from&lt;/tt&gt; is the client index of the player whose team color will be utilized in the message. The message will now look like this (assuming &lt;tt&gt;player_from&lt;/tt&gt; is on the RED team):<br /> <br /> &lt;span style=&quot;color:#AA0&quot;&gt;&amp;lt;&lt;/span&gt;&lt;span style=&quot;color:#F00&quot;&gt;player_from team color&lt;/span&gt;&lt;span style=&quot;color:#AA0&quot;&gt;&amp;gt; My message&lt;/span&gt;<br /> <br /> There's another catch, however: this is only known to work in CS:S and TF2. For other mods, your mileage may vary.<br /> <br /> ==Color Libraries==<br /> There are a few libraries that can handle colors for you, so you don't have to muck with UserMessages:<br /> <br /> ===exvel's Colors===<br /> This is a simple include file, allowing easy control over chat coloring. You can grab it [http://forums.alliedmods.net/showthread.php?t=96831 on the forums]. Instead of hex codes, colors are denoted with tags, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{default}&lt;/tt&gt;&lt;/span&gt;, &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;, or &lt;span style=&quot;color: #00F;&quot;&gt;&lt;tt&gt;{blue}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> Here's some example usage. Note that this code assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;colors&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> CPrintToChatAll(&quot;{green}Hello {red}World! {default}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> CPrintToChatAllEx(client_on_blu_team, &quot;{teamcolor}BLU team {default}says {green}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> Note that to use a team color, there needs to be at least one player on that team. Otherwise, it will default to &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> ===SMLib===<br /> [http://forums.alliedmods.net/showthread.php?p=1398699 SMLib] is a huge collection of stock functions to keep plug-in developers from reinventing the wheel. It includes a [http://forums.alliedmods.net/showthread.php?p=1398702#post1398702 colors API] very similar to [[#exvel's Colors|exvel's]]. The benefits of SMLib are it supports shorthand color names, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{N}&lt;/tt&gt;&lt;/span&gt; and &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{G}&lt;/tt&gt;&lt;/span&gt;, and all colors are supported in its &lt;tt&gt;Client_PrintToChat()&lt;/tt&gt; function.<br /> <br /> Here's how to print the same thing as the above example with SMLib. Note that this code also assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;smlib&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> Client_PrintToChatAll(&quot;{G}Hello {R}World! {N}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> Client_PrintToChatAll(client_on_blu_team, &quot;{T}BLU team {N}says {G}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> =Why do I get an &quot;unknown symbol&quot; error when using an SDKTools native?=<br /> None of SourceMod's or SDKTools's functions are built into SourcePawn. Therefore, every time you use one of their functions, SourcePawn needs to know how to call the function. Normally, this is done using includes. Just like you would #include &lt;sourcemod&gt; to use SourceMod's functions, you need to:<br /> &lt;pawn&gt;#include &lt;sdktools&gt;&lt;/pawn&gt;<br /> to use an SDKTools native.<br /> <br /> =Why is Source telling me my command is an &quot;Unknown command&quot;?=<br /> This is because you're not returning &lt;tt&gt;Plugin_Handled&lt;/tt&gt; in your callback. If you don't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so.<br /> <br /> &lt;pawn&gt;public Action:MyCommand(client, args)<br /> {<br /> // Do something...<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Scripting_FAQ_(SourceMod)&diff=10111 2016-02-16T21:06:21Z

<p>Xerox8521: /* How do I get rid of loose indentation warnings? */</p> <hr /> <div>[[Image:Yak.gif]]<br /> yak wuz heer<br /> <br /> =How do I learn SourcePawn?=<br /> A good start is on the [[Introduction to SourcePawn]] page, which will teach you the SourcePawn language. Then go through the [[Introduction to SourceMod Plugins]], which will teach you how to write your first plug-in.<br /> <br /> =Where can I find all the SourcePawn functions and other information?=<br /> All SourceMod plug-ins have this line:<br /> <br /> &lt;pawn&gt;#include &lt;sourcemod&gt;&lt;/pawn&gt;<br /> <br /> This line instructs the compiler to retrieve the file &lt;tt&gt;sourcemod.inc&lt;/tt&gt; from the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder. Every function, variable, and definition can be found in the &lt;tt&gt;.inc&lt;/tt&gt; files inside the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder.<br /> <br /> But searching through all those files can be quite tedious. Thankfully, the honourable [https://forums.alliedmods.net/member.php?u=9443 Nican] created an API reference viewable on the web, complete with searching and commenting: [http://docs.sourcemod.net/api/ http://docs.sourcemod.net/api/]<br /> <br /> Also, if you are in the SourceMod IRC channel ([irc://irc.gamesurge.net/sourcemod #sourcemod on GameSurge]), you can use the &lt;tt&gt;!api&lt;/tt&gt; command to search [https://forums.alliedmods.net/member.php?u=9443 Nican's] API reference:<br /> &lt;pre&gt;&lt;theY4Kman&gt; !api Netclass<br /> &lt;yakbot&gt; theY4Kman: GetEntityNetClass(edict, String:clsname[], maxlength): Retrieves an entity's networkable serverclass name. This is not the same as the classname and is used for networkable state changes. (http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=66)&lt;/pre&gt;<br /> <br /> =How do I find the classname of an entity? (e.g., &quot;&lt;tt&gt;weapon_knife&lt;/tt&gt;&quot; or &quot;&lt;tt&gt;prop_physics&lt;/tt&gt;&quot;)=<br /> The classname of an entity (not to be confused with a netclass such as &lt;tt&gt;CCSPlayer&lt;/tt&gt;) is a unique identifier. It's the most well known of entity names. To find it, use the function [https://sm.alliedmods.net/new-api/entity/GetEdictClassname GetEdictClassname()]:<br /> <br /> &lt;pawn&gt;char classname[128];<br /> GetEdictClassname(myentity, classname, sizeof(classname));<br /> <br /> PrintToServer(&quot;myentity classname: %s&quot;, classname);<br /> // myentity classname: weapon_knife&lt;/pawn&gt;<br /> <br /> =How do I block regular commands, such as &lt;tt&gt;kill&lt;/tt&gt; and &lt;tt&gt;say&lt;/tt&gt;?=<br /> As of version 1.3, the recommended way to hook and block commands is with [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()]. Previously, using [https://sm.alliedmods.net/new-api/console/RegConsoleCmd RegConsoleCmd()] with the command name was the only way to hook commands, but this creates a whole new command for the command dispatch to check every time any command is executed. [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] creates only a lightweight hook, processed only when the specific command is executed.<br /> <br /> Here's how to use it to block the &lt;tt&gt;say&lt;/tt&gt; command:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> AddCommandListener(SayCallback, &quot;say&quot;);<br /> }<br /> <br /> public Action SayCallback(int client, const char[] command, int argc)<br /> {<br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I hook +commands, such as &lt;tt&gt;+zoom&lt;/tt&gt; and &lt;tt&gt;+attack&lt;/tt&gt;?=<br /> Unlike regular commands, &lt;tt&gt;+commands&lt;/tt&gt; are handled on the client's computer, then sent to the server in a more compressed fashion. This means [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] cannot be used to hook &lt;tt&gt;+commands&lt;/tt&gt;. As of version 1.3, the recommended solution is to use the global forward [https://sm.alliedmods.net/new-api/sdktools_hooks/OnPlayerRunCmd OnPlayerRunCmd()]. This forward is fired every time a player uses a movement button. To detect or block a &lt;tt&gt;+command&lt;/tt&gt;, you'll first have to find out its proper &lt;tt&gt;IN_&lt;/tt&gt; constant (see &lt;tt&gt;[https://sm.alliedmods.net/new-api/entity_prop_stocks/__raw entity_prop_stocks.inc]&lt;/tt&gt;).<br /> <br /> Here's how to use it to block crouching when attacking:<br /> <br /> &lt;pawn&gt;public Action OnPlayerRunCmd(int client, int &amp;buttons, int &amp;impulse, float vel[3], float angles[3], int &amp;weapon)<br /> {<br /> // Check if the player is attacking (+attack)<br /> if ((buttons &amp; IN_ATTACK) == IN_ATTACK)<br /> {<br /> // If so, block their crouching (+duck)<br /> buttons &amp;= ~IN_DUCK;<br /> }<br /> <br /> // We must return Plugin_Continue to let the changes be processed.<br /> // Otherwise, we can return Plugin_Handled to block the commands<br /> return Plugin_Continue;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of loose indentation warnings?=<br /> &lt;pre&gt;myplugin.sp(#) : warning 217: loose indentation&lt;/pre&gt;<br /> <br /> Loose indentation warnings arise when indentation in your code is inconsistent. This usually means using both tabs and spaces as indentation. However, it can also mean a different amount of spaces or tabs are being used. Therefore, to correct it, use just one type of indentation. Because different editors have different settings for the size of tab stops, it is recommended you use 4 spaces to indent.<br /> <br /> Good:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> int myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> Bad:<br /> <br /> &lt;pawn&gt;public voidOnPluginStart()<br /> {<br /> int myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of tag mismatch warnings?=<br /> Though every variable in SourcePawn is one cell (4 bytes), with the exception of strings, there are many different ways to interpret what's inside a cell. To signify a cell's contents, tags are used. The most common are &lt;tt&gt;_&lt;/tt&gt; (the default tag: a vanilla cell. This tag is implied when no other tag is specified.), &lt;tt&gt;Float&lt;/tt&gt;, &lt;tt&gt;bool&lt;/tt&gt;, and &lt;tt&gt;String&lt;/tt&gt;. See [[Introduction to SourcePawn#Variables_2]] for more information.<br /> <br /> Functions wear these tags on their parameters so you can tell what needs to be passed to the function:<br /> &lt;pawn&gt;native SetEntPropFloat(entity, PropType:type, const String:prop[], Float:value);&lt;/pawn&gt;<br /> <br /> This function calls for '''&lt;tt&gt;entity&lt;/tt&gt;''', a cell with the implied tag '''''&lt;tt&gt;_&lt;/tt&gt;'''''; '''&lt;tt&gt;type&lt;/tt&gt;''', with the developer-defined tag '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; '''&lt;tt&gt;prop&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;String&lt;/tt&gt;'''''; and '''&lt;tt&gt;value&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;Float&lt;/tt&gt;'''''.<br /> To call this function, then, you must pass values with the specified tags. For example:<br /> &lt;pawn&gt;SetEntPropFloat(1234, Prop_Send, &quot;m_fNumber&quot;, 1.0);&lt;/pawn&gt;<br /> <br /> This calls the function correctly: &lt;tt&gt;1234&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''), &lt;tt&gt;Prop_Send&lt;/tt&gt; is a variable defined in the enum '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [http://docs.sourcemod.net/api/index.php?fastload=file&amp;id=4&amp;file=&amp; entity.inc], &lt;tt&gt;&quot;m_fNumber&quot;&lt;/tt&gt; is a '''''&lt;tt&gt;String&lt;/tt&gt;''''', and &lt;tt&gt;1.0&lt;/tt&gt; is a '''''&lt;tt&gt;Float&lt;/tt&gt;'''''. For a nonexample:<br /> &lt;pawn&gt;SetEntPropFloat(1234.0, 1, &quot;m_fNumber&quot;, 1337);&lt;/pawn&gt;<br /> <br /> This is incorrect! &lt;tt&gt;1234.0&lt;/tt&gt; is a '''''&lt;tt&gt;Float&lt;/tt&gt;''''' that should be a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''); &lt;tt&gt;1&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; and &lt;tt&gt;1337&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;Float&lt;/tt&gt;'''''. This call will generate a tag mismatch warning. To correct it, simply use a value with the correct tag. Most of the time, tags that are not built-in (such as '''''&lt;tt&gt;PropType&lt;/tt&gt;''''') can be found in the same file where a function uses them (you can find '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [http://docs.sourcemod.net/api/index.php?fastload=file&amp;id=4&amp;file=&amp; entity.inc]).<br /> <br /> =How do I add color to my messages?=<br /> Though the actual colors will vary depending on the mod, you can add color to any chat message using the characters &lt;tt&gt;0x01&lt;/tt&gt; to &lt;tt&gt;0x08&lt;/tt&gt;. For example:<br /> &lt;pawn&gt;PrintToChatAll (&quot;\x01 1 .. \x02 2 .. \x03 3 .. \x04 4 .. \x05 5 .. \x06 6 .. \x07 7 .. \x08 8&quot;);&lt;/pawn&gt;<br /> <br /> Example output from Left 4 Dead:<br /> <br /> [[Image:Left_4_Dead_Colors.png]]<br /> <br /> With a little experimenting, you can learn the colors for a mod. However, the meaning behind the colors is generally as follows:<br /> <br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x01&lt;/tt&gt; = Normal color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x02&lt;/tt&gt; = Use team color to the end of a player's name. When used, it can be the only color used, and it must be at the start of the message.<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x03&lt;/tt&gt; = Team color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x04&lt;/tt&gt; = Location color<br /> <br /> This data comes from Counter-Strike: Source.<br /> <br /> For CS:GO, here are some colors:<br /> &lt;pawn&gt;PrintToChat(&quot;\x011\x022\x033\x044\x055\x066\x077\x088\x099\x0AA\x0BB\x0CC\x0DD\x0EE\x0FF&quot;);&lt;/pawn&gt;<br /> <br /> Unfortunately, to use players' team colors, you must use UserMessages, because there is no way for the current SourceMod functions to know which team color to use. Here's an example:<br /> <br /> &lt;pawn&gt;new Handle:hBf;<br /> hBf = StartMessageOne(&quot;SayText2&quot;, player_to); // To send the message to all players, use StartMessageAll(&quot;SayText2&quot;);<br /> if (hBf != INVALID_HANDLE)<br /> {<br /> BfWriteByte(hBf, player_from); <br /> BfWriteByte(hBf, 0); <br /> BfWriteString(hBf, &quot;&lt;\x03player_from team color\x01&gt; My message&quot;);<br /> EndMessage();<br /> }&lt;/pawn&gt;<br /> <br /> &lt;tt&gt;player_to&lt;/tt&gt; is the client index to send the message to (or use [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=132&amp; StartMessageAll()] instead of [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=133&amp; StartMessageOne()] to send the message to all players). &lt;tt&gt;player_from&lt;/tt&gt; is the client index of the player whose team color will be utilized in the message. The message will now look like this (assuming &lt;tt&gt;player_from&lt;/tt&gt; is on the RED team):<br /> <br /> &lt;span style=&quot;color:#AA0&quot;&gt;&amp;lt;&lt;/span&gt;&lt;span style=&quot;color:#F00&quot;&gt;player_from team color&lt;/span&gt;&lt;span style=&quot;color:#AA0&quot;&gt;&amp;gt; My message&lt;/span&gt;<br /> <br /> There's another catch, however: this is only known to work in CS:S and TF2. For other mods, your mileage may vary.<br /> <br /> ==Color Libraries==<br /> There are a few libraries that can handle colors for you, so you don't have to muck with UserMessages:<br /> <br /> ===exvel's Colors===<br /> This is a simple include file, allowing easy control over chat coloring. You can grab it [http://forums.alliedmods.net/showthread.php?t=96831 on the forums]. Instead of hex codes, colors are denoted with tags, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{default}&lt;/tt&gt;&lt;/span&gt;, &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;, or &lt;span style=&quot;color: #00F;&quot;&gt;&lt;tt&gt;{blue}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> Here's some example usage. Note that this code assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;colors&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> CPrintToChatAll(&quot;{green}Hello {red}World! {default}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> CPrintToChatAllEx(client_on_blu_team, &quot;{teamcolor}BLU team {default}says {green}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> Note that to use a team color, there needs to be at least one player on that team. Otherwise, it will default to &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> ===SMLib===<br /> [http://forums.alliedmods.net/showthread.php?p=1398699 SMLib] is a huge collection of stock functions to keep plug-in developers from reinventing the wheel. It includes a [http://forums.alliedmods.net/showthread.php?p=1398702#post1398702 colors API] very similar to [[#exvel's Colors|exvel's]]. The benefits of SMLib are it supports shorthand color names, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{N}&lt;/tt&gt;&lt;/span&gt; and &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{G}&lt;/tt&gt;&lt;/span&gt;, and all colors are supported in its &lt;tt&gt;Client_PrintToChat()&lt;/tt&gt; function.<br /> <br /> Here's how to print the same thing as the above example with SMLib. Note that this code also assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;smlib&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> Client_PrintToChatAll(&quot;{G}Hello {R}World! {N}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> Client_PrintToChatAll(client_on_blu_team, &quot;{T}BLU team {N}says {G}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> =Why do I get an &quot;unknown symbol&quot; error when using an SDKTools native?=<br /> None of SourceMod's or SDKTools's functions are built into SourcePawn. Therefore, every time you use one of their functions, SourcePawn needs to know how to call the function. Normally, this is done using includes. Just like you would #include &lt;sourcemod&gt; to use SourceMod's functions, you need to:<br /> &lt;pawn&gt;#include &lt;sdktools&gt;&lt;/pawn&gt;<br /> to use an SDKTools native.<br /> <br /> =Why is Source telling me my command is an &quot;Unknown command&quot;?=<br /> This is because you're not returning &lt;tt&gt;Plugin_Handled&lt;/tt&gt; in your callback. If you don't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so.<br /> <br /> &lt;pawn&gt;public Action:MyCommand(client, args)<br /> {<br /> // Do something...<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Scripting_FAQ_(SourceMod)&diff=10110 2016-02-16T21:05:43Z

<p>Xerox8521: /* How do I hook +commands, such as +zoom and +attack? */</p> <hr /> <div>[[Image:Yak.gif]]<br /> yak wuz heer<br /> <br /> =How do I learn SourcePawn?=<br /> A good start is on the [[Introduction to SourcePawn]] page, which will teach you the SourcePawn language. Then go through the [[Introduction to SourceMod Plugins]], which will teach you how to write your first plug-in.<br /> <br /> =Where can I find all the SourcePawn functions and other information?=<br /> All SourceMod plug-ins have this line:<br /> <br /> &lt;pawn&gt;#include &lt;sourcemod&gt;&lt;/pawn&gt;<br /> <br /> This line instructs the compiler to retrieve the file &lt;tt&gt;sourcemod.inc&lt;/tt&gt; from the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder. Every function, variable, and definition can be found in the &lt;tt&gt;.inc&lt;/tt&gt; files inside the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder.<br /> <br /> But searching through all those files can be quite tedious. Thankfully, the honourable [https://forums.alliedmods.net/member.php?u=9443 Nican] created an API reference viewable on the web, complete with searching and commenting: [http://docs.sourcemod.net/api/ http://docs.sourcemod.net/api/]<br /> <br /> Also, if you are in the SourceMod IRC channel ([irc://irc.gamesurge.net/sourcemod #sourcemod on GameSurge]), you can use the &lt;tt&gt;!api&lt;/tt&gt; command to search [https://forums.alliedmods.net/member.php?u=9443 Nican's] API reference:<br /> &lt;pre&gt;&lt;theY4Kman&gt; !api Netclass<br /> &lt;yakbot&gt; theY4Kman: GetEntityNetClass(edict, String:clsname[], maxlength): Retrieves an entity's networkable serverclass name. This is not the same as the classname and is used for networkable state changes. (http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=66)&lt;/pre&gt;<br /> <br /> =How do I find the classname of an entity? (e.g., &quot;&lt;tt&gt;weapon_knife&lt;/tt&gt;&quot; or &quot;&lt;tt&gt;prop_physics&lt;/tt&gt;&quot;)=<br /> The classname of an entity (not to be confused with a netclass such as &lt;tt&gt;CCSPlayer&lt;/tt&gt;) is a unique identifier. It's the most well known of entity names. To find it, use the function [https://sm.alliedmods.net/new-api/entity/GetEdictClassname GetEdictClassname()]:<br /> <br /> &lt;pawn&gt;char classname[128];<br /> GetEdictClassname(myentity, classname, sizeof(classname));<br /> <br /> PrintToServer(&quot;myentity classname: %s&quot;, classname);<br /> // myentity classname: weapon_knife&lt;/pawn&gt;<br /> <br /> =How do I block regular commands, such as &lt;tt&gt;kill&lt;/tt&gt; and &lt;tt&gt;say&lt;/tt&gt;?=<br /> As of version 1.3, the recommended way to hook and block commands is with [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()]. Previously, using [https://sm.alliedmods.net/new-api/console/RegConsoleCmd RegConsoleCmd()] with the command name was the only way to hook commands, but this creates a whole new command for the command dispatch to check every time any command is executed. [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] creates only a lightweight hook, processed only when the specific command is executed.<br /> <br /> Here's how to use it to block the &lt;tt&gt;say&lt;/tt&gt; command:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> AddCommandListener(SayCallback, &quot;say&quot;);<br /> }<br /> <br /> public Action SayCallback(int client, const char[] command, int argc)<br /> {<br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I hook +commands, such as &lt;tt&gt;+zoom&lt;/tt&gt; and &lt;tt&gt;+attack&lt;/tt&gt;?=<br /> Unlike regular commands, &lt;tt&gt;+commands&lt;/tt&gt; are handled on the client's computer, then sent to the server in a more compressed fashion. This means [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] cannot be used to hook &lt;tt&gt;+commands&lt;/tt&gt;. As of version 1.3, the recommended solution is to use the global forward [https://sm.alliedmods.net/new-api/sdktools_hooks/OnPlayerRunCmd OnPlayerRunCmd()]. This forward is fired every time a player uses a movement button. To detect or block a &lt;tt&gt;+command&lt;/tt&gt;, you'll first have to find out its proper &lt;tt&gt;IN_&lt;/tt&gt; constant (see &lt;tt&gt;[https://sm.alliedmods.net/new-api/entity_prop_stocks/__raw entity_prop_stocks.inc]&lt;/tt&gt;).<br /> <br /> Here's how to use it to block crouching when attacking:<br /> <br /> &lt;pawn&gt;public Action OnPlayerRunCmd(int client, int &amp;buttons, int &amp;impulse, float vel[3], float angles[3], int &amp;weapon)<br /> {<br /> // Check if the player is attacking (+attack)<br /> if ((buttons &amp; IN_ATTACK) == IN_ATTACK)<br /> {<br /> // If so, block their crouching (+duck)<br /> buttons &amp;= ~IN_DUCK;<br /> }<br /> <br /> // We must return Plugin_Continue to let the changes be processed.<br /> // Otherwise, we can return Plugin_Handled to block the commands<br /> return Plugin_Continue;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of loose indentation warnings?=<br /> &lt;pre&gt;myplugin.sp(#) : warning 217: loose indentation&lt;/pre&gt;<br /> <br /> Loose indentation warnings arise when indentation in your code is inconsistent. This usually means using both tabs and spaces as indentation. However, it can also mean a different amount of spaces or tabs are being used. Therefore, to correct it, use just one type of indentation. Because different editors have different settings for the size of tab stops, it is recommended you use 4 spaces to indent.<br /> <br /> Good:<br /> <br /> &lt;pawn&gt;public OnPluginStart()<br /> {<br /> new myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> Bad:<br /> <br /> &lt;pawn&gt;public OnPluginStart()<br /> {<br /> new myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of tag mismatch warnings?=<br /> Though every variable in SourcePawn is one cell (4 bytes), with the exception of strings, there are many different ways to interpret what's inside a cell. To signify a cell's contents, tags are used. The most common are &lt;tt&gt;_&lt;/tt&gt; (the default tag: a vanilla cell. This tag is implied when no other tag is specified.), &lt;tt&gt;Float&lt;/tt&gt;, &lt;tt&gt;bool&lt;/tt&gt;, and &lt;tt&gt;String&lt;/tt&gt;. See [[Introduction to SourcePawn#Variables_2]] for more information.<br /> <br /> Functions wear these tags on their parameters so you can tell what needs to be passed to the function:<br /> &lt;pawn&gt;native SetEntPropFloat(entity, PropType:type, const String:prop[], Float:value);&lt;/pawn&gt;<br /> <br /> This function calls for '''&lt;tt&gt;entity&lt;/tt&gt;''', a cell with the implied tag '''''&lt;tt&gt;_&lt;/tt&gt;'''''; '''&lt;tt&gt;type&lt;/tt&gt;''', with the developer-defined tag '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; '''&lt;tt&gt;prop&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;String&lt;/tt&gt;'''''; and '''&lt;tt&gt;value&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;Float&lt;/tt&gt;'''''.<br /> To call this function, then, you must pass values with the specified tags. For example:<br /> &lt;pawn&gt;SetEntPropFloat(1234, Prop_Send, &quot;m_fNumber&quot;, 1.0);&lt;/pawn&gt;<br /> <br /> This calls the function correctly: &lt;tt&gt;1234&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''), &lt;tt&gt;Prop_Send&lt;/tt&gt; is a variable defined in the enum '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [http://docs.sourcemod.net/api/index.php?fastload=file&amp;id=4&amp;file=&amp; entity.inc], &lt;tt&gt;&quot;m_fNumber&quot;&lt;/tt&gt; is a '''''&lt;tt&gt;String&lt;/tt&gt;''''', and &lt;tt&gt;1.0&lt;/tt&gt; is a '''''&lt;tt&gt;Float&lt;/tt&gt;'''''. For a nonexample:<br /> &lt;pawn&gt;SetEntPropFloat(1234.0, 1, &quot;m_fNumber&quot;, 1337);&lt;/pawn&gt;<br /> <br /> This is incorrect! &lt;tt&gt;1234.0&lt;/tt&gt; is a '''''&lt;tt&gt;Float&lt;/tt&gt;''''' that should be a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''); &lt;tt&gt;1&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; and &lt;tt&gt;1337&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;Float&lt;/tt&gt;'''''. This call will generate a tag mismatch warning. To correct it, simply use a value with the correct tag. Most of the time, tags that are not built-in (such as '''''&lt;tt&gt;PropType&lt;/tt&gt;''''') can be found in the same file where a function uses them (you can find '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [http://docs.sourcemod.net/api/index.php?fastload=file&amp;id=4&amp;file=&amp; entity.inc]).<br /> <br /> =How do I add color to my messages?=<br /> Though the actual colors will vary depending on the mod, you can add color to any chat message using the characters &lt;tt&gt;0x01&lt;/tt&gt; to &lt;tt&gt;0x08&lt;/tt&gt;. For example:<br /> &lt;pawn&gt;PrintToChatAll (&quot;\x01 1 .. \x02 2 .. \x03 3 .. \x04 4 .. \x05 5 .. \x06 6 .. \x07 7 .. \x08 8&quot;);&lt;/pawn&gt;<br /> <br /> Example output from Left 4 Dead:<br /> <br /> [[Image:Left_4_Dead_Colors.png]]<br /> <br /> With a little experimenting, you can learn the colors for a mod. However, the meaning behind the colors is generally as follows:<br /> <br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x01&lt;/tt&gt; = Normal color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x02&lt;/tt&gt; = Use team color to the end of a player's name. When used, it can be the only color used, and it must be at the start of the message.<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x03&lt;/tt&gt; = Team color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x04&lt;/tt&gt; = Location color<br /> <br /> This data comes from Counter-Strike: Source.<br /> <br /> For CS:GO, here are some colors:<br /> &lt;pawn&gt;PrintToChat(&quot;\x011\x022\x033\x044\x055\x066\x077\x088\x099\x0AA\x0BB\x0CC\x0DD\x0EE\x0FF&quot;);&lt;/pawn&gt;<br /> <br /> Unfortunately, to use players' team colors, you must use UserMessages, because there is no way for the current SourceMod functions to know which team color to use. Here's an example:<br /> <br /> &lt;pawn&gt;new Handle:hBf;<br /> hBf = StartMessageOne(&quot;SayText2&quot;, player_to); // To send the message to all players, use StartMessageAll(&quot;SayText2&quot;);<br /> if (hBf != INVALID_HANDLE)<br /> {<br /> BfWriteByte(hBf, player_from); <br /> BfWriteByte(hBf, 0); <br /> BfWriteString(hBf, &quot;&lt;\x03player_from team color\x01&gt; My message&quot;);<br /> EndMessage();<br /> }&lt;/pawn&gt;<br /> <br /> &lt;tt&gt;player_to&lt;/tt&gt; is the client index to send the message to (or use [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=132&amp; StartMessageAll()] instead of [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=133&amp; StartMessageOne()] to send the message to all players). &lt;tt&gt;player_from&lt;/tt&gt; is the client index of the player whose team color will be utilized in the message. The message will now look like this (assuming &lt;tt&gt;player_from&lt;/tt&gt; is on the RED team):<br /> <br /> &lt;span style=&quot;color:#AA0&quot;&gt;&amp;lt;&lt;/span&gt;&lt;span style=&quot;color:#F00&quot;&gt;player_from team color&lt;/span&gt;&lt;span style=&quot;color:#AA0&quot;&gt;&amp;gt; My message&lt;/span&gt;<br /> <br /> There's another catch, however: this is only known to work in CS:S and TF2. For other mods, your mileage may vary.<br /> <br /> ==Color Libraries==<br /> There are a few libraries that can handle colors for you, so you don't have to muck with UserMessages:<br /> <br /> ===exvel's Colors===<br /> This is a simple include file, allowing easy control over chat coloring. You can grab it [http://forums.alliedmods.net/showthread.php?t=96831 on the forums]. Instead of hex codes, colors are denoted with tags, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{default}&lt;/tt&gt;&lt;/span&gt;, &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;, or &lt;span style=&quot;color: #00F;&quot;&gt;&lt;tt&gt;{blue}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> Here's some example usage. Note that this code assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;colors&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> CPrintToChatAll(&quot;{green}Hello {red}World! {default}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> CPrintToChatAllEx(client_on_blu_team, &quot;{teamcolor}BLU team {default}says {green}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> Note that to use a team color, there needs to be at least one player on that team. Otherwise, it will default to &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> ===SMLib===<br /> [http://forums.alliedmods.net/showthread.php?p=1398699 SMLib] is a huge collection of stock functions to keep plug-in developers from reinventing the wheel. It includes a [http://forums.alliedmods.net/showthread.php?p=1398702#post1398702 colors API] very similar to [[#exvel's Colors|exvel's]]. The benefits of SMLib are it supports shorthand color names, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{N}&lt;/tt&gt;&lt;/span&gt; and &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{G}&lt;/tt&gt;&lt;/span&gt;, and all colors are supported in its &lt;tt&gt;Client_PrintToChat()&lt;/tt&gt; function.<br /> <br /> Here's how to print the same thing as the above example with SMLib. Note that this code also assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;smlib&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> Client_PrintToChatAll(&quot;{G}Hello {R}World! {N}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> Client_PrintToChatAll(client_on_blu_team, &quot;{T}BLU team {N}says {G}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> =Why do I get an &quot;unknown symbol&quot; error when using an SDKTools native?=<br /> None of SourceMod's or SDKTools's functions are built into SourcePawn. Therefore, every time you use one of their functions, SourcePawn needs to know how to call the function. Normally, this is done using includes. Just like you would #include &lt;sourcemod&gt; to use SourceMod's functions, you need to:<br /> &lt;pawn&gt;#include &lt;sdktools&gt;&lt;/pawn&gt;<br /> to use an SDKTools native.<br /> <br /> =Why is Source telling me my command is an &quot;Unknown command&quot;?=<br /> This is because you're not returning &lt;tt&gt;Plugin_Handled&lt;/tt&gt; in your callback. If you don't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so.<br /> <br /> &lt;pawn&gt;public Action:MyCommand(client, args)<br /> {<br /> // Do something...<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Scripting_FAQ_(SourceMod)&diff=10109 2016-02-16T21:01:22Z

<p>Xerox8521: /* How do I block regular commands, such as kill and say? */</p> <hr /> <div>[[Image:Yak.gif]]<br /> yak wuz heer<br /> <br /> =How do I learn SourcePawn?=<br /> A good start is on the [[Introduction to SourcePawn]] page, which will teach you the SourcePawn language. Then go through the [[Introduction to SourceMod Plugins]], which will teach you how to write your first plug-in.<br /> <br /> =Where can I find all the SourcePawn functions and other information?=<br /> All SourceMod plug-ins have this line:<br /> <br /> &lt;pawn&gt;#include &lt;sourcemod&gt;&lt;/pawn&gt;<br /> <br /> This line instructs the compiler to retrieve the file &lt;tt&gt;sourcemod.inc&lt;/tt&gt; from the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder. Every function, variable, and definition can be found in the &lt;tt&gt;.inc&lt;/tt&gt; files inside the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder.<br /> <br /> But searching through all those files can be quite tedious. Thankfully, the honourable [https://forums.alliedmods.net/member.php?u=9443 Nican] created an API reference viewable on the web, complete with searching and commenting: [http://docs.sourcemod.net/api/ http://docs.sourcemod.net/api/]<br /> <br /> Also, if you are in the SourceMod IRC channel ([irc://irc.gamesurge.net/sourcemod #sourcemod on GameSurge]), you can use the &lt;tt&gt;!api&lt;/tt&gt; command to search [https://forums.alliedmods.net/member.php?u=9443 Nican's] API reference:<br /> &lt;pre&gt;&lt;theY4Kman&gt; !api Netclass<br /> &lt;yakbot&gt; theY4Kman: GetEntityNetClass(edict, String:clsname[], maxlength): Retrieves an entity's networkable serverclass name. This is not the same as the classname and is used for networkable state changes. (http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=66)&lt;/pre&gt;<br /> <br /> =How do I find the classname of an entity? (e.g., &quot;&lt;tt&gt;weapon_knife&lt;/tt&gt;&quot; or &quot;&lt;tt&gt;prop_physics&lt;/tt&gt;&quot;)=<br /> The classname of an entity (not to be confused with a netclass such as &lt;tt&gt;CCSPlayer&lt;/tt&gt;) is a unique identifier. It's the most well known of entity names. To find it, use the function [https://sm.alliedmods.net/new-api/entity/GetEdictClassname GetEdictClassname()]:<br /> <br /> &lt;pawn&gt;char classname[128];<br /> GetEdictClassname(myentity, classname, sizeof(classname));<br /> <br /> PrintToServer(&quot;myentity classname: %s&quot;, classname);<br /> // myentity classname: weapon_knife&lt;/pawn&gt;<br /> <br /> =How do I block regular commands, such as &lt;tt&gt;kill&lt;/tt&gt; and &lt;tt&gt;say&lt;/tt&gt;?=<br /> As of version 1.3, the recommended way to hook and block commands is with [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()]. Previously, using [https://sm.alliedmods.net/new-api/console/RegConsoleCmd RegConsoleCmd()] with the command name was the only way to hook commands, but this creates a whole new command for the command dispatch to check every time any command is executed. [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] creates only a lightweight hook, processed only when the specific command is executed.<br /> <br /> Here's how to use it to block the &lt;tt&gt;say&lt;/tt&gt; command:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> AddCommandListener(SayCallback, &quot;say&quot;);<br /> }<br /> <br /> public Action SayCallback(int client, const char[] command, int argc)<br /> {<br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I hook +commands, such as &lt;tt&gt;+zoom&lt;/tt&gt; and &lt;tt&gt;+attack&lt;/tt&gt;?=<br /> Unlike regular commands, &lt;tt&gt;+commands&lt;/tt&gt; are handled on the client's computer, then sent to the server in a more compressed fashion. This means [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=949 AddCommandListener()] cannot be used to hook &lt;tt&gt;+commands&lt;/tt&gt;. As of version 1.3, the recommended solution is to use the global forward [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=937 OnPlayerRunCmd()]. This forward is fired every time a player uses a movement button. To detect or block a &lt;tt&gt;+command&lt;/tt&gt;, you'll first have to find out its proper &lt;tt&gt;IN_&lt;/tt&gt; constant (see &lt;tt&gt;[http://docs.sourcemod.net/api/index.php?fastload=file&amp;id=47&amp;file=&amp; entity_prop_stocks.inc]&lt;/tt&gt;).<br /> <br /> Here's how to use it to block crouching when attacking:<br /> <br /> &lt;pawn&gt;public Action:OnPlayerRunCmd(client, &amp;buttons, &amp;impulse, Float:vel[3], Float:angles[3], &amp;weapon)<br /> {<br /> // Check if the player is attacking (+attack)<br /> if ((buttons &amp; IN_ATTACK) == IN_ATTACK)<br /> {<br /> // If so, block their crouching (+duck)<br /> buttons &amp;= ~IN_DUCK;<br /> }<br /> <br /> // We must return Plugin_Continue to let the changes be processed.<br /> // Otherwise, we can return Plugin_Handled to block the commands<br /> return Plugin_Continue;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of loose indentation warnings?=<br /> &lt;pre&gt;myplugin.sp(#) : warning 217: loose indentation&lt;/pre&gt;<br /> <br /> Loose indentation warnings arise when indentation in your code is inconsistent. This usually means using both tabs and spaces as indentation. However, it can also mean a different amount of spaces or tabs are being used. Therefore, to correct it, use just one type of indentation. Because different editors have different settings for the size of tab stops, it is recommended you use 4 spaces to indent.<br /> <br /> Good:<br /> <br /> &lt;pawn&gt;public OnPluginStart()<br /> {<br /> new myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> Bad:<br /> <br /> &lt;pawn&gt;public OnPluginStart()<br /> {<br /> new myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of tag mismatch warnings?=<br /> Though every variable in SourcePawn is one cell (4 bytes), with the exception of strings, there are many different ways to interpret what's inside a cell. To signify a cell's contents, tags are used. The most common are &lt;tt&gt;_&lt;/tt&gt; (the default tag: a vanilla cell. This tag is implied when no other tag is specified.), &lt;tt&gt;Float&lt;/tt&gt;, &lt;tt&gt;bool&lt;/tt&gt;, and &lt;tt&gt;String&lt;/tt&gt;. See [[Introduction to SourcePawn#Variables_2]] for more information.<br /> <br /> Functions wear these tags on their parameters so you can tell what needs to be passed to the function:<br /> &lt;pawn&gt;native SetEntPropFloat(entity, PropType:type, const String:prop[], Float:value);&lt;/pawn&gt;<br /> <br /> This function calls for '''&lt;tt&gt;entity&lt;/tt&gt;''', a cell with the implied tag '''''&lt;tt&gt;_&lt;/tt&gt;'''''; '''&lt;tt&gt;type&lt;/tt&gt;''', with the developer-defined tag '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; '''&lt;tt&gt;prop&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;String&lt;/tt&gt;'''''; and '''&lt;tt&gt;value&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;Float&lt;/tt&gt;'''''.<br /> To call this function, then, you must pass values with the specified tags. For example:<br /> &lt;pawn&gt;SetEntPropFloat(1234, Prop_Send, &quot;m_fNumber&quot;, 1.0);&lt;/pawn&gt;<br /> <br /> This calls the function correctly: &lt;tt&gt;1234&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''), &lt;tt&gt;Prop_Send&lt;/tt&gt; is a variable defined in the enum '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [http://docs.sourcemod.net/api/index.php?fastload=file&amp;id=4&amp;file=&amp; entity.inc], &lt;tt&gt;&quot;m_fNumber&quot;&lt;/tt&gt; is a '''''&lt;tt&gt;String&lt;/tt&gt;''''', and &lt;tt&gt;1.0&lt;/tt&gt; is a '''''&lt;tt&gt;Float&lt;/tt&gt;'''''. For a nonexample:<br /> &lt;pawn&gt;SetEntPropFloat(1234.0, 1, &quot;m_fNumber&quot;, 1337);&lt;/pawn&gt;<br /> <br /> This is incorrect! &lt;tt&gt;1234.0&lt;/tt&gt; is a '''''&lt;tt&gt;Float&lt;/tt&gt;''''' that should be a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''); &lt;tt&gt;1&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; and &lt;tt&gt;1337&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;Float&lt;/tt&gt;'''''. This call will generate a tag mismatch warning. To correct it, simply use a value with the correct tag. Most of the time, tags that are not built-in (such as '''''&lt;tt&gt;PropType&lt;/tt&gt;''''') can be found in the same file where a function uses them (you can find '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [http://docs.sourcemod.net/api/index.php?fastload=file&amp;id=4&amp;file=&amp; entity.inc]).<br /> <br /> =How do I add color to my messages?=<br /> Though the actual colors will vary depending on the mod, you can add color to any chat message using the characters &lt;tt&gt;0x01&lt;/tt&gt; to &lt;tt&gt;0x08&lt;/tt&gt;. For example:<br /> &lt;pawn&gt;PrintToChatAll (&quot;\x01 1 .. \x02 2 .. \x03 3 .. \x04 4 .. \x05 5 .. \x06 6 .. \x07 7 .. \x08 8&quot;);&lt;/pawn&gt;<br /> <br /> Example output from Left 4 Dead:<br /> <br /> [[Image:Left_4_Dead_Colors.png]]<br /> <br /> With a little experimenting, you can learn the colors for a mod. However, the meaning behind the colors is generally as follows:<br /> <br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x01&lt;/tt&gt; = Normal color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x02&lt;/tt&gt; = Use team color to the end of a player's name. When used, it can be the only color used, and it must be at the start of the message.<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x03&lt;/tt&gt; = Team color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x04&lt;/tt&gt; = Location color<br /> <br /> This data comes from Counter-Strike: Source.<br /> <br /> For CS:GO, here are some colors:<br /> &lt;pawn&gt;PrintToChat(&quot;\x011\x022\x033\x044\x055\x066\x077\x088\x099\x0AA\x0BB\x0CC\x0DD\x0EE\x0FF&quot;);&lt;/pawn&gt;<br /> <br /> Unfortunately, to use players' team colors, you must use UserMessages, because there is no way for the current SourceMod functions to know which team color to use. Here's an example:<br /> <br /> &lt;pawn&gt;new Handle:hBf;<br /> hBf = StartMessageOne(&quot;SayText2&quot;, player_to); // To send the message to all players, use StartMessageAll(&quot;SayText2&quot;);<br /> if (hBf != INVALID_HANDLE)<br /> {<br /> BfWriteByte(hBf, player_from); <br /> BfWriteByte(hBf, 0); <br /> BfWriteString(hBf, &quot;&lt;\x03player_from team color\x01&gt; My message&quot;);<br /> EndMessage();<br /> }&lt;/pawn&gt;<br /> <br /> &lt;tt&gt;player_to&lt;/tt&gt; is the client index to send the message to (or use [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=132&amp; StartMessageAll()] instead of [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=133&amp; StartMessageOne()] to send the message to all players). &lt;tt&gt;player_from&lt;/tt&gt; is the client index of the player whose team color will be utilized in the message. The message will now look like this (assuming &lt;tt&gt;player_from&lt;/tt&gt; is on the RED team):<br /> <br /> &lt;span style=&quot;color:#AA0&quot;&gt;&amp;lt;&lt;/span&gt;&lt;span style=&quot;color:#F00&quot;&gt;player_from team color&lt;/span&gt;&lt;span style=&quot;color:#AA0&quot;&gt;&amp;gt; My message&lt;/span&gt;<br /> <br /> There's another catch, however: this is only known to work in CS:S and TF2. For other mods, your mileage may vary.<br /> <br /> ==Color Libraries==<br /> There are a few libraries that can handle colors for you, so you don't have to muck with UserMessages:<br /> <br /> ===exvel's Colors===<br /> This is a simple include file, allowing easy control over chat coloring. You can grab it [http://forums.alliedmods.net/showthread.php?t=96831 on the forums]. Instead of hex codes, colors are denoted with tags, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{default}&lt;/tt&gt;&lt;/span&gt;, &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;, or &lt;span style=&quot;color: #00F;&quot;&gt;&lt;tt&gt;{blue}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> Here's some example usage. Note that this code assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;colors&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> CPrintToChatAll(&quot;{green}Hello {red}World! {default}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> CPrintToChatAllEx(client_on_blu_team, &quot;{teamcolor}BLU team {default}says {green}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> Note that to use a team color, there needs to be at least one player on that team. Otherwise, it will default to &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> ===SMLib===<br /> [http://forums.alliedmods.net/showthread.php?p=1398699 SMLib] is a huge collection of stock functions to keep plug-in developers from reinventing the wheel. It includes a [http://forums.alliedmods.net/showthread.php?p=1398702#post1398702 colors API] very similar to [[#exvel's Colors|exvel's]]. The benefits of SMLib are it supports shorthand color names, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{N}&lt;/tt&gt;&lt;/span&gt; and &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{G}&lt;/tt&gt;&lt;/span&gt;, and all colors are supported in its &lt;tt&gt;Client_PrintToChat()&lt;/tt&gt; function.<br /> <br /> Here's how to print the same thing as the above example with SMLib. Note that this code also assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;smlib&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> Client_PrintToChatAll(&quot;{G}Hello {R}World! {N}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> Client_PrintToChatAll(client_on_blu_team, &quot;{T}BLU team {N}says {G}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> =Why do I get an &quot;unknown symbol&quot; error when using an SDKTools native?=<br /> None of SourceMod's or SDKTools's functions are built into SourcePawn. Therefore, every time you use one of their functions, SourcePawn needs to know how to call the function. Normally, this is done using includes. Just like you would #include &lt;sourcemod&gt; to use SourceMod's functions, you need to:<br /> &lt;pawn&gt;#include &lt;sdktools&gt;&lt;/pawn&gt;<br /> to use an SDKTools native.<br /> <br /> =Why is Source telling me my command is an &quot;Unknown command&quot;?=<br /> This is because you're not returning &lt;tt&gt;Plugin_Handled&lt;/tt&gt; in your callback. If you don't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so.<br /> <br /> &lt;pawn&gt;public Action:MyCommand(client, args)<br /> {<br /> // Do something...<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Scripting_FAQ_(SourceMod)&diff=10108 2016-02-16T21:01:02Z

<p>Xerox8521: /* How do I block regular commands, such as kill and say? */</p> <hr /> <div>[[Image:Yak.gif]]<br /> yak wuz heer<br /> <br /> =How do I learn SourcePawn?=<br /> A good start is on the [[Introduction to SourcePawn]] page, which will teach you the SourcePawn language. Then go through the [[Introduction to SourceMod Plugins]], which will teach you how to write your first plug-in.<br /> <br /> =Where can I find all the SourcePawn functions and other information?=<br /> All SourceMod plug-ins have this line:<br /> <br /> &lt;pawn&gt;#include &lt;sourcemod&gt;&lt;/pawn&gt;<br /> <br /> This line instructs the compiler to retrieve the file &lt;tt&gt;sourcemod.inc&lt;/tt&gt; from the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder. Every function, variable, and definition can be found in the &lt;tt&gt;.inc&lt;/tt&gt; files inside the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder.<br /> <br /> But searching through all those files can be quite tedious. Thankfully, the honourable [https://forums.alliedmods.net/member.php?u=9443 Nican] created an API reference viewable on the web, complete with searching and commenting: [http://docs.sourcemod.net/api/ http://docs.sourcemod.net/api/]<br /> <br /> Also, if you are in the SourceMod IRC channel ([irc://irc.gamesurge.net/sourcemod #sourcemod on GameSurge]), you can use the &lt;tt&gt;!api&lt;/tt&gt; command to search [https://forums.alliedmods.net/member.php?u=9443 Nican's] API reference:<br /> &lt;pre&gt;&lt;theY4Kman&gt; !api Netclass<br /> &lt;yakbot&gt; theY4Kman: GetEntityNetClass(edict, String:clsname[], maxlength): Retrieves an entity's networkable serverclass name. This is not the same as the classname and is used for networkable state changes. (http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=66)&lt;/pre&gt;<br /> <br /> =How do I find the classname of an entity? (e.g., &quot;&lt;tt&gt;weapon_knife&lt;/tt&gt;&quot; or &quot;&lt;tt&gt;prop_physics&lt;/tt&gt;&quot;)=<br /> The classname of an entity (not to be confused with a netclass such as &lt;tt&gt;CCSPlayer&lt;/tt&gt;) is a unique identifier. It's the most well known of entity names. To find it, use the function [https://sm.alliedmods.net/new-api/entity/GetEdictClassname GetEdictClassname()]:<br /> <br /> &lt;pawn&gt;char classname[128];<br /> GetEdictClassname(myentity, classname, sizeof(classname));<br /> <br /> PrintToServer(&quot;myentity classname: %s&quot;, classname);<br /> // myentity classname: weapon_knife&lt;/pawn&gt;<br /> <br /> =How do I block regular commands, such as &lt;tt&gt;kill&lt;/tt&gt; and &lt;tt&gt;say&lt;/tt&gt;?=<br /> As of version 1.3, the recommended way to hook and block commands is with [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=949 AddCommandListener()]. Previously, using [https://sm.alliedmods.net/new-api/console/RegConsoleCmd RegConsoleCmd()] with the command name was the only way to hook commands, but this creates a whole new command for the command dispatch to check every time any command is executed. [https://sm.alliedmods.net/new-api/console/AddCommandListener AddCommandListener()] creates only a lightweight hook, processed only when the specific command is executed.<br /> <br /> Here's how to use it to block the &lt;tt&gt;say&lt;/tt&gt; command:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> AddCommandListener(SayCallback, &quot;say&quot;);<br /> }<br /> <br /> public Action SayCallback(int client, const char[] command, int argc)<br /> {<br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I hook +commands, such as &lt;tt&gt;+zoom&lt;/tt&gt; and &lt;tt&gt;+attack&lt;/tt&gt;?=<br /> Unlike regular commands, &lt;tt&gt;+commands&lt;/tt&gt; are handled on the client's computer, then sent to the server in a more compressed fashion. This means [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=949 AddCommandListener()] cannot be used to hook &lt;tt&gt;+commands&lt;/tt&gt;. As of version 1.3, the recommended solution is to use the global forward [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=937 OnPlayerRunCmd()]. This forward is fired every time a player uses a movement button. To detect or block a &lt;tt&gt;+command&lt;/tt&gt;, you'll first have to find out its proper &lt;tt&gt;IN_&lt;/tt&gt; constant (see &lt;tt&gt;[http://docs.sourcemod.net/api/index.php?fastload=file&amp;id=47&amp;file=&amp; entity_prop_stocks.inc]&lt;/tt&gt;).<br /> <br /> Here's how to use it to block crouching when attacking:<br /> <br /> &lt;pawn&gt;public Action:OnPlayerRunCmd(client, &amp;buttons, &amp;impulse, Float:vel[3], Float:angles[3], &amp;weapon)<br /> {<br /> // Check if the player is attacking (+attack)<br /> if ((buttons &amp; IN_ATTACK) == IN_ATTACK)<br /> {<br /> // If so, block their crouching (+duck)<br /> buttons &amp;= ~IN_DUCK;<br /> }<br /> <br /> // We must return Plugin_Continue to let the changes be processed.<br /> // Otherwise, we can return Plugin_Handled to block the commands<br /> return Plugin_Continue;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of loose indentation warnings?=<br /> &lt;pre&gt;myplugin.sp(#) : warning 217: loose indentation&lt;/pre&gt;<br /> <br /> Loose indentation warnings arise when indentation in your code is inconsistent. This usually means using both tabs and spaces as indentation. However, it can also mean a different amount of spaces or tabs are being used. Therefore, to correct it, use just one type of indentation. Because different editors have different settings for the size of tab stops, it is recommended you use 4 spaces to indent.<br /> <br /> Good:<br /> <br /> &lt;pawn&gt;public OnPluginStart()<br /> {<br /> new myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> Bad:<br /> <br /> &lt;pawn&gt;public OnPluginStart()<br /> {<br /> new myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of tag mismatch warnings?=<br /> Though every variable in SourcePawn is one cell (4 bytes), with the exception of strings, there are many different ways to interpret what's inside a cell. To signify a cell's contents, tags are used. The most common are &lt;tt&gt;_&lt;/tt&gt; (the default tag: a vanilla cell. This tag is implied when no other tag is specified.), &lt;tt&gt;Float&lt;/tt&gt;, &lt;tt&gt;bool&lt;/tt&gt;, and &lt;tt&gt;String&lt;/tt&gt;. See [[Introduction to SourcePawn#Variables_2]] for more information.<br /> <br /> Functions wear these tags on their parameters so you can tell what needs to be passed to the function:<br /> &lt;pawn&gt;native SetEntPropFloat(entity, PropType:type, const String:prop[], Float:value);&lt;/pawn&gt;<br /> <br /> This function calls for '''&lt;tt&gt;entity&lt;/tt&gt;''', a cell with the implied tag '''''&lt;tt&gt;_&lt;/tt&gt;'''''; '''&lt;tt&gt;type&lt;/tt&gt;''', with the developer-defined tag '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; '''&lt;tt&gt;prop&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;String&lt;/tt&gt;'''''; and '''&lt;tt&gt;value&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;Float&lt;/tt&gt;'''''.<br /> To call this function, then, you must pass values with the specified tags. For example:<br /> &lt;pawn&gt;SetEntPropFloat(1234, Prop_Send, &quot;m_fNumber&quot;, 1.0);&lt;/pawn&gt;<br /> <br /> This calls the function correctly: &lt;tt&gt;1234&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''), &lt;tt&gt;Prop_Send&lt;/tt&gt; is a variable defined in the enum '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [http://docs.sourcemod.net/api/index.php?fastload=file&amp;id=4&amp;file=&amp; entity.inc], &lt;tt&gt;&quot;m_fNumber&quot;&lt;/tt&gt; is a '''''&lt;tt&gt;String&lt;/tt&gt;''''', and &lt;tt&gt;1.0&lt;/tt&gt; is a '''''&lt;tt&gt;Float&lt;/tt&gt;'''''. For a nonexample:<br /> &lt;pawn&gt;SetEntPropFloat(1234.0, 1, &quot;m_fNumber&quot;, 1337);&lt;/pawn&gt;<br /> <br /> This is incorrect! &lt;tt&gt;1234.0&lt;/tt&gt; is a '''''&lt;tt&gt;Float&lt;/tt&gt;''''' that should be a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''); &lt;tt&gt;1&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; and &lt;tt&gt;1337&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;Float&lt;/tt&gt;'''''. This call will generate a tag mismatch warning. To correct it, simply use a value with the correct tag. Most of the time, tags that are not built-in (such as '''''&lt;tt&gt;PropType&lt;/tt&gt;''''') can be found in the same file where a function uses them (you can find '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [http://docs.sourcemod.net/api/index.php?fastload=file&amp;id=4&amp;file=&amp; entity.inc]).<br /> <br /> =How do I add color to my messages?=<br /> Though the actual colors will vary depending on the mod, you can add color to any chat message using the characters &lt;tt&gt;0x01&lt;/tt&gt; to &lt;tt&gt;0x08&lt;/tt&gt;. For example:<br /> &lt;pawn&gt;PrintToChatAll (&quot;\x01 1 .. \x02 2 .. \x03 3 .. \x04 4 .. \x05 5 .. \x06 6 .. \x07 7 .. \x08 8&quot;);&lt;/pawn&gt;<br /> <br /> Example output from Left 4 Dead:<br /> <br /> [[Image:Left_4_Dead_Colors.png]]<br /> <br /> With a little experimenting, you can learn the colors for a mod. However, the meaning behind the colors is generally as follows:<br /> <br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x01&lt;/tt&gt; = Normal color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x02&lt;/tt&gt; = Use team color to the end of a player's name. When used, it can be the only color used, and it must be at the start of the message.<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x03&lt;/tt&gt; = Team color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x04&lt;/tt&gt; = Location color<br /> <br /> This data comes from Counter-Strike: Source.<br /> <br /> For CS:GO, here are some colors:<br /> &lt;pawn&gt;PrintToChat(&quot;\x011\x022\x033\x044\x055\x066\x077\x088\x099\x0AA\x0BB\x0CC\x0DD\x0EE\x0FF&quot;);&lt;/pawn&gt;<br /> <br /> Unfortunately, to use players' team colors, you must use UserMessages, because there is no way for the current SourceMod functions to know which team color to use. Here's an example:<br /> <br /> &lt;pawn&gt;new Handle:hBf;<br /> hBf = StartMessageOne(&quot;SayText2&quot;, player_to); // To send the message to all players, use StartMessageAll(&quot;SayText2&quot;);<br /> if (hBf != INVALID_HANDLE)<br /> {<br /> BfWriteByte(hBf, player_from); <br /> BfWriteByte(hBf, 0); <br /> BfWriteString(hBf, &quot;&lt;\x03player_from team color\x01&gt; My message&quot;);<br /> EndMessage();<br /> }&lt;/pawn&gt;<br /> <br /> &lt;tt&gt;player_to&lt;/tt&gt; is the client index to send the message to (or use [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=132&amp; StartMessageAll()] instead of [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=133&amp; StartMessageOne()] to send the message to all players). &lt;tt&gt;player_from&lt;/tt&gt; is the client index of the player whose team color will be utilized in the message. The message will now look like this (assuming &lt;tt&gt;player_from&lt;/tt&gt; is on the RED team):<br /> <br /> &lt;span style=&quot;color:#AA0&quot;&gt;&amp;lt;&lt;/span&gt;&lt;span style=&quot;color:#F00&quot;&gt;player_from team color&lt;/span&gt;&lt;span style=&quot;color:#AA0&quot;&gt;&amp;gt; My message&lt;/span&gt;<br /> <br /> There's another catch, however: this is only known to work in CS:S and TF2. For other mods, your mileage may vary.<br /> <br /> ==Color Libraries==<br /> There are a few libraries that can handle colors for you, so you don't have to muck with UserMessages:<br /> <br /> ===exvel's Colors===<br /> This is a simple include file, allowing easy control over chat coloring. You can grab it [http://forums.alliedmods.net/showthread.php?t=96831 on the forums]. Instead of hex codes, colors are denoted with tags, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{default}&lt;/tt&gt;&lt;/span&gt;, &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;, or &lt;span style=&quot;color: #00F;&quot;&gt;&lt;tt&gt;{blue}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> Here's some example usage. Note that this code assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;colors&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> CPrintToChatAll(&quot;{green}Hello {red}World! {default}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> CPrintToChatAllEx(client_on_blu_team, &quot;{teamcolor}BLU team {default}says {green}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> Note that to use a team color, there needs to be at least one player on that team. Otherwise, it will default to &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> ===SMLib===<br /> [http://forums.alliedmods.net/showthread.php?p=1398699 SMLib] is a huge collection of stock functions to keep plug-in developers from reinventing the wheel. It includes a [http://forums.alliedmods.net/showthread.php?p=1398702#post1398702 colors API] very similar to [[#exvel's Colors|exvel's]]. The benefits of SMLib are it supports shorthand color names, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{N}&lt;/tt&gt;&lt;/span&gt; and &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{G}&lt;/tt&gt;&lt;/span&gt;, and all colors are supported in its &lt;tt&gt;Client_PrintToChat()&lt;/tt&gt; function.<br /> <br /> Here's how to print the same thing as the above example with SMLib. Note that this code also assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;smlib&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> Client_PrintToChatAll(&quot;{G}Hello {R}World! {N}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> Client_PrintToChatAll(client_on_blu_team, &quot;{T}BLU team {N}says {G}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> =Why do I get an &quot;unknown symbol&quot; error when using an SDKTools native?=<br /> None of SourceMod's or SDKTools's functions are built into SourcePawn. Therefore, every time you use one of their functions, SourcePawn needs to know how to call the function. Normally, this is done using includes. Just like you would #include &lt;sourcemod&gt; to use SourceMod's functions, you need to:<br /> &lt;pawn&gt;#include &lt;sdktools&gt;&lt;/pawn&gt;<br /> to use an SDKTools native.<br /> <br /> =Why is Source telling me my command is an &quot;Unknown command&quot;?=<br /> This is because you're not returning &lt;tt&gt;Plugin_Handled&lt;/tt&gt; in your callback. If you don't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so.<br /> <br /> &lt;pawn&gt;public Action:MyCommand(client, args)<br /> {<br /> // Do something...<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Scripting_FAQ_(SourceMod)&diff=10107 2016-02-16T20:58:51Z

<p>Xerox8521: /* How do I find the classname of an entity? (e.g., &quot;weapon_knife&quot; or &quot;prop_physics&quot;) */</p> <hr /> <div>[[Image:Yak.gif]]<br /> yak wuz heer<br /> <br /> =How do I learn SourcePawn?=<br /> A good start is on the [[Introduction to SourcePawn]] page, which will teach you the SourcePawn language. Then go through the [[Introduction to SourceMod Plugins]], which will teach you how to write your first plug-in.<br /> <br /> =Where can I find all the SourcePawn functions and other information?=<br /> All SourceMod plug-ins have this line:<br /> <br /> &lt;pawn&gt;#include &lt;sourcemod&gt;&lt;/pawn&gt;<br /> <br /> This line instructs the compiler to retrieve the file &lt;tt&gt;sourcemod.inc&lt;/tt&gt; from the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder. Every function, variable, and definition can be found in the &lt;tt&gt;.inc&lt;/tt&gt; files inside the &lt;tt&gt;sourcemod/scripting/include&lt;/tt&gt; folder.<br /> <br /> But searching through all those files can be quite tedious. Thankfully, the honourable [https://forums.alliedmods.net/member.php?u=9443 Nican] created an API reference viewable on the web, complete with searching and commenting: [http://docs.sourcemod.net/api/ http://docs.sourcemod.net/api/]<br /> <br /> Also, if you are in the SourceMod IRC channel ([irc://irc.gamesurge.net/sourcemod #sourcemod on GameSurge]), you can use the &lt;tt&gt;!api&lt;/tt&gt; command to search [https://forums.alliedmods.net/member.php?u=9443 Nican's] API reference:<br /> &lt;pre&gt;&lt;theY4Kman&gt; !api Netclass<br /> &lt;yakbot&gt; theY4Kman: GetEntityNetClass(edict, String:clsname[], maxlength): Retrieves an entity's networkable serverclass name. This is not the same as the classname and is used for networkable state changes. (http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=66)&lt;/pre&gt;<br /> <br /> =How do I find the classname of an entity? (e.g., &quot;&lt;tt&gt;weapon_knife&lt;/tt&gt;&quot; or &quot;&lt;tt&gt;prop_physics&lt;/tt&gt;&quot;)=<br /> The classname of an entity (not to be confused with a netclass such as &lt;tt&gt;CCSPlayer&lt;/tt&gt;) is a unique identifier. It's the most well known of entity names. To find it, use the function [https://sm.alliedmods.net/new-api/entity/GetEdictClassname GetEdictClassname()]:<br /> <br /> &lt;pawn&gt;char classname[128];<br /> GetEdictClassname(myentity, classname, sizeof(classname));<br /> <br /> PrintToServer(&quot;myentity classname: %s&quot;, classname);<br /> // myentity classname: weapon_knife&lt;/pawn&gt;<br /> <br /> =How do I block regular commands, such as &lt;tt&gt;kill&lt;/tt&gt; and &lt;tt&gt;say&lt;/tt&gt;?=<br /> As of version 1.3, the recommended way to hook and block commands is with [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=949 AddCommandListener()]. Previously, using [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=470 RegConsoleCmd()] with the command name was the only way to hook commands, but this creates a whole new command for the command dispatch to check every time any command is executed. [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=949 AddCommandListener()] creates only a lightweight hook, processed only when the specific command is executed.<br /> <br /> Here's how to use it to block the &lt;tt&gt;say&lt;/tt&gt; command:<br /> <br /> &lt;pawn&gt;public OnPluginStart()<br /> {<br /> AddCommandListener(SayCallback, &quot;say&quot;);<br /> }<br /> <br /> public Action:SayCallback(client, const String:command[], argc)<br /> {<br /> Return Plugin_Handled;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I hook +commands, such as &lt;tt&gt;+zoom&lt;/tt&gt; and &lt;tt&gt;+attack&lt;/tt&gt;?=<br /> Unlike regular commands, &lt;tt&gt;+commands&lt;/tt&gt; are handled on the client's computer, then sent to the server in a more compressed fashion. This means [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=949 AddCommandListener()] cannot be used to hook &lt;tt&gt;+commands&lt;/tt&gt;. As of version 1.3, the recommended solution is to use the global forward [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=937 OnPlayerRunCmd()]. This forward is fired every time a player uses a movement button. To detect or block a &lt;tt&gt;+command&lt;/tt&gt;, you'll first have to find out its proper &lt;tt&gt;IN_&lt;/tt&gt; constant (see &lt;tt&gt;[http://docs.sourcemod.net/api/index.php?fastload=file&amp;id=47&amp;file=&amp; entity_prop_stocks.inc]&lt;/tt&gt;).<br /> <br /> Here's how to use it to block crouching when attacking:<br /> <br /> &lt;pawn&gt;public Action:OnPlayerRunCmd(client, &amp;buttons, &amp;impulse, Float:vel[3], Float:angles[3], &amp;weapon)<br /> {<br /> // Check if the player is attacking (+attack)<br /> if ((buttons &amp; IN_ATTACK) == IN_ATTACK)<br /> {<br /> // If so, block their crouching (+duck)<br /> buttons &amp;= ~IN_DUCK;<br /> }<br /> <br /> // We must return Plugin_Continue to let the changes be processed.<br /> // Otherwise, we can return Plugin_Handled to block the commands<br /> return Plugin_Continue;<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of loose indentation warnings?=<br /> &lt;pre&gt;myplugin.sp(#) : warning 217: loose indentation&lt;/pre&gt;<br /> <br /> Loose indentation warnings arise when indentation in your code is inconsistent. This usually means using both tabs and spaces as indentation. However, it can also mean a different amount of spaces or tabs are being used. Therefore, to correct it, use just one type of indentation. Because different editors have different settings for the size of tab stops, it is recommended you use 4 spaces to indent.<br /> <br /> Good:<br /> <br /> &lt;pawn&gt;public OnPluginStart()<br /> {<br /> new myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> Bad:<br /> <br /> &lt;pawn&gt;public OnPluginStart()<br /> {<br /> new myvar = 5;<br /> if (myvar == (2 + 3))<br /> PrintToServer(&quot;myvar is %d&quot;, myvar);<br /> }&lt;/pawn&gt;<br /> <br /> =How do I get rid of tag mismatch warnings?=<br /> Though every variable in SourcePawn is one cell (4 bytes), with the exception of strings, there are many different ways to interpret what's inside a cell. To signify a cell's contents, tags are used. The most common are &lt;tt&gt;_&lt;/tt&gt; (the default tag: a vanilla cell. This tag is implied when no other tag is specified.), &lt;tt&gt;Float&lt;/tt&gt;, &lt;tt&gt;bool&lt;/tt&gt;, and &lt;tt&gt;String&lt;/tt&gt;. See [[Introduction to SourcePawn#Variables_2]] for more information.<br /> <br /> Functions wear these tags on their parameters so you can tell what needs to be passed to the function:<br /> &lt;pawn&gt;native SetEntPropFloat(entity, PropType:type, const String:prop[], Float:value);&lt;/pawn&gt;<br /> <br /> This function calls for '''&lt;tt&gt;entity&lt;/tt&gt;''', a cell with the implied tag '''''&lt;tt&gt;_&lt;/tt&gt;'''''; '''&lt;tt&gt;type&lt;/tt&gt;''', with the developer-defined tag '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; '''&lt;tt&gt;prop&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;String&lt;/tt&gt;'''''; and '''&lt;tt&gt;value&lt;/tt&gt;''', with the built-in tag '''''&lt;tt&gt;Float&lt;/tt&gt;'''''.<br /> To call this function, then, you must pass values with the specified tags. For example:<br /> &lt;pawn&gt;SetEntPropFloat(1234, Prop_Send, &quot;m_fNumber&quot;, 1.0);&lt;/pawn&gt;<br /> <br /> This calls the function correctly: &lt;tt&gt;1234&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''), &lt;tt&gt;Prop_Send&lt;/tt&gt; is a variable defined in the enum '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [http://docs.sourcemod.net/api/index.php?fastload=file&amp;id=4&amp;file=&amp; entity.inc], &lt;tt&gt;&quot;m_fNumber&quot;&lt;/tt&gt; is a '''''&lt;tt&gt;String&lt;/tt&gt;''''', and &lt;tt&gt;1.0&lt;/tt&gt; is a '''''&lt;tt&gt;Float&lt;/tt&gt;'''''. For a nonexample:<br /> &lt;pawn&gt;SetEntPropFloat(1234.0, 1, &quot;m_fNumber&quot;, 1337);&lt;/pawn&gt;<br /> <br /> This is incorrect! &lt;tt&gt;1234.0&lt;/tt&gt; is a '''''&lt;tt&gt;Float&lt;/tt&gt;''''' that should be a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;'''''); &lt;tt&gt;1&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;PropType&lt;/tt&gt;'''''; and &lt;tt&gt;1337&lt;/tt&gt; is a regular cell ('''''&lt;tt&gt;_&lt;/tt&gt;''''') that should be a '''''&lt;tt&gt;Float&lt;/tt&gt;'''''. This call will generate a tag mismatch warning. To correct it, simply use a value with the correct tag. Most of the time, tags that are not built-in (such as '''''&lt;tt&gt;PropType&lt;/tt&gt;''''') can be found in the same file where a function uses them (you can find '''''&lt;tt&gt;PropType&lt;/tt&gt;''''' in [http://docs.sourcemod.net/api/index.php?fastload=file&amp;id=4&amp;file=&amp; entity.inc]).<br /> <br /> =How do I add color to my messages?=<br /> Though the actual colors will vary depending on the mod, you can add color to any chat message using the characters &lt;tt&gt;0x01&lt;/tt&gt; to &lt;tt&gt;0x08&lt;/tt&gt;. For example:<br /> &lt;pawn&gt;PrintToChatAll (&quot;\x01 1 .. \x02 2 .. \x03 3 .. \x04 4 .. \x05 5 .. \x06 6 .. \x07 7 .. \x08 8&quot;);&lt;/pawn&gt;<br /> <br /> Example output from Left 4 Dead:<br /> <br /> [[Image:Left_4_Dead_Colors.png]]<br /> <br /> With a little experimenting, you can learn the colors for a mod. However, the meaning behind the colors is generally as follows:<br /> <br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x01&lt;/tt&gt; = Normal color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x02&lt;/tt&gt; = Use team color to the end of a player's name. When used, it can be the only color used, and it must be at the start of the message.<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x03&lt;/tt&gt; = Team color<br /> * &lt;tt style=&quot;color: blue;&quot;&gt;0x04&lt;/tt&gt; = Location color<br /> <br /> This data comes from Counter-Strike: Source.<br /> <br /> For CS:GO, here are some colors:<br /> &lt;pawn&gt;PrintToChat(&quot;\x011\x022\x033\x044\x055\x066\x077\x088\x099\x0AA\x0BB\x0CC\x0DD\x0EE\x0FF&quot;);&lt;/pawn&gt;<br /> <br /> Unfortunately, to use players' team colors, you must use UserMessages, because there is no way for the current SourceMod functions to know which team color to use. Here's an example:<br /> <br /> &lt;pawn&gt;new Handle:hBf;<br /> hBf = StartMessageOne(&quot;SayText2&quot;, player_to); // To send the message to all players, use StartMessageAll(&quot;SayText2&quot;);<br /> if (hBf != INVALID_HANDLE)<br /> {<br /> BfWriteByte(hBf, player_from); <br /> BfWriteByte(hBf, 0); <br /> BfWriteString(hBf, &quot;&lt;\x03player_from team color\x01&gt; My message&quot;);<br /> EndMessage();<br /> }&lt;/pawn&gt;<br /> <br /> &lt;tt&gt;player_to&lt;/tt&gt; is the client index to send the message to (or use [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=132&amp; StartMessageAll()] instead of [http://docs.sourcemod.net/api/index.php?fastload=show&amp;id=133&amp; StartMessageOne()] to send the message to all players). &lt;tt&gt;player_from&lt;/tt&gt; is the client index of the player whose team color will be utilized in the message. The message will now look like this (assuming &lt;tt&gt;player_from&lt;/tt&gt; is on the RED team):<br /> <br /> &lt;span style=&quot;color:#AA0&quot;&gt;&amp;lt;&lt;/span&gt;&lt;span style=&quot;color:#F00&quot;&gt;player_from team color&lt;/span&gt;&lt;span style=&quot;color:#AA0&quot;&gt;&amp;gt; My message&lt;/span&gt;<br /> <br /> There's another catch, however: this is only known to work in CS:S and TF2. For other mods, your mileage may vary.<br /> <br /> ==Color Libraries==<br /> There are a few libraries that can handle colors for you, so you don't have to muck with UserMessages:<br /> <br /> ===exvel's Colors===<br /> This is a simple include file, allowing easy control over chat coloring. You can grab it [http://forums.alliedmods.net/showthread.php?t=96831 on the forums]. Instead of hex codes, colors are denoted with tags, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{default}&lt;/tt&gt;&lt;/span&gt;, &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;, or &lt;span style=&quot;color: #00F;&quot;&gt;&lt;tt&gt;{blue}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> Here's some example usage. Note that this code assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;colors&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> CPrintToChatAll(&quot;{green}Hello {red}World! {default}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> CPrintToChatAllEx(client_on_blu_team, &quot;{teamcolor}BLU team {default}says {green}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> Note that to use a team color, there needs to be at least one player on that team. Otherwise, it will default to &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{green}&lt;/tt&gt;&lt;/span&gt;.<br /> <br /> ===SMLib===<br /> [http://forums.alliedmods.net/showthread.php?p=1398699 SMLib] is a huge collection of stock functions to keep plug-in developers from reinventing the wheel. It includes a [http://forums.alliedmods.net/showthread.php?p=1398702#post1398702 colors API] very similar to [[#exvel's Colors|exvel's]]. The benefits of SMLib are it supports shorthand color names, such as &lt;span style=&quot;color: #AA0;&quot;&gt;&lt;tt&gt;{N}&lt;/tt&gt;&lt;/span&gt; and &lt;span style=&quot;color: #0F0;&quot;&gt;&lt;tt&gt;{G}&lt;/tt&gt;&lt;/span&gt;, and all colors are supported in its &lt;tt&gt;Client_PrintToChat()&lt;/tt&gt; function.<br /> <br /> Here's how to print the same thing as the above example with SMLib. Note that this code also assumes client 1 is in game and on the &lt;span style=&quot;color: #00F;&quot;&gt;BLU&lt;/span&gt; team:<br /> <br /> &lt;pawn&gt;#include &lt;smlib&gt;<br /> <br /> public OnPluginStart()<br /> {<br /> Client_PrintToChatAll(&quot;{G}Hello {R}World! {N}Test 1 concluded.&quot;);<br /> <br /> new client_on_blu_team = 1;<br /> Client_PrintToChatAll(client_on_blu_team, &quot;{T}BLU team {N}says {G}hi!&quot;);<br /> }&lt;/pawn&gt;<br /> <br /> &lt;span style=&quot;color: #0F0;&quot;&gt;Hello &lt;/span&gt;&lt;span style=&quot;color: #F00;&quot;&gt;World! &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;Test 1 concluded.&lt;/span&gt;<br /> &lt;span style=&quot;color: #00F;&quot;&gt;BLU team &lt;/span&gt;&lt;span style=&quot;color: #AA0;&quot;&gt;says &lt;/span&gt;&lt;span style=&quot;color: #0F0;&quot;&gt;hi!&lt;/span&gt;<br /> <br /> =Why do I get an &quot;unknown symbol&quot; error when using an SDKTools native?=<br /> None of SourceMod's or SDKTools's functions are built into SourcePawn. Therefore, every time you use one of their functions, SourcePawn needs to know how to call the function. Normally, this is done using includes. Just like you would #include &lt;sourcemod&gt; to use SourceMod's functions, you need to:<br /> &lt;pawn&gt;#include &lt;sdktools&gt;&lt;/pawn&gt;<br /> to use an SDKTools native.<br /> <br /> =Why is Source telling me my command is an &quot;Unknown command&quot;?=<br /> This is because you're not returning &lt;tt&gt;Plugin_Handled&lt;/tt&gt; in your callback. If you don't, SourceMod believes you didn't want the Source Engine to know the command was registered, and it handles it so.<br /> <br /> &lt;pawn&gt;public Action:MyCommand(client, args)<br /> {<br /> // Do something...<br /> <br /> return Plugin_Handled;<br /> }&lt;/pawn&gt;</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=SQL_(SourceMod_Scripting)&diff=10106 2016-02-10T04:10:35Z

<p>Xerox8521: /* Operations */</p> <hr /> <div>This article is an introduction to using SourceMod's SQL features. It is not an introduction or tutorial about SQL or any specific SQL implementation.<br /> <br /> SourceMod's SQL layer is formally called ''DBI'', or the '''D'''ata'''b'''ase '''I'''nterface. The interface is a generic abstraction of common SQL functions. To connect to a specific database implementation (such as MySQL, or sqLite), a SourceMod DBI &quot;driver&quot; must be loaded. Currently, there are drivers for MySQL and SQLite<br /> <br /> SourceMod automatically detects and loads drivers on demand (if they exist, of course). All database natives are in &lt;tt&gt;scripting/include/dbi.inc&lt;/tt&gt;. The C++ API is in &lt;tt&gt;public/IDBDriver.h&lt;/tt&gt;.<br /> <br /> =Connecting=<br /> There are two ways to connect to a database. The first is through named configurations. Named configurations are preset configurations listed in &lt;tt&gt;configs/databases.cfg&lt;/tt&gt;. SourceMod specifies that if SQL is being used, there should always be one configuration named &quot;default.&quot;<br /> <br /> An example of such a configuration looks like:<br /> &lt;pre&gt; &quot;default&quot;<br /> {<br /> &quot;host&quot; &quot;localhost&quot;<br /> &quot;database&quot; &quot;sourcemod&quot;<br /> &quot;user&quot; &quot;root&quot;<br /> &quot;pass&quot; &quot;&quot;<br /> //&quot;timeout&quot; &quot;0&quot;<br /> //&quot;port&quot; &quot;0&quot;<br /> }&lt;/pre&gt;<br /> <br /> Connections based on named configurations can be instantiated with either &lt;tt&gt;SQL_Connect&lt;/tt&gt; or &lt;tt&gt;SQL_DefConnect&lt;/tt&gt;. <br /> <br /> The other option is to use &lt;tt&gt;SQL_ConnectCustom&lt;/tt&gt; and manually specify all connection parameters by passing a keyvalue handle containing them.<br /> <br /> Example of a typical connection:<br /> &lt;pawn&gt;char error[255];<br /> Database db = SQL_DefConnect(error, sizeof(error));<br /> <br /> if (db == null)<br /> {<br /> PrintToServer(&quot;Could not connect: %s&quot;, error);<br /> } <br /> else <br /> {<br /> delete db;<br /> }&lt;/pawn&gt;<br /> <br /> =Queries=<br /> <br /> ==No Results==<br /> The simplest queries are ones which do not return results -- for example, CREATE, DROP, UPDATE, INSERT, and DELETE. For such queries it is recommended to use &lt;tt&gt;SQL_FastQuery()&lt;/tt&gt;. The name does not imply that the query will be faster, but rather, it is faster to write code using this function. For example, given that &lt;tt&gt;db&lt;/tt&gt; is a valid database Handle:<br /> <br /> &lt;pawn&gt;if (!SQL_FastQuery(db, &quot;UPDATE stats SET players = players + 1&quot;))<br /> {<br /> char error[255];<br /> SQL_GetError(db, error, sizeof(error));<br /> PrintToServer(&quot;Failed to query (error: %s)&quot;, error);<br /> }&lt;/pawn&gt;<br /> <br /> ==Results==<br /> If a query returns a result set and the results must be processed, you must use &lt;tt&gt;SQL_Query()&lt;/tt&gt;. Unlike &lt;tt&gt;SQL_FastQuery()&lt;/tt&gt;, this function returns a Handle which must be closed.<br /> <br /> An example of a query which will produce results is:<br /> &lt;pawn&gt;DBResultSet query = SQL_Query(db, &quot;SELECT userid FROM vb_user WHERE username = 'BAILOPAN'&quot;);<br /> if (query == null)<br /> {<br /> char error[255];<br /> SQL_GetError(db, error, sizeof(error));<br /> PrintToServer(&quot;Failed to query (error: %s)&quot;, error);<br /> } <br /> else <br /> {<br /> /* Process results here!<br /> */<br /> <br /> /* Free the Handle */<br /> delete query;<br /> }&lt;/pawn&gt;<br /> <br /> =Prepared Statements=<br /> Prepared statements are another method of querying. The idea behind a prepared statement is that you construct a query &quot;template&quot; once, and re-use it as many times as needed. Prepared statements have the following benefits:<br /> *A good SQL implementation will be able to cache the query better if it is a prepared statement.<br /> *You don't have to rebuild the entire query string every execution.<br /> *You don't have to allocate a new query structure on every execution.<br /> *Input is &quot;always&quot; secure (more on this later).<br /> <br /> A prepared statement has &quot;markers&quot; for inputs. For example, let's consider a function that takes in a database Handle and a name, and retrieves some info from a table:<br /> &lt;pawn&gt;int GetSomeInfo(Database db, const char[] name)<br /> {<br /> DBResultSet hQuery;<br /> char query[100];<br /> <br /> /* Create enough space to make sure our string is quoted properly */<br /> int buffer_len = strlen(name) * 2 + 1;<br /> char[] new_name = new char[buffer_len];<br /> <br /> /* Ask the SQL driver to make sure our string is safely quoted */<br /> SQL_EscapeString(db, name, new_name, buffer_len);<br /> <br /> /* Build the query */<br /> Format(query, sizeof(query), &quot;SELECT userid FROM vb_user WHERE username = '%s'&quot;, new_name);<br /> <br /> /* Execute the query */<br /> if ((hQuery = SQL_Query(query)) == null)<br /> {<br /> return 0;<br /> }<br /> <br /> /* Get some info here<br /> */<br /> <br /> delete hQuery;<br /> }&lt;/pawn&gt;<br /> <br /> Observe a version with prepared statements:<br /> &lt;pawn&gt;DBStatement hUserStmt = null;<br /> int GetSomeInfo(Database db, const char[] name)<br /> {<br /> /* Check if we haven't already created the statement */<br /> if (hUserStmt == null)<br /> {<br /> char error[255];<br /> hUserStmt = SQL_PrepareQuery(db, &quot;SELECT userid FROM vb_user WHERE username = ?&quot;, error, sizeof(error));<br /> if (hUserStmt == null)<br /> {<br /> return 0;<br /> }<br /> }<br /> <br /> SQL_BindParamString(hUserStmt, 0, name, false);<br /> if (!SQL_Execute(hUserStmt))<br /> {<br /> return 0;<br /> }<br /> <br /> /**<br /> * Get some info here<br /> */<br /> }&lt;/pawn&gt;<br /> <br /> The important differences:<br /> *The input string (&lt;tt&gt;name&lt;/tt&gt;) did not need to be backticked (quoted). The SQL engine automatically performs all type safety and insertion checks.<br /> *There was no need for quotation marks around the parameter marker, &lt;tt&gt;?&lt;/tt&gt;, even though it accepted a string.<br /> *We only needed to create the statement Handle once; after that it can live for the lifetime of the database connection.<br /> <br /> =Processing Results=<br /> Processing results is done in the same manner for both normal queries and prepared statements. The important functions are:<br /> *&lt;tt&gt;SQL_GetRowCount()&lt;/tt&gt; - Returns the number of rows.<br /> *&lt;tt&gt;SQL_FetchRow()&lt;/tt&gt; - Fetches the next row if one is available.<br /> *&lt;tt&gt;SQL_Fetch[Int|String|Float]()&lt;/tt&gt; - Fetches data from a field in the current row.<br /> <br /> Let's consider a sample table that looks like this:<br /> &lt;pawn&gt;CREATE TABLE users (<br /> name VARCHAR(64) NOT NULL PRIMARY KEY,<br /> age INT UNSIGNED NOT NULL<br /> );&lt;/pawn&gt;<br /> <br /> The following example has code that will print out all users matching a certain age. There is an example for both prepared statements and normal queries.<br /> &lt;pawn&gt;void PrintResults(Handle query)<br /> {<br /> /* Even if we have just one row, you must call SQL_FetchRow() first */<br /> char name[MAX_NAME_LENGTH];<br /> while (SQL_FetchRow(query))<br /> {<br /> SQL_FetchString(query, 0, name, sizeof(name));<br /> PrintToServer(&quot;Name \&quot;%s\&quot; was found.&quot;, name);<br /> }<br /> }<br /> <br /> bool GetByAge_Query(Database db, int age)<br /> {<br /> char query[100];<br /> Format(query, sizeof(query), &quot;SELECT name FROM users WHERE age = %d&quot;, age);<br /> <br /> DBResultSet hQuery = SQL_Query(db, query);<br /> if (hQuery == null)<br /> {<br /> return false;<br /> }<br /> <br /> PrintResults(hQuery);<br /> <br /> delete hQuery;<br /> <br /> return true;<br /> }<br /> <br /> DBStatement hAgeStmt = null;<br /> bool GetByAge_Statement(Database db, int age)<br /> {<br /> if (hAgeSmt == null)<br /> {<br /> char error[255];<br /> if ((hAgeStmt = SQL_PrepareQuery(db, <br /> &quot;SELECT name FROM users WHERE age = ?&quot;, <br /> error, <br /> sizeof(error))) <br /> == null)<br /> {<br /> return false;<br /> }<br /> }<br /> <br /> SQL_BindParamInt(hAgeStmt, 0, age);<br /> if (!SQL_Execute(hAgeStmt))<br /> {<br /> return false;<br /> }<br /> <br /> PrintResults(hAgeStmt);<br /> <br /> return true;<br /> }&lt;/pawn&gt;<br /> <br /> Note that these examples did not close the statement Handles. These examples assume a global database instance that is only closed when the plugin is unloaded. For plugins which maintain temporary database connections, prepared statement Handles must be freed or else the database connection will never be closed.<br /> <br /> =Threading=<br /> SourceMod supports threaded SQL querying. That is, SQL operations can be completed in a separate thread from main gameplay. If your database server is remote or requires a network connection, queries can cause noticeable gameplay lag, and supporting threading is often a good idea if your queries occur in the middle of gameplay.<br /> <br /> Threaded queries are ''asynchronous''. That is, they are dispatched and you can only find the results through a callback. Although the callback is guaranteed to fire eventually, it may not fire in any specific given timeframe. Certain drivers may not support threading; if this is the case, an RTE will be thrown. If the threader cannot start or the threader is currently disabled, SourceMod will transparently execute the query in the main thread as a fallback.<br /> <br /> ==Operations==<br /> All threaded operations (except connecting) use the same callback for result notification: &lt;tt&gt;SQLQueryCallback&lt;/tt&gt;. The parameters are:<br /> *&lt;tt&gt;db&lt;/tt&gt; - The cloned database handle. If the db handle was not found or was invalidated, &lt;tt&gt;null&lt;/tt&gt; is passed.<br /> *&lt;tt&gt;results&lt;/tt&gt; - Result object, or null on failure.<br /> *&lt;tt&gt;error&lt;/tt&gt; - An error string.<br /> *&lt;tt&gt;data&lt;/tt&gt; - Custom data that can be passed via some SQL operations.<br /> <br /> The following operations can be done via threads:<br /> *&lt;b&gt;Connection&lt;/b&gt;, via &lt;tt&gt;SQL_TConnect&lt;/tt&gt;.<br /> *&lt;b&gt;Querying&lt;/b&gt;, via &lt;tt&gt;SQL_TQuery()&lt;/tt&gt;.<br /> *''Note: prepared statements are not yet available for the threader.''<br /> <br /> It is always safe to chain one operation from another.<br /> <br /> ===Connecting===<br /> It is not necessary to make a threaded connection in order to make threaded queries. However, creating a threaded connection will not pause the game server if a connection cannot be immediately established. <br /> Connecting however uses a different callback: &lt;tt&gt;SQLConnectCallback&lt;/tt&gt;.<br /> <br /> The following parameters are used for the threaded connection callback:<br /> *&lt;tt&gt;db&lt;/tt&gt;: Handle to the database connection, or &lt;tt&gt;null&lt;/tt&gt; if it could not be found.<br /> *&lt;tt&gt;error&lt;/tt&gt;: The error string, if any.<br /> *&lt;tt&gt;data&lt;/tt&gt;: Unused (0)<br /> <br /> Example: <br /> &lt;pawn&gt;Database hDatabase = null;<br /> <br /> void StartSQL()<br /> {<br /> SQL_TConnect(GotDatabase);<br /> }<br /> <br /> public void GotDatabase(Database db, const char[] error, any data)<br /> {<br /> if (db == null)<br /> {<br /> LogError(&quot;Database failure: %s&quot;, error);<br /> } <br /> else <br /> {<br /> hDatabase = hndl;<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> ===Querying===<br /> Threaded queries can be performed on any database Handle as long as the driver supports threading. All query results for the first result set are retrieved while in the thread. If your query returns more than one set of results (for example, &lt;tt&gt;CALL&lt;/tt&gt; on MySQL with certain functions), the behaviour of the threader is undefined at this time. &lt;b&gt;Note that if you want to perform both threaded and non-threaded queries on the same connection, you MUST read the &quot;Locking&quot; section below.&lt;/b&gt;<br /> <br /> Query operations use the following callback parameters:<br /> *&lt;tt&gt;owner&lt;/tt&gt;: A Handle to the database used to query. The Handle is not the same as the Handle originally passed; however, it will test positively with &lt;tt&gt;SQL_IsSameConnection&lt;/tt&gt;. The Handle can be cloned but it cannot be closed (it is closed automatically). It may be &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; in the case of a serious error (for example, the driver being unloaded).<br /> *&lt;tt&gt;hndl&lt;/tt&gt;: A Handle to the query. It can be cloned, but not closed (it is closed automatically). It may be &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; if there was an error.<br /> *&lt;tt&gt;error&lt;/tt&gt;: Error string, if any.<br /> *&lt;tt&gt;data&lt;/tt&gt;: Optional user-defined data passed in through &lt;tt&gt;SQL_TQuery()&lt;/tt&gt;.<br /> <br /> Example, continuing from above:<br /> &lt;pawn&gt;CheckSteamID(userid, const String:auth[])<br /> {<br /> decl String:query[255];<br /> Format(query, sizeof(query), &quot;SELECT userid FROM users WHERE steamid = '%s'&quot;, auth);<br /> SQL_TQuery(hdatabase, T_CheckSteamID, query, userid)<br /> }<br /> <br /> public T_CheckSteamID(Handle:owner, Handle:hndl, const String:error[], any:data)<br /> {<br /> new client;<br /> <br /> /* Make sure the client didn't disconnect while the thread was running */<br /> if ((client = GetClientOfUserId(data)) == 0)<br /> {<br /> return;<br /> }<br /> <br /> if (hndl == INVALID_HANDLE)<br /> {<br /> LogError(&quot;Query failed! %s&quot;, error);<br /> KickClient(client, &quot;Authorization failed&quot;);<br /> } else if (!SQL_GetRowCount(hndl)) {<br /> KickClient(client, &quot;You are not a member&quot;);<br /> }<br /> }<br /> &lt;/pawn&gt;<br /> <br /> ==Locking==<br /> It is possible to run both threaded and non-threaded queries on the same connection. However, without the proper precautions, you could corrupt the network stream (even if it's local), corrupt memory, or otherwise cause a crash in the SQL driver. To solve this, SourceMod has ''database locking''. Locking is done via &lt;tt&gt;SQL_LockDatabase()&lt;/tt&gt; and &lt;tt&gt;SQL_UnlockDatabase&lt;/tt&gt;.<br /> <br /> Whenever performing any of the following non-threaded operations on a database, it is absolutely necessary to enclose the entire operation with a lock:<br /> *&lt;tt&gt;SQL_Query()&lt;/tt&gt; (and &lt;tt&gt;SQL_FetchMoreResults&lt;/tt&gt; pairings)<br /> *&lt;tt&gt;SQL_FastQuery&lt;/tt&gt;<br /> *&lt;tt&gt;SQL_PrepareQuery&lt;/tt&gt;<br /> *&lt;tt&gt;SQL_Bind*&lt;/tt&gt; and &lt;tt&gt;SQL_Execute&lt;/tt&gt; pairings<br /> <br /> The rule of thumb is: if your operation is going to use the database connection, it must be locked until the operation is fully completed. <br /> <br /> Example:<br /> &lt;pawn&gt;bool:GetByAge_Query(Handle:db, age)<br /> {<br /> new String:query[100]<br /> Format(query, sizeof(query), &quot;SELECT name FROM users WHERE age = %d&quot;, age)<br /> <br /> SQL_LockDatabase(db);<br /> new Handle:hQuery = SQL_Query(db, query)<br /> if (hQuery == INVALID_HANDLE)<br /> {<br /> SQL_UnlockDatabase(db);<br /> return false<br /> }<br /> SQL_UnlockDatabase(db);<br /> <br /> PrintResults(hQuery)<br /> <br /> CloseHandle(hQuery)<br /> <br /> return true<br /> }&lt;/pawn&gt;<br /> <br /> Note that it was only necessary to lock the query; SourceMod pre-fetches the result set, and thus the network queue is clean.<br /> <br /> ===Warnings===<br /> *&lt;b&gt;Never&lt;/b&gt; call &lt;tt&gt;SQL_LockDatabase&lt;/tt&gt; right before a threaded operation. You will deadlock the server and have to terminate/kill it. <br /> *&lt;b&gt;Always pair every Lock with an Unlock.&lt;/b&gt; Otherwise you risk a deadlock.<br /> *If your query returns multiple result sets, for example, a procedure call on MySQL that returns results, you must lock both the query and the entire fetch operation. SourceMod is only able to fetch one result set at a time, and all result sets must be cleared before a new query is started.<br /> <br /> ==Priority==<br /> Threaded SQL operations are placed in a simple priority queue. The priority levels are &lt;tt&gt;High&lt;/tt&gt;, &lt;tt&gt;Medium&lt;/tt&gt;, and &lt;tt&gt;Low&lt;/tt&gt;. Connections always have the highest priority. <br /> <br /> Changing the priority can be useful if you have many queries with different purposes. For example, a statistics plugin might execute 10 queries on death, and one query on join. Because the statistics might rely on the join info, the join query might need to be high priority, while the death queries can be low priority.<br /> <br /> You should &lt;b&gt;never&lt;/b&gt; simply assign a high priority to all of your queries simply because you want them to get done fast. Not only does it not work that way, but you may be inserting subtle problems into other plugins by being greedy.<br /> <br /> <br /> =SQLite=<br /> ==Introduction==<br /> [http://www.sqlite.org/ SQLite] is a fast local-file SQL database engine and SourceMod provides a DBI driver for it. SQLite differs from MySQL, and thus MySQL queries may not work in SQLite. The driver type for connections is &lt;tt&gt;sqlite&lt;/tt&gt;.<br /> <br /> ==Usage==<br /> Since SQLite is local only, most of the connection parameters can be ignored. The only connection parameter required is &lt;tt&gt;database&lt;/tt&gt;, which specifies the file name of the database. Databases are created on demand if they do not already exist, and are stored in &lt;tt&gt;addons/sourcemod/data/sqlite&lt;/tt&gt;. An extension of &quot;.sq3&quot; is automatically appended to the file name.<br /> <br /> Additionally, you can specify sub-folders in the database name. For example, &quot;cssdm/players&quot; will become &lt;tt&gt;addons/sourcemod/data/sqlite/cssdm/players.sq3&lt;/tt&gt;.<br /> <br /> SQLite supports the threading layer, and requires all of the same rules as the MySQL driver (including locks on shared connections).<br /> <br /> ==External Links==<br /> *[http://www.sqlite.org SQLite Homepage]<br /> *[http://sqlitebrowser.sourceforge.net/ SQLite Browser]<br /> <br /> <br /> [[Category:SourceMod Scripting]]<br /> <br /> {{LanguageSwitch}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=SQL_(SourceMod_Scripting)&diff=10105 2016-02-10T04:02:01Z

<p>Xerox8521: /* Processing Results */ Updated to Transitional Syntax</p> <hr /> <div>This article is an introduction to using SourceMod's SQL features. It is not an introduction or tutorial about SQL or any specific SQL implementation.<br /> <br /> SourceMod's SQL layer is formally called ''DBI'', or the '''D'''ata'''b'''ase '''I'''nterface. The interface is a generic abstraction of common SQL functions. To connect to a specific database implementation (such as MySQL, or sqLite), a SourceMod DBI &quot;driver&quot; must be loaded. Currently, there are drivers for MySQL and SQLite<br /> <br /> SourceMod automatically detects and loads drivers on demand (if they exist, of course). All database natives are in &lt;tt&gt;scripting/include/dbi.inc&lt;/tt&gt;. The C++ API is in &lt;tt&gt;public/IDBDriver.h&lt;/tt&gt;.<br /> <br /> =Connecting=<br /> There are two ways to connect to a database. The first is through named configurations. Named configurations are preset configurations listed in &lt;tt&gt;configs/databases.cfg&lt;/tt&gt;. SourceMod specifies that if SQL is being used, there should always be one configuration named &quot;default.&quot;<br /> <br /> An example of such a configuration looks like:<br /> &lt;pre&gt; &quot;default&quot;<br /> {<br /> &quot;host&quot; &quot;localhost&quot;<br /> &quot;database&quot; &quot;sourcemod&quot;<br /> &quot;user&quot; &quot;root&quot;<br /> &quot;pass&quot; &quot;&quot;<br /> //&quot;timeout&quot; &quot;0&quot;<br /> //&quot;port&quot; &quot;0&quot;<br /> }&lt;/pre&gt;<br /> <br /> Connections based on named configurations can be instantiated with either &lt;tt&gt;SQL_Connect&lt;/tt&gt; or &lt;tt&gt;SQL_DefConnect&lt;/tt&gt;. <br /> <br /> The other option is to use &lt;tt&gt;SQL_ConnectCustom&lt;/tt&gt; and manually specify all connection parameters by passing a keyvalue handle containing them.<br /> <br /> Example of a typical connection:<br /> &lt;pawn&gt;char error[255];<br /> Database db = SQL_DefConnect(error, sizeof(error));<br /> <br /> if (db == null)<br /> {<br /> PrintToServer(&quot;Could not connect: %s&quot;, error);<br /> } <br /> else <br /> {<br /> delete db;<br /> }&lt;/pawn&gt;<br /> <br /> =Queries=<br /> <br /> ==No Results==<br /> The simplest queries are ones which do not return results -- for example, CREATE, DROP, UPDATE, INSERT, and DELETE. For such queries it is recommended to use &lt;tt&gt;SQL_FastQuery()&lt;/tt&gt;. The name does not imply that the query will be faster, but rather, it is faster to write code using this function. For example, given that &lt;tt&gt;db&lt;/tt&gt; is a valid database Handle:<br /> <br /> &lt;pawn&gt;if (!SQL_FastQuery(db, &quot;UPDATE stats SET players = players + 1&quot;))<br /> {<br /> char error[255];<br /> SQL_GetError(db, error, sizeof(error));<br /> PrintToServer(&quot;Failed to query (error: %s)&quot;, error);<br /> }&lt;/pawn&gt;<br /> <br /> ==Results==<br /> If a query returns a result set and the results must be processed, you must use &lt;tt&gt;SQL_Query()&lt;/tt&gt;. Unlike &lt;tt&gt;SQL_FastQuery()&lt;/tt&gt;, this function returns a Handle which must be closed.<br /> <br /> An example of a query which will produce results is:<br /> &lt;pawn&gt;DBResultSet query = SQL_Query(db, &quot;SELECT userid FROM vb_user WHERE username = 'BAILOPAN'&quot;);<br /> if (query == null)<br /> {<br /> char error[255];<br /> SQL_GetError(db, error, sizeof(error));<br /> PrintToServer(&quot;Failed to query (error: %s)&quot;, error);<br /> } <br /> else <br /> {<br /> /* Process results here!<br /> */<br /> <br /> /* Free the Handle */<br /> delete query;<br /> }&lt;/pawn&gt;<br /> <br /> =Prepared Statements=<br /> Prepared statements are another method of querying. The idea behind a prepared statement is that you construct a query &quot;template&quot; once, and re-use it as many times as needed. Prepared statements have the following benefits:<br /> *A good SQL implementation will be able to cache the query better if it is a prepared statement.<br /> *You don't have to rebuild the entire query string every execution.<br /> *You don't have to allocate a new query structure on every execution.<br /> *Input is &quot;always&quot; secure (more on this later).<br /> <br /> A prepared statement has &quot;markers&quot; for inputs. For example, let's consider a function that takes in a database Handle and a name, and retrieves some info from a table:<br /> &lt;pawn&gt;int GetSomeInfo(Database db, const char[] name)<br /> {<br /> DBResultSet hQuery;<br /> char query[100];<br /> <br /> /* Create enough space to make sure our string is quoted properly */<br /> int buffer_len = strlen(name) * 2 + 1;<br /> char[] new_name = new char[buffer_len];<br /> <br /> /* Ask the SQL driver to make sure our string is safely quoted */<br /> SQL_EscapeString(db, name, new_name, buffer_len);<br /> <br /> /* Build the query */<br /> Format(query, sizeof(query), &quot;SELECT userid FROM vb_user WHERE username = '%s'&quot;, new_name);<br /> <br /> /* Execute the query */<br /> if ((hQuery = SQL_Query(query)) == null)<br /> {<br /> return 0;<br /> }<br /> <br /> /* Get some info here<br /> */<br /> <br /> delete hQuery;<br /> }&lt;/pawn&gt;<br /> <br /> Observe a version with prepared statements:<br /> &lt;pawn&gt;DBStatement hUserStmt = null;<br /> int GetSomeInfo(Database db, const char[] name)<br /> {<br /> /* Check if we haven't already created the statement */<br /> if (hUserStmt == null)<br /> {<br /> char error[255];<br /> hUserStmt = SQL_PrepareQuery(db, &quot;SELECT userid FROM vb_user WHERE username = ?&quot;, error, sizeof(error));<br /> if (hUserStmt == null)<br /> {<br /> return 0;<br /> }<br /> }<br /> <br /> SQL_BindParamString(hUserStmt, 0, name, false);<br /> if (!SQL_Execute(hUserStmt))<br /> {<br /> return 0;<br /> }<br /> <br /> /**<br /> * Get some info here<br /> */<br /> }&lt;/pawn&gt;<br /> <br /> The important differences:<br /> *The input string (&lt;tt&gt;name&lt;/tt&gt;) did not need to be backticked (quoted). The SQL engine automatically performs all type safety and insertion checks.<br /> *There was no need for quotation marks around the parameter marker, &lt;tt&gt;?&lt;/tt&gt;, even though it accepted a string.<br /> *We only needed to create the statement Handle once; after that it can live for the lifetime of the database connection.<br /> <br /> =Processing Results=<br /> Processing results is done in the same manner for both normal queries and prepared statements. The important functions are:<br /> *&lt;tt&gt;SQL_GetRowCount()&lt;/tt&gt; - Returns the number of rows.<br /> *&lt;tt&gt;SQL_FetchRow()&lt;/tt&gt; - Fetches the next row if one is available.<br /> *&lt;tt&gt;SQL_Fetch[Int|String|Float]()&lt;/tt&gt; - Fetches data from a field in the current row.<br /> <br /> Let's consider a sample table that looks like this:<br /> &lt;pawn&gt;CREATE TABLE users (<br /> name VARCHAR(64) NOT NULL PRIMARY KEY,<br /> age INT UNSIGNED NOT NULL<br /> );&lt;/pawn&gt;<br /> <br /> The following example has code that will print out all users matching a certain age. There is an example for both prepared statements and normal queries.<br /> &lt;pawn&gt;void PrintResults(Handle query)<br /> {<br /> /* Even if we have just one row, you must call SQL_FetchRow() first */<br /> char name[MAX_NAME_LENGTH];<br /> while (SQL_FetchRow(query))<br /> {<br /> SQL_FetchString(query, 0, name, sizeof(name));<br /> PrintToServer(&quot;Name \&quot;%s\&quot; was found.&quot;, name);<br /> }<br /> }<br /> <br /> bool GetByAge_Query(Database db, int age)<br /> {<br /> char query[100];<br /> Format(query, sizeof(query), &quot;SELECT name FROM users WHERE age = %d&quot;, age);<br /> <br /> DBResultSet hQuery = SQL_Query(db, query);<br /> if (hQuery == null)<br /> {<br /> return false;<br /> }<br /> <br /> PrintResults(hQuery);<br /> <br /> delete hQuery;<br /> <br /> return true;<br /> }<br /> <br /> DBStatement hAgeStmt = null;<br /> bool GetByAge_Statement(Database db, int age)<br /> {<br /> if (hAgeSmt == null)<br /> {<br /> char error[255];<br /> if ((hAgeStmt = SQL_PrepareQuery(db, <br /> &quot;SELECT name FROM users WHERE age = ?&quot;, <br /> error, <br /> sizeof(error))) <br /> == null)<br /> {<br /> return false;<br /> }<br /> }<br /> <br /> SQL_BindParamInt(hAgeStmt, 0, age);<br /> if (!SQL_Execute(hAgeStmt))<br /> {<br /> return false;<br /> }<br /> <br /> PrintResults(hAgeStmt);<br /> <br /> return true;<br /> }&lt;/pawn&gt;<br /> <br /> Note that these examples did not close the statement Handles. These examples assume a global database instance that is only closed when the plugin is unloaded. For plugins which maintain temporary database connections, prepared statement Handles must be freed or else the database connection will never be closed.<br /> <br /> =Threading=<br /> SourceMod supports threaded SQL querying. That is, SQL operations can be completed in a separate thread from main gameplay. If your database server is remote or requires a network connection, queries can cause noticeable gameplay lag, and supporting threading is often a good idea if your queries occur in the middle of gameplay.<br /> <br /> Threaded queries are ''asynchronous''. That is, they are dispatched and you can only find the results through a callback. Although the callback is guaranteed to fire eventually, it may not fire in any specific given timeframe. Certain drivers may not support threading; if this is the case, an RTE will be thrown. If the threader cannot start or the threader is currently disabled, SourceMod will transparently execute the query in the main thread as a fallback.<br /> <br /> ==Operations==<br /> All threaded operations use the same callback for result notification: &lt;tt&gt;SQLTCallback&lt;/tt&gt;. The parameters are:<br /> *&lt;tt&gt;owner&lt;/tt&gt; - The &quot;owner&quot; of the operation. For a query, this is a database. For a database, this is a driver. If the owner was not found or was invalidated, &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; is passed.<br /> *&lt;tt&gt;hndl&lt;/tt&gt; - The object being requested. The value is defined by the SQL operation.<br /> *&lt;tt&gt;error&lt;/tt&gt; - An error string.<br /> *&lt;tt&gt;data&lt;/tt&gt; - Custom data that can be passed via some SQL operations.<br /> <br /> The following operations can be done via threads:<br /> *&lt;b&gt;Connection&lt;/b&gt;, via &lt;tt&gt;SQL_TConnect&lt;/tt&gt;.<br /> *&lt;b&gt;Querying&lt;/b&gt;, via &lt;tt&gt;SQL_TQuery()&lt;/tt&gt;.<br /> *''Note: prepared statements are not yet available for the threader.''<br /> <br /> It is always safe to chain one operation from another.<br /> <br /> ===Connecting===<br /> It is not necessary to make a threaded connection in order to make threaded queries. However, creating a threaded connection will not pause the game server if a connection cannot be immediately established. <br /> <br /> The following parameters are used for the threaded connection callback:<br /> *&lt;tt&gt;owner&lt;/tt&gt;: A Handle to the driver, or &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; if it could not be found.<br /> *&lt;tt&gt;hndl&lt;/tt&gt;: A Handle to the database, or &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; if the connection failed.<br /> *&lt;tt&gt;error&lt;/tt&gt;: The error string, if any.<br /> *&lt;tt&gt;data&lt;/tt&gt;: Unused (0)<br /> <br /> Example: <br /> &lt;pawn&gt;new Handle:hDatabase = INVALID_HANDLE;<br /> <br /> StartSQL()<br /> {<br /> SQL_TConnect(GotDatabase);<br /> }<br /> <br /> public GotDatabase(Handle:owner, Handle:hndl, const String:error[], any:data)<br /> {<br /> if (hndl == INVALID_HANDLE)<br /> {<br /> LogError(&quot;Database failure: %s&quot;, error);<br /> } else {<br /> hDatabase = hndl;<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> ===Querying===<br /> Threaded queries can be performed on any database Handle as long as the driver supports threading. All query results for the first result set are retrieved while in the thread. If your query returns more than one set of results (for example, &lt;tt&gt;CALL&lt;/tt&gt; on MySQL with certain functions), the behaviour of the threader is undefined at this time. &lt;b&gt;Note that if you want to perform both threaded and non-threaded queries on the same connection, you MUST read the &quot;Locking&quot; section below.&lt;/b&gt;<br /> <br /> Query operations use the following callback parameters:<br /> *&lt;tt&gt;owner&lt;/tt&gt;: A Handle to the database used to query. The Handle is not the same as the Handle originally passed; however, it will test positively with &lt;tt&gt;SQL_IsSameConnection&lt;/tt&gt;. The Handle can be cloned but it cannot be closed (it is closed automatically). It may be &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; in the case of a serious error (for example, the driver being unloaded).<br /> *&lt;tt&gt;hndl&lt;/tt&gt;: A Handle to the query. It can be cloned, but not closed (it is closed automatically). It may be &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; if there was an error.<br /> *&lt;tt&gt;error&lt;/tt&gt;: Error string, if any.<br /> *&lt;tt&gt;data&lt;/tt&gt;: Optional user-defined data passed in through &lt;tt&gt;SQL_TQuery()&lt;/tt&gt;.<br /> <br /> Example, continuing from above:<br /> &lt;pawn&gt;CheckSteamID(userid, const String:auth[])<br /> {<br /> decl String:query[255];<br /> Format(query, sizeof(query), &quot;SELECT userid FROM users WHERE steamid = '%s'&quot;, auth);<br /> SQL_TQuery(hdatabase, T_CheckSteamID, query, userid)<br /> }<br /> <br /> public T_CheckSteamID(Handle:owner, Handle:hndl, const String:error[], any:data)<br /> {<br /> new client;<br /> <br /> /* Make sure the client didn't disconnect while the thread was running */<br /> if ((client = GetClientOfUserId(data)) == 0)<br /> {<br /> return;<br /> }<br /> <br /> if (hndl == INVALID_HANDLE)<br /> {<br /> LogError(&quot;Query failed! %s&quot;, error);<br /> KickClient(client, &quot;Authorization failed&quot;);<br /> } else if (!SQL_GetRowCount(hndl)) {<br /> KickClient(client, &quot;You are not a member&quot;);<br /> }<br /> }<br /> &lt;/pawn&gt;<br /> <br /> ==Locking==<br /> It is possible to run both threaded and non-threaded queries on the same connection. However, without the proper precautions, you could corrupt the network stream (even if it's local), corrupt memory, or otherwise cause a crash in the SQL driver. To solve this, SourceMod has ''database locking''. Locking is done via &lt;tt&gt;SQL_LockDatabase()&lt;/tt&gt; and &lt;tt&gt;SQL_UnlockDatabase&lt;/tt&gt;.<br /> <br /> Whenever performing any of the following non-threaded operations on a database, it is absolutely necessary to enclose the entire operation with a lock:<br /> *&lt;tt&gt;SQL_Query()&lt;/tt&gt; (and &lt;tt&gt;SQL_FetchMoreResults&lt;/tt&gt; pairings)<br /> *&lt;tt&gt;SQL_FastQuery&lt;/tt&gt;<br /> *&lt;tt&gt;SQL_PrepareQuery&lt;/tt&gt;<br /> *&lt;tt&gt;SQL_Bind*&lt;/tt&gt; and &lt;tt&gt;SQL_Execute&lt;/tt&gt; pairings<br /> <br /> The rule of thumb is: if your operation is going to use the database connection, it must be locked until the operation is fully completed. <br /> <br /> Example:<br /> &lt;pawn&gt;bool:GetByAge_Query(Handle:db, age)<br /> {<br /> new String:query[100]<br /> Format(query, sizeof(query), &quot;SELECT name FROM users WHERE age = %d&quot;, age)<br /> <br /> SQL_LockDatabase(db);<br /> new Handle:hQuery = SQL_Query(db, query)<br /> if (hQuery == INVALID_HANDLE)<br /> {<br /> SQL_UnlockDatabase(db);<br /> return false<br /> }<br /> SQL_UnlockDatabase(db);<br /> <br /> PrintResults(hQuery)<br /> <br /> CloseHandle(hQuery)<br /> <br /> return true<br /> }&lt;/pawn&gt;<br /> <br /> Note that it was only necessary to lock the query; SourceMod pre-fetches the result set, and thus the network queue is clean.<br /> <br /> ===Warnings===<br /> *&lt;b&gt;Never&lt;/b&gt; call &lt;tt&gt;SQL_LockDatabase&lt;/tt&gt; right before a threaded operation. You will deadlock the server and have to terminate/kill it. <br /> *&lt;b&gt;Always pair every Lock with an Unlock.&lt;/b&gt; Otherwise you risk a deadlock.<br /> *If your query returns multiple result sets, for example, a procedure call on MySQL that returns results, you must lock both the query and the entire fetch operation. SourceMod is only able to fetch one result set at a time, and all result sets must be cleared before a new query is started.<br /> <br /> ==Priority==<br /> Threaded SQL operations are placed in a simple priority queue. The priority levels are &lt;tt&gt;High&lt;/tt&gt;, &lt;tt&gt;Medium&lt;/tt&gt;, and &lt;tt&gt;Low&lt;/tt&gt;. Connections always have the highest priority. <br /> <br /> Changing the priority can be useful if you have many queries with different purposes. For example, a statistics plugin might execute 10 queries on death, and one query on join. Because the statistics might rely on the join info, the join query might need to be high priority, while the death queries can be low priority.<br /> <br /> You should &lt;b&gt;never&lt;/b&gt; simply assign a high priority to all of your queries simply because you want them to get done fast. Not only does it not work that way, but you may be inserting subtle problems into other plugins by being greedy.<br /> <br /> <br /> =SQLite=<br /> ==Introduction==<br /> [http://www.sqlite.org/ SQLite] is a fast local-file SQL database engine and SourceMod provides a DBI driver for it. SQLite differs from MySQL, and thus MySQL queries may not work in SQLite. The driver type for connections is &lt;tt&gt;sqlite&lt;/tt&gt;.<br /> <br /> ==Usage==<br /> Since SQLite is local only, most of the connection parameters can be ignored. The only connection parameter required is &lt;tt&gt;database&lt;/tt&gt;, which specifies the file name of the database. Databases are created on demand if they do not already exist, and are stored in &lt;tt&gt;addons/sourcemod/data/sqlite&lt;/tt&gt;. An extension of &quot;.sq3&quot; is automatically appended to the file name.<br /> <br /> Additionally, you can specify sub-folders in the database name. For example, &quot;cssdm/players&quot; will become &lt;tt&gt;addons/sourcemod/data/sqlite/cssdm/players.sq3&lt;/tt&gt;.<br /> <br /> SQLite supports the threading layer, and requires all of the same rules as the MySQL driver (including locks on shared connections).<br /> <br /> ==External Links==<br /> *[http://www.sqlite.org SQLite Homepage]<br /> *[http://sqlitebrowser.sourceforge.net/ SQLite Browser]<br /> <br /> <br /> [[Category:SourceMod Scripting]]<br /> <br /> {{LanguageSwitch}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=SQL_(SourceMod_Scripting)&diff=10104 2016-02-10T03:53:26Z

<p>Xerox8521: /* Prepared Statements */ Updated to Transitional Syntax</p> <hr /> <div>This article is an introduction to using SourceMod's SQL features. It is not an introduction or tutorial about SQL or any specific SQL implementation.<br /> <br /> SourceMod's SQL layer is formally called ''DBI'', or the '''D'''ata'''b'''ase '''I'''nterface. The interface is a generic abstraction of common SQL functions. To connect to a specific database implementation (such as MySQL, or sqLite), a SourceMod DBI &quot;driver&quot; must be loaded. Currently, there are drivers for MySQL and SQLite<br /> <br /> SourceMod automatically detects and loads drivers on demand (if they exist, of course). All database natives are in &lt;tt&gt;scripting/include/dbi.inc&lt;/tt&gt;. The C++ API is in &lt;tt&gt;public/IDBDriver.h&lt;/tt&gt;.<br /> <br /> =Connecting=<br /> There are two ways to connect to a database. The first is through named configurations. Named configurations are preset configurations listed in &lt;tt&gt;configs/databases.cfg&lt;/tt&gt;. SourceMod specifies that if SQL is being used, there should always be one configuration named &quot;default.&quot;<br /> <br /> An example of such a configuration looks like:<br /> &lt;pre&gt; &quot;default&quot;<br /> {<br /> &quot;host&quot; &quot;localhost&quot;<br /> &quot;database&quot; &quot;sourcemod&quot;<br /> &quot;user&quot; &quot;root&quot;<br /> &quot;pass&quot; &quot;&quot;<br /> //&quot;timeout&quot; &quot;0&quot;<br /> //&quot;port&quot; &quot;0&quot;<br /> }&lt;/pre&gt;<br /> <br /> Connections based on named configurations can be instantiated with either &lt;tt&gt;SQL_Connect&lt;/tt&gt; or &lt;tt&gt;SQL_DefConnect&lt;/tt&gt;. <br /> <br /> The other option is to use &lt;tt&gt;SQL_ConnectCustom&lt;/tt&gt; and manually specify all connection parameters by passing a keyvalue handle containing them.<br /> <br /> Example of a typical connection:<br /> &lt;pawn&gt;char error[255];<br /> Database db = SQL_DefConnect(error, sizeof(error));<br /> <br /> if (db == null)<br /> {<br /> PrintToServer(&quot;Could not connect: %s&quot;, error);<br /> } <br /> else <br /> {<br /> delete db;<br /> }&lt;/pawn&gt;<br /> <br /> =Queries=<br /> <br /> ==No Results==<br /> The simplest queries are ones which do not return results -- for example, CREATE, DROP, UPDATE, INSERT, and DELETE. For such queries it is recommended to use &lt;tt&gt;SQL_FastQuery()&lt;/tt&gt;. The name does not imply that the query will be faster, but rather, it is faster to write code using this function. For example, given that &lt;tt&gt;db&lt;/tt&gt; is a valid database Handle:<br /> <br /> &lt;pawn&gt;if (!SQL_FastQuery(db, &quot;UPDATE stats SET players = players + 1&quot;))<br /> {<br /> char error[255];<br /> SQL_GetError(db, error, sizeof(error));<br /> PrintToServer(&quot;Failed to query (error: %s)&quot;, error);<br /> }&lt;/pawn&gt;<br /> <br /> ==Results==<br /> If a query returns a result set and the results must be processed, you must use &lt;tt&gt;SQL_Query()&lt;/tt&gt;. Unlike &lt;tt&gt;SQL_FastQuery()&lt;/tt&gt;, this function returns a Handle which must be closed.<br /> <br /> An example of a query which will produce results is:<br /> &lt;pawn&gt;DBResultSet query = SQL_Query(db, &quot;SELECT userid FROM vb_user WHERE username = 'BAILOPAN'&quot;);<br /> if (query == null)<br /> {<br /> char error[255];<br /> SQL_GetError(db, error, sizeof(error));<br /> PrintToServer(&quot;Failed to query (error: %s)&quot;, error);<br /> } <br /> else <br /> {<br /> /* Process results here!<br /> */<br /> <br /> /* Free the Handle */<br /> delete query;<br /> }&lt;/pawn&gt;<br /> <br /> =Prepared Statements=<br /> Prepared statements are another method of querying. The idea behind a prepared statement is that you construct a query &quot;template&quot; once, and re-use it as many times as needed. Prepared statements have the following benefits:<br /> *A good SQL implementation will be able to cache the query better if it is a prepared statement.<br /> *You don't have to rebuild the entire query string every execution.<br /> *You don't have to allocate a new query structure on every execution.<br /> *Input is &quot;always&quot; secure (more on this later).<br /> <br /> A prepared statement has &quot;markers&quot; for inputs. For example, let's consider a function that takes in a database Handle and a name, and retrieves some info from a table:<br /> &lt;pawn&gt;int GetSomeInfo(Database db, const char[] name)<br /> {<br /> DBResultSet hQuery;<br /> char query[100];<br /> <br /> /* Create enough space to make sure our string is quoted properly */<br /> int buffer_len = strlen(name) * 2 + 1;<br /> char[] new_name = new char[buffer_len];<br /> <br /> /* Ask the SQL driver to make sure our string is safely quoted */<br /> SQL_EscapeString(db, name, new_name, buffer_len);<br /> <br /> /* Build the query */<br /> Format(query, sizeof(query), &quot;SELECT userid FROM vb_user WHERE username = '%s'&quot;, new_name);<br /> <br /> /* Execute the query */<br /> if ((hQuery = SQL_Query(query)) == null)<br /> {<br /> return 0;<br /> }<br /> <br /> /* Get some info here<br /> */<br /> <br /> delete hQuery;<br /> }&lt;/pawn&gt;<br /> <br /> Observe a version with prepared statements:<br /> &lt;pawn&gt;DBStatement hUserStmt = null;<br /> int GetSomeInfo(Database db, const char[] name)<br /> {<br /> /* Check if we haven't already created the statement */<br /> if (hUserStmt == null)<br /> {<br /> char error[255];<br /> hUserStmt = SQL_PrepareQuery(db, &quot;SELECT userid FROM vb_user WHERE username = ?&quot;, error, sizeof(error));<br /> if (hUserStmt == null)<br /> {<br /> return 0;<br /> }<br /> }<br /> <br /> SQL_BindParamString(hUserStmt, 0, name, false);<br /> if (!SQL_Execute(hUserStmt))<br /> {<br /> return 0;<br /> }<br /> <br /> /**<br /> * Get some info here<br /> */<br /> }&lt;/pawn&gt;<br /> <br /> The important differences:<br /> *The input string (&lt;tt&gt;name&lt;/tt&gt;) did not need to be backticked (quoted). The SQL engine automatically performs all type safety and insertion checks.<br /> *There was no need for quotation marks around the parameter marker, &lt;tt&gt;?&lt;/tt&gt;, even though it accepted a string.<br /> *We only needed to create the statement Handle once; after that it can live for the lifetime of the database connection.<br /> <br /> =Processing Results=<br /> Processing results is done in the same manner for both normal queries and prepared statements. The important functions are:<br /> *&lt;tt&gt;SQL_GetRowCount()&lt;/tt&gt; - Returns the number of rows.<br /> *&lt;tt&gt;SQL_FetchRow()&lt;/tt&gt; - Fetches the next row if one is available.<br /> *&lt;tt&gt;SQL_Fetch[Int|String|Float]()&lt;/tt&gt; - Fetches data from a field in the current row.<br /> <br /> Let's consider a sample table that looks like this:<br /> &lt;pawn&gt;CREATE TABLE users (<br /> name VARCHAR(64) NOT NULL PRIMARY KEY,<br /> age INT UNSIGNED NOT NULL<br /> );&lt;/pawn&gt;<br /> <br /> The following example has code that will print out all users matching a certain age. There is an example for both prepared statements and normal queries.<br /> &lt;pawn&gt;PrintResults(Handle:query)<br /> {<br /> /* Even if we have just one row, you must call SQL_FetchRow() first */<br /> new String:name[65]<br /> while (SQL_FetchRow(query))<br /> {<br /> SQL_FetchString(query, 0, name, sizeof(name))<br /> PrintToServer(&quot;Name \&quot;%s\&quot; was found.&quot;, name)<br /> }<br /> }<br /> <br /> bool:GetByAge_Query(Handle:db, age)<br /> {<br /> new String:query[100]<br /> Format(query, sizeof(query), &quot;SELECT name FROM users WHERE age = %d&quot;, age)<br /> <br /> new Handle:hQuery = SQL_Query(db, query)<br /> if (hQuery == INVALID_HANDLE)<br /> {<br /> return false<br /> }<br /> <br /> PrintResults(hQuery)<br /> <br /> CloseHandle(hQuery)<br /> <br /> return true<br /> }<br /> <br /> new Handle:hAgeStmt = INVALID_HANDLE<br /> bool:GetByAge_Statement(Handle:db, age)<br /> {<br /> if (hAgeSmt == INVALID_HANDLE)<br /> {<br /> new String:error[255]<br /> if ((hAgeStmt = SQL_PrepareQuery(db, <br /> &quot;SELECT name FROM users WHERE age = ?&quot;, <br /> error, <br /> sizeof(error))) <br /> == INVALID_HANDLE)<br /> {<br /> return false<br /> }<br /> }<br /> <br /> SQL_BindParamInt(hAgeStmt, 0, age)<br /> if (!SQL_Execute(hAgeStmt))<br /> {<br /> return false<br /> }<br /> <br /> PrintResults(hAgeStmt)<br /> <br /> return true<br /> }&lt;/pawn&gt;<br /> <br /> Note that these examples did not close the statement Handles. These examples assume a global database instance that is only closed when the plugin is unloaded. For plugins which maintain temporary database connections, prepared statement Handles must be freed or else the database connection will never be closed.<br /> <br /> <br /> =Threading=<br /> SourceMod supports threaded SQL querying. That is, SQL operations can be completed in a separate thread from main gameplay. If your database server is remote or requires a network connection, queries can cause noticeable gameplay lag, and supporting threading is often a good idea if your queries occur in the middle of gameplay.<br /> <br /> Threaded queries are ''asynchronous''. That is, they are dispatched and you can only find the results through a callback. Although the callback is guaranteed to fire eventually, it may not fire in any specific given timeframe. Certain drivers may not support threading; if this is the case, an RTE will be thrown. If the threader cannot start or the threader is currently disabled, SourceMod will transparently execute the query in the main thread as a fallback.<br /> <br /> ==Operations==<br /> All threaded operations use the same callback for result notification: &lt;tt&gt;SQLTCallback&lt;/tt&gt;. The parameters are:<br /> *&lt;tt&gt;owner&lt;/tt&gt; - The &quot;owner&quot; of the operation. For a query, this is a database. For a database, this is a driver. If the owner was not found or was invalidated, &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; is passed.<br /> *&lt;tt&gt;hndl&lt;/tt&gt; - The object being requested. The value is defined by the SQL operation.<br /> *&lt;tt&gt;error&lt;/tt&gt; - An error string.<br /> *&lt;tt&gt;data&lt;/tt&gt; - Custom data that can be passed via some SQL operations.<br /> <br /> The following operations can be done via threads:<br /> *&lt;b&gt;Connection&lt;/b&gt;, via &lt;tt&gt;SQL_TConnect&lt;/tt&gt;.<br /> *&lt;b&gt;Querying&lt;/b&gt;, via &lt;tt&gt;SQL_TQuery()&lt;/tt&gt;.<br /> *''Note: prepared statements are not yet available for the threader.''<br /> <br /> It is always safe to chain one operation from another.<br /> <br /> ===Connecting===<br /> It is not necessary to make a threaded connection in order to make threaded queries. However, creating a threaded connection will not pause the game server if a connection cannot be immediately established. <br /> <br /> The following parameters are used for the threaded connection callback:<br /> *&lt;tt&gt;owner&lt;/tt&gt;: A Handle to the driver, or &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; if it could not be found.<br /> *&lt;tt&gt;hndl&lt;/tt&gt;: A Handle to the database, or &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; if the connection failed.<br /> *&lt;tt&gt;error&lt;/tt&gt;: The error string, if any.<br /> *&lt;tt&gt;data&lt;/tt&gt;: Unused (0)<br /> <br /> Example: <br /> &lt;pawn&gt;new Handle:hDatabase = INVALID_HANDLE;<br /> <br /> StartSQL()<br /> {<br /> SQL_TConnect(GotDatabase);<br /> }<br /> <br /> public GotDatabase(Handle:owner, Handle:hndl, const String:error[], any:data)<br /> {<br /> if (hndl == INVALID_HANDLE)<br /> {<br /> LogError(&quot;Database failure: %s&quot;, error);<br /> } else {<br /> hDatabase = hndl;<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> ===Querying===<br /> Threaded queries can be performed on any database Handle as long as the driver supports threading. All query results for the first result set are retrieved while in the thread. If your query returns more than one set of results (for example, &lt;tt&gt;CALL&lt;/tt&gt; on MySQL with certain functions), the behaviour of the threader is undefined at this time. &lt;b&gt;Note that if you want to perform both threaded and non-threaded queries on the same connection, you MUST read the &quot;Locking&quot; section below.&lt;/b&gt;<br /> <br /> Query operations use the following callback parameters:<br /> *&lt;tt&gt;owner&lt;/tt&gt;: A Handle to the database used to query. The Handle is not the same as the Handle originally passed; however, it will test positively with &lt;tt&gt;SQL_IsSameConnection&lt;/tt&gt;. The Handle can be cloned but it cannot be closed (it is closed automatically). It may be &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; in the case of a serious error (for example, the driver being unloaded).<br /> *&lt;tt&gt;hndl&lt;/tt&gt;: A Handle to the query. It can be cloned, but not closed (it is closed automatically). It may be &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; if there was an error.<br /> *&lt;tt&gt;error&lt;/tt&gt;: Error string, if any.<br /> *&lt;tt&gt;data&lt;/tt&gt;: Optional user-defined data passed in through &lt;tt&gt;SQL_TQuery()&lt;/tt&gt;.<br /> <br /> Example, continuing from above:<br /> &lt;pawn&gt;CheckSteamID(userid, const String:auth[])<br /> {<br /> decl String:query[255];<br /> Format(query, sizeof(query), &quot;SELECT userid FROM users WHERE steamid = '%s'&quot;, auth);<br /> SQL_TQuery(hdatabase, T_CheckSteamID, query, userid)<br /> }<br /> <br /> public T_CheckSteamID(Handle:owner, Handle:hndl, const String:error[], any:data)<br /> {<br /> new client;<br /> <br /> /* Make sure the client didn't disconnect while the thread was running */<br /> if ((client = GetClientOfUserId(data)) == 0)<br /> {<br /> return;<br /> }<br /> <br /> if (hndl == INVALID_HANDLE)<br /> {<br /> LogError(&quot;Query failed! %s&quot;, error);<br /> KickClient(client, &quot;Authorization failed&quot;);<br /> } else if (!SQL_GetRowCount(hndl)) {<br /> KickClient(client, &quot;You are not a member&quot;);<br /> }<br /> }<br /> &lt;/pawn&gt;<br /> <br /> ==Locking==<br /> It is possible to run both threaded and non-threaded queries on the same connection. However, without the proper precautions, you could corrupt the network stream (even if it's local), corrupt memory, or otherwise cause a crash in the SQL driver. To solve this, SourceMod has ''database locking''. Locking is done via &lt;tt&gt;SQL_LockDatabase()&lt;/tt&gt; and &lt;tt&gt;SQL_UnlockDatabase&lt;/tt&gt;.<br /> <br /> Whenever performing any of the following non-threaded operations on a database, it is absolutely necessary to enclose the entire operation with a lock:<br /> *&lt;tt&gt;SQL_Query()&lt;/tt&gt; (and &lt;tt&gt;SQL_FetchMoreResults&lt;/tt&gt; pairings)<br /> *&lt;tt&gt;SQL_FastQuery&lt;/tt&gt;<br /> *&lt;tt&gt;SQL_PrepareQuery&lt;/tt&gt;<br /> *&lt;tt&gt;SQL_Bind*&lt;/tt&gt; and &lt;tt&gt;SQL_Execute&lt;/tt&gt; pairings<br /> <br /> The rule of thumb is: if your operation is going to use the database connection, it must be locked until the operation is fully completed. <br /> <br /> Example:<br /> &lt;pawn&gt;bool:GetByAge_Query(Handle:db, age)<br /> {<br /> new String:query[100]<br /> Format(query, sizeof(query), &quot;SELECT name FROM users WHERE age = %d&quot;, age)<br /> <br /> SQL_LockDatabase(db);<br /> new Handle:hQuery = SQL_Query(db, query)<br /> if (hQuery == INVALID_HANDLE)<br /> {<br /> SQL_UnlockDatabase(db);<br /> return false<br /> }<br /> SQL_UnlockDatabase(db);<br /> <br /> PrintResults(hQuery)<br /> <br /> CloseHandle(hQuery)<br /> <br /> return true<br /> }&lt;/pawn&gt;<br /> <br /> Note that it was only necessary to lock the query; SourceMod pre-fetches the result set, and thus the network queue is clean.<br /> <br /> ===Warnings===<br /> *&lt;b&gt;Never&lt;/b&gt; call &lt;tt&gt;SQL_LockDatabase&lt;/tt&gt; right before a threaded operation. You will deadlock the server and have to terminate/kill it. <br /> *&lt;b&gt;Always pair every Lock with an Unlock.&lt;/b&gt; Otherwise you risk a deadlock.<br /> *If your query returns multiple result sets, for example, a procedure call on MySQL that returns results, you must lock both the query and the entire fetch operation. SourceMod is only able to fetch one result set at a time, and all result sets must be cleared before a new query is started.<br /> <br /> ==Priority==<br /> Threaded SQL operations are placed in a simple priority queue. The priority levels are &lt;tt&gt;High&lt;/tt&gt;, &lt;tt&gt;Medium&lt;/tt&gt;, and &lt;tt&gt;Low&lt;/tt&gt;. Connections always have the highest priority. <br /> <br /> Changing the priority can be useful if you have many queries with different purposes. For example, a statistics plugin might execute 10 queries on death, and one query on join. Because the statistics might rely on the join info, the join query might need to be high priority, while the death queries can be low priority.<br /> <br /> You should &lt;b&gt;never&lt;/b&gt; simply assign a high priority to all of your queries simply because you want them to get done fast. Not only does it not work that way, but you may be inserting subtle problems into other plugins by being greedy.<br /> <br /> <br /> =SQLite=<br /> ==Introduction==<br /> [http://www.sqlite.org/ SQLite] is a fast local-file SQL database engine and SourceMod provides a DBI driver for it. SQLite differs from MySQL, and thus MySQL queries may not work in SQLite. The driver type for connections is &lt;tt&gt;sqlite&lt;/tt&gt;.<br /> <br /> ==Usage==<br /> Since SQLite is local only, most of the connection parameters can be ignored. The only connection parameter required is &lt;tt&gt;database&lt;/tt&gt;, which specifies the file name of the database. Databases are created on demand if they do not already exist, and are stored in &lt;tt&gt;addons/sourcemod/data/sqlite&lt;/tt&gt;. An extension of &quot;.sq3&quot; is automatically appended to the file name.<br /> <br /> Additionally, you can specify sub-folders in the database name. For example, &quot;cssdm/players&quot; will become &lt;tt&gt;addons/sourcemod/data/sqlite/cssdm/players.sq3&lt;/tt&gt;.<br /> <br /> SQLite supports the threading layer, and requires all of the same rules as the MySQL driver (including locks on shared connections).<br /> <br /> ==External Links==<br /> *[http://www.sqlite.org SQLite Homepage]<br /> *[http://sqlitebrowser.sourceforge.net/ SQLite Browser]<br /> <br /> <br /> [[Category:SourceMod Scripting]]<br /> <br /> {{LanguageSwitch}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=SQL_(SourceMod_Scripting)&diff=10103 2016-02-10T03:48:16Z

<p>Xerox8521: /* Results */ Updated to Transitional Syntax</p> <hr /> <div>This article is an introduction to using SourceMod's SQL features. It is not an introduction or tutorial about SQL or any specific SQL implementation.<br /> <br /> SourceMod's SQL layer is formally called ''DBI'', or the '''D'''ata'''b'''ase '''I'''nterface. The interface is a generic abstraction of common SQL functions. To connect to a specific database implementation (such as MySQL, or sqLite), a SourceMod DBI &quot;driver&quot; must be loaded. Currently, there are drivers for MySQL and SQLite<br /> <br /> SourceMod automatically detects and loads drivers on demand (if they exist, of course). All database natives are in &lt;tt&gt;scripting/include/dbi.inc&lt;/tt&gt;. The C++ API is in &lt;tt&gt;public/IDBDriver.h&lt;/tt&gt;.<br /> <br /> =Connecting=<br /> There are two ways to connect to a database. The first is through named configurations. Named configurations are preset configurations listed in &lt;tt&gt;configs/databases.cfg&lt;/tt&gt;. SourceMod specifies that if SQL is being used, there should always be one configuration named &quot;default.&quot;<br /> <br /> An example of such a configuration looks like:<br /> &lt;pre&gt; &quot;default&quot;<br /> {<br /> &quot;host&quot; &quot;localhost&quot;<br /> &quot;database&quot; &quot;sourcemod&quot;<br /> &quot;user&quot; &quot;root&quot;<br /> &quot;pass&quot; &quot;&quot;<br /> //&quot;timeout&quot; &quot;0&quot;<br /> //&quot;port&quot; &quot;0&quot;<br /> }&lt;/pre&gt;<br /> <br /> Connections based on named configurations can be instantiated with either &lt;tt&gt;SQL_Connect&lt;/tt&gt; or &lt;tt&gt;SQL_DefConnect&lt;/tt&gt;. <br /> <br /> The other option is to use &lt;tt&gt;SQL_ConnectCustom&lt;/tt&gt; and manually specify all connection parameters by passing a keyvalue handle containing them.<br /> <br /> Example of a typical connection:<br /> &lt;pawn&gt;char error[255];<br /> Database db = SQL_DefConnect(error, sizeof(error));<br /> <br /> if (db == null)<br /> {<br /> PrintToServer(&quot;Could not connect: %s&quot;, error);<br /> } <br /> else <br /> {<br /> delete db;<br /> }&lt;/pawn&gt;<br /> <br /> =Queries=<br /> <br /> ==No Results==<br /> The simplest queries are ones which do not return results -- for example, CREATE, DROP, UPDATE, INSERT, and DELETE. For such queries it is recommended to use &lt;tt&gt;SQL_FastQuery()&lt;/tt&gt;. The name does not imply that the query will be faster, but rather, it is faster to write code using this function. For example, given that &lt;tt&gt;db&lt;/tt&gt; is a valid database Handle:<br /> <br /> &lt;pawn&gt;if (!SQL_FastQuery(db, &quot;UPDATE stats SET players = players + 1&quot;))<br /> {<br /> char error[255];<br /> SQL_GetError(db, error, sizeof(error));<br /> PrintToServer(&quot;Failed to query (error: %s)&quot;, error);<br /> }&lt;/pawn&gt;<br /> <br /> ==Results==<br /> If a query returns a result set and the results must be processed, you must use &lt;tt&gt;SQL_Query()&lt;/tt&gt;. Unlike &lt;tt&gt;SQL_FastQuery()&lt;/tt&gt;, this function returns a Handle which must be closed.<br /> <br /> An example of a query which will produce results is:<br /> &lt;pawn&gt;DBResultSet query = SQL_Query(db, &quot;SELECT userid FROM vb_user WHERE username = 'BAILOPAN'&quot;);<br /> if (query == null)<br /> {<br /> char error[255];<br /> SQL_GetError(db, error, sizeof(error));<br /> PrintToServer(&quot;Failed to query (error: %s)&quot;, error);<br /> } <br /> else <br /> {<br /> /* Process results here!<br /> */<br /> <br /> /* Free the Handle */<br /> delete query;<br /> }&lt;/pawn&gt;<br /> <br /> =Prepared Statements=<br /> Prepared statements are another method of querying. The idea behind a prepared statement is that you construct a query &quot;template&quot; once, and re-use it as many times as needed. Prepared statements have the following benefits:<br /> *A good SQL implementation will be able to cache the query better if it is a prepared statement.<br /> *You don't have to rebuild the entire query string every execution.<br /> *You don't have to allocate a new query structure on every execution.<br /> *Input is &quot;always&quot; secure (more on this later).<br /> <br /> A prepared statement has &quot;markers&quot; for inputs. For example, let's consider a function that takes in a database Handle and a name, and retrieves some info from a table:<br /> &lt;pawn&gt;GetSomeInfo(Handle:db, const String:name[])<br /> {<br /> new Handle:hQuery<br /> new String:query[100]<br /> <br /> /* Create enough space to make sure our string is quoted properly */<br /> new buffer_len = strlen(name) * 2 + 1<br /> new String:new_name[buffer_len]<br /> <br /> /* Ask the SQL driver to make sure our string is safely quoted */<br /> SQL_EscapeString(db, name, new_name, buffer_len)<br /> <br /> /* Build the query */<br /> Format(query, sizeof(query), &quot;SELECT userid FROM vb_user WHERE username = '%s'&quot;, new_name)<br /> <br /> /* Execute the query */<br /> if ((hQuery = SQL_Query(query)) == INVALID_HANDLE)<br /> {<br /> return 0<br /> }<br /> <br /> /* Get some info here<br /> */<br /> <br /> CloseHandle(hQuery)<br /> }&lt;/pawn&gt;<br /> <br /> Observe a version with prepared statements:<br /> &lt;pawn&gt;new Handle:hUserStmt = INVALID_HANDLE;<br /> GetSomeInfo(Handle:db, const String:name[])<br /> {<br /> /* Check if we haven't already created the statement */<br /> if (hUserStmt == INVALID_HANDLE)<br /> {<br /> new String:error[255]<br /> hUserStmt = SQL_PrepareQuery(db, &quot;SELECT userid FROM vb_user WHERE username = ?&quot;, error, sizeof(error));<br /> if (hUserStmt == INVALID_HANDLE)<br /> {<br /> return 0;<br /> }<br /> }<br /> <br /> SQL_BindParamString(hUserStmt, 0, name, false);<br /> if (!SQL_Execute(hUserStmt))<br /> {<br /> return 0;<br /> }<br /> <br /> /**<br /> * Get some info here<br /> */<br /> }&lt;/pawn&gt;<br /> <br /> The important differences:<br /> *The input string (&lt;tt&gt;name&lt;/tt&gt;) did not need to be backticked (quoted). The SQL engine automatically performs all type safety and insertion checks.<br /> *There was no need for quotation marks around the parameter marker, &lt;tt&gt;?&lt;/tt&gt;, even though it accepted a string.<br /> *We only needed to create the statement Handle once; after that it can live for the lifetime of the database connection.<br /> <br /> =Processing Results=<br /> Processing results is done in the same manner for both normal queries and prepared statements. The important functions are:<br /> *&lt;tt&gt;SQL_GetRowCount()&lt;/tt&gt; - Returns the number of rows.<br /> *&lt;tt&gt;SQL_FetchRow()&lt;/tt&gt; - Fetches the next row if one is available.<br /> *&lt;tt&gt;SQL_Fetch[Int|String|Float]()&lt;/tt&gt; - Fetches data from a field in the current row.<br /> <br /> Let's consider a sample table that looks like this:<br /> &lt;pawn&gt;CREATE TABLE users (<br /> name VARCHAR(64) NOT NULL PRIMARY KEY,<br /> age INT UNSIGNED NOT NULL<br /> );&lt;/pawn&gt;<br /> <br /> The following example has code that will print out all users matching a certain age. There is an example for both prepared statements and normal queries.<br /> &lt;pawn&gt;PrintResults(Handle:query)<br /> {<br /> /* Even if we have just one row, you must call SQL_FetchRow() first */<br /> new String:name[65]<br /> while (SQL_FetchRow(query))<br /> {<br /> SQL_FetchString(query, 0, name, sizeof(name))<br /> PrintToServer(&quot;Name \&quot;%s\&quot; was found.&quot;, name)<br /> }<br /> }<br /> <br /> bool:GetByAge_Query(Handle:db, age)<br /> {<br /> new String:query[100]<br /> Format(query, sizeof(query), &quot;SELECT name FROM users WHERE age = %d&quot;, age)<br /> <br /> new Handle:hQuery = SQL_Query(db, query)<br /> if (hQuery == INVALID_HANDLE)<br /> {<br /> return false<br /> }<br /> <br /> PrintResults(hQuery)<br /> <br /> CloseHandle(hQuery)<br /> <br /> return true<br /> }<br /> <br /> new Handle:hAgeStmt = INVALID_HANDLE<br /> bool:GetByAge_Statement(Handle:db, age)<br /> {<br /> if (hAgeSmt == INVALID_HANDLE)<br /> {<br /> new String:error[255]<br /> if ((hAgeStmt = SQL_PrepareQuery(db, <br /> &quot;SELECT name FROM users WHERE age = ?&quot;, <br /> error, <br /> sizeof(error))) <br /> == INVALID_HANDLE)<br /> {<br /> return false<br /> }<br /> }<br /> <br /> SQL_BindParamInt(hAgeStmt, 0, age)<br /> if (!SQL_Execute(hAgeStmt))<br /> {<br /> return false<br /> }<br /> <br /> PrintResults(hAgeStmt)<br /> <br /> return true<br /> }&lt;/pawn&gt;<br /> <br /> Note that these examples did not close the statement Handles. These examples assume a global database instance that is only closed when the plugin is unloaded. For plugins which maintain temporary database connections, prepared statement Handles must be freed or else the database connection will never be closed.<br /> <br /> <br /> =Threading=<br /> SourceMod supports threaded SQL querying. That is, SQL operations can be completed in a separate thread from main gameplay. If your database server is remote or requires a network connection, queries can cause noticeable gameplay lag, and supporting threading is often a good idea if your queries occur in the middle of gameplay.<br /> <br /> Threaded queries are ''asynchronous''. That is, they are dispatched and you can only find the results through a callback. Although the callback is guaranteed to fire eventually, it may not fire in any specific given timeframe. Certain drivers may not support threading; if this is the case, an RTE will be thrown. If the threader cannot start or the threader is currently disabled, SourceMod will transparently execute the query in the main thread as a fallback.<br /> <br /> ==Operations==<br /> All threaded operations use the same callback for result notification: &lt;tt&gt;SQLTCallback&lt;/tt&gt;. The parameters are:<br /> *&lt;tt&gt;owner&lt;/tt&gt; - The &quot;owner&quot; of the operation. For a query, this is a database. For a database, this is a driver. If the owner was not found or was invalidated, &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; is passed.<br /> *&lt;tt&gt;hndl&lt;/tt&gt; - The object being requested. The value is defined by the SQL operation.<br /> *&lt;tt&gt;error&lt;/tt&gt; - An error string.<br /> *&lt;tt&gt;data&lt;/tt&gt; - Custom data that can be passed via some SQL operations.<br /> <br /> The following operations can be done via threads:<br /> *&lt;b&gt;Connection&lt;/b&gt;, via &lt;tt&gt;SQL_TConnect&lt;/tt&gt;.<br /> *&lt;b&gt;Querying&lt;/b&gt;, via &lt;tt&gt;SQL_TQuery()&lt;/tt&gt;.<br /> *''Note: prepared statements are not yet available for the threader.''<br /> <br /> It is always safe to chain one operation from another.<br /> <br /> ===Connecting===<br /> It is not necessary to make a threaded connection in order to make threaded queries. However, creating a threaded connection will not pause the game server if a connection cannot be immediately established. <br /> <br /> The following parameters are used for the threaded connection callback:<br /> *&lt;tt&gt;owner&lt;/tt&gt;: A Handle to the driver, or &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; if it could not be found.<br /> *&lt;tt&gt;hndl&lt;/tt&gt;: A Handle to the database, or &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; if the connection failed.<br /> *&lt;tt&gt;error&lt;/tt&gt;: The error string, if any.<br /> *&lt;tt&gt;data&lt;/tt&gt;: Unused (0)<br /> <br /> Example: <br /> &lt;pawn&gt;new Handle:hDatabase = INVALID_HANDLE;<br /> <br /> StartSQL()<br /> {<br /> SQL_TConnect(GotDatabase);<br /> }<br /> <br /> public GotDatabase(Handle:owner, Handle:hndl, const String:error[], any:data)<br /> {<br /> if (hndl == INVALID_HANDLE)<br /> {<br /> LogError(&quot;Database failure: %s&quot;, error);<br /> } else {<br /> hDatabase = hndl;<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> ===Querying===<br /> Threaded queries can be performed on any database Handle as long as the driver supports threading. All query results for the first result set are retrieved while in the thread. If your query returns more than one set of results (for example, &lt;tt&gt;CALL&lt;/tt&gt; on MySQL with certain functions), the behaviour of the threader is undefined at this time. &lt;b&gt;Note that if you want to perform both threaded and non-threaded queries on the same connection, you MUST read the &quot;Locking&quot; section below.&lt;/b&gt;<br /> <br /> Query operations use the following callback parameters:<br /> *&lt;tt&gt;owner&lt;/tt&gt;: A Handle to the database used to query. The Handle is not the same as the Handle originally passed; however, it will test positively with &lt;tt&gt;SQL_IsSameConnection&lt;/tt&gt;. The Handle can be cloned but it cannot be closed (it is closed automatically). It may be &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; in the case of a serious error (for example, the driver being unloaded).<br /> *&lt;tt&gt;hndl&lt;/tt&gt;: A Handle to the query. It can be cloned, but not closed (it is closed automatically). It may be &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; if there was an error.<br /> *&lt;tt&gt;error&lt;/tt&gt;: Error string, if any.<br /> *&lt;tt&gt;data&lt;/tt&gt;: Optional user-defined data passed in through &lt;tt&gt;SQL_TQuery()&lt;/tt&gt;.<br /> <br /> Example, continuing from above:<br /> &lt;pawn&gt;CheckSteamID(userid, const String:auth[])<br /> {<br /> decl String:query[255];<br /> Format(query, sizeof(query), &quot;SELECT userid FROM users WHERE steamid = '%s'&quot;, auth);<br /> SQL_TQuery(hdatabase, T_CheckSteamID, query, userid)<br /> }<br /> <br /> public T_CheckSteamID(Handle:owner, Handle:hndl, const String:error[], any:data)<br /> {<br /> new client;<br /> <br /> /* Make sure the client didn't disconnect while the thread was running */<br /> if ((client = GetClientOfUserId(data)) == 0)<br /> {<br /> return;<br /> }<br /> <br /> if (hndl == INVALID_HANDLE)<br /> {<br /> LogError(&quot;Query failed! %s&quot;, error);<br /> KickClient(client, &quot;Authorization failed&quot;);<br /> } else if (!SQL_GetRowCount(hndl)) {<br /> KickClient(client, &quot;You are not a member&quot;);<br /> }<br /> }<br /> &lt;/pawn&gt;<br /> <br /> ==Locking==<br /> It is possible to run both threaded and non-threaded queries on the same connection. However, without the proper precautions, you could corrupt the network stream (even if it's local), corrupt memory, or otherwise cause a crash in the SQL driver. To solve this, SourceMod has ''database locking''. Locking is done via &lt;tt&gt;SQL_LockDatabase()&lt;/tt&gt; and &lt;tt&gt;SQL_UnlockDatabase&lt;/tt&gt;.<br /> <br /> Whenever performing any of the following non-threaded operations on a database, it is absolutely necessary to enclose the entire operation with a lock:<br /> *&lt;tt&gt;SQL_Query()&lt;/tt&gt; (and &lt;tt&gt;SQL_FetchMoreResults&lt;/tt&gt; pairings)<br /> *&lt;tt&gt;SQL_FastQuery&lt;/tt&gt;<br /> *&lt;tt&gt;SQL_PrepareQuery&lt;/tt&gt;<br /> *&lt;tt&gt;SQL_Bind*&lt;/tt&gt; and &lt;tt&gt;SQL_Execute&lt;/tt&gt; pairings<br /> <br /> The rule of thumb is: if your operation is going to use the database connection, it must be locked until the operation is fully completed. <br /> <br /> Example:<br /> &lt;pawn&gt;bool:GetByAge_Query(Handle:db, age)<br /> {<br /> new String:query[100]<br /> Format(query, sizeof(query), &quot;SELECT name FROM users WHERE age = %d&quot;, age)<br /> <br /> SQL_LockDatabase(db);<br /> new Handle:hQuery = SQL_Query(db, query)<br /> if (hQuery == INVALID_HANDLE)<br /> {<br /> SQL_UnlockDatabase(db);<br /> return false<br /> }<br /> SQL_UnlockDatabase(db);<br /> <br /> PrintResults(hQuery)<br /> <br /> CloseHandle(hQuery)<br /> <br /> return true<br /> }&lt;/pawn&gt;<br /> <br /> Note that it was only necessary to lock the query; SourceMod pre-fetches the result set, and thus the network queue is clean.<br /> <br /> ===Warnings===<br /> *&lt;b&gt;Never&lt;/b&gt; call &lt;tt&gt;SQL_LockDatabase&lt;/tt&gt; right before a threaded operation. You will deadlock the server and have to terminate/kill it. <br /> *&lt;b&gt;Always pair every Lock with an Unlock.&lt;/b&gt; Otherwise you risk a deadlock.<br /> *If your query returns multiple result sets, for example, a procedure call on MySQL that returns results, you must lock both the query and the entire fetch operation. SourceMod is only able to fetch one result set at a time, and all result sets must be cleared before a new query is started.<br /> <br /> ==Priority==<br /> Threaded SQL operations are placed in a simple priority queue. The priority levels are &lt;tt&gt;High&lt;/tt&gt;, &lt;tt&gt;Medium&lt;/tt&gt;, and &lt;tt&gt;Low&lt;/tt&gt;. Connections always have the highest priority. <br /> <br /> Changing the priority can be useful if you have many queries with different purposes. For example, a statistics plugin might execute 10 queries on death, and one query on join. Because the statistics might rely on the join info, the join query might need to be high priority, while the death queries can be low priority.<br /> <br /> You should &lt;b&gt;never&lt;/b&gt; simply assign a high priority to all of your queries simply because you want them to get done fast. Not only does it not work that way, but you may be inserting subtle problems into other plugins by being greedy.<br /> <br /> <br /> =SQLite=<br /> ==Introduction==<br /> [http://www.sqlite.org/ SQLite] is a fast local-file SQL database engine and SourceMod provides a DBI driver for it. SQLite differs from MySQL, and thus MySQL queries may not work in SQLite. The driver type for connections is &lt;tt&gt;sqlite&lt;/tt&gt;.<br /> <br /> ==Usage==<br /> Since SQLite is local only, most of the connection parameters can be ignored. The only connection parameter required is &lt;tt&gt;database&lt;/tt&gt;, which specifies the file name of the database. Databases are created on demand if they do not already exist, and are stored in &lt;tt&gt;addons/sourcemod/data/sqlite&lt;/tt&gt;. An extension of &quot;.sq3&quot; is automatically appended to the file name.<br /> <br /> Additionally, you can specify sub-folders in the database name. For example, &quot;cssdm/players&quot; will become &lt;tt&gt;addons/sourcemod/data/sqlite/cssdm/players.sq3&lt;/tt&gt;.<br /> <br /> SQLite supports the threading layer, and requires all of the same rules as the MySQL driver (including locks on shared connections).<br /> <br /> ==External Links==<br /> *[http://www.sqlite.org SQLite Homepage]<br /> *[http://sqlitebrowser.sourceforge.net/ SQLite Browser]<br /> <br /> <br /> [[Category:SourceMod Scripting]]<br /> <br /> {{LanguageSwitch}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=SQL_(SourceMod_Scripting)&diff=10102 2016-02-10T03:46:30Z

<p>Xerox8521: /* No Results */ Updated to Transitional Syntax</p> <hr /> <div>This article is an introduction to using SourceMod's SQL features. It is not an introduction or tutorial about SQL or any specific SQL implementation.<br /> <br /> SourceMod's SQL layer is formally called ''DBI'', or the '''D'''ata'''b'''ase '''I'''nterface. The interface is a generic abstraction of common SQL functions. To connect to a specific database implementation (such as MySQL, or sqLite), a SourceMod DBI &quot;driver&quot; must be loaded. Currently, there are drivers for MySQL and SQLite<br /> <br /> SourceMod automatically detects and loads drivers on demand (if they exist, of course). All database natives are in &lt;tt&gt;scripting/include/dbi.inc&lt;/tt&gt;. The C++ API is in &lt;tt&gt;public/IDBDriver.h&lt;/tt&gt;.<br /> <br /> =Connecting=<br /> There are two ways to connect to a database. The first is through named configurations. Named configurations are preset configurations listed in &lt;tt&gt;configs/databases.cfg&lt;/tt&gt;. SourceMod specifies that if SQL is being used, there should always be one configuration named &quot;default.&quot;<br /> <br /> An example of such a configuration looks like:<br /> &lt;pre&gt; &quot;default&quot;<br /> {<br /> &quot;host&quot; &quot;localhost&quot;<br /> &quot;database&quot; &quot;sourcemod&quot;<br /> &quot;user&quot; &quot;root&quot;<br /> &quot;pass&quot; &quot;&quot;<br /> //&quot;timeout&quot; &quot;0&quot;<br /> //&quot;port&quot; &quot;0&quot;<br /> }&lt;/pre&gt;<br /> <br /> Connections based on named configurations can be instantiated with either &lt;tt&gt;SQL_Connect&lt;/tt&gt; or &lt;tt&gt;SQL_DefConnect&lt;/tt&gt;. <br /> <br /> The other option is to use &lt;tt&gt;SQL_ConnectCustom&lt;/tt&gt; and manually specify all connection parameters by passing a keyvalue handle containing them.<br /> <br /> Example of a typical connection:<br /> &lt;pawn&gt;char error[255];<br /> Database db = SQL_DefConnect(error, sizeof(error));<br /> <br /> if (db == null)<br /> {<br /> PrintToServer(&quot;Could not connect: %s&quot;, error);<br /> } <br /> else <br /> {<br /> delete db;<br /> }&lt;/pawn&gt;<br /> <br /> =Queries=<br /> <br /> ==No Results==<br /> The simplest queries are ones which do not return results -- for example, CREATE, DROP, UPDATE, INSERT, and DELETE. For such queries it is recommended to use &lt;tt&gt;SQL_FastQuery()&lt;/tt&gt;. The name does not imply that the query will be faster, but rather, it is faster to write code using this function. For example, given that &lt;tt&gt;db&lt;/tt&gt; is a valid database Handle:<br /> <br /> &lt;pawn&gt;if (!SQL_FastQuery(db, &quot;UPDATE stats SET players = players + 1&quot;))<br /> {<br /> char error[255];<br /> SQL_GetError(db, error, sizeof(error));<br /> PrintToServer(&quot;Failed to query (error: %s)&quot;, error);<br /> }&lt;/pawn&gt;<br /> <br /> ==Results==<br /> If a query returns a result set and the results must be processed, you must use &lt;tt&gt;SQL_Query()&lt;/tt&gt;. Unlike &lt;tt&gt;SQL_FastQuery()&lt;/tt&gt;, this function returns a Handle which must be closed.<br /> <br /> An example of a query which will produce results is:<br /> &lt;pawn&gt;new Handle:query = SQL_Query(db, &quot;SELECT userid FROM vb_user WHERE username = 'BAILOPAN'&quot;)<br /> if (query == INVALID_HANDLE)<br /> {<br /> new String:error[255]<br /> SQL_GetError(db, error, sizeof(error))<br /> PrintToServer(&quot;Failed to query (error: %s)&quot;, error)<br /> } else {<br /> /* Process results here!<br /> */<br /> <br /> /* Free the Handle */<br /> CloseHandle(query)<br /> }&lt;/pawn&gt;<br /> <br /> =Prepared Statements=<br /> Prepared statements are another method of querying. The idea behind a prepared statement is that you construct a query &quot;template&quot; once, and re-use it as many times as needed. Prepared statements have the following benefits:<br /> *A good SQL implementation will be able to cache the query better if it is a prepared statement.<br /> *You don't have to rebuild the entire query string every execution.<br /> *You don't have to allocate a new query structure on every execution.<br /> *Input is &quot;always&quot; secure (more on this later).<br /> <br /> A prepared statement has &quot;markers&quot; for inputs. For example, let's consider a function that takes in a database Handle and a name, and retrieves some info from a table:<br /> &lt;pawn&gt;GetSomeInfo(Handle:db, const String:name[])<br /> {<br /> new Handle:hQuery<br /> new String:query[100]<br /> <br /> /* Create enough space to make sure our string is quoted properly */<br /> new buffer_len = strlen(name) * 2 + 1<br /> new String:new_name[buffer_len]<br /> <br /> /* Ask the SQL driver to make sure our string is safely quoted */<br /> SQL_EscapeString(db, name, new_name, buffer_len)<br /> <br /> /* Build the query */<br /> Format(query, sizeof(query), &quot;SELECT userid FROM vb_user WHERE username = '%s'&quot;, new_name)<br /> <br /> /* Execute the query */<br /> if ((hQuery = SQL_Query(query)) == INVALID_HANDLE)<br /> {<br /> return 0<br /> }<br /> <br /> /* Get some info here<br /> */<br /> <br /> CloseHandle(hQuery)<br /> }&lt;/pawn&gt;<br /> <br /> Observe a version with prepared statements:<br /> &lt;pawn&gt;new Handle:hUserStmt = INVALID_HANDLE;<br /> GetSomeInfo(Handle:db, const String:name[])<br /> {<br /> /* Check if we haven't already created the statement */<br /> if (hUserStmt == INVALID_HANDLE)<br /> {<br /> new String:error[255]<br /> hUserStmt = SQL_PrepareQuery(db, &quot;SELECT userid FROM vb_user WHERE username = ?&quot;, error, sizeof(error));<br /> if (hUserStmt == INVALID_HANDLE)<br /> {<br /> return 0;<br /> }<br /> }<br /> <br /> SQL_BindParamString(hUserStmt, 0, name, false);<br /> if (!SQL_Execute(hUserStmt))<br /> {<br /> return 0;<br /> }<br /> <br /> /**<br /> * Get some info here<br /> */<br /> }&lt;/pawn&gt;<br /> <br /> The important differences:<br /> *The input string (&lt;tt&gt;name&lt;/tt&gt;) did not need to be backticked (quoted). The SQL engine automatically performs all type safety and insertion checks.<br /> *There was no need for quotation marks around the parameter marker, &lt;tt&gt;?&lt;/tt&gt;, even though it accepted a string.<br /> *We only needed to create the statement Handle once; after that it can live for the lifetime of the database connection.<br /> <br /> =Processing Results=<br /> Processing results is done in the same manner for both normal queries and prepared statements. The important functions are:<br /> *&lt;tt&gt;SQL_GetRowCount()&lt;/tt&gt; - Returns the number of rows.<br /> *&lt;tt&gt;SQL_FetchRow()&lt;/tt&gt; - Fetches the next row if one is available.<br /> *&lt;tt&gt;SQL_Fetch[Int|String|Float]()&lt;/tt&gt; - Fetches data from a field in the current row.<br /> <br /> Let's consider a sample table that looks like this:<br /> &lt;pawn&gt;CREATE TABLE users (<br /> name VARCHAR(64) NOT NULL PRIMARY KEY,<br /> age INT UNSIGNED NOT NULL<br /> );&lt;/pawn&gt;<br /> <br /> The following example has code that will print out all users matching a certain age. There is an example for both prepared statements and normal queries.<br /> &lt;pawn&gt;PrintResults(Handle:query)<br /> {<br /> /* Even if we have just one row, you must call SQL_FetchRow() first */<br /> new String:name[65]<br /> while (SQL_FetchRow(query))<br /> {<br /> SQL_FetchString(query, 0, name, sizeof(name))<br /> PrintToServer(&quot;Name \&quot;%s\&quot; was found.&quot;, name)<br /> }<br /> }<br /> <br /> bool:GetByAge_Query(Handle:db, age)<br /> {<br /> new String:query[100]<br /> Format(query, sizeof(query), &quot;SELECT name FROM users WHERE age = %d&quot;, age)<br /> <br /> new Handle:hQuery = SQL_Query(db, query)<br /> if (hQuery == INVALID_HANDLE)<br /> {<br /> return false<br /> }<br /> <br /> PrintResults(hQuery)<br /> <br /> CloseHandle(hQuery)<br /> <br /> return true<br /> }<br /> <br /> new Handle:hAgeStmt = INVALID_HANDLE<br /> bool:GetByAge_Statement(Handle:db, age)<br /> {<br /> if (hAgeSmt == INVALID_HANDLE)<br /> {<br /> new String:error[255]<br /> if ((hAgeStmt = SQL_PrepareQuery(db, <br /> &quot;SELECT name FROM users WHERE age = ?&quot;, <br /> error, <br /> sizeof(error))) <br /> == INVALID_HANDLE)<br /> {<br /> return false<br /> }<br /> }<br /> <br /> SQL_BindParamInt(hAgeStmt, 0, age)<br /> if (!SQL_Execute(hAgeStmt))<br /> {<br /> return false<br /> }<br /> <br /> PrintResults(hAgeStmt)<br /> <br /> return true<br /> }&lt;/pawn&gt;<br /> <br /> Note that these examples did not close the statement Handles. These examples assume a global database instance that is only closed when the plugin is unloaded. For plugins which maintain temporary database connections, prepared statement Handles must be freed or else the database connection will never be closed.<br /> <br /> <br /> =Threading=<br /> SourceMod supports threaded SQL querying. That is, SQL operations can be completed in a separate thread from main gameplay. If your database server is remote or requires a network connection, queries can cause noticeable gameplay lag, and supporting threading is often a good idea if your queries occur in the middle of gameplay.<br /> <br /> Threaded queries are ''asynchronous''. That is, they are dispatched and you can only find the results through a callback. Although the callback is guaranteed to fire eventually, it may not fire in any specific given timeframe. Certain drivers may not support threading; if this is the case, an RTE will be thrown. If the threader cannot start or the threader is currently disabled, SourceMod will transparently execute the query in the main thread as a fallback.<br /> <br /> ==Operations==<br /> All threaded operations use the same callback for result notification: &lt;tt&gt;SQLTCallback&lt;/tt&gt;. The parameters are:<br /> *&lt;tt&gt;owner&lt;/tt&gt; - The &quot;owner&quot; of the operation. For a query, this is a database. For a database, this is a driver. If the owner was not found or was invalidated, &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; is passed.<br /> *&lt;tt&gt;hndl&lt;/tt&gt; - The object being requested. The value is defined by the SQL operation.<br /> *&lt;tt&gt;error&lt;/tt&gt; - An error string.<br /> *&lt;tt&gt;data&lt;/tt&gt; - Custom data that can be passed via some SQL operations.<br /> <br /> The following operations can be done via threads:<br /> *&lt;b&gt;Connection&lt;/b&gt;, via &lt;tt&gt;SQL_TConnect&lt;/tt&gt;.<br /> *&lt;b&gt;Querying&lt;/b&gt;, via &lt;tt&gt;SQL_TQuery()&lt;/tt&gt;.<br /> *''Note: prepared statements are not yet available for the threader.''<br /> <br /> It is always safe to chain one operation from another.<br /> <br /> ===Connecting===<br /> It is not necessary to make a threaded connection in order to make threaded queries. However, creating a threaded connection will not pause the game server if a connection cannot be immediately established. <br /> <br /> The following parameters are used for the threaded connection callback:<br /> *&lt;tt&gt;owner&lt;/tt&gt;: A Handle to the driver, or &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; if it could not be found.<br /> *&lt;tt&gt;hndl&lt;/tt&gt;: A Handle to the database, or &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; if the connection failed.<br /> *&lt;tt&gt;error&lt;/tt&gt;: The error string, if any.<br /> *&lt;tt&gt;data&lt;/tt&gt;: Unused (0)<br /> <br /> Example: <br /> &lt;pawn&gt;new Handle:hDatabase = INVALID_HANDLE;<br /> <br /> StartSQL()<br /> {<br /> SQL_TConnect(GotDatabase);<br /> }<br /> <br /> public GotDatabase(Handle:owner, Handle:hndl, const String:error[], any:data)<br /> {<br /> if (hndl == INVALID_HANDLE)<br /> {<br /> LogError(&quot;Database failure: %s&quot;, error);<br /> } else {<br /> hDatabase = hndl;<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> ===Querying===<br /> Threaded queries can be performed on any database Handle as long as the driver supports threading. All query results for the first result set are retrieved while in the thread. If your query returns more than one set of results (for example, &lt;tt&gt;CALL&lt;/tt&gt; on MySQL with certain functions), the behaviour of the threader is undefined at this time. &lt;b&gt;Note that if you want to perform both threaded and non-threaded queries on the same connection, you MUST read the &quot;Locking&quot; section below.&lt;/b&gt;<br /> <br /> Query operations use the following callback parameters:<br /> *&lt;tt&gt;owner&lt;/tt&gt;: A Handle to the database used to query. The Handle is not the same as the Handle originally passed; however, it will test positively with &lt;tt&gt;SQL_IsSameConnection&lt;/tt&gt;. The Handle can be cloned but it cannot be closed (it is closed automatically). It may be &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; in the case of a serious error (for example, the driver being unloaded).<br /> *&lt;tt&gt;hndl&lt;/tt&gt;: A Handle to the query. It can be cloned, but not closed (it is closed automatically). It may be &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; if there was an error.<br /> *&lt;tt&gt;error&lt;/tt&gt;: Error string, if any.<br /> *&lt;tt&gt;data&lt;/tt&gt;: Optional user-defined data passed in through &lt;tt&gt;SQL_TQuery()&lt;/tt&gt;.<br /> <br /> Example, continuing from above:<br /> &lt;pawn&gt;CheckSteamID(userid, const String:auth[])<br /> {<br /> decl String:query[255];<br /> Format(query, sizeof(query), &quot;SELECT userid FROM users WHERE steamid = '%s'&quot;, auth);<br /> SQL_TQuery(hdatabase, T_CheckSteamID, query, userid)<br /> }<br /> <br /> public T_CheckSteamID(Handle:owner, Handle:hndl, const String:error[], any:data)<br /> {<br /> new client;<br /> <br /> /* Make sure the client didn't disconnect while the thread was running */<br /> if ((client = GetClientOfUserId(data)) == 0)<br /> {<br /> return;<br /> }<br /> <br /> if (hndl == INVALID_HANDLE)<br /> {<br /> LogError(&quot;Query failed! %s&quot;, error);<br /> KickClient(client, &quot;Authorization failed&quot;);<br /> } else if (!SQL_GetRowCount(hndl)) {<br /> KickClient(client, &quot;You are not a member&quot;);<br /> }<br /> }<br /> &lt;/pawn&gt;<br /> <br /> ==Locking==<br /> It is possible to run both threaded and non-threaded queries on the same connection. However, without the proper precautions, you could corrupt the network stream (even if it's local), corrupt memory, or otherwise cause a crash in the SQL driver. To solve this, SourceMod has ''database locking''. Locking is done via &lt;tt&gt;SQL_LockDatabase()&lt;/tt&gt; and &lt;tt&gt;SQL_UnlockDatabase&lt;/tt&gt;.<br /> <br /> Whenever performing any of the following non-threaded operations on a database, it is absolutely necessary to enclose the entire operation with a lock:<br /> *&lt;tt&gt;SQL_Query()&lt;/tt&gt; (and &lt;tt&gt;SQL_FetchMoreResults&lt;/tt&gt; pairings)<br /> *&lt;tt&gt;SQL_FastQuery&lt;/tt&gt;<br /> *&lt;tt&gt;SQL_PrepareQuery&lt;/tt&gt;<br /> *&lt;tt&gt;SQL_Bind*&lt;/tt&gt; and &lt;tt&gt;SQL_Execute&lt;/tt&gt; pairings<br /> <br /> The rule of thumb is: if your operation is going to use the database connection, it must be locked until the operation is fully completed. <br /> <br /> Example:<br /> &lt;pawn&gt;bool:GetByAge_Query(Handle:db, age)<br /> {<br /> new String:query[100]<br /> Format(query, sizeof(query), &quot;SELECT name FROM users WHERE age = %d&quot;, age)<br /> <br /> SQL_LockDatabase(db);<br /> new Handle:hQuery = SQL_Query(db, query)<br /> if (hQuery == INVALID_HANDLE)<br /> {<br /> SQL_UnlockDatabase(db);<br /> return false<br /> }<br /> SQL_UnlockDatabase(db);<br /> <br /> PrintResults(hQuery)<br /> <br /> CloseHandle(hQuery)<br /> <br /> return true<br /> }&lt;/pawn&gt;<br /> <br /> Note that it was only necessary to lock the query; SourceMod pre-fetches the result set, and thus the network queue is clean.<br /> <br /> ===Warnings===<br /> *&lt;b&gt;Never&lt;/b&gt; call &lt;tt&gt;SQL_LockDatabase&lt;/tt&gt; right before a threaded operation. You will deadlock the server and have to terminate/kill it. <br /> *&lt;b&gt;Always pair every Lock with an Unlock.&lt;/b&gt; Otherwise you risk a deadlock.<br /> *If your query returns multiple result sets, for example, a procedure call on MySQL that returns results, you must lock both the query and the entire fetch operation. SourceMod is only able to fetch one result set at a time, and all result sets must be cleared before a new query is started.<br /> <br /> ==Priority==<br /> Threaded SQL operations are placed in a simple priority queue. The priority levels are &lt;tt&gt;High&lt;/tt&gt;, &lt;tt&gt;Medium&lt;/tt&gt;, and &lt;tt&gt;Low&lt;/tt&gt;. Connections always have the highest priority. <br /> <br /> Changing the priority can be useful if you have many queries with different purposes. For example, a statistics plugin might execute 10 queries on death, and one query on join. Because the statistics might rely on the join info, the join query might need to be high priority, while the death queries can be low priority.<br /> <br /> You should &lt;b&gt;never&lt;/b&gt; simply assign a high priority to all of your queries simply because you want them to get done fast. Not only does it not work that way, but you may be inserting subtle problems into other plugins by being greedy.<br /> <br /> <br /> =SQLite=<br /> ==Introduction==<br /> [http://www.sqlite.org/ SQLite] is a fast local-file SQL database engine and SourceMod provides a DBI driver for it. SQLite differs from MySQL, and thus MySQL queries may not work in SQLite. The driver type for connections is &lt;tt&gt;sqlite&lt;/tt&gt;.<br /> <br /> ==Usage==<br /> Since SQLite is local only, most of the connection parameters can be ignored. The only connection parameter required is &lt;tt&gt;database&lt;/tt&gt;, which specifies the file name of the database. Databases are created on demand if they do not already exist, and are stored in &lt;tt&gt;addons/sourcemod/data/sqlite&lt;/tt&gt;. An extension of &quot;.sq3&quot; is automatically appended to the file name.<br /> <br /> Additionally, you can specify sub-folders in the database name. For example, &quot;cssdm/players&quot; will become &lt;tt&gt;addons/sourcemod/data/sqlite/cssdm/players.sq3&lt;/tt&gt;.<br /> <br /> SQLite supports the threading layer, and requires all of the same rules as the MySQL driver (including locks on shared connections).<br /> <br /> ==External Links==<br /> *[http://www.sqlite.org SQLite Homepage]<br /> *[http://sqlitebrowser.sourceforge.net/ SQLite Browser]<br /> <br /> <br /> [[Category:SourceMod Scripting]]<br /> <br /> {{LanguageSwitch}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=SQL_(SourceMod_Scripting)&diff=10101 2016-02-10T03:45:42Z

<p>Xerox8521: Updated to 1.7 Syntax</p> <hr /> <div>This article is an introduction to using SourceMod's SQL features. It is not an introduction or tutorial about SQL or any specific SQL implementation.<br /> <br /> SourceMod's SQL layer is formally called ''DBI'', or the '''D'''ata'''b'''ase '''I'''nterface. The interface is a generic abstraction of common SQL functions. To connect to a specific database implementation (such as MySQL, or sqLite), a SourceMod DBI &quot;driver&quot; must be loaded. Currently, there are drivers for MySQL and SQLite<br /> <br /> SourceMod automatically detects and loads drivers on demand (if they exist, of course). All database natives are in &lt;tt&gt;scripting/include/dbi.inc&lt;/tt&gt;. The C++ API is in &lt;tt&gt;public/IDBDriver.h&lt;/tt&gt;.<br /> <br /> =Connecting=<br /> There are two ways to connect to a database. The first is through named configurations. Named configurations are preset configurations listed in &lt;tt&gt;configs/databases.cfg&lt;/tt&gt;. SourceMod specifies that if SQL is being used, there should always be one configuration named &quot;default.&quot;<br /> <br /> An example of such a configuration looks like:<br /> &lt;pre&gt; &quot;default&quot;<br /> {<br /> &quot;host&quot; &quot;localhost&quot;<br /> &quot;database&quot; &quot;sourcemod&quot;<br /> &quot;user&quot; &quot;root&quot;<br /> &quot;pass&quot; &quot;&quot;<br /> //&quot;timeout&quot; &quot;0&quot;<br /> //&quot;port&quot; &quot;0&quot;<br /> }&lt;/pre&gt;<br /> <br /> Connections based on named configurations can be instantiated with either &lt;tt&gt;SQL_Connect&lt;/tt&gt; or &lt;tt&gt;SQL_DefConnect&lt;/tt&gt;. <br /> <br /> The other option is to use &lt;tt&gt;SQL_ConnectCustom&lt;/tt&gt; and manually specify all connection parameters by passing a keyvalue handle containing them.<br /> <br /> Example of a typical connection:<br /> &lt;pawn&gt;char error[255];<br /> Database db = SQL_DefConnect(error, sizeof(error));<br /> <br /> if (db == null)<br /> {<br /> PrintToServer(&quot;Could not connect: %s&quot;, error);<br /> } <br /> else <br /> {<br /> delete db;<br /> }&lt;/pawn&gt;<br /> <br /> =Queries=<br /> <br /> ==No Results==<br /> The simplest queries are ones which do not return results -- for example, CREATE, DROP, UPDATE, INSERT, and DELETE. For such queries it is recommended to use &lt;tt&gt;SQL_FastQuery()&lt;/tt&gt;. The name does not imply that the query will be faster, but rather, it is faster to write code using this function. For example, given that &lt;tt&gt;db&lt;/tt&gt; is a valid database Handle:<br /> <br /> &lt;pawn&gt;if (!SQL_FastQuery(db, &quot;UPDATE stats SET players = players + 1&quot;))<br /> {<br /> new String:error[255]<br /> SQL_GetError(db, error, sizeof(error))<br /> PrintToServer(&quot;Failed to query (error: %s)&quot;, error)<br /> }&lt;/pawn&gt;<br /> <br /> ==Results==<br /> If a query returns a result set and the results must be processed, you must use &lt;tt&gt;SQL_Query()&lt;/tt&gt;. Unlike &lt;tt&gt;SQL_FastQuery()&lt;/tt&gt;, this function returns a Handle which must be closed.<br /> <br /> An example of a query which will produce results is:<br /> &lt;pawn&gt;new Handle:query = SQL_Query(db, &quot;SELECT userid FROM vb_user WHERE username = 'BAILOPAN'&quot;)<br /> if (query == INVALID_HANDLE)<br /> {<br /> new String:error[255]<br /> SQL_GetError(db, error, sizeof(error))<br /> PrintToServer(&quot;Failed to query (error: %s)&quot;, error)<br /> } else {<br /> /* Process results here!<br /> */<br /> <br /> /* Free the Handle */<br /> CloseHandle(query)<br /> }&lt;/pawn&gt;<br /> <br /> =Prepared Statements=<br /> Prepared statements are another method of querying. The idea behind a prepared statement is that you construct a query &quot;template&quot; once, and re-use it as many times as needed. Prepared statements have the following benefits:<br /> *A good SQL implementation will be able to cache the query better if it is a prepared statement.<br /> *You don't have to rebuild the entire query string every execution.<br /> *You don't have to allocate a new query structure on every execution.<br /> *Input is &quot;always&quot; secure (more on this later).<br /> <br /> A prepared statement has &quot;markers&quot; for inputs. For example, let's consider a function that takes in a database Handle and a name, and retrieves some info from a table:<br /> &lt;pawn&gt;GetSomeInfo(Handle:db, const String:name[])<br /> {<br /> new Handle:hQuery<br /> new String:query[100]<br /> <br /> /* Create enough space to make sure our string is quoted properly */<br /> new buffer_len = strlen(name) * 2 + 1<br /> new String:new_name[buffer_len]<br /> <br /> /* Ask the SQL driver to make sure our string is safely quoted */<br /> SQL_EscapeString(db, name, new_name, buffer_len)<br /> <br /> /* Build the query */<br /> Format(query, sizeof(query), &quot;SELECT userid FROM vb_user WHERE username = '%s'&quot;, new_name)<br /> <br /> /* Execute the query */<br /> if ((hQuery = SQL_Query(query)) == INVALID_HANDLE)<br /> {<br /> return 0<br /> }<br /> <br /> /* Get some info here<br /> */<br /> <br /> CloseHandle(hQuery)<br /> }&lt;/pawn&gt;<br /> <br /> Observe a version with prepared statements:<br /> &lt;pawn&gt;new Handle:hUserStmt = INVALID_HANDLE;<br /> GetSomeInfo(Handle:db, const String:name[])<br /> {<br /> /* Check if we haven't already created the statement */<br /> if (hUserStmt == INVALID_HANDLE)<br /> {<br /> new String:error[255]<br /> hUserStmt = SQL_PrepareQuery(db, &quot;SELECT userid FROM vb_user WHERE username = ?&quot;, error, sizeof(error));<br /> if (hUserStmt == INVALID_HANDLE)<br /> {<br /> return 0;<br /> }<br /> }<br /> <br /> SQL_BindParamString(hUserStmt, 0, name, false);<br /> if (!SQL_Execute(hUserStmt))<br /> {<br /> return 0;<br /> }<br /> <br /> /**<br /> * Get some info here<br /> */<br /> }&lt;/pawn&gt;<br /> <br /> The important differences:<br /> *The input string (&lt;tt&gt;name&lt;/tt&gt;) did not need to be backticked (quoted). The SQL engine automatically performs all type safety and insertion checks.<br /> *There was no need for quotation marks around the parameter marker, &lt;tt&gt;?&lt;/tt&gt;, even though it accepted a string.<br /> *We only needed to create the statement Handle once; after that it can live for the lifetime of the database connection.<br /> <br /> =Processing Results=<br /> Processing results is done in the same manner for both normal queries and prepared statements. The important functions are:<br /> *&lt;tt&gt;SQL_GetRowCount()&lt;/tt&gt; - Returns the number of rows.<br /> *&lt;tt&gt;SQL_FetchRow()&lt;/tt&gt; - Fetches the next row if one is available.<br /> *&lt;tt&gt;SQL_Fetch[Int|String|Float]()&lt;/tt&gt; - Fetches data from a field in the current row.<br /> <br /> Let's consider a sample table that looks like this:<br /> &lt;pawn&gt;CREATE TABLE users (<br /> name VARCHAR(64) NOT NULL PRIMARY KEY,<br /> age INT UNSIGNED NOT NULL<br /> );&lt;/pawn&gt;<br /> <br /> The following example has code that will print out all users matching a certain age. There is an example for both prepared statements and normal queries.<br /> &lt;pawn&gt;PrintResults(Handle:query)<br /> {<br /> /* Even if we have just one row, you must call SQL_FetchRow() first */<br /> new String:name[65]<br /> while (SQL_FetchRow(query))<br /> {<br /> SQL_FetchString(query, 0, name, sizeof(name))<br /> PrintToServer(&quot;Name \&quot;%s\&quot; was found.&quot;, name)<br /> }<br /> }<br /> <br /> bool:GetByAge_Query(Handle:db, age)<br /> {<br /> new String:query[100]<br /> Format(query, sizeof(query), &quot;SELECT name FROM users WHERE age = %d&quot;, age)<br /> <br /> new Handle:hQuery = SQL_Query(db, query)<br /> if (hQuery == INVALID_HANDLE)<br /> {<br /> return false<br /> }<br /> <br /> PrintResults(hQuery)<br /> <br /> CloseHandle(hQuery)<br /> <br /> return true<br /> }<br /> <br /> new Handle:hAgeStmt = INVALID_HANDLE<br /> bool:GetByAge_Statement(Handle:db, age)<br /> {<br /> if (hAgeSmt == INVALID_HANDLE)<br /> {<br /> new String:error[255]<br /> if ((hAgeStmt = SQL_PrepareQuery(db, <br /> &quot;SELECT name FROM users WHERE age = ?&quot;, <br /> error, <br /> sizeof(error))) <br /> == INVALID_HANDLE)<br /> {<br /> return false<br /> }<br /> }<br /> <br /> SQL_BindParamInt(hAgeStmt, 0, age)<br /> if (!SQL_Execute(hAgeStmt))<br /> {<br /> return false<br /> }<br /> <br /> PrintResults(hAgeStmt)<br /> <br /> return true<br /> }&lt;/pawn&gt;<br /> <br /> Note that these examples did not close the statement Handles. These examples assume a global database instance that is only closed when the plugin is unloaded. For plugins which maintain temporary database connections, prepared statement Handles must be freed or else the database connection will never be closed.<br /> <br /> <br /> =Threading=<br /> SourceMod supports threaded SQL querying. That is, SQL operations can be completed in a separate thread from main gameplay. If your database server is remote or requires a network connection, queries can cause noticeable gameplay lag, and supporting threading is often a good idea if your queries occur in the middle of gameplay.<br /> <br /> Threaded queries are ''asynchronous''. That is, they are dispatched and you can only find the results through a callback. Although the callback is guaranteed to fire eventually, it may not fire in any specific given timeframe. Certain drivers may not support threading; if this is the case, an RTE will be thrown. If the threader cannot start or the threader is currently disabled, SourceMod will transparently execute the query in the main thread as a fallback.<br /> <br /> ==Operations==<br /> All threaded operations use the same callback for result notification: &lt;tt&gt;SQLTCallback&lt;/tt&gt;. The parameters are:<br /> *&lt;tt&gt;owner&lt;/tt&gt; - The &quot;owner&quot; of the operation. For a query, this is a database. For a database, this is a driver. If the owner was not found or was invalidated, &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; is passed.<br /> *&lt;tt&gt;hndl&lt;/tt&gt; - The object being requested. The value is defined by the SQL operation.<br /> *&lt;tt&gt;error&lt;/tt&gt; - An error string.<br /> *&lt;tt&gt;data&lt;/tt&gt; - Custom data that can be passed via some SQL operations.<br /> <br /> The following operations can be done via threads:<br /> *&lt;b&gt;Connection&lt;/b&gt;, via &lt;tt&gt;SQL_TConnect&lt;/tt&gt;.<br /> *&lt;b&gt;Querying&lt;/b&gt;, via &lt;tt&gt;SQL_TQuery()&lt;/tt&gt;.<br /> *''Note: prepared statements are not yet available for the threader.''<br /> <br /> It is always safe to chain one operation from another.<br /> <br /> ===Connecting===<br /> It is not necessary to make a threaded connection in order to make threaded queries. However, creating a threaded connection will not pause the game server if a connection cannot be immediately established. <br /> <br /> The following parameters are used for the threaded connection callback:<br /> *&lt;tt&gt;owner&lt;/tt&gt;: A Handle to the driver, or &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; if it could not be found.<br /> *&lt;tt&gt;hndl&lt;/tt&gt;: A Handle to the database, or &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; if the connection failed.<br /> *&lt;tt&gt;error&lt;/tt&gt;: The error string, if any.<br /> *&lt;tt&gt;data&lt;/tt&gt;: Unused (0)<br /> <br /> Example: <br /> &lt;pawn&gt;new Handle:hDatabase = INVALID_HANDLE;<br /> <br /> StartSQL()<br /> {<br /> SQL_TConnect(GotDatabase);<br /> }<br /> <br /> public GotDatabase(Handle:owner, Handle:hndl, const String:error[], any:data)<br /> {<br /> if (hndl == INVALID_HANDLE)<br /> {<br /> LogError(&quot;Database failure: %s&quot;, error);<br /> } else {<br /> hDatabase = hndl;<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> ===Querying===<br /> Threaded queries can be performed on any database Handle as long as the driver supports threading. All query results for the first result set are retrieved while in the thread. If your query returns more than one set of results (for example, &lt;tt&gt;CALL&lt;/tt&gt; on MySQL with certain functions), the behaviour of the threader is undefined at this time. &lt;b&gt;Note that if you want to perform both threaded and non-threaded queries on the same connection, you MUST read the &quot;Locking&quot; section below.&lt;/b&gt;<br /> <br /> Query operations use the following callback parameters:<br /> *&lt;tt&gt;owner&lt;/tt&gt;: A Handle to the database used to query. The Handle is not the same as the Handle originally passed; however, it will test positively with &lt;tt&gt;SQL_IsSameConnection&lt;/tt&gt;. The Handle can be cloned but it cannot be closed (it is closed automatically). It may be &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; in the case of a serious error (for example, the driver being unloaded).<br /> *&lt;tt&gt;hndl&lt;/tt&gt;: A Handle to the query. It can be cloned, but not closed (it is closed automatically). It may be &lt;tt&gt;INVALID_HANDLE&lt;/tt&gt; if there was an error.<br /> *&lt;tt&gt;error&lt;/tt&gt;: Error string, if any.<br /> *&lt;tt&gt;data&lt;/tt&gt;: Optional user-defined data passed in through &lt;tt&gt;SQL_TQuery()&lt;/tt&gt;.<br /> <br /> Example, continuing from above:<br /> &lt;pawn&gt;CheckSteamID(userid, const String:auth[])<br /> {<br /> decl String:query[255];<br /> Format(query, sizeof(query), &quot;SELECT userid FROM users WHERE steamid = '%s'&quot;, auth);<br /> SQL_TQuery(hdatabase, T_CheckSteamID, query, userid)<br /> }<br /> <br /> public T_CheckSteamID(Handle:owner, Handle:hndl, const String:error[], any:data)<br /> {<br /> new client;<br /> <br /> /* Make sure the client didn't disconnect while the thread was running */<br /> if ((client = GetClientOfUserId(data)) == 0)<br /> {<br /> return;<br /> }<br /> <br /> if (hndl == INVALID_HANDLE)<br /> {<br /> LogError(&quot;Query failed! %s&quot;, error);<br /> KickClient(client, &quot;Authorization failed&quot;);<br /> } else if (!SQL_GetRowCount(hndl)) {<br /> KickClient(client, &quot;You are not a member&quot;);<br /> }<br /> }<br /> &lt;/pawn&gt;<br /> <br /> ==Locking==<br /> It is possible to run both threaded and non-threaded queries on the same connection. However, without the proper precautions, you could corrupt the network stream (even if it's local), corrupt memory, or otherwise cause a crash in the SQL driver. To solve this, SourceMod has ''database locking''. Locking is done via &lt;tt&gt;SQL_LockDatabase()&lt;/tt&gt; and &lt;tt&gt;SQL_UnlockDatabase&lt;/tt&gt;.<br /> <br /> Whenever performing any of the following non-threaded operations on a database, it is absolutely necessary to enclose the entire operation with a lock:<br /> *&lt;tt&gt;SQL_Query()&lt;/tt&gt; (and &lt;tt&gt;SQL_FetchMoreResults&lt;/tt&gt; pairings)<br /> *&lt;tt&gt;SQL_FastQuery&lt;/tt&gt;<br /> *&lt;tt&gt;SQL_PrepareQuery&lt;/tt&gt;<br /> *&lt;tt&gt;SQL_Bind*&lt;/tt&gt; and &lt;tt&gt;SQL_Execute&lt;/tt&gt; pairings<br /> <br /> The rule of thumb is: if your operation is going to use the database connection, it must be locked until the operation is fully completed. <br /> <br /> Example:<br /> &lt;pawn&gt;bool:GetByAge_Query(Handle:db, age)<br /> {<br /> new String:query[100]<br /> Format(query, sizeof(query), &quot;SELECT name FROM users WHERE age = %d&quot;, age)<br /> <br /> SQL_LockDatabase(db);<br /> new Handle:hQuery = SQL_Query(db, query)<br /> if (hQuery == INVALID_HANDLE)<br /> {<br /> SQL_UnlockDatabase(db);<br /> return false<br /> }<br /> SQL_UnlockDatabase(db);<br /> <br /> PrintResults(hQuery)<br /> <br /> CloseHandle(hQuery)<br /> <br /> return true<br /> }&lt;/pawn&gt;<br /> <br /> Note that it was only necessary to lock the query; SourceMod pre-fetches the result set, and thus the network queue is clean.<br /> <br /> ===Warnings===<br /> *&lt;b&gt;Never&lt;/b&gt; call &lt;tt&gt;SQL_LockDatabase&lt;/tt&gt; right before a threaded operation. You will deadlock the server and have to terminate/kill it. <br /> *&lt;b&gt;Always pair every Lock with an Unlock.&lt;/b&gt; Otherwise you risk a deadlock.<br /> *If your query returns multiple result sets, for example, a procedure call on MySQL that returns results, you must lock both the query and the entire fetch operation. SourceMod is only able to fetch one result set at a time, and all result sets must be cleared before a new query is started.<br /> <br /> ==Priority==<br /> Threaded SQL operations are placed in a simple priority queue. The priority levels are &lt;tt&gt;High&lt;/tt&gt;, &lt;tt&gt;Medium&lt;/tt&gt;, and &lt;tt&gt;Low&lt;/tt&gt;. Connections always have the highest priority. <br /> <br /> Changing the priority can be useful if you have many queries with different purposes. For example, a statistics plugin might execute 10 queries on death, and one query on join. Because the statistics might rely on the join info, the join query might need to be high priority, while the death queries can be low priority.<br /> <br /> You should &lt;b&gt;never&lt;/b&gt; simply assign a high priority to all of your queries simply because you want them to get done fast. Not only does it not work that way, but you may be inserting subtle problems into other plugins by being greedy.<br /> <br /> <br /> =SQLite=<br /> ==Introduction==<br /> [http://www.sqlite.org/ SQLite] is a fast local-file SQL database engine and SourceMod provides a DBI driver for it. SQLite differs from MySQL, and thus MySQL queries may not work in SQLite. The driver type for connections is &lt;tt&gt;sqlite&lt;/tt&gt;.<br /> <br /> ==Usage==<br /> Since SQLite is local only, most of the connection parameters can be ignored. The only connection parameter required is &lt;tt&gt;database&lt;/tt&gt;, which specifies the file name of the database. Databases are created on demand if they do not already exist, and are stored in &lt;tt&gt;addons/sourcemod/data/sqlite&lt;/tt&gt;. An extension of &quot;.sq3&quot; is automatically appended to the file name.<br /> <br /> Additionally, you can specify sub-folders in the database name. For example, &quot;cssdm/players&quot; will become &lt;tt&gt;addons/sourcemod/data/sqlite/cssdm/players.sq3&lt;/tt&gt;.<br /> <br /> SQLite supports the threading layer, and requires all of the same rules as the MySQL driver (including locks on shared connections).<br /> <br /> ==External Links==<br /> *[http://www.sqlite.org SQLite Homepage]<br /> *[http://sqlitebrowser.sourceforge.net/ SQLite Browser]<br /> <br /> <br /> [[Category:SourceMod Scripting]]<br /> <br /> {{LanguageSwitch}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Format_Class_Functions_(SourceMod_Scripting)&diff=10096 2015-12-29T16:31:58Z

<p>Xerox8521: /* Making your function Format-Class */</p> <hr /> <div>=Introduction=<br /> Format-class functions are variable argument functions in [[SourceMod]] which allow you to format a string. A simple example of this is the &lt;tt&gt;Format()&lt;/tt&gt; function, which looks like:<br /> <br /> &lt;pawn&gt;char buffer[512];<br /> Format(buffer, sizeof(buffer), &quot;Your name is: %s&quot;, userName);&lt;/pawn&gt;<br /> <br /> If userName contains &quot;&lt;tt&gt;Mark&lt;/tt&gt;,&quot; the contents of &lt;tt&gt;buffer&lt;/tt&gt; will then be: &quot;&lt;tt&gt;Your name is: Mark&lt;/tt&gt;.&quot; The prototype of these functions almost always contains the following parameters:<br /> &lt;pawn&gt;const char[] fmt, {Handle,Float,_} ...&lt;/pawn&gt;<br /> <br /> For example, observe the following two natives:<br /> &lt;pawn&gt;native void Format(char[] buffer, int maxlength, const char[] fmt, {Handle,Float,_} ...);<br /> native void PrintToClient(int client, char[] fmt, {Handle,Float,_} ...);&lt;/pawn&gt;<br /> <br /> Thus, &lt;tt&gt;PrintToClient&lt;/tt&gt; is a format-class function. It can be used exactly as shown earlier:<br /> &lt;pawn&gt;PrintToClient(client, &quot;Your name is: %s&quot;, userName);&lt;/pawn&gt;<br /> <br /> =Format Specifiers=<br /> A format specifier is a code that allows you to specify what data-type to print. The most common specifiers are:<br /> *'''Numerical'''<br /> **'''d''' or '''i''': Integer number as decimal<br /> **'''u''': Unsigned integer number as decimal<br /> **'''b''': Binary digits in the value<br /> **'''f''': Floating-point number<br /> **'''x''' or '''X''': Hexadecimal representation of the binary value (capitalization affects hex letter casing)<br /> *'''Character(s)'''<br /> **'''s''': String<br /> **'''t''' or '''T''': Translates a phrase (explained in [[Translations (SourceMod_Scripting)#Usage_in_a_Plugin|Translations]])<br /> **'''c''': Prints one character (UTF-8 compliant)<br /> *'''Special'''<br /> **'''L''': Requires a client index; expands to 1&lt;2&gt;&lt;3&gt;&lt;&gt; where 1 is the player's name, 2 is the player's userid, and 3 is the player's Steam ID. If the client index is 0, the string will be: &lt;tt&gt;&lt;nowiki&gt;Console&lt;0&gt;&lt;Console&gt;&lt;Console&gt;&lt;/nowiki&gt;&lt;/tt&gt;<br /> **'''N''': Requires a client index; expands to a string containing the player's name. If the client index is 0, the string will be: &lt;tt&gt;Console&lt;/tt&gt;<br /> <br /> =Usage=<br /> Format specifiers are denoted with a &lt;tt&gt;'%s'&lt;/tt&gt; symbol. For example, to print a float, a number, and a string, you might use this code:<br /> &lt;pawn&gt;float fNum = 5.0;<br /> int iNum = 5;<br /> char[] str = &quot;5&quot;;<br /> <br /> PrintToClient(client, &quot;Number: %d Float: %f String: %s&quot;, iNum, fNum, str);&lt;/pawn&gt;<br /> <br /> '''Note''': Using the wrong data type with a specifier can be very dangerous. Always make sure you are printing as the right type. For example, specifying a string and passing a number can crash the server.<br /> <br /> =Advanced Formatting=<br /> Format specifiers have an extended syntax for controlling various aspects of how data is printed. The full syntax is:<br /> &lt;tt&gt;%[flags][width][.precision]specifier&lt;/tt&gt;<br /> <br /> Each bracketed section is an optional extension. Explanations of supported SourceMod format extensions:<br /> *'''%''': Obviously, this is always required.<br /> *'''flags''':<br /> **'''-''': Left-justify (right-justify is set by default)<br /> **'''0''': Pads with 0s instead of spaces when needed (see '''width''' below).<br /> *'''width''': Minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger.<br /> *'''precision''': <br /> **'''For integers''': specifies the minimum number of digits to print (or pad with spaces/zeroes if below the minimum). <br /> **'''For strings''': specifies the maximum number of characters to print.<br /> **'''For floats''': specifies the number of digits to be printed ''after the decimal point''.<br /> **'''For all other types''': no effect.<br /> *'''specifier''': character specifying the data type (always required).<br /> <br /> todo: examples<br /> <br /> For more information, see [http://www.cplusplus.com/reference/clibrary/cstdio/printf.html printf] from the C Standard Library, although not all modes are supported from C.<br /> <br /> =Making your function Format-Class=<br /> <br /> Sourcemod allows you to make your function Format-class, ie. pass parameters to format string variables.<br /> Here's an example :<br /> <br /> &lt;pawn&gt;public void formatExample(const char[] myString , any ...)<br /> {<br /> char[] myFormattedString = new char[strlen(myString)+255];<br /> VFormat(myFormattedString, sizeof(myFormattedString), myString, 2);<br /> <br /> PrintToServer(myFormattedString);<br /> }&lt;/pawn&gt;<br /> <br /> Using the parameter &quot;any ...&quot;, we can pass data(s) to format our string.<br /> Now, in order to replace the Format Specifiers by our data(s), we use the API &quot;VFormat&quot;, which documentation can be found here : [https://sm.alliedmods.net/new-api/].<br /> <br /> The three first parameters passed in VFormat are pretty obvious since they are the as in the Format(..) API.<br /> <br /> The 4th parameter indicate the &quot;any ...&quot; parameter position in your function prototype.<br /> <br /> [[Category:SourceMod Scripting]]</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Format_Class_Functions_(SourceMod_Scripting)&diff=10095 2015-12-29T16:30:33Z

<p>Xerox8521: /* Usage */</p> <hr /> <div>=Introduction=<br /> Format-class functions are variable argument functions in [[SourceMod]] which allow you to format a string. A simple example of this is the &lt;tt&gt;Format()&lt;/tt&gt; function, which looks like:<br /> <br /> &lt;pawn&gt;char buffer[512];<br /> Format(buffer, sizeof(buffer), &quot;Your name is: %s&quot;, userName);&lt;/pawn&gt;<br /> <br /> If userName contains &quot;&lt;tt&gt;Mark&lt;/tt&gt;,&quot; the contents of &lt;tt&gt;buffer&lt;/tt&gt; will then be: &quot;&lt;tt&gt;Your name is: Mark&lt;/tt&gt;.&quot; The prototype of these functions almost always contains the following parameters:<br /> &lt;pawn&gt;const char[] fmt, {Handle,Float,_} ...&lt;/pawn&gt;<br /> <br /> For example, observe the following two natives:<br /> &lt;pawn&gt;native void Format(char[] buffer, int maxlength, const char[] fmt, {Handle,Float,_} ...);<br /> native void PrintToClient(int client, char[] fmt, {Handle,Float,_} ...);&lt;/pawn&gt;<br /> <br /> Thus, &lt;tt&gt;PrintToClient&lt;/tt&gt; is a format-class function. It can be used exactly as shown earlier:<br /> &lt;pawn&gt;PrintToClient(client, &quot;Your name is: %s&quot;, userName);&lt;/pawn&gt;<br /> <br /> =Format Specifiers=<br /> A format specifier is a code that allows you to specify what data-type to print. The most common specifiers are:<br /> *'''Numerical'''<br /> **'''d''' or '''i''': Integer number as decimal<br /> **'''u''': Unsigned integer number as decimal<br /> **'''b''': Binary digits in the value<br /> **'''f''': Floating-point number<br /> **'''x''' or '''X''': Hexadecimal representation of the binary value (capitalization affects hex letter casing)<br /> *'''Character(s)'''<br /> **'''s''': String<br /> **'''t''' or '''T''': Translates a phrase (explained in [[Translations (SourceMod_Scripting)#Usage_in_a_Plugin|Translations]])<br /> **'''c''': Prints one character (UTF-8 compliant)<br /> *'''Special'''<br /> **'''L''': Requires a client index; expands to 1&lt;2&gt;&lt;3&gt;&lt;&gt; where 1 is the player's name, 2 is the player's userid, and 3 is the player's Steam ID. If the client index is 0, the string will be: &lt;tt&gt;&lt;nowiki&gt;Console&lt;0&gt;&lt;Console&gt;&lt;Console&gt;&lt;/nowiki&gt;&lt;/tt&gt;<br /> **'''N''': Requires a client index; expands to a string containing the player's name. If the client index is 0, the string will be: &lt;tt&gt;Console&lt;/tt&gt;<br /> <br /> =Usage=<br /> Format specifiers are denoted with a &lt;tt&gt;'%s'&lt;/tt&gt; symbol. For example, to print a float, a number, and a string, you might use this code:<br /> &lt;pawn&gt;float fNum = 5.0;<br /> int iNum = 5;<br /> char[] str = &quot;5&quot;;<br /> <br /> PrintToClient(client, &quot;Number: %d Float: %f String: %s&quot;, iNum, fNum, str);&lt;/pawn&gt;<br /> <br /> '''Note''': Using the wrong data type with a specifier can be very dangerous. Always make sure you are printing as the right type. For example, specifying a string and passing a number can crash the server.<br /> <br /> =Advanced Formatting=<br /> Format specifiers have an extended syntax for controlling various aspects of how data is printed. The full syntax is:<br /> &lt;tt&gt;%[flags][width][.precision]specifier&lt;/tt&gt;<br /> <br /> Each bracketed section is an optional extension. Explanations of supported SourceMod format extensions:<br /> *'''%''': Obviously, this is always required.<br /> *'''flags''':<br /> **'''-''': Left-justify (right-justify is set by default)<br /> **'''0''': Pads with 0s instead of spaces when needed (see '''width''' below).<br /> *'''width''': Minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger.<br /> *'''precision''': <br /> **'''For integers''': specifies the minimum number of digits to print (or pad with spaces/zeroes if below the minimum). <br /> **'''For strings''': specifies the maximum number of characters to print.<br /> **'''For floats''': specifies the number of digits to be printed ''after the decimal point''.<br /> **'''For all other types''': no effect.<br /> *'''specifier''': character specifying the data type (always required).<br /> <br /> todo: examples<br /> <br /> For more information, see [http://www.cplusplus.com/reference/clibrary/cstdio/printf.html printf] from the C Standard Library, although not all modes are supported from C.<br /> <br /> =Making your function Format-Class=<br /> <br /> Sourcemod allows you to make your function Format-class, ie. pass parameters to format string variables.<br /> Here's an example :<br /> <br /> &lt;pawn&gt;public formatExample(const String:myString[] , any:...)<br /> {<br /> new String:myFormattedString[strlen(myString)+255];<br /> VFormat(myFormattedString, sizeof(myFormattedString), myString, 2);<br /> <br /> PrintToServer(myFormattedString);<br /> }&lt;/pawn&gt;<br /> <br /> Using the parameter &quot;any: ...&quot;, we can pass data(s) to format our string.<br /> Now, in order to replace the Format Specifiers by our data(s), we use the API &quot;VFormat&quot;, which documentation can be found here : [http://docs.sourcemod.net/api/].<br /> <br /> The three first parameters passed in VFormat are pretty obvious since they are the as in the Format(..) API.<br /> <br /> The 4th parameter indicate the &quot;any: ...&quot; parameter position in your function prototype.<br /> <br /> [[Category:SourceMod Scripting]]</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Format_Class_Functions_(SourceMod_Scripting)&diff=10094 2015-12-29T16:29:45Z

<p>Xerox8521: /* Introduction */</p> <hr /> <div>=Introduction=<br /> Format-class functions are variable argument functions in [[SourceMod]] which allow you to format a string. A simple example of this is the &lt;tt&gt;Format()&lt;/tt&gt; function, which looks like:<br /> <br /> &lt;pawn&gt;char buffer[512];<br /> Format(buffer, sizeof(buffer), &quot;Your name is: %s&quot;, userName);&lt;/pawn&gt;<br /> <br /> If userName contains &quot;&lt;tt&gt;Mark&lt;/tt&gt;,&quot; the contents of &lt;tt&gt;buffer&lt;/tt&gt; will then be: &quot;&lt;tt&gt;Your name is: Mark&lt;/tt&gt;.&quot; The prototype of these functions almost always contains the following parameters:<br /> &lt;pawn&gt;const char[] fmt, {Handle,Float,_} ...&lt;/pawn&gt;<br /> <br /> For example, observe the following two natives:<br /> &lt;pawn&gt;native void Format(char[] buffer, int maxlength, const char[] fmt, {Handle,Float,_} ...);<br /> native void PrintToClient(int client, char[] fmt, {Handle,Float,_} ...);&lt;/pawn&gt;<br /> <br /> Thus, &lt;tt&gt;PrintToClient&lt;/tt&gt; is a format-class function. It can be used exactly as shown earlier:<br /> &lt;pawn&gt;PrintToClient(client, &quot;Your name is: %s&quot;, userName);&lt;/pawn&gt;<br /> <br /> =Format Specifiers=<br /> A format specifier is a code that allows you to specify what data-type to print. The most common specifiers are:<br /> *'''Numerical'''<br /> **'''d''' or '''i''': Integer number as decimal<br /> **'''u''': Unsigned integer number as decimal<br /> **'''b''': Binary digits in the value<br /> **'''f''': Floating-point number<br /> **'''x''' or '''X''': Hexadecimal representation of the binary value (capitalization affects hex letter casing)<br /> *'''Character(s)'''<br /> **'''s''': String<br /> **'''t''' or '''T''': Translates a phrase (explained in [[Translations (SourceMod_Scripting)#Usage_in_a_Plugin|Translations]])<br /> **'''c''': Prints one character (UTF-8 compliant)<br /> *'''Special'''<br /> **'''L''': Requires a client index; expands to 1&lt;2&gt;&lt;3&gt;&lt;&gt; where 1 is the player's name, 2 is the player's userid, and 3 is the player's Steam ID. If the client index is 0, the string will be: &lt;tt&gt;&lt;nowiki&gt;Console&lt;0&gt;&lt;Console&gt;&lt;Console&gt;&lt;/nowiki&gt;&lt;/tt&gt;<br /> **'''N''': Requires a client index; expands to a string containing the player's name. If the client index is 0, the string will be: &lt;tt&gt;Console&lt;/tt&gt;<br /> <br /> =Usage=<br /> Format specifiers are denoted with a &lt;tt&gt;'%s'&lt;/tt&gt; symbol. For example, to print a float, a number, and a string, you might use this code:<br /> &lt;pawn&gt;new Float:fNum = 5.0;<br /> new iNum = 5<br /> new String:str[] = &quot;5&quot;<br /> <br /> PrintToClient(client, &quot;Number: %d Float: %f String: %s&quot;, iNum, fNum, str);&lt;/pawn&gt;<br /> <br /> '''Note''': Using the wrong data type with a specifier can be very dangerous. Always make sure you are printing as the right type. For example, specifying a string and passing a number can crash the server.<br /> <br /> =Advanced Formatting=<br /> Format specifiers have an extended syntax for controlling various aspects of how data is printed. The full syntax is:<br /> &lt;tt&gt;%[flags][width][.precision]specifier&lt;/tt&gt;<br /> <br /> Each bracketed section is an optional extension. Explanations of supported SourceMod format extensions:<br /> *'''%''': Obviously, this is always required.<br /> *'''flags''':<br /> **'''-''': Left-justify (right-justify is set by default)<br /> **'''0''': Pads with 0s instead of spaces when needed (see '''width''' below).<br /> *'''width''': Minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger.<br /> *'''precision''': <br /> **'''For integers''': specifies the minimum number of digits to print (or pad with spaces/zeroes if below the minimum). <br /> **'''For strings''': specifies the maximum number of characters to print.<br /> **'''For floats''': specifies the number of digits to be printed ''after the decimal point''.<br /> **'''For all other types''': no effect.<br /> *'''specifier''': character specifying the data type (always required).<br /> <br /> todo: examples<br /> <br /> For more information, see [http://www.cplusplus.com/reference/clibrary/cstdio/printf.html printf] from the C Standard Library, although not all modes are supported from C.<br /> <br /> =Making your function Format-Class=<br /> <br /> Sourcemod allows you to make your function Format-class, ie. pass parameters to format string variables.<br /> Here's an example :<br /> <br /> &lt;pawn&gt;public formatExample(const String:myString[] , any:...)<br /> {<br /> new String:myFormattedString[strlen(myString)+255];<br /> VFormat(myFormattedString, sizeof(myFormattedString), myString, 2);<br /> <br /> PrintToServer(myFormattedString);<br /> }&lt;/pawn&gt;<br /> <br /> Using the parameter &quot;any: ...&quot;, we can pass data(s) to format our string.<br /> Now, in order to replace the Format Specifiers by our data(s), we use the API &quot;VFormat&quot;, which documentation can be found here : [http://docs.sourcemod.net/api/].<br /> <br /> The three first parameters passed in VFormat are pretty obvious since they are the as in the Format(..) API.<br /> <br /> The 4th parameter indicate the &quot;any: ...&quot; parameter position in your function prototype.<br /> <br /> [[Category:SourceMod Scripting]]</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Introduction_to_SourcePawn_1.7&diff=10060 2015-11-15T18:41:46Z

<p>Xerox8521: /* Extended Variable Declarations */</p> <hr /> <div>This guide is designed to give you a very basic overview to fundamentals of scripting in SourcePawn. [[Pawn]] is a &quot;scripting&quot; language used to embed functionality in other programs. That means it is not a standalone language, like C++ or Java, and its details will differ based on the application. SourcePawn is the version of Pawn used in [[SourceMod]].<br /> <br /> This guide does not tell you how to write SourceMod plugins; it is intended as an overview of the syntax and semantics of the language instead. Read the separate article, [[Introduction to SourceMod Plugins]] for SourceMod API specifics. <br /> <br /> =Non-Programmer Intro=<br /> This section is intended for non-programmers. If you're still confused, you may want to pick up a book on another language, such as PHP, Python, or Java, to get a better idea of what programming is like.<br /> <br /> ==Symbols/Keywords==<br /> A symbol is a series of letters, numbers, and/or underscores, that uniquely represents something. Symbols are case-sensitive, and usually start with a letter.<br /> <br /> There are a few reserved symbols that have special meaning. For example, &lt;tt&gt;if&lt;/tt&gt;, &lt;tt&gt;for&lt;/tt&gt;, and &lt;tt&gt;return&lt;/tt&gt; are special constructs in the language that will explained later. They cannot be used as symbol names.<br /> <br /> ==Variables==<br /> There a few important constructs you should know before you begin to script. The first is a '''variable'''. A variable is a symbol, or name, that holds data. For example, the variable &quot;a&quot; could hold the number &quot;2&quot;, &quot;16&quot;, &quot;0&quot;, et cetera. Since a variable holds data, it also allocates the memory needed to store that data.<br /> <br /> In addition to a name, variables have a '''type'''. A type tells the program how to interpret the data, and how much memory the data will use. Pawn has three types of data that are most commonly used:<br /> * Integers, using the &lt;tt&gt;int&lt;/tt&gt; type. Integer types may store a whole number from -2147483648 to 2147483647.<br /> * Floats, using the &lt;tt&gt;float&lt;/tt&gt; type. Float types may store fractional numbers in a huge range, though they are not as precise as integers.<br /> * Characters, using the &lt;tt&gt;char&lt;/tt&gt; type. Character types store one byte of character information, typically an [http://www.asciitable.com/ ASCII] character.<br /> * Booleans, using the &lt;tt&gt;bool&lt;/tt&gt; type. Booleans store either true or false.<br /> <br /> Example of creating variables and assigning values:<br /> <br /> &lt;pawn&gt;int money = 5400;<br /> float percent = 67.3;<br /> bool enabled = false;<br /> &lt;/pawn&gt;<br /> <br /> ==Functions==<br /> The next important concept is '''functions'''. Functions are symbols or names that perform an action. When you invoke, or call them, they carry out a specific sequence of code and then return a result. There are a few types of functions, but every function is activated the same way. Example:<br /> <br /> &lt;pawn&gt;<br /> show(56); // Calls the &quot;show&quot; function, and gives it the number 56.<br /> enable(); // Calls the &quot;s &quot;enable&quot; function with no values.<br /> bool visible = show(a); //Calls the &quot;show&quot; function, stores its result in a variable.<br /> &lt;/pawn&gt;<br /> <br /> Every piece of data passed to a function is called a '''parameter'''. A function can have any number of parameters (there is a &quot;reasonable&quot; limit of 32 in SourceMod). Parameters will be explained further in the article.<br /> <br /> ==Comments==<br /> Note any text that appears after a &quot;//&quot; is considered a &quot;comment&quot; and is not actual code. There are two comment styles:<br /> *&lt;tt&gt;//&lt;/tt&gt; - Double slash, everything following on that line is ignored.<br /> *&lt;tt&gt;/* */&lt;/tt&gt; - Multi-line comment, everything in between the asterisks is ignored. You cannot nest these.<br /> <br /> <br /> ==Block Coding==<br /> The next concept is block coding. You can group code into &quot;blocks&quot; separated by { and }. This effectively makes one large block of code act as one statement. For example:<br /> <br /> &lt;pawn&gt;{<br /> here;<br /> is;<br /> some;<br /> code;<br /> }&lt;/pawn&gt;<br /> <br /> Block coding using braces is used everywhere in programming. Blocks of code can be nested within each other. It is a good idea to adapt a consistent and readable indentation style early on to prevent spaghetti-looking code.<br /> <br /> =Language Paradigms=<br /> Pawn may seem similar to other languages, like C, but it has fundamental differences. It is not important that you immediately understand these differences, but they may be helpful if you're familiar with another language already.<br /> *'''Pawn is sort of typed.''' Before SourceMod 1.7, Pawn did not have types. Older code and older natives will reflect this by using tags and the &lt;tt&gt;new&lt;/tt&gt; keyword. As of SourceMod 1.7, we recommend that all code use types. For more information see [[SourcePawn Transitional Syntax]].<br /> *'''Pawn is not garbage collected.''' Pawn, as a language, has no built-in memory allocation, and thus has no garbage. If a function allocates memory, you may be responsible for freeing it.<br /> *'''Pawn is not object oriented.''' Pawn does not have structs or objects. As of SourceMod 1.7, it has limited sugaring for treating some data types as objects, but users cannot create their own objects or classes.<br /> *'''Pawn is single-threaded.''' As of this writing, Pawn is not thread safe. <br /> *'''Pawn is compiled.''' Pawn is compiled to an intermediate, machine-independent code, which is stored in a &quot;.smx&quot; file. When loading .smx files, SourceMod translates this code to machine code for the platform and CPU it's running on.<br /> <br /> Early language design decisions were made by ITB CompuPhase. It is designed for low-level embedded devices and is thus very small and very fast.<br /> <br /> =Variables=<br /> Pawn currently supports the following basic variable types:<br /> *&lt;tt&gt;bool&lt;/tt&gt; - true or false.<br /> *&lt;tt&gt;char&lt;/tt&gt; - an 8-bit ASCII character.<br /> *&lt;tt&gt;int&lt;/tt&gt; - a 32-bit signed integer.<br /> *&lt;tt&gt;float&lt;/tt&gt; - a 32-bit IEEE-754 floating point number.<br /> *&lt;tt&gt;Handle&lt;/tt&gt; - the base type of a SourceMod object<br /> <br /> Other types may exist when defined in include files - for example, enums create new types for named integers, and many types derive from &lt;tt&gt;Handle&lt;/tt&gt;.<br /> <br /> Strings, currently, are 0-terminated arrays of &lt;tt&gt;char&lt;/tt&gt;s. They're described a little further ahead.<br /> <br /> ==Declaration==<br /> Below we include some examples of variable declarations, both valid and invalid. Keep in mind that SourcePawn has recently added new syntax, and that's what's documented below. Older code may use older declaration syntax, which is no longer supported.<br /> <br /> &lt;pawn&gt;<br /> int a = 5;<br /> float b = 5.0;<br /> bool c = true;<br /> bool d = false;<br /> &lt;/pawn&gt;<br /> <br /> Invalid variable usage:<br /> &lt;pawn&gt;<br /> int a = 5.0; // Type mismatch. 5.0 is a float.<br /> float b = 5; // Type mismatch. 5 is an integer.<br /> &lt;/pawn&gt;<br /> <br /> If a variable is not assigned upon declaration, it will be set to 0. For example:<br /> &lt;pawn&gt;<br /> int a; // Set to 0<br /> float b; // Set to 0.0<br /> bool c; // Set to false<br /> &lt;/pawn&gt;<br /> <br /> ==Assignment==<br /> Variables can be re-assigned data after they are created. For example:<br /> &lt;pawn&gt;int a;<br /> float b;<br /> bool c;<br /> <br /> a = 5;<br /> b = 5.0;<br /> c = true;<br /> &lt;/pawn&gt;<br /> <br /> =Arrays=<br /> An array is a sequence of data in a list. Arrays are useful for storing multiple pieces of data in one variable, or mapping one type of data to another.<br /> <br /> ==Declaration==<br /> An array is declared using brackets. Some examples of arrays:<br /> &lt;pawn&gt;<br /> int players[32]; // Stores 32 integers.<br /> float origin[3]; // Stores 3 floating point numbers<br /> &lt;/pawn&gt;<br /> <br /> By default, arrays are initialized to 0. You can assign them different default values, however:<br /> &lt;pawn&gt;<br /> int numbers[5] = {1, 2, 3, 4, 5}; // Stores 1, 2, 3, 4, 5.<br /> float origin[3] = {1.0, 2.0, 3.0}; // Stores 1.0, 2.0, 3.0.<br /> &lt;/pawn&gt;<br /> <br /> You can leave out the array size if you're going to pre-assign data to it. For example:<br /> &lt;pawn&gt;<br /> int numbers[] = {1, 3, 5, 7, 9};<br /> &lt;/pawn&gt;<br /> <br /> The compiler will automatically deduce that you intended an array of size 5.<br /> <br /> When array is declared with brackets after its name, Pawn considers that array to have a '''fixed size'''. The size of a fixed-size array is always known. Some arrays can be '''dynamically sized''', by putting the brackets before the name. For example,<br /> <br /> &lt;pawn&gt;<br /> int[] numbers = new int[MaxClients]<br /> &lt;/pawn&gt;<br /> <br /> This creates an array of size &lt;tt&gt;MaxClients&lt;/tt&gt;, which could be anything, so the size of the array is not known until the array is allocated.<br /> <br /> ==Usage==<br /> Using an array is just like using a normal variable. The only difference is the array must be '''indexed'''. Indexing an array means choosing the element which you wish to use.<br /> <br /> For example, here is an example of the above code using indexes:<br /> &lt;pawn&gt;<br /> int numbers[5];<br /> float origin[3];<br /> <br /> numbers[0] = 1;<br /> numbers[1] = 2;<br /> numbers[2] = 3;<br /> numbers[3] = 4;<br /> numbers[4] = 5;<br /> origin[0] = 1.0;<br /> origin[1] = 2.0;<br /> origin[2] = 3.0;<br /> &lt;/pawn&gt;<br /> <br /> Note that the '''index''' is what's in between the brackets. The index always starts from 0. That is, if an array has N elements, its valid indexes are from 0 to N-1. Accessing the data at these indexes works like a normal variable.<br /> <br /> Using an incorrect index will cause an error. For example:<br /> &lt;pawn&gt;<br /> int numbers[5];<br /> <br /> numbers[5] = 20;&lt;/pawn&gt;<br /> <br /> This may look correct, but 5 is not a valid index. The highest valid index is 4.<br /> <br /> You can use any expression as an index. For example:<br /> &lt;pawn&gt;int a, numbers[5];<br /> <br /> a = 1; // Set a = 1<br /> numbers[a] = 4; // Set numbers[1] = 4<br /> numbers[numbers[a]] = 2; // Set numbers[4] = 2<br /> &lt;/pawn&gt;<br /> <br /> Expressions will be discussed in depth later in the article.<br /> <br /> =Strings=<br /> Strings are a construct for storing text (or even raw binary data). A string is just an array of characters, except that the final character must be 0 (called the null terminator). Without a null terminator, Pawn would not know where to stop reading the string. All strings are [http://en.wikipedia.org/wiki/UTF-8 UTF-8] in SourcePawn.<br /> <br /> In general, you must have an idea of how large a string will be before you store it. SourcePawn does not yet have the capability of pre-determining storage space for strings.<br /> <br /> ==Usage==<br /> Strings are usually declared as arrays. For example:<br /> &lt;pawn&gt;<br /> char message[] = &quot;Hello!&quot;;<br /> char clams[6] = &quot;Clams&quot;;<br /> &lt;/pawn&gt;<br /> <br /> These are equivalent to doing:<br /> &lt;pawn&gt;<br /> char message[7];<br /> char clams[6];<br /> <br /> message[0] = 'H';<br /> message[1] = 'e';<br /> message[2] = 'l';<br /> message[3] = 'l';<br /> message[4] = 'o';<br /> message[5] = '!';<br /> message[6] = 0;<br /> clams[0] = 'C';<br /> clams[1] = 'l';<br /> clams[2] = 'a';<br /> clams[3] = 'm';<br /> clams[4] = 's';<br /> clams[5] = 0;<br /> &lt;/pawn&gt;<br /> <br /> Although strings are rarely initialized in this manner, it is very important to remember the concept of the null terminator, which signals the end of a string. The compiler, and most SourceMod functions will automatically null-terminate for you, so it is mainly important when manipulating strings directly.<br /> <br /> Note that a string is enclosed in double-quotes, but a character is enclosed in single quotes.<br /> <br /> ==Characters==<br /> A character of text can be used in either a String or a cell. For example:<br /> &lt;pawn&gt;char text[] = &quot;Crab&quot;;<br /> char clam;<br /> <br /> clam = 'D'; //Set clam to 'D'<br /> text[0] = 'A'; //Change the 'C' to 'A', it is now 'Arab'<br /> clam = text[0]; //Set clam to 'A'<br /> text[1] = clam; //Change the 'r' to 'A', is is now 'AAab'<br /> &lt;/pawn&gt;<br /> <br /> What you can't do is mix character arrays with strings. The internal storage is different. For example:<br /> &lt;pawn&gt;<br /> int clams[] = &quot;Clams&quot;; // Invalid.<br /> int clams[] = {'C', 'l', 'a', 'm', 's', 0}; // Valid, but NOT A STRING.<br /> &lt;/pawn&gt;<br /> <br /> =Functions=<br /> Functions, as stated before, are isolated blocks of code that perform an action. They can be invoked, or '''called''', with '''parameters''' that give specific options.<br /> <br /> There are two types of ways functions are called:<br /> *'''direct call''' - You specifically call a function in your code.<br /> *'''callback''' - The application calls a function in your code, as if it were an event trigger.<br /> <br /> There are six types of functions:<br /> *'''native''': A direct, internal function provided by the application.<br /> *'''public''': A callback function that is visible to the application and other scripts.<br /> *'''normal''': A normal function that only you can call.<br /> *'''static''': The scope of this function is restricted to the current file, can be used in combination with stock.<br /> *'''stock''': A normal function provided by an include file. If unused, it won't be compiled.<br /> *'''forward''': This function is a global event provided by the application. If you implement it, it will be a callback.<br /> <br /> All code in Pawn must exist in functions. This is in contrast to languages like PHP, Perl, and Python which let you write global code. That is because Pawn is a callback-based language: it responds to actions from a parent application, and functions must be written to handle those actions. Although our examples often contain free-floating code, this is purely for demonstration purposes. Free-floating code in our examples implies the code is part of some function.<br /> <br /> ==Declaration==<br /> Unlike variables, functions do not need to be declared before you use them. Functions have two pieces, the '''signature''' and the '''body'''. The signature contains the name of your function and the parameters it will accept. The body is the contents of its code.<br /> <br /> Example of a function:<br /> &lt;pawn&gt;<br /> int AddTwoNumbers(int first, int second)<br /> {<br /> int sum = first + second;<br /> return sum;<br /> }&lt;/pawn&gt;<br /> <br /> This is a simple function. The prototype is this line:<br /> &lt;pawn&gt;int AddTwoNumbers(int first, int second)&lt;/pawn&gt;<br /> <br /> Broken down, it means:<br /> *&lt;tt&gt;int&lt;/tt&gt; - Return value type (integer).<br /> *&lt;tt&gt;AddTwoNumbers&lt;/tt&gt; - Name of the function.<br /> *&lt;tt&gt;int first&lt;/tt&gt; - First parameter, an integer.<br /> *&lt;tt&gt;int second&lt;/tt&gt; - Second parameter, an integer.<br /> <br /> The body is a block of code. It creates a new variable, called &lt;tt&gt;sum&lt;/tt&gt;, and assigns it the value of the two parameters added together (more on expressions later). The important thing to notice is the &lt;tt&gt;return&lt;/tt&gt; statement, which tells the function to end and return a value to the caller of the function. All functions return something on completion, unless they return a special type called &lt;tt&gt;void&lt;/tt&gt;.<br /> <br /> A function can accept any type of input, and it can return any non-array type.<br /> <br /> You can, of course, pass variables to functions:<br /> &lt;pawn&gt;int numbers[3] = {1, 2, 0};<br /> <br /> numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);&lt;/pawn&gt;<br /> <br /> Note that cells are passed '''by value'''. That is, their value cannot be changed by the function. For example:<br /> &lt;pawn&gt;int a = 5;<br /> <br /> ChangeValue(a);<br /> <br /> ChangeValue(b)<br /> {<br /> b = 5;<br /> }&lt;/pawn&gt;<br /> <br /> This code would not change the value of &lt;tt&gt;a&lt;/tt&gt;. That is because a copy of the value in &lt;tt&gt;a&lt;/tt&gt; is passed instead of &lt;tt&gt;a&lt;/tt&gt; itself. <br /> <br /> More examples of functions will be provided throughout the article.<br /> <br /> ==Publics==<br /> Public functions are used to implement callbacks. You should not create a public function unless it is specifically implementing a callback. For example, here are two callbacks from &lt;tt&gt;sourcemod.inc&lt;/tt&gt;:<br /> <br /> &lt;pawn&gt;forward void OnPluginStart();<br /> forward void OnClientDisconnected(int client);&lt;/pawn&gt;<br /> <br /> To implement and receive these two events, you would write functions as such:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> /* Code here */<br /> }<br /> <br /> public void OnClientDisconnected(int client)<br /> {<br /> /* Code here */<br /> }&lt;/pawn&gt;<br /> <br /> The '''public''' keyword signals to the parent application that it should attach the function to the appropriate forwarded event.<br /> <br /> ==Natives==<br /> Natives are builtin functions provided by SourceMod. You can call them as if they were a normal function. For example, SourceMod has the following function:<br /> <br /> &lt;pawn&gt;native float FloatRound(float num);&lt;/pawn&gt;<br /> <br /> It can be called like so:<br /> &lt;pawn&gt;int rounded = FloatRound(5.2); // rounded will be 5&lt;/pawn&gt;<br /> <br /> ==Array Parameters==<br /> You can pass arrays or Strings as parameters. It is important to note that these are passed '''by reference'''. That is, rather than making a copy of the data, the data is referenced directly. There is a simple way of explaining this more concretely.<br /> <br /> &lt;pawn&gt;<br /> int example[] = {1, 2, 3, 4, 5};<br /> <br /> ChangeArray(example, 2, 29);<br /> <br /> void ChangeArray(int[] array, int index, int value)<br /> {<br /> array[index] = value;<br /> }&lt;/pawn&gt;<br /> <br /> The function sets the given index in the array to a given value. When it is run on our example array, it changes index 2 to from the value 3 to 29. I.e.:<br /> &lt;pawn&gt;example[2] = 29;&lt;/pawn&gt;<br /> <br /> Note two important things here. First, arrays are not copied when they are passed to functions - they are passed ''by reference'', so the view of the array is consistent at all times. Second, the brackets changed position in our function signature. This is because our function accepts an array of any size, and since we don't know the size, we must use the dynamic array syntax.<br /> <br /> To prevent an array from being modified in a function, you can mark it as &lt;tt&gt;const&lt;/tt&gt;. This will raise an error on code that attempts to modify it. For example:<br /> <br /> &lt;pawn&gt;void CantChangeArray(const array[], int index, int value)<br /> {<br /> array[index] = value; //Won't compile<br /> }&lt;/pawn&gt;<br /> <br /> It is a good idea to use &lt;tt&gt;const&lt;/tt&gt; in array parameters if you know the array won't be modified; this can prevent coding mistakes.<br /> <br /> =Expressions=<br /> Expressions are exactly the same as they are in mathematics. They are groups of operators/symbols which evaluate to one piece of data. They are often parenthetical (comprised of parenthesis). They contain a strict &quot;order of operations.&quot; They can contain variables, functions, numbers, and expressions themselves can be nested inside other expressions, or even passed as parameters.<br /> <br /> The simplest expression is a single number. For example:<br /> &lt;pawn&gt;<br /> 0; //Returns the number 0<br /> (0); //Returns the number 0 as well<br /> &lt;/pawn&gt;<br /> <br /> Although expressions can return any value, they are also said to either return ''zero or non-zero''. In that sense, ''zero'' is ''false'', and ''non-zero'' is ''true''. For example, -1 is '''true''' in Pawn, since it is non-zero. Do not assume negative numbers are false.<br /> <br /> The order of operations for expressions is similar to C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Here are some example expressions:<br /> &lt;pawn&gt;<br /> 5 + 6; //Evaluates to 11<br /> 5 * 6 + 3; //Evaluates to 33<br /> 5 * (6 + 3); //Evaluates to 45<br /> 5.0 + 2.3; //Evaluates to 7.3<br /> (5 * 6) % 7; //Modulo operator, evaluates to 2<br /> (5 + 3) / 2 * 4 - 9; //Evaluates to -8<br /> &lt;/pawn&gt;<br /> <br /> As noted, expressions can contain variables, or even functions:<br /> &lt;pawn&gt;<br /> int a = 5 * 6;<br /> int b = a * 3; //Evaluates to 90<br /> int c = AddTwoNumbers(a, b) + (a * b);<br /> &lt;/pawn&gt;<br /> <br /> Note: String manipulation routines may be found in the string.inc file located in the include subdirectory. They may be browsed through the [http://docs.sourcemod.net/api/ API Reference] as well.<br /> <br /> ==Operators==<br /> There are a few extra helpful operators in Pawn. The first set simplifies self-aggregation expressions. For example:<br /> &lt;pawn&gt;int a = 5;<br /> <br /> a = a + 5;&lt;/pawn&gt;<br /> <br /> Can be rewritten as:<br /> &lt;pawn&gt;int a = 5;<br /> a += 5;&lt;/pawn&gt;<br /> <br /> This is true of the following operators in Pawn:<br /> *Four-function: *, /, -, +<br /> *Bit-wise: |, &amp;, ^, ~, &lt;&lt;, &gt;&gt;<br /> <br /> Additionally, there are increment/decrement operators:<br /> &lt;pawn&gt;a = a + 1;<br /> a = a - 1;&lt;/pawn&gt;<br /> <br /> Can be simplified as:<br /> &lt;pawn&gt;a++;<br /> a--;&lt;/pawn&gt;<br /> <br /> As an advanced note, the ++ or -- can come before the variable (pre-increment, pre-decrement) or after the variable (post-increment, post-decrement). The difference is in how the rest of the expression containing them sees their result.<br /> <br /> * ''Pre:'' The variable is incremented before evaluation, and the rest of the expression sees the new value.<br /> * ''Post:'' The variable is incremented after evaluation, and the rest of the expression sees the old value.<br /> <br /> In other words, &lt;tt&gt;a++&lt;/tt&gt; evaluates to the value of &lt;tt&gt;a&lt;/tt&gt; while &lt;tt&gt;++a&lt;/tt&gt; evaluates to the value of &lt;tt&gt;a + 1&lt;/tt&gt;. In both cases &lt;tt&gt;a&lt;/tt&gt; is incremented by &lt;tt&gt;1&lt;/tt&gt;.<br /> <br /> For example:<br /> <br /> &lt;pawn&gt;int a = 5;<br /> int b = a++; // b = 5, a = 6 (1)<br /> int c = ++a; // a = 7, c = 7 (2)<br /> &lt;/pawn&gt;<br /> <br /> In (1) &lt;tt&gt;b&lt;/tt&gt; is assigned &lt;tt&gt;a&lt;/tt&gt;'s ''old'' value ''before'' it is incremented to &lt;tt&gt;6&lt;/tt&gt;, but in (2) &lt;tt&gt;c&lt;/tt&gt; is assigned &lt;tt&gt;a&lt;/tt&gt;'s ''int'' value ''after'' it is incremented to &lt;tt&gt;7&lt;/tt&gt;.<br /> <br /> ==Comparison Operators==<br /> There are six operators for comparing two values numerically, and the result is either true (non-zero) or false (zero):<br /> *&lt;tt&gt;a == b&lt;/tt&gt; - True if a and b have the same value.<br /> *&lt;tt&gt;a != b&lt;/tt&gt; - True if a and b have different values.<br /> *&lt;tt&gt;a &amp;gt; b&lt;/tt&gt; - True if a is greater than b<br /> *&lt;tt&gt;a &amp;gt;= b&lt;/tt&gt; - True if a is greater than or equal to b<br /> *&lt;tt&gt;a &amp;lt; b&lt;/tt&gt; - True if a is less than b<br /> *&lt;tt&gt;a &amp;lt;= b&lt;/tt&gt; - True if a is less than or equal to b<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> (1 != 3); //Evaluates to true because 1 is not equal to 3.<br /> (3 + 3 == 6); //Evaluates to true because 3+3 is 6.<br /> (5 - 2 &gt;= 4); //Evaluates to false because 3 is less than 4.<br /> &lt;/pawn&gt;<br /> <br /> Note that these operators do not work on arrays or strings. That is, you cannot compare either using &lt;tt&gt;==&lt;/tt&gt;.<br /> <br /> ==Truth Operators==<br /> These truth values can be combined using three boolean operators:<br /> *&lt;tt&gt;a &amp;&amp; b&lt;/tt&gt; - True if both a and b are true. False if a or b (or both) is false.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;&amp;&amp;&lt;/tt&gt; !! 0 !! 1<br /> |-<br /> ! 0<br /> | 0 || 0<br /> |-<br /> ! 1<br /> | 0 || 1<br /> |}<br /> *&lt;tt&gt;a || b&lt;/tt&gt; - True if a or b (or both) is true. False if both a and b are false.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;&lt;nowiki&gt;||&lt;/nowiki&gt;&lt;/tt&gt; !! 0 !! 1<br /> |-<br /> ! 0<br /> | 0 || 1<br /> |-<br /> ! 1<br /> | 1 || 1<br /> |}<br /> *&lt;tt&gt;!a&lt;/tt&gt; - True if a is false. False if a is true.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;!&lt;/tt&gt; !! 0 !! 1<br /> |- <br /> !<br /> | 1 || 0<br /> |}<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> (1 || 0); //Evaluates to true because the expression 1 is true<br /> (1 &amp;&amp; 0); //Evaluates to false because the expression 0 is false<br /> (!1 || 0); //Evaluates to false because !1 is false.<br /> &lt;/pawn&gt;<br /> <br /> ==Left/Right Values==<br /> Two important concepts are left-hand and right-hand values, or l-values and r-values. An l-value is what appears on the left-hand side of a variable assignment, and an r-value is what appears on the right side of a variable assignment.<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> int a = 5;&lt;/pawn&gt;<br /> <br /> In this example &lt;tt&gt;a&lt;/tt&gt; is an l-value and &lt;tt&gt;5&lt;/tt&gt; is an r-value.<br /> <br /> The rules:<br /> *'''Expressions are never l-values'''.<br /> *'''Variables are both l-values and r-values'''.<br /> <br /> =Conditionals=<br /> Conditional statements let you only run code if a certain condition is matched.<br /> <br /> ==If Statements==<br /> If statements test one or more conditions. For example:<br /> <br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code that will run if the expression was true */<br /> }&lt;/pawn&gt;<br /> <br /> They can be extended to handle more cases as well:<br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code */<br /> }<br /> else if (a == 6)<br /> {<br /> /* Code */<br /> }<br /> else if (a == 7)<br /> {<br /> /* Code */<br /> }&lt;/pawn&gt;<br /> <br /> You can also handle the case of no expression being matched. For example:<br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code */<br /> }<br /> else<br /> {<br /> /* Code that will run if no expressions were true */<br /> }&lt;/pawn&gt;<br /> <br /> ==Switch Statements==<br /> Switch statements are restricted if statements. They test one expression for a series of possible values. For example:<br /> <br /> &lt;pawn&gt;<br /> switch (a)<br /> {<br /> case 5:<br /> {<br /> /* code */<br /> }<br /> case 6:<br /> {<br /> /* code */<br /> }<br /> case 7:<br /> {<br /> /* code */<br /> }<br /> case 8, 9, 10:<br /> {<br /> /* Code */<br /> }<br /> default:<br /> {<br /> /* will run if no case matched */<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> Unlike some other languages, switches are not fall-through. That is, multiple cases will never be run. When a case matches its code is executed, and the switch is then immediately terminated.<br /> <br /> =Loops=<br /> Loops allow you to conveniently repeat a block of code while a given condition remains true. <br /> <br /> ==For Loops==<br /> For loops are loops which have four parts:<br /> *The '''initialization''' statement - run once before the first loop.<br /> *The '''condition''' statement - checks whether the next loop should run, including the first one. The loop terminates when this expression evaluates to false.<br /> *The '''iteration''' statement - run after each loop.<br /> *The '''body''' block - run each time the '''condition''' statement evaluates to true.<br /> <br /> &lt;pawn&gt;<br /> for ( /* initialization */ ; /* condition */ ; /* iteration */ )<br /> {<br /> /* body */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> A simple example is a function to sum an array:<br /> &lt;pawn&gt;<br /> int array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};<br /> int sum = SumArray(array, 10);<br /> <br /> int SumArray(const int array[], int count)<br /> {<br /> int total;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> total += array[i];<br /> }<br /> <br /> return total;<br /> }&lt;/pawn&gt;<br /> <br /> Broken down:<br /> *&lt;tt&gt;int i = 0&lt;/tt&gt; - Creates a new variable for the loop, sets it to 0.<br /> *&lt;tt&gt;i &lt; count&lt;/tt&gt; - Only runs the loop if &lt;tt&gt;i&lt;/tt&gt; is less than &lt;tt&gt;count&lt;/tt&gt;. This ensures that the loop stops reading at a certain point. In this case, we don't want to read invalid indexes in the array.<br /> *&lt;tt&gt;i++&lt;/tt&gt; - Increments &lt;tt&gt;i&lt;/tt&gt; by one after each loop. This ensures that the loop doesn't run forever; eventually &lt;tt&gt;i&lt;/tt&gt; will become too big and the loop will end.<br /> <br /> Thus, the &lt;tt&gt;SumArray&lt;/tt&gt; function will loop through each valid index of the array, each time adding that value of the array into a sum. For loops are very common for processing arrays like this.<br /> <br /> ==While Loops==<br /> While loops are less common than for loops but are actually the simplest possible loop. They have only two parts:<br /> *The '''condition''' statement - checked before each loop. The loop terminates when it evaluates to false.<br /> *The '''body''' block - run each time through the loop.<br /> <br /> &lt;pawn&gt;<br /> while ( /* condition */ )<br /> {<br /> /* body */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> As long as the condition expression remains true, the loop will continue. Every for loop can be rewritten as a while loop:<br /> <br /> &lt;pawn&gt;<br /> /* initialization */<br /> while ( /* condition */ )<br /> {<br /> /* body */<br /> /* iteration */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> Here is the previous for loop rewritten as a while loop:<br /> &lt;pawn&gt;<br /> int SumArray(const int array[], int count)<br /> {<br /> int total, i;<br /> <br /> while (i &lt; count)<br /> {<br /> total += array[i];<br /> i++;<br /> }<br /> <br /> return total;<br /> }&lt;/pawn&gt;<br /> <br /> There are also '''do...while''' loops which are even less common. These are the same as while loops except the condition check is AFTER each loop, rather than before. This means the loop is always run at least once. For example:<br /> <br /> &lt;pawn&gt;<br /> do<br /> {<br /> /* body */<br /> }<br /> while ( /* condition */ );<br /> &lt;/pawn&gt;<br /> <br /> ==Loop Control==<br /> There are two cases in which you want to selectively control a loop:<br /> *'''skipping''' one iteration of the loop but continuing as normal, or;<br /> *'''breaking''' the loop entirely before it's finished.<br /> <br /> Let's say you have a function which takes in an array and searches for a matching number. You want it to stop once the number is found:<br /> &lt;pawn&gt;<br /> /**<br /> * Returns the array index where the value is, or -1 if not found.<br /> */<br /> int SearchInArray(const int array[], int count, int value)<br /> {<br /> int index = -1;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> if (array[i] == value)<br /> {<br /> index = i;<br /> break;<br /> }<br /> }<br /> <br /> return index;<br /> }&lt;/pawn&gt;<br /> <br /> Certainly, this function could simply &lt;tt&gt;return i&lt;/tt&gt; instead, but the example shows how &lt;tt&gt;break&lt;/tt&gt; will terminate the loop.<br /> <br /> Similarly, the &lt;tt&gt;continue&lt;/tt&gt; keyword skips an iteration of a loop. For example, let's say we wanted to sum all even numbers:<br /> &lt;pawn&gt;<br /> int SumEvenNumbers(const int array[], int count)<br /> {<br /> int sum;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> /* If divisibility by 2 is 1, we know it's odd */<br /> if (array[i] % 2 == 1)<br /> {<br /> /* Skip the rest of this loop iteration */<br /> continue;<br /> }<br /> sum += array[i];<br /> }<br /> <br /> return sum;<br /> }&lt;/pawn&gt;<br /> <br /> =Scope=<br /> Scope refers to the '''visibility''' of code. That is, code at one level may not be &quot;visible&quot; to code at another level. For example:<br /> <br /> &lt;pawn&gt;<br /> int A, B, C;<br /> <br /> void Function1()<br /> {<br /> int B;<br /> <br /> Function2();<br /> }<br /> <br /> void Function2()<br /> {<br /> int C;<br /> }&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;A&lt;/tt&gt;, &lt;tt&gt;B&lt;/tt&gt;, and &lt;tt&gt;C&lt;/tt&gt; exist at '''global scope'''. They can be seen by any function. However, the &lt;tt&gt;B&lt;/tt&gt; in &lt;tt&gt;Function1&lt;/tt&gt; is not the same variable as the &lt;tt&gt;B&lt;/tt&gt; at the global level. Instead, it is at '''local scope''', and is thus a '''local variable'''.<br /> <br /> Similarly, &lt;tt&gt;Function1&lt;/tt&gt; and &lt;tt&gt;Function2&lt;/tt&gt; know nothing about each other's variables.<br /> <br /> Not only is the variable private to &lt;tt&gt;Function1&lt;/tt&gt;, but it is re-created each time the function is invoked. Imagine this:<br /> &lt;pawn&gt;<br /> void Function1()<br /> {<br /> int B;<br /> <br /> Function1();<br /> }&lt;/pawn&gt;<br /> <br /> In the above example, &lt;tt&gt;Function1&lt;/tt&gt; calls itself. Of course, this is infinite recursion (a bad thing), but the idea is that each time the function runs, there is a new copy of &lt;tt&gt;B&lt;/tt&gt;. When the function ends, &lt;tt&gt;B&lt;/tt&gt; is destroyed, and the value is lost.<br /> <br /> This property can be simplified by saying that a variable's scope is equal to the nesting level it is in. That is, a variable at global scope is visible globally to all functions. A variable at local scope is visible to all code blocks &quot;beneath&quot; its nesting level. For example:<br /> <br /> &lt;pawn&gt;void Function1()<br /> {<br /> int A;<br /> <br /> if (A)<br /> {<br /> A = 5;<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> The above code is valid since A's scope extends throughout the function. The following code, however, is not valid:<br /> &lt;pawn&gt;<br /> void Function1()<br /> {<br /> int A;<br /> <br /> if (A)<br /> {<br /> int B = 5;<br /> }<br /> <br /> B = 5;<br /> }&lt;/pawn&gt;<br /> <br /> Notice that &lt;tt&gt;B&lt;/tt&gt; is declared in a new code block. That means &lt;tt&gt;B&lt;/tt&gt; is only accessible to that code block (and all sub-blocks nested within). As soon as the code block terminates, &lt;tt&gt;B&lt;/tt&gt; is no longer valid.<br /> <br /> =Dynamic Arrays=<br /> Dynamic arrays are arrays which don't have a hardcoded size. For example:<br /> <br /> &lt;pawn&gt;void Function1(int size)<br /> {<br /> int array[size];<br /> <br /> /* Code */<br /> }&lt;/pawn&gt;<br /> <br /> Dynamic arrays can have any expression as their size as long as the expression evaluates to a number larger than 0. Like normal arrays, SourcePawn does not know the array size after it is created; you have to save it if you want it later.<br /> <br /> Dynamic arrays are only valid at the local scope level, since code cannot exist globally.<br /> <br /> =Extended Variable Declarations=<br /> Variables can be declared in more ways than simply &lt;tt&gt;int float or char&lt;/tt&gt;.<br /> <br /> ==static==<br /> The &lt;tt&gt;static&lt;/tt&gt; keyword is available at global and local scope. It has different meanings in each.<br /> <br /> ===Global static===<br /> A global static variable can only be accessed from within the same file. For example:<br /> <br /> &lt;pawn&gt;//file1.inc<br /> static float g_value1 = 0.15f;<br /> <br /> //file2.inc<br /> static float g_value2 = 0.15f;&lt;/pawn&gt;<br /> <br /> If a plugin includes both of these files, it will not be able to use either &lt;tt&gt;g_value1&lt;/tt&gt; or &lt;tt&gt;g_value2&lt;/tt&gt;. This is a simple information hiding mechanism, and is similar to declaring member variables as &lt;tt&gt;private&lt;/tt&gt; in languages like C++, Java, or C#.<br /> <br /> ===Local static===<br /> A local static variable is a global variable that is only visible from its local lexical scope. For example:<br /> <br /> &lt;pawn&gt;<br /> int MyFunction(int inc)<br /> {<br /> static int counter = -1;<br /> <br /> counter += inc;<br /> <br /> return counter;<br /> }&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;counter&lt;/tt&gt; is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time &lt;tt&gt;MyFunction&lt;/tt&gt; runs, the &lt;tt&gt;counter&lt;/tt&gt; variable and its storage in memory is the same.<br /> <br /> Take this example:<br /> &lt;pawn&gt;MyFunction(5);<br /> MyFunction(6);<br /> MyFunction(10);&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;counter&lt;/tt&gt; will be &lt;tt&gt;-1 + 5 + 6 + 10&lt;/tt&gt;, or &lt;tt&gt;20&lt;/tt&gt;, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then &lt;tt&gt;static&lt;/tt&gt; is usually not a good idea unless your code is re-entrant. <br /> <br /> The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.<br /> <br /> Note that statics can exist in any local scope:<br /> <br /> &lt;pawn&gt;<br /> int MyFunction(int inc)<br /> {<br /> if (inc &gt; 0)<br /> {<br /> static int counter;<br /> return (counter += inc);<br /> }<br /> return -1;<br /> }&lt;/pawn&gt;<br /> <br /> [[Category:SourceMod Scripting]]<br /> <br /> {{LanguageSwitch}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Introduction_to_SourcePawn_1.7&diff=10059 2015-11-15T18:41:01Z

<p>Xerox8521: Removal of decl as it is removed as of 1.7</p> <hr /> <div>This guide is designed to give you a very basic overview to fundamentals of scripting in SourcePawn. [[Pawn]] is a &quot;scripting&quot; language used to embed functionality in other programs. That means it is not a standalone language, like C++ or Java, and its details will differ based on the application. SourcePawn is the version of Pawn used in [[SourceMod]].<br /> <br /> This guide does not tell you how to write SourceMod plugins; it is intended as an overview of the syntax and semantics of the language instead. Read the separate article, [[Introduction to SourceMod Plugins]] for SourceMod API specifics. <br /> <br /> =Non-Programmer Intro=<br /> This section is intended for non-programmers. If you're still confused, you may want to pick up a book on another language, such as PHP, Python, or Java, to get a better idea of what programming is like.<br /> <br /> ==Symbols/Keywords==<br /> A symbol is a series of letters, numbers, and/or underscores, that uniquely represents something. Symbols are case-sensitive, and usually start with a letter.<br /> <br /> There are a few reserved symbols that have special meaning. For example, &lt;tt&gt;if&lt;/tt&gt;, &lt;tt&gt;for&lt;/tt&gt;, and &lt;tt&gt;return&lt;/tt&gt; are special constructs in the language that will explained later. They cannot be used as symbol names.<br /> <br /> ==Variables==<br /> There a few important constructs you should know before you begin to script. The first is a '''variable'''. A variable is a symbol, or name, that holds data. For example, the variable &quot;a&quot; could hold the number &quot;2&quot;, &quot;16&quot;, &quot;0&quot;, et cetera. Since a variable holds data, it also allocates the memory needed to store that data.<br /> <br /> In addition to a name, variables have a '''type'''. A type tells the program how to interpret the data, and how much memory the data will use. Pawn has three types of data that are most commonly used:<br /> * Integers, using the &lt;tt&gt;int&lt;/tt&gt; type. Integer types may store a whole number from -2147483648 to 2147483647.<br /> * Floats, using the &lt;tt&gt;float&lt;/tt&gt; type. Float types may store fractional numbers in a huge range, though they are not as precise as integers.<br /> * Characters, using the &lt;tt&gt;char&lt;/tt&gt; type. Character types store one byte of character information, typically an [http://www.asciitable.com/ ASCII] character.<br /> * Booleans, using the &lt;tt&gt;bool&lt;/tt&gt; type. Booleans store either true or false.<br /> <br /> Example of creating variables and assigning values:<br /> <br /> &lt;pawn&gt;int money = 5400;<br /> float percent = 67.3;<br /> bool enabled = false;<br /> &lt;/pawn&gt;<br /> <br /> ==Functions==<br /> The next important concept is '''functions'''. Functions are symbols or names that perform an action. When you invoke, or call them, they carry out a specific sequence of code and then return a result. There are a few types of functions, but every function is activated the same way. Example:<br /> <br /> &lt;pawn&gt;<br /> show(56); // Calls the &quot;show&quot; function, and gives it the number 56.<br /> enable(); // Calls the &quot;s &quot;enable&quot; function with no values.<br /> bool visible = show(a); //Calls the &quot;show&quot; function, stores its result in a variable.<br /> &lt;/pawn&gt;<br /> <br /> Every piece of data passed to a function is called a '''parameter'''. A function can have any number of parameters (there is a &quot;reasonable&quot; limit of 32 in SourceMod). Parameters will be explained further in the article.<br /> <br /> ==Comments==<br /> Note any text that appears after a &quot;//&quot; is considered a &quot;comment&quot; and is not actual code. There are two comment styles:<br /> *&lt;tt&gt;//&lt;/tt&gt; - Double slash, everything following on that line is ignored.<br /> *&lt;tt&gt;/* */&lt;/tt&gt; - Multi-line comment, everything in between the asterisks is ignored. You cannot nest these.<br /> <br /> <br /> ==Block Coding==<br /> The next concept is block coding. You can group code into &quot;blocks&quot; separated by { and }. This effectively makes one large block of code act as one statement. For example:<br /> <br /> &lt;pawn&gt;{<br /> here;<br /> is;<br /> some;<br /> code;<br /> }&lt;/pawn&gt;<br /> <br /> Block coding using braces is used everywhere in programming. Blocks of code can be nested within each other. It is a good idea to adapt a consistent and readable indentation style early on to prevent spaghetti-looking code.<br /> <br /> =Language Paradigms=<br /> Pawn may seem similar to other languages, like C, but it has fundamental differences. It is not important that you immediately understand these differences, but they may be helpful if you're familiar with another language already.<br /> *'''Pawn is sort of typed.''' Before SourceMod 1.7, Pawn did not have types. Older code and older natives will reflect this by using tags and the &lt;tt&gt;new&lt;/tt&gt; keyword. As of SourceMod 1.7, we recommend that all code use types. For more information see [[SourcePawn Transitional Syntax]].<br /> *'''Pawn is not garbage collected.''' Pawn, as a language, has no built-in memory allocation, and thus has no garbage. If a function allocates memory, you may be responsible for freeing it.<br /> *'''Pawn is not object oriented.''' Pawn does not have structs or objects. As of SourceMod 1.7, it has limited sugaring for treating some data types as objects, but users cannot create their own objects or classes.<br /> *'''Pawn is single-threaded.''' As of this writing, Pawn is not thread safe. <br /> *'''Pawn is compiled.''' Pawn is compiled to an intermediate, machine-independent code, which is stored in a &quot;.smx&quot; file. When loading .smx files, SourceMod translates this code to machine code for the platform and CPU it's running on.<br /> <br /> Early language design decisions were made by ITB CompuPhase. It is designed for low-level embedded devices and is thus very small and very fast.<br /> <br /> =Variables=<br /> Pawn currently supports the following basic variable types:<br /> *&lt;tt&gt;bool&lt;/tt&gt; - true or false.<br /> *&lt;tt&gt;char&lt;/tt&gt; - an 8-bit ASCII character.<br /> *&lt;tt&gt;int&lt;/tt&gt; - a 32-bit signed integer.<br /> *&lt;tt&gt;float&lt;/tt&gt; - a 32-bit IEEE-754 floating point number.<br /> *&lt;tt&gt;Handle&lt;/tt&gt; - the base type of a SourceMod object<br /> <br /> Other types may exist when defined in include files - for example, enums create new types for named integers, and many types derive from &lt;tt&gt;Handle&lt;/tt&gt;.<br /> <br /> Strings, currently, are 0-terminated arrays of &lt;tt&gt;char&lt;/tt&gt;s. They're described a little further ahead.<br /> <br /> ==Declaration==<br /> Below we include some examples of variable declarations, both valid and invalid. Keep in mind that SourcePawn has recently added new syntax, and that's what's documented below. Older code may use older declaration syntax, which is no longer supported.<br /> <br /> &lt;pawn&gt;<br /> int a = 5;<br /> float b = 5.0;<br /> bool c = true;<br /> bool d = false;<br /> &lt;/pawn&gt;<br /> <br /> Invalid variable usage:<br /> &lt;pawn&gt;<br /> int a = 5.0; // Type mismatch. 5.0 is a float.<br /> float b = 5; // Type mismatch. 5 is an integer.<br /> &lt;/pawn&gt;<br /> <br /> If a variable is not assigned upon declaration, it will be set to 0. For example:<br /> &lt;pawn&gt;<br /> int a; // Set to 0<br /> float b; // Set to 0.0<br /> bool c; // Set to false<br /> &lt;/pawn&gt;<br /> <br /> ==Assignment==<br /> Variables can be re-assigned data after they are created. For example:<br /> &lt;pawn&gt;int a;<br /> float b;<br /> bool c;<br /> <br /> a = 5;<br /> b = 5.0;<br /> c = true;<br /> &lt;/pawn&gt;<br /> <br /> =Arrays=<br /> An array is a sequence of data in a list. Arrays are useful for storing multiple pieces of data in one variable, or mapping one type of data to another.<br /> <br /> ==Declaration==<br /> An array is declared using brackets. Some examples of arrays:<br /> &lt;pawn&gt;<br /> int players[32]; // Stores 32 integers.<br /> float origin[3]; // Stores 3 floating point numbers<br /> &lt;/pawn&gt;<br /> <br /> By default, arrays are initialized to 0. You can assign them different default values, however:<br /> &lt;pawn&gt;<br /> int numbers[5] = {1, 2, 3, 4, 5}; // Stores 1, 2, 3, 4, 5.<br /> float origin[3] = {1.0, 2.0, 3.0}; // Stores 1.0, 2.0, 3.0.<br /> &lt;/pawn&gt;<br /> <br /> You can leave out the array size if you're going to pre-assign data to it. For example:<br /> &lt;pawn&gt;<br /> int numbers[] = {1, 3, 5, 7, 9};<br /> &lt;/pawn&gt;<br /> <br /> The compiler will automatically deduce that you intended an array of size 5.<br /> <br /> When array is declared with brackets after its name, Pawn considers that array to have a '''fixed size'''. The size of a fixed-size array is always known. Some arrays can be '''dynamically sized''', by putting the brackets before the name. For example,<br /> <br /> &lt;pawn&gt;<br /> int[] numbers = new int[MaxClients]<br /> &lt;/pawn&gt;<br /> <br /> This creates an array of size &lt;tt&gt;MaxClients&lt;/tt&gt;, which could be anything, so the size of the array is not known until the array is allocated.<br /> <br /> ==Usage==<br /> Using an array is just like using a normal variable. The only difference is the array must be '''indexed'''. Indexing an array means choosing the element which you wish to use.<br /> <br /> For example, here is an example of the above code using indexes:<br /> &lt;pawn&gt;<br /> int numbers[5];<br /> float origin[3];<br /> <br /> numbers[0] = 1;<br /> numbers[1] = 2;<br /> numbers[2] = 3;<br /> numbers[3] = 4;<br /> numbers[4] = 5;<br /> origin[0] = 1.0;<br /> origin[1] = 2.0;<br /> origin[2] = 3.0;<br /> &lt;/pawn&gt;<br /> <br /> Note that the '''index''' is what's in between the brackets. The index always starts from 0. That is, if an array has N elements, its valid indexes are from 0 to N-1. Accessing the data at these indexes works like a normal variable.<br /> <br /> Using an incorrect index will cause an error. For example:<br /> &lt;pawn&gt;<br /> int numbers[5];<br /> <br /> numbers[5] = 20;&lt;/pawn&gt;<br /> <br /> This may look correct, but 5 is not a valid index. The highest valid index is 4.<br /> <br /> You can use any expression as an index. For example:<br /> &lt;pawn&gt;int a, numbers[5];<br /> <br /> a = 1; // Set a = 1<br /> numbers[a] = 4; // Set numbers[1] = 4<br /> numbers[numbers[a]] = 2; // Set numbers[4] = 2<br /> &lt;/pawn&gt;<br /> <br /> Expressions will be discussed in depth later in the article.<br /> <br /> =Strings=<br /> Strings are a construct for storing text (or even raw binary data). A string is just an array of characters, except that the final character must be 0 (called the null terminator). Without a null terminator, Pawn would not know where to stop reading the string. All strings are [http://en.wikipedia.org/wiki/UTF-8 UTF-8] in SourcePawn.<br /> <br /> In general, you must have an idea of how large a string will be before you store it. SourcePawn does not yet have the capability of pre-determining storage space for strings.<br /> <br /> ==Usage==<br /> Strings are usually declared as arrays. For example:<br /> &lt;pawn&gt;<br /> char message[] = &quot;Hello!&quot;;<br /> char clams[6] = &quot;Clams&quot;;<br /> &lt;/pawn&gt;<br /> <br /> These are equivalent to doing:<br /> &lt;pawn&gt;<br /> char message[7];<br /> char clams[6];<br /> <br /> message[0] = 'H';<br /> message[1] = 'e';<br /> message[2] = 'l';<br /> message[3] = 'l';<br /> message[4] = 'o';<br /> message[5] = '!';<br /> message[6] = 0;<br /> clams[0] = 'C';<br /> clams[1] = 'l';<br /> clams[2] = 'a';<br /> clams[3] = 'm';<br /> clams[4] = 's';<br /> clams[5] = 0;<br /> &lt;/pawn&gt;<br /> <br /> Although strings are rarely initialized in this manner, it is very important to remember the concept of the null terminator, which signals the end of a string. The compiler, and most SourceMod functions will automatically null-terminate for you, so it is mainly important when manipulating strings directly.<br /> <br /> Note that a string is enclosed in double-quotes, but a character is enclosed in single quotes.<br /> <br /> ==Characters==<br /> A character of text can be used in either a String or a cell. For example:<br /> &lt;pawn&gt;char text[] = &quot;Crab&quot;;<br /> char clam;<br /> <br /> clam = 'D'; //Set clam to 'D'<br /> text[0] = 'A'; //Change the 'C' to 'A', it is now 'Arab'<br /> clam = text[0]; //Set clam to 'A'<br /> text[1] = clam; //Change the 'r' to 'A', is is now 'AAab'<br /> &lt;/pawn&gt;<br /> <br /> What you can't do is mix character arrays with strings. The internal storage is different. For example:<br /> &lt;pawn&gt;<br /> int clams[] = &quot;Clams&quot;; // Invalid.<br /> int clams[] = {'C', 'l', 'a', 'm', 's', 0}; // Valid, but NOT A STRING.<br /> &lt;/pawn&gt;<br /> <br /> =Functions=<br /> Functions, as stated before, are isolated blocks of code that perform an action. They can be invoked, or '''called''', with '''parameters''' that give specific options.<br /> <br /> There are two types of ways functions are called:<br /> *'''direct call''' - You specifically call a function in your code.<br /> *'''callback''' - The application calls a function in your code, as if it were an event trigger.<br /> <br /> There are six types of functions:<br /> *'''native''': A direct, internal function provided by the application.<br /> *'''public''': A callback function that is visible to the application and other scripts.<br /> *'''normal''': A normal function that only you can call.<br /> *'''static''': The scope of this function is restricted to the current file, can be used in combination with stock.<br /> *'''stock''': A normal function provided by an include file. If unused, it won't be compiled.<br /> *'''forward''': This function is a global event provided by the application. If you implement it, it will be a callback.<br /> <br /> All code in Pawn must exist in functions. This is in contrast to languages like PHP, Perl, and Python which let you write global code. That is because Pawn is a callback-based language: it responds to actions from a parent application, and functions must be written to handle those actions. Although our examples often contain free-floating code, this is purely for demonstration purposes. Free-floating code in our examples implies the code is part of some function.<br /> <br /> ==Declaration==<br /> Unlike variables, functions do not need to be declared before you use them. Functions have two pieces, the '''signature''' and the '''body'''. The signature contains the name of your function and the parameters it will accept. The body is the contents of its code.<br /> <br /> Example of a function:<br /> &lt;pawn&gt;<br /> int AddTwoNumbers(int first, int second)<br /> {<br /> int sum = first + second;<br /> return sum;<br /> }&lt;/pawn&gt;<br /> <br /> This is a simple function. The prototype is this line:<br /> &lt;pawn&gt;int AddTwoNumbers(int first, int second)&lt;/pawn&gt;<br /> <br /> Broken down, it means:<br /> *&lt;tt&gt;int&lt;/tt&gt; - Return value type (integer).<br /> *&lt;tt&gt;AddTwoNumbers&lt;/tt&gt; - Name of the function.<br /> *&lt;tt&gt;int first&lt;/tt&gt; - First parameter, an integer.<br /> *&lt;tt&gt;int second&lt;/tt&gt; - Second parameter, an integer.<br /> <br /> The body is a block of code. It creates a new variable, called &lt;tt&gt;sum&lt;/tt&gt;, and assigns it the value of the two parameters added together (more on expressions later). The important thing to notice is the &lt;tt&gt;return&lt;/tt&gt; statement, which tells the function to end and return a value to the caller of the function. All functions return something on completion, unless they return a special type called &lt;tt&gt;void&lt;/tt&gt;.<br /> <br /> A function can accept any type of input, and it can return any non-array type.<br /> <br /> You can, of course, pass variables to functions:<br /> &lt;pawn&gt;int numbers[3] = {1, 2, 0};<br /> <br /> numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);&lt;/pawn&gt;<br /> <br /> Note that cells are passed '''by value'''. That is, their value cannot be changed by the function. For example:<br /> &lt;pawn&gt;int a = 5;<br /> <br /> ChangeValue(a);<br /> <br /> ChangeValue(b)<br /> {<br /> b = 5;<br /> }&lt;/pawn&gt;<br /> <br /> This code would not change the value of &lt;tt&gt;a&lt;/tt&gt;. That is because a copy of the value in &lt;tt&gt;a&lt;/tt&gt; is passed instead of &lt;tt&gt;a&lt;/tt&gt; itself. <br /> <br /> More examples of functions will be provided throughout the article.<br /> <br /> ==Publics==<br /> Public functions are used to implement callbacks. You should not create a public function unless it is specifically implementing a callback. For example, here are two callbacks from &lt;tt&gt;sourcemod.inc&lt;/tt&gt;:<br /> <br /> &lt;pawn&gt;forward void OnPluginStart();<br /> forward void OnClientDisconnected(int client);&lt;/pawn&gt;<br /> <br /> To implement and receive these two events, you would write functions as such:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> /* Code here */<br /> }<br /> <br /> public void OnClientDisconnected(int client)<br /> {<br /> /* Code here */<br /> }&lt;/pawn&gt;<br /> <br /> The '''public''' keyword signals to the parent application that it should attach the function to the appropriate forwarded event.<br /> <br /> ==Natives==<br /> Natives are builtin functions provided by SourceMod. You can call them as if they were a normal function. For example, SourceMod has the following function:<br /> <br /> &lt;pawn&gt;native float FloatRound(float num);&lt;/pawn&gt;<br /> <br /> It can be called like so:<br /> &lt;pawn&gt;int rounded = FloatRound(5.2); // rounded will be 5&lt;/pawn&gt;<br /> <br /> ==Array Parameters==<br /> You can pass arrays or Strings as parameters. It is important to note that these are passed '''by reference'''. That is, rather than making a copy of the data, the data is referenced directly. There is a simple way of explaining this more concretely.<br /> <br /> &lt;pawn&gt;<br /> int example[] = {1, 2, 3, 4, 5};<br /> <br /> ChangeArray(example, 2, 29);<br /> <br /> void ChangeArray(int[] array, int index, int value)<br /> {<br /> array[index] = value;<br /> }&lt;/pawn&gt;<br /> <br /> The function sets the given index in the array to a given value. When it is run on our example array, it changes index 2 to from the value 3 to 29. I.e.:<br /> &lt;pawn&gt;example[2] = 29;&lt;/pawn&gt;<br /> <br /> Note two important things here. First, arrays are not copied when they are passed to functions - they are passed ''by reference'', so the view of the array is consistent at all times. Second, the brackets changed position in our function signature. This is because our function accepts an array of any size, and since we don't know the size, we must use the dynamic array syntax.<br /> <br /> To prevent an array from being modified in a function, you can mark it as &lt;tt&gt;const&lt;/tt&gt;. This will raise an error on code that attempts to modify it. For example:<br /> <br /> &lt;pawn&gt;void CantChangeArray(const array[], int index, int value)<br /> {<br /> array[index] = value; //Won't compile<br /> }&lt;/pawn&gt;<br /> <br /> It is a good idea to use &lt;tt&gt;const&lt;/tt&gt; in array parameters if you know the array won't be modified; this can prevent coding mistakes.<br /> <br /> =Expressions=<br /> Expressions are exactly the same as they are in mathematics. They are groups of operators/symbols which evaluate to one piece of data. They are often parenthetical (comprised of parenthesis). They contain a strict &quot;order of operations.&quot; They can contain variables, functions, numbers, and expressions themselves can be nested inside other expressions, or even passed as parameters.<br /> <br /> The simplest expression is a single number. For example:<br /> &lt;pawn&gt;<br /> 0; //Returns the number 0<br /> (0); //Returns the number 0 as well<br /> &lt;/pawn&gt;<br /> <br /> Although expressions can return any value, they are also said to either return ''zero or non-zero''. In that sense, ''zero'' is ''false'', and ''non-zero'' is ''true''. For example, -1 is '''true''' in Pawn, since it is non-zero. Do not assume negative numbers are false.<br /> <br /> The order of operations for expressions is similar to C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Here are some example expressions:<br /> &lt;pawn&gt;<br /> 5 + 6; //Evaluates to 11<br /> 5 * 6 + 3; //Evaluates to 33<br /> 5 * (6 + 3); //Evaluates to 45<br /> 5.0 + 2.3; //Evaluates to 7.3<br /> (5 * 6) % 7; //Modulo operator, evaluates to 2<br /> (5 + 3) / 2 * 4 - 9; //Evaluates to -8<br /> &lt;/pawn&gt;<br /> <br /> As noted, expressions can contain variables, or even functions:<br /> &lt;pawn&gt;<br /> int a = 5 * 6;<br /> int b = a * 3; //Evaluates to 90<br /> int c = AddTwoNumbers(a, b) + (a * b);<br /> &lt;/pawn&gt;<br /> <br /> Note: String manipulation routines may be found in the string.inc file located in the include subdirectory. They may be browsed through the [http://docs.sourcemod.net/api/ API Reference] as well.<br /> <br /> ==Operators==<br /> There are a few extra helpful operators in Pawn. The first set simplifies self-aggregation expressions. For example:<br /> &lt;pawn&gt;int a = 5;<br /> <br /> a = a + 5;&lt;/pawn&gt;<br /> <br /> Can be rewritten as:<br /> &lt;pawn&gt;int a = 5;<br /> a += 5;&lt;/pawn&gt;<br /> <br /> This is true of the following operators in Pawn:<br /> *Four-function: *, /, -, +<br /> *Bit-wise: |, &amp;, ^, ~, &lt;&lt;, &gt;&gt;<br /> <br /> Additionally, there are increment/decrement operators:<br /> &lt;pawn&gt;a = a + 1;<br /> a = a - 1;&lt;/pawn&gt;<br /> <br /> Can be simplified as:<br /> &lt;pawn&gt;a++;<br /> a--;&lt;/pawn&gt;<br /> <br /> As an advanced note, the ++ or -- can come before the variable (pre-increment, pre-decrement) or after the variable (post-increment, post-decrement). The difference is in how the rest of the expression containing them sees their result.<br /> <br /> * ''Pre:'' The variable is incremented before evaluation, and the rest of the expression sees the new value.<br /> * ''Post:'' The variable is incremented after evaluation, and the rest of the expression sees the old value.<br /> <br /> In other words, &lt;tt&gt;a++&lt;/tt&gt; evaluates to the value of &lt;tt&gt;a&lt;/tt&gt; while &lt;tt&gt;++a&lt;/tt&gt; evaluates to the value of &lt;tt&gt;a + 1&lt;/tt&gt;. In both cases &lt;tt&gt;a&lt;/tt&gt; is incremented by &lt;tt&gt;1&lt;/tt&gt;.<br /> <br /> For example:<br /> <br /> &lt;pawn&gt;int a = 5;<br /> int b = a++; // b = 5, a = 6 (1)<br /> int c = ++a; // a = 7, c = 7 (2)<br /> &lt;/pawn&gt;<br /> <br /> In (1) &lt;tt&gt;b&lt;/tt&gt; is assigned &lt;tt&gt;a&lt;/tt&gt;'s ''old'' value ''before'' it is incremented to &lt;tt&gt;6&lt;/tt&gt;, but in (2) &lt;tt&gt;c&lt;/tt&gt; is assigned &lt;tt&gt;a&lt;/tt&gt;'s ''int'' value ''after'' it is incremented to &lt;tt&gt;7&lt;/tt&gt;.<br /> <br /> ==Comparison Operators==<br /> There are six operators for comparing two values numerically, and the result is either true (non-zero) or false (zero):<br /> *&lt;tt&gt;a == b&lt;/tt&gt; - True if a and b have the same value.<br /> *&lt;tt&gt;a != b&lt;/tt&gt; - True if a and b have different values.<br /> *&lt;tt&gt;a &amp;gt; b&lt;/tt&gt; - True if a is greater than b<br /> *&lt;tt&gt;a &amp;gt;= b&lt;/tt&gt; - True if a is greater than or equal to b<br /> *&lt;tt&gt;a &amp;lt; b&lt;/tt&gt; - True if a is less than b<br /> *&lt;tt&gt;a &amp;lt;= b&lt;/tt&gt; - True if a is less than or equal to b<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> (1 != 3); //Evaluates to true because 1 is not equal to 3.<br /> (3 + 3 == 6); //Evaluates to true because 3+3 is 6.<br /> (5 - 2 &gt;= 4); //Evaluates to false because 3 is less than 4.<br /> &lt;/pawn&gt;<br /> <br /> Note that these operators do not work on arrays or strings. That is, you cannot compare either using &lt;tt&gt;==&lt;/tt&gt;.<br /> <br /> ==Truth Operators==<br /> These truth values can be combined using three boolean operators:<br /> *&lt;tt&gt;a &amp;&amp; b&lt;/tt&gt; - True if both a and b are true. False if a or b (or both) is false.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;&amp;&amp;&lt;/tt&gt; !! 0 !! 1<br /> |-<br /> ! 0<br /> | 0 || 0<br /> |-<br /> ! 1<br /> | 0 || 1<br /> |}<br /> *&lt;tt&gt;a || b&lt;/tt&gt; - True if a or b (or both) is true. False if both a and b are false.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;&lt;nowiki&gt;||&lt;/nowiki&gt;&lt;/tt&gt; !! 0 !! 1<br /> |-<br /> ! 0<br /> | 0 || 1<br /> |-<br /> ! 1<br /> | 1 || 1<br /> |}<br /> *&lt;tt&gt;!a&lt;/tt&gt; - True if a is false. False if a is true.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;!&lt;/tt&gt; !! 0 !! 1<br /> |- <br /> !<br /> | 1 || 0<br /> |}<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> (1 || 0); //Evaluates to true because the expression 1 is true<br /> (1 &amp;&amp; 0); //Evaluates to false because the expression 0 is false<br /> (!1 || 0); //Evaluates to false because !1 is false.<br /> &lt;/pawn&gt;<br /> <br /> ==Left/Right Values==<br /> Two important concepts are left-hand and right-hand values, or l-values and r-values. An l-value is what appears on the left-hand side of a variable assignment, and an r-value is what appears on the right side of a variable assignment.<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> int a = 5;&lt;/pawn&gt;<br /> <br /> In this example &lt;tt&gt;a&lt;/tt&gt; is an l-value and &lt;tt&gt;5&lt;/tt&gt; is an r-value.<br /> <br /> The rules:<br /> *'''Expressions are never l-values'''.<br /> *'''Variables are both l-values and r-values'''.<br /> <br /> =Conditionals=<br /> Conditional statements let you only run code if a certain condition is matched.<br /> <br /> ==If Statements==<br /> If statements test one or more conditions. For example:<br /> <br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code that will run if the expression was true */<br /> }&lt;/pawn&gt;<br /> <br /> They can be extended to handle more cases as well:<br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code */<br /> }<br /> else if (a == 6)<br /> {<br /> /* Code */<br /> }<br /> else if (a == 7)<br /> {<br /> /* Code */<br /> }&lt;/pawn&gt;<br /> <br /> You can also handle the case of no expression being matched. For example:<br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code */<br /> }<br /> else<br /> {<br /> /* Code that will run if no expressions were true */<br /> }&lt;/pawn&gt;<br /> <br /> ==Switch Statements==<br /> Switch statements are restricted if statements. They test one expression for a series of possible values. For example:<br /> <br /> &lt;pawn&gt;<br /> switch (a)<br /> {<br /> case 5:<br /> {<br /> /* code */<br /> }<br /> case 6:<br /> {<br /> /* code */<br /> }<br /> case 7:<br /> {<br /> /* code */<br /> }<br /> case 8, 9, 10:<br /> {<br /> /* Code */<br /> }<br /> default:<br /> {<br /> /* will run if no case matched */<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> Unlike some other languages, switches are not fall-through. That is, multiple cases will never be run. When a case matches its code is executed, and the switch is then immediately terminated.<br /> <br /> =Loops=<br /> Loops allow you to conveniently repeat a block of code while a given condition remains true. <br /> <br /> ==For Loops==<br /> For loops are loops which have four parts:<br /> *The '''initialization''' statement - run once before the first loop.<br /> *The '''condition''' statement - checks whether the next loop should run, including the first one. The loop terminates when this expression evaluates to false.<br /> *The '''iteration''' statement - run after each loop.<br /> *The '''body''' block - run each time the '''condition''' statement evaluates to true.<br /> <br /> &lt;pawn&gt;<br /> for ( /* initialization */ ; /* condition */ ; /* iteration */ )<br /> {<br /> /* body */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> A simple example is a function to sum an array:<br /> &lt;pawn&gt;<br /> int array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};<br /> int sum = SumArray(array, 10);<br /> <br /> int SumArray(const int array[], int count)<br /> {<br /> int total;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> total += array[i];<br /> }<br /> <br /> return total;<br /> }&lt;/pawn&gt;<br /> <br /> Broken down:<br /> *&lt;tt&gt;int i = 0&lt;/tt&gt; - Creates a new variable for the loop, sets it to 0.<br /> *&lt;tt&gt;i &lt; count&lt;/tt&gt; - Only runs the loop if &lt;tt&gt;i&lt;/tt&gt; is less than &lt;tt&gt;count&lt;/tt&gt;. This ensures that the loop stops reading at a certain point. In this case, we don't want to read invalid indexes in the array.<br /> *&lt;tt&gt;i++&lt;/tt&gt; - Increments &lt;tt&gt;i&lt;/tt&gt; by one after each loop. This ensures that the loop doesn't run forever; eventually &lt;tt&gt;i&lt;/tt&gt; will become too big and the loop will end.<br /> <br /> Thus, the &lt;tt&gt;SumArray&lt;/tt&gt; function will loop through each valid index of the array, each time adding that value of the array into a sum. For loops are very common for processing arrays like this.<br /> <br /> ==While Loops==<br /> While loops are less common than for loops but are actually the simplest possible loop. They have only two parts:<br /> *The '''condition''' statement - checked before each loop. The loop terminates when it evaluates to false.<br /> *The '''body''' block - run each time through the loop.<br /> <br /> &lt;pawn&gt;<br /> while ( /* condition */ )<br /> {<br /> /* body */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> As long as the condition expression remains true, the loop will continue. Every for loop can be rewritten as a while loop:<br /> <br /> &lt;pawn&gt;<br /> /* initialization */<br /> while ( /* condition */ )<br /> {<br /> /* body */<br /> /* iteration */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> Here is the previous for loop rewritten as a while loop:<br /> &lt;pawn&gt;<br /> int SumArray(const int array[], int count)<br /> {<br /> int total, i;<br /> <br /> while (i &lt; count)<br /> {<br /> total += array[i];<br /> i++;<br /> }<br /> <br /> return total;<br /> }&lt;/pawn&gt;<br /> <br /> There are also '''do...while''' loops which are even less common. These are the same as while loops except the condition check is AFTER each loop, rather than before. This means the loop is always run at least once. For example:<br /> <br /> &lt;pawn&gt;<br /> do<br /> {<br /> /* body */<br /> }<br /> while ( /* condition */ );<br /> &lt;/pawn&gt;<br /> <br /> ==Loop Control==<br /> There are two cases in which you want to selectively control a loop:<br /> *'''skipping''' one iteration of the loop but continuing as normal, or;<br /> *'''breaking''' the loop entirely before it's finished.<br /> <br /> Let's say you have a function which takes in an array and searches for a matching number. You want it to stop once the number is found:<br /> &lt;pawn&gt;<br /> /**<br /> * Returns the array index where the value is, or -1 if not found.<br /> */<br /> int SearchInArray(const int array[], int count, int value)<br /> {<br /> int index = -1;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> if (array[i] == value)<br /> {<br /> index = i;<br /> break;<br /> }<br /> }<br /> <br /> return index;<br /> }&lt;/pawn&gt;<br /> <br /> Certainly, this function could simply &lt;tt&gt;return i&lt;/tt&gt; instead, but the example shows how &lt;tt&gt;break&lt;/tt&gt; will terminate the loop.<br /> <br /> Similarly, the &lt;tt&gt;continue&lt;/tt&gt; keyword skips an iteration of a loop. For example, let's say we wanted to sum all even numbers:<br /> &lt;pawn&gt;<br /> int SumEvenNumbers(const int array[], int count)<br /> {<br /> int sum;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> /* If divisibility by 2 is 1, we know it's odd */<br /> if (array[i] % 2 == 1)<br /> {<br /> /* Skip the rest of this loop iteration */<br /> continue;<br /> }<br /> sum += array[i];<br /> }<br /> <br /> return sum;<br /> }&lt;/pawn&gt;<br /> <br /> =Scope=<br /> Scope refers to the '''visibility''' of code. That is, code at one level may not be &quot;visible&quot; to code at another level. For example:<br /> <br /> &lt;pawn&gt;<br /> int A, B, C;<br /> <br /> void Function1()<br /> {<br /> int B;<br /> <br /> Function2();<br /> }<br /> <br /> void Function2()<br /> {<br /> int C;<br /> }&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;A&lt;/tt&gt;, &lt;tt&gt;B&lt;/tt&gt;, and &lt;tt&gt;C&lt;/tt&gt; exist at '''global scope'''. They can be seen by any function. However, the &lt;tt&gt;B&lt;/tt&gt; in &lt;tt&gt;Function1&lt;/tt&gt; is not the same variable as the &lt;tt&gt;B&lt;/tt&gt; at the global level. Instead, it is at '''local scope''', and is thus a '''local variable'''.<br /> <br /> Similarly, &lt;tt&gt;Function1&lt;/tt&gt; and &lt;tt&gt;Function2&lt;/tt&gt; know nothing about each other's variables.<br /> <br /> Not only is the variable private to &lt;tt&gt;Function1&lt;/tt&gt;, but it is re-created each time the function is invoked. Imagine this:<br /> &lt;pawn&gt;<br /> void Function1()<br /> {<br /> int B;<br /> <br /> Function1();<br /> }&lt;/pawn&gt;<br /> <br /> In the above example, &lt;tt&gt;Function1&lt;/tt&gt; calls itself. Of course, this is infinite recursion (a bad thing), but the idea is that each time the function runs, there is a new copy of &lt;tt&gt;B&lt;/tt&gt;. When the function ends, &lt;tt&gt;B&lt;/tt&gt; is destroyed, and the value is lost.<br /> <br /> This property can be simplified by saying that a variable's scope is equal to the nesting level it is in. That is, a variable at global scope is visible globally to all functions. A variable at local scope is visible to all code blocks &quot;beneath&quot; its nesting level. For example:<br /> <br /> &lt;pawn&gt;void Function1()<br /> {<br /> int A;<br /> <br /> if (A)<br /> {<br /> A = 5;<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> The above code is valid since A's scope extends throughout the function. The following code, however, is not valid:<br /> &lt;pawn&gt;<br /> void Function1()<br /> {<br /> int A;<br /> <br /> if (A)<br /> {<br /> int B = 5;<br /> }<br /> <br /> B = 5;<br /> }&lt;/pawn&gt;<br /> <br /> Notice that &lt;tt&gt;B&lt;/tt&gt; is declared in a new code block. That means &lt;tt&gt;B&lt;/tt&gt; is only accessible to that code block (and all sub-blocks nested within). As soon as the code block terminates, &lt;tt&gt;B&lt;/tt&gt; is no longer valid.<br /> <br /> =Dynamic Arrays=<br /> Dynamic arrays are arrays which don't have a hardcoded size. For example:<br /> <br /> &lt;pawn&gt;void Function1(int size)<br /> {<br /> int array[size];<br /> <br /> /* Code */<br /> }&lt;/pawn&gt;<br /> <br /> Dynamic arrays can have any expression as their size as long as the expression evaluates to a number larger than 0. Like normal arrays, SourcePawn does not know the array size after it is created; you have to save it if you want it later.<br /> <br /> Dynamic arrays are only valid at the local scope level, since code cannot exist globally.<br /> <br /> =Extended Variable Declarations=<br /> Variables can be declared in more ways than simply &lt;tt&gt;new&lt;/tt&gt;.<br /> <br /> ==static==<br /> The &lt;tt&gt;static&lt;/tt&gt; keyword is available at global and local scope. It has different meanings in each.<br /> <br /> ===Global static===<br /> A global static variable can only be accessed from within the same file. For example:<br /> <br /> &lt;pawn&gt;//file1.inc<br /> static float g_value1 = 0.15f;<br /> <br /> //file2.inc<br /> static float g_value2 = 0.15f;&lt;/pawn&gt;<br /> <br /> If a plugin includes both of these files, it will not be able to use either &lt;tt&gt;g_value1&lt;/tt&gt; or &lt;tt&gt;g_value2&lt;/tt&gt;. This is a simple information hiding mechanism, and is similar to declaring member variables as &lt;tt&gt;private&lt;/tt&gt; in languages like C++, Java, or C#.<br /> <br /> ===Local static===<br /> A local static variable is a global variable that is only visible from its local lexical scope. For example:<br /> <br /> &lt;pawn&gt;<br /> int MyFunction(int inc)<br /> {<br /> static int counter = -1;<br /> <br /> counter += inc;<br /> <br /> return counter;<br /> }&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;counter&lt;/tt&gt; is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time &lt;tt&gt;MyFunction&lt;/tt&gt; runs, the &lt;tt&gt;counter&lt;/tt&gt; variable and its storage in memory is the same.<br /> <br /> Take this example:<br /> &lt;pawn&gt;MyFunction(5);<br /> MyFunction(6);<br /> MyFunction(10);&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;counter&lt;/tt&gt; will be &lt;tt&gt;-1 + 5 + 6 + 10&lt;/tt&gt;, or &lt;tt&gt;20&lt;/tt&gt;, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then &lt;tt&gt;static&lt;/tt&gt; is usually not a good idea unless your code is re-entrant. <br /> <br /> The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.<br /> <br /> Note that statics can exist in any local scope:<br /> <br /> &lt;pawn&gt;<br /> int MyFunction(int inc)<br /> {<br /> if (inc &gt; 0)<br /> {<br /> static int counter;<br /> return (counter += inc);<br /> }<br /> return -1;<br /> }&lt;/pawn&gt;<br /> <br /> [[Category:SourceMod Scripting]]<br /> <br /> {{LanguageSwitch}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Introduction_to_SourcePawn_1.7&diff=10058 2015-11-15T18:37:59Z

<p>Xerox8521: /* Scope */</p> <hr /> <div>This guide is designed to give you a very basic overview to fundamentals of scripting in SourcePawn. [[Pawn]] is a &quot;scripting&quot; language used to embed functionality in other programs. That means it is not a standalone language, like C++ or Java, and its details will differ based on the application. SourcePawn is the version of Pawn used in [[SourceMod]].<br /> <br /> This guide does not tell you how to write SourceMod plugins; it is intended as an overview of the syntax and semantics of the language instead. Read the separate article, [[Introduction to SourceMod Plugins]] for SourceMod API specifics. <br /> <br /> =Non-Programmer Intro=<br /> This section is intended for non-programmers. If you're still confused, you may want to pick up a book on another language, such as PHP, Python, or Java, to get a better idea of what programming is like.<br /> <br /> ==Symbols/Keywords==<br /> A symbol is a series of letters, numbers, and/or underscores, that uniquely represents something. Symbols are case-sensitive, and usually start with a letter.<br /> <br /> There are a few reserved symbols that have special meaning. For example, &lt;tt&gt;if&lt;/tt&gt;, &lt;tt&gt;for&lt;/tt&gt;, and &lt;tt&gt;return&lt;/tt&gt; are special constructs in the language that will explained later. They cannot be used as symbol names.<br /> <br /> ==Variables==<br /> There a few important constructs you should know before you begin to script. The first is a '''variable'''. A variable is a symbol, or name, that holds data. For example, the variable &quot;a&quot; could hold the number &quot;2&quot;, &quot;16&quot;, &quot;0&quot;, et cetera. Since a variable holds data, it also allocates the memory needed to store that data.<br /> <br /> In addition to a name, variables have a '''type'''. A type tells the program how to interpret the data, and how much memory the data will use. Pawn has three types of data that are most commonly used:<br /> * Integers, using the &lt;tt&gt;int&lt;/tt&gt; type. Integer types may store a whole number from -2147483648 to 2147483647.<br /> * Floats, using the &lt;tt&gt;float&lt;/tt&gt; type. Float types may store fractional numbers in a huge range, though they are not as precise as integers.<br /> * Characters, using the &lt;tt&gt;char&lt;/tt&gt; type. Character types store one byte of character information, typically an [http://www.asciitable.com/ ASCII] character.<br /> * Booleans, using the &lt;tt&gt;bool&lt;/tt&gt; type. Booleans store either true or false.<br /> <br /> Example of creating variables and assigning values:<br /> <br /> &lt;pawn&gt;int money = 5400;<br /> float percent = 67.3;<br /> bool enabled = false;<br /> &lt;/pawn&gt;<br /> <br /> ==Functions==<br /> The next important concept is '''functions'''. Functions are symbols or names that perform an action. When you invoke, or call them, they carry out a specific sequence of code and then return a result. There are a few types of functions, but every function is activated the same way. Example:<br /> <br /> &lt;pawn&gt;<br /> show(56); // Calls the &quot;show&quot; function, and gives it the number 56.<br /> enable(); // Calls the &quot;s &quot;enable&quot; function with no values.<br /> bool visible = show(a); //Calls the &quot;show&quot; function, stores its result in a variable.<br /> &lt;/pawn&gt;<br /> <br /> Every piece of data passed to a function is called a '''parameter'''. A function can have any number of parameters (there is a &quot;reasonable&quot; limit of 32 in SourceMod). Parameters will be explained further in the article.<br /> <br /> ==Comments==<br /> Note any text that appears after a &quot;//&quot; is considered a &quot;comment&quot; and is not actual code. There are two comment styles:<br /> *&lt;tt&gt;//&lt;/tt&gt; - Double slash, everything following on that line is ignored.<br /> *&lt;tt&gt;/* */&lt;/tt&gt; - Multi-line comment, everything in between the asterisks is ignored. You cannot nest these.<br /> <br /> <br /> ==Block Coding==<br /> The next concept is block coding. You can group code into &quot;blocks&quot; separated by { and }. This effectively makes one large block of code act as one statement. For example:<br /> <br /> &lt;pawn&gt;{<br /> here;<br /> is;<br /> some;<br /> code;<br /> }&lt;/pawn&gt;<br /> <br /> Block coding using braces is used everywhere in programming. Blocks of code can be nested within each other. It is a good idea to adapt a consistent and readable indentation style early on to prevent spaghetti-looking code.<br /> <br /> =Language Paradigms=<br /> Pawn may seem similar to other languages, like C, but it has fundamental differences. It is not important that you immediately understand these differences, but they may be helpful if you're familiar with another language already.<br /> *'''Pawn is sort of typed.''' Before SourceMod 1.7, Pawn did not have types. Older code and older natives will reflect this by using tags and the &lt;tt&gt;new&lt;/tt&gt; keyword. As of SourceMod 1.7, we recommend that all code use types. For more information see [[SourcePawn Transitional Syntax]].<br /> *'''Pawn is not garbage collected.''' Pawn, as a language, has no built-in memory allocation, and thus has no garbage. If a function allocates memory, you may be responsible for freeing it.<br /> *'''Pawn is not object oriented.''' Pawn does not have structs or objects. As of SourceMod 1.7, it has limited sugaring for treating some data types as objects, but users cannot create their own objects or classes.<br /> *'''Pawn is single-threaded.''' As of this writing, Pawn is not thread safe. <br /> *'''Pawn is compiled.''' Pawn is compiled to an intermediate, machine-independent code, which is stored in a &quot;.smx&quot; file. When loading .smx files, SourceMod translates this code to machine code for the platform and CPU it's running on.<br /> <br /> Early language design decisions were made by ITB CompuPhase. It is designed for low-level embedded devices and is thus very small and very fast.<br /> <br /> =Variables=<br /> Pawn currently supports the following basic variable types:<br /> *&lt;tt&gt;bool&lt;/tt&gt; - true or false.<br /> *&lt;tt&gt;char&lt;/tt&gt; - an 8-bit ASCII character.<br /> *&lt;tt&gt;int&lt;/tt&gt; - a 32-bit signed integer.<br /> *&lt;tt&gt;float&lt;/tt&gt; - a 32-bit IEEE-754 floating point number.<br /> *&lt;tt&gt;Handle&lt;/tt&gt; - the base type of a SourceMod object<br /> <br /> Other types may exist when defined in include files - for example, enums create new types for named integers, and many types derive from &lt;tt&gt;Handle&lt;/tt&gt;.<br /> <br /> Strings, currently, are 0-terminated arrays of &lt;tt&gt;char&lt;/tt&gt;s. They're described a little further ahead.<br /> <br /> ==Declaration==<br /> Below we include some examples of variable declarations, both valid and invalid. Keep in mind that SourcePawn has recently added new syntax, and that's what's documented below. Older code may use older declaration syntax, which is no longer supported.<br /> <br /> &lt;pawn&gt;<br /> int a = 5;<br /> float b = 5.0;<br /> bool c = true;<br /> bool d = false;<br /> &lt;/pawn&gt;<br /> <br /> Invalid variable usage:<br /> &lt;pawn&gt;<br /> int a = 5.0; // Type mismatch. 5.0 is a float.<br /> float b = 5; // Type mismatch. 5 is an integer.<br /> &lt;/pawn&gt;<br /> <br /> If a variable is not assigned upon declaration, it will be set to 0. For example:<br /> &lt;pawn&gt;<br /> int a; // Set to 0<br /> float b; // Set to 0.0<br /> bool c; // Set to false<br /> &lt;/pawn&gt;<br /> <br /> ==Assignment==<br /> Variables can be re-assigned data after they are created. For example:<br /> &lt;pawn&gt;int a;<br /> float b;<br /> bool c;<br /> <br /> a = 5;<br /> b = 5.0;<br /> c = true;<br /> &lt;/pawn&gt;<br /> <br /> =Arrays=<br /> An array is a sequence of data in a list. Arrays are useful for storing multiple pieces of data in one variable, or mapping one type of data to another.<br /> <br /> ==Declaration==<br /> An array is declared using brackets. Some examples of arrays:<br /> &lt;pawn&gt;<br /> int players[32]; // Stores 32 integers.<br /> float origin[3]; // Stores 3 floating point numbers<br /> &lt;/pawn&gt;<br /> <br /> By default, arrays are initialized to 0. You can assign them different default values, however:<br /> &lt;pawn&gt;<br /> int numbers[5] = {1, 2, 3, 4, 5}; // Stores 1, 2, 3, 4, 5.<br /> float origin[3] = {1.0, 2.0, 3.0}; // Stores 1.0, 2.0, 3.0.<br /> &lt;/pawn&gt;<br /> <br /> You can leave out the array size if you're going to pre-assign data to it. For example:<br /> &lt;pawn&gt;<br /> int numbers[] = {1, 3, 5, 7, 9};<br /> &lt;/pawn&gt;<br /> <br /> The compiler will automatically deduce that you intended an array of size 5.<br /> <br /> When array is declared with brackets after its name, Pawn considers that array to have a '''fixed size'''. The size of a fixed-size array is always known. Some arrays can be '''dynamically sized''', by putting the brackets before the name. For example,<br /> <br /> &lt;pawn&gt;<br /> int[] numbers = new int[MaxClients]<br /> &lt;/pawn&gt;<br /> <br /> This creates an array of size &lt;tt&gt;MaxClients&lt;/tt&gt;, which could be anything, so the size of the array is not known until the array is allocated.<br /> <br /> ==Usage==<br /> Using an array is just like using a normal variable. The only difference is the array must be '''indexed'''. Indexing an array means choosing the element which you wish to use.<br /> <br /> For example, here is an example of the above code using indexes:<br /> &lt;pawn&gt;<br /> int numbers[5];<br /> float origin[3];<br /> <br /> numbers[0] = 1;<br /> numbers[1] = 2;<br /> numbers[2] = 3;<br /> numbers[3] = 4;<br /> numbers[4] = 5;<br /> origin[0] = 1.0;<br /> origin[1] = 2.0;<br /> origin[2] = 3.0;<br /> &lt;/pawn&gt;<br /> <br /> Note that the '''index''' is what's in between the brackets. The index always starts from 0. That is, if an array has N elements, its valid indexes are from 0 to N-1. Accessing the data at these indexes works like a normal variable.<br /> <br /> Using an incorrect index will cause an error. For example:<br /> &lt;pawn&gt;<br /> int numbers[5];<br /> <br /> numbers[5] = 20;&lt;/pawn&gt;<br /> <br /> This may look correct, but 5 is not a valid index. The highest valid index is 4.<br /> <br /> You can use any expression as an index. For example:<br /> &lt;pawn&gt;int a, numbers[5];<br /> <br /> a = 1; // Set a = 1<br /> numbers[a] = 4; // Set numbers[1] = 4<br /> numbers[numbers[a]] = 2; // Set numbers[4] = 2<br /> &lt;/pawn&gt;<br /> <br /> Expressions will be discussed in depth later in the article.<br /> <br /> =Strings=<br /> Strings are a construct for storing text (or even raw binary data). A string is just an array of characters, except that the final character must be 0 (called the null terminator). Without a null terminator, Pawn would not know where to stop reading the string. All strings are [http://en.wikipedia.org/wiki/UTF-8 UTF-8] in SourcePawn.<br /> <br /> In general, you must have an idea of how large a string will be before you store it. SourcePawn does not yet have the capability of pre-determining storage space for strings.<br /> <br /> ==Usage==<br /> Strings are usually declared as arrays. For example:<br /> &lt;pawn&gt;<br /> char message[] = &quot;Hello!&quot;;<br /> char clams[6] = &quot;Clams&quot;;<br /> &lt;/pawn&gt;<br /> <br /> These are equivalent to doing:<br /> &lt;pawn&gt;<br /> char message[7];<br /> char clams[6];<br /> <br /> message[0] = 'H';<br /> message[1] = 'e';<br /> message[2] = 'l';<br /> message[3] = 'l';<br /> message[4] = 'o';<br /> message[5] = '!';<br /> message[6] = 0;<br /> clams[0] = 'C';<br /> clams[1] = 'l';<br /> clams[2] = 'a';<br /> clams[3] = 'm';<br /> clams[4] = 's';<br /> clams[5] = 0;<br /> &lt;/pawn&gt;<br /> <br /> Although strings are rarely initialized in this manner, it is very important to remember the concept of the null terminator, which signals the end of a string. The compiler, and most SourceMod functions will automatically null-terminate for you, so it is mainly important when manipulating strings directly.<br /> <br /> Note that a string is enclosed in double-quotes, but a character is enclosed in single quotes.<br /> <br /> ==Characters==<br /> A character of text can be used in either a String or a cell. For example:<br /> &lt;pawn&gt;char text[] = &quot;Crab&quot;;<br /> char clam;<br /> <br /> clam = 'D'; //Set clam to 'D'<br /> text[0] = 'A'; //Change the 'C' to 'A', it is now 'Arab'<br /> clam = text[0]; //Set clam to 'A'<br /> text[1] = clam; //Change the 'r' to 'A', is is now 'AAab'<br /> &lt;/pawn&gt;<br /> <br /> What you can't do is mix character arrays with strings. The internal storage is different. For example:<br /> &lt;pawn&gt;<br /> int clams[] = &quot;Clams&quot;; // Invalid.<br /> int clams[] = {'C', 'l', 'a', 'm', 's', 0}; // Valid, but NOT A STRING.<br /> &lt;/pawn&gt;<br /> <br /> =Functions=<br /> Functions, as stated before, are isolated blocks of code that perform an action. They can be invoked, or '''called''', with '''parameters''' that give specific options.<br /> <br /> There are two types of ways functions are called:<br /> *'''direct call''' - You specifically call a function in your code.<br /> *'''callback''' - The application calls a function in your code, as if it were an event trigger.<br /> <br /> There are six types of functions:<br /> *'''native''': A direct, internal function provided by the application.<br /> *'''public''': A callback function that is visible to the application and other scripts.<br /> *'''normal''': A normal function that only you can call.<br /> *'''static''': The scope of this function is restricted to the current file, can be used in combination with stock.<br /> *'''stock''': A normal function provided by an include file. If unused, it won't be compiled.<br /> *'''forward''': This function is a global event provided by the application. If you implement it, it will be a callback.<br /> <br /> All code in Pawn must exist in functions. This is in contrast to languages like PHP, Perl, and Python which let you write global code. That is because Pawn is a callback-based language: it responds to actions from a parent application, and functions must be written to handle those actions. Although our examples often contain free-floating code, this is purely for demonstration purposes. Free-floating code in our examples implies the code is part of some function.<br /> <br /> ==Declaration==<br /> Unlike variables, functions do not need to be declared before you use them. Functions have two pieces, the '''signature''' and the '''body'''. The signature contains the name of your function and the parameters it will accept. The body is the contents of its code.<br /> <br /> Example of a function:<br /> &lt;pawn&gt;<br /> int AddTwoNumbers(int first, int second)<br /> {<br /> int sum = first + second;<br /> return sum;<br /> }&lt;/pawn&gt;<br /> <br /> This is a simple function. The prototype is this line:<br /> &lt;pawn&gt;int AddTwoNumbers(int first, int second)&lt;/pawn&gt;<br /> <br /> Broken down, it means:<br /> *&lt;tt&gt;int&lt;/tt&gt; - Return value type (integer).<br /> *&lt;tt&gt;AddTwoNumbers&lt;/tt&gt; - Name of the function.<br /> *&lt;tt&gt;int first&lt;/tt&gt; - First parameter, an integer.<br /> *&lt;tt&gt;int second&lt;/tt&gt; - Second parameter, an integer.<br /> <br /> The body is a block of code. It creates a new variable, called &lt;tt&gt;sum&lt;/tt&gt;, and assigns it the value of the two parameters added together (more on expressions later). The important thing to notice is the &lt;tt&gt;return&lt;/tt&gt; statement, which tells the function to end and return a value to the caller of the function. All functions return something on completion, unless they return a special type called &lt;tt&gt;void&lt;/tt&gt;.<br /> <br /> A function can accept any type of input, and it can return any non-array type.<br /> <br /> You can, of course, pass variables to functions:<br /> &lt;pawn&gt;int numbers[3] = {1, 2, 0};<br /> <br /> numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);&lt;/pawn&gt;<br /> <br /> Note that cells are passed '''by value'''. That is, their value cannot be changed by the function. For example:<br /> &lt;pawn&gt;int a = 5;<br /> <br /> ChangeValue(a);<br /> <br /> ChangeValue(b)<br /> {<br /> b = 5;<br /> }&lt;/pawn&gt;<br /> <br /> This code would not change the value of &lt;tt&gt;a&lt;/tt&gt;. That is because a copy of the value in &lt;tt&gt;a&lt;/tt&gt; is passed instead of &lt;tt&gt;a&lt;/tt&gt; itself. <br /> <br /> More examples of functions will be provided throughout the article.<br /> <br /> ==Publics==<br /> Public functions are used to implement callbacks. You should not create a public function unless it is specifically implementing a callback. For example, here are two callbacks from &lt;tt&gt;sourcemod.inc&lt;/tt&gt;:<br /> <br /> &lt;pawn&gt;forward void OnPluginStart();<br /> forward void OnClientDisconnected(int client);&lt;/pawn&gt;<br /> <br /> To implement and receive these two events, you would write functions as such:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> /* Code here */<br /> }<br /> <br /> public void OnClientDisconnected(int client)<br /> {<br /> /* Code here */<br /> }&lt;/pawn&gt;<br /> <br /> The '''public''' keyword signals to the parent application that it should attach the function to the appropriate forwarded event.<br /> <br /> ==Natives==<br /> Natives are builtin functions provided by SourceMod. You can call them as if they were a normal function. For example, SourceMod has the following function:<br /> <br /> &lt;pawn&gt;native float FloatRound(float num);&lt;/pawn&gt;<br /> <br /> It can be called like so:<br /> &lt;pawn&gt;int rounded = FloatRound(5.2); // rounded will be 5&lt;/pawn&gt;<br /> <br /> ==Array Parameters==<br /> You can pass arrays or Strings as parameters. It is important to note that these are passed '''by reference'''. That is, rather than making a copy of the data, the data is referenced directly. There is a simple way of explaining this more concretely.<br /> <br /> &lt;pawn&gt;<br /> int example[] = {1, 2, 3, 4, 5};<br /> <br /> ChangeArray(example, 2, 29);<br /> <br /> void ChangeArray(int[] array, int index, int value)<br /> {<br /> array[index] = value;<br /> }&lt;/pawn&gt;<br /> <br /> The function sets the given index in the array to a given value. When it is run on our example array, it changes index 2 to from the value 3 to 29. I.e.:<br /> &lt;pawn&gt;example[2] = 29;&lt;/pawn&gt;<br /> <br /> Note two important things here. First, arrays are not copied when they are passed to functions - they are passed ''by reference'', so the view of the array is consistent at all times. Second, the brackets changed position in our function signature. This is because our function accepts an array of any size, and since we don't know the size, we must use the dynamic array syntax.<br /> <br /> To prevent an array from being modified in a function, you can mark it as &lt;tt&gt;const&lt;/tt&gt;. This will raise an error on code that attempts to modify it. For example:<br /> <br /> &lt;pawn&gt;void CantChangeArray(const array[], int index, int value)<br /> {<br /> array[index] = value; //Won't compile<br /> }&lt;/pawn&gt;<br /> <br /> It is a good idea to use &lt;tt&gt;const&lt;/tt&gt; in array parameters if you know the array won't be modified; this can prevent coding mistakes.<br /> <br /> =Expressions=<br /> Expressions are exactly the same as they are in mathematics. They are groups of operators/symbols which evaluate to one piece of data. They are often parenthetical (comprised of parenthesis). They contain a strict &quot;order of operations.&quot; They can contain variables, functions, numbers, and expressions themselves can be nested inside other expressions, or even passed as parameters.<br /> <br /> The simplest expression is a single number. For example:<br /> &lt;pawn&gt;<br /> 0; //Returns the number 0<br /> (0); //Returns the number 0 as well<br /> &lt;/pawn&gt;<br /> <br /> Although expressions can return any value, they are also said to either return ''zero or non-zero''. In that sense, ''zero'' is ''false'', and ''non-zero'' is ''true''. For example, -1 is '''true''' in Pawn, since it is non-zero. Do not assume negative numbers are false.<br /> <br /> The order of operations for expressions is similar to C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Here are some example expressions:<br /> &lt;pawn&gt;<br /> 5 + 6; //Evaluates to 11<br /> 5 * 6 + 3; //Evaluates to 33<br /> 5 * (6 + 3); //Evaluates to 45<br /> 5.0 + 2.3; //Evaluates to 7.3<br /> (5 * 6) % 7; //Modulo operator, evaluates to 2<br /> (5 + 3) / 2 * 4 - 9; //Evaluates to -8<br /> &lt;/pawn&gt;<br /> <br /> As noted, expressions can contain variables, or even functions:<br /> &lt;pawn&gt;<br /> int a = 5 * 6;<br /> int b = a * 3; //Evaluates to 90<br /> int c = AddTwoNumbers(a, b) + (a * b);<br /> &lt;/pawn&gt;<br /> <br /> Note: String manipulation routines may be found in the string.inc file located in the include subdirectory. They may be browsed through the [http://docs.sourcemod.net/api/ API Reference] as well.<br /> <br /> ==Operators==<br /> There are a few extra helpful operators in Pawn. The first set simplifies self-aggregation expressions. For example:<br /> &lt;pawn&gt;int a = 5;<br /> <br /> a = a + 5;&lt;/pawn&gt;<br /> <br /> Can be rewritten as:<br /> &lt;pawn&gt;int a = 5;<br /> a += 5;&lt;/pawn&gt;<br /> <br /> This is true of the following operators in Pawn:<br /> *Four-function: *, /, -, +<br /> *Bit-wise: |, &amp;, ^, ~, &lt;&lt;, &gt;&gt;<br /> <br /> Additionally, there are increment/decrement operators:<br /> &lt;pawn&gt;a = a + 1;<br /> a = a - 1;&lt;/pawn&gt;<br /> <br /> Can be simplified as:<br /> &lt;pawn&gt;a++;<br /> a--;&lt;/pawn&gt;<br /> <br /> As an advanced note, the ++ or -- can come before the variable (pre-increment, pre-decrement) or after the variable (post-increment, post-decrement). The difference is in how the rest of the expression containing them sees their result.<br /> <br /> * ''Pre:'' The variable is incremented before evaluation, and the rest of the expression sees the new value.<br /> * ''Post:'' The variable is incremented after evaluation, and the rest of the expression sees the old value.<br /> <br /> In other words, &lt;tt&gt;a++&lt;/tt&gt; evaluates to the value of &lt;tt&gt;a&lt;/tt&gt; while &lt;tt&gt;++a&lt;/tt&gt; evaluates to the value of &lt;tt&gt;a + 1&lt;/tt&gt;. In both cases &lt;tt&gt;a&lt;/tt&gt; is incremented by &lt;tt&gt;1&lt;/tt&gt;.<br /> <br /> For example:<br /> <br /> &lt;pawn&gt;int a = 5;<br /> int b = a++; // b = 5, a = 6 (1)<br /> int c = ++a; // a = 7, c = 7 (2)<br /> &lt;/pawn&gt;<br /> <br /> In (1) &lt;tt&gt;b&lt;/tt&gt; is assigned &lt;tt&gt;a&lt;/tt&gt;'s ''old'' value ''before'' it is incremented to &lt;tt&gt;6&lt;/tt&gt;, but in (2) &lt;tt&gt;c&lt;/tt&gt; is assigned &lt;tt&gt;a&lt;/tt&gt;'s ''int'' value ''after'' it is incremented to &lt;tt&gt;7&lt;/tt&gt;.<br /> <br /> ==Comparison Operators==<br /> There are six operators for comparing two values numerically, and the result is either true (non-zero) or false (zero):<br /> *&lt;tt&gt;a == b&lt;/tt&gt; - True if a and b have the same value.<br /> *&lt;tt&gt;a != b&lt;/tt&gt; - True if a and b have different values.<br /> *&lt;tt&gt;a &amp;gt; b&lt;/tt&gt; - True if a is greater than b<br /> *&lt;tt&gt;a &amp;gt;= b&lt;/tt&gt; - True if a is greater than or equal to b<br /> *&lt;tt&gt;a &amp;lt; b&lt;/tt&gt; - True if a is less than b<br /> *&lt;tt&gt;a &amp;lt;= b&lt;/tt&gt; - True if a is less than or equal to b<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> (1 != 3); //Evaluates to true because 1 is not equal to 3.<br /> (3 + 3 == 6); //Evaluates to true because 3+3 is 6.<br /> (5 - 2 &gt;= 4); //Evaluates to false because 3 is less than 4.<br /> &lt;/pawn&gt;<br /> <br /> Note that these operators do not work on arrays or strings. That is, you cannot compare either using &lt;tt&gt;==&lt;/tt&gt;.<br /> <br /> ==Truth Operators==<br /> These truth values can be combined using three boolean operators:<br /> *&lt;tt&gt;a &amp;&amp; b&lt;/tt&gt; - True if both a and b are true. False if a or b (or both) is false.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;&amp;&amp;&lt;/tt&gt; !! 0 !! 1<br /> |-<br /> ! 0<br /> | 0 || 0<br /> |-<br /> ! 1<br /> | 0 || 1<br /> |}<br /> *&lt;tt&gt;a || b&lt;/tt&gt; - True if a or b (or both) is true. False if both a and b are false.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;&lt;nowiki&gt;||&lt;/nowiki&gt;&lt;/tt&gt; !! 0 !! 1<br /> |-<br /> ! 0<br /> | 0 || 1<br /> |-<br /> ! 1<br /> | 1 || 1<br /> |}<br /> *&lt;tt&gt;!a&lt;/tt&gt; - True if a is false. False if a is true.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;!&lt;/tt&gt; !! 0 !! 1<br /> |- <br /> !<br /> | 1 || 0<br /> |}<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> (1 || 0); //Evaluates to true because the expression 1 is true<br /> (1 &amp;&amp; 0); //Evaluates to false because the expression 0 is false<br /> (!1 || 0); //Evaluates to false because !1 is false.<br /> &lt;/pawn&gt;<br /> <br /> ==Left/Right Values==<br /> Two important concepts are left-hand and right-hand values, or l-values and r-values. An l-value is what appears on the left-hand side of a variable assignment, and an r-value is what appears on the right side of a variable assignment.<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> int a = 5;&lt;/pawn&gt;<br /> <br /> In this example &lt;tt&gt;a&lt;/tt&gt; is an l-value and &lt;tt&gt;5&lt;/tt&gt; is an r-value.<br /> <br /> The rules:<br /> *'''Expressions are never l-values'''.<br /> *'''Variables are both l-values and r-values'''.<br /> <br /> =Conditionals=<br /> Conditional statements let you only run code if a certain condition is matched.<br /> <br /> ==If Statements==<br /> If statements test one or more conditions. For example:<br /> <br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code that will run if the expression was true */<br /> }&lt;/pawn&gt;<br /> <br /> They can be extended to handle more cases as well:<br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code */<br /> }<br /> else if (a == 6)<br /> {<br /> /* Code */<br /> }<br /> else if (a == 7)<br /> {<br /> /* Code */<br /> }&lt;/pawn&gt;<br /> <br /> You can also handle the case of no expression being matched. For example:<br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code */<br /> }<br /> else<br /> {<br /> /* Code that will run if no expressions were true */<br /> }&lt;/pawn&gt;<br /> <br /> ==Switch Statements==<br /> Switch statements are restricted if statements. They test one expression for a series of possible values. For example:<br /> <br /> &lt;pawn&gt;<br /> switch (a)<br /> {<br /> case 5:<br /> {<br /> /* code */<br /> }<br /> case 6:<br /> {<br /> /* code */<br /> }<br /> case 7:<br /> {<br /> /* code */<br /> }<br /> case 8, 9, 10:<br /> {<br /> /* Code */<br /> }<br /> default:<br /> {<br /> /* will run if no case matched */<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> Unlike some other languages, switches are not fall-through. That is, multiple cases will never be run. When a case matches its code is executed, and the switch is then immediately terminated.<br /> <br /> =Loops=<br /> Loops allow you to conveniently repeat a block of code while a given condition remains true. <br /> <br /> ==For Loops==<br /> For loops are loops which have four parts:<br /> *The '''initialization''' statement - run once before the first loop.<br /> *The '''condition''' statement - checks whether the next loop should run, including the first one. The loop terminates when this expression evaluates to false.<br /> *The '''iteration''' statement - run after each loop.<br /> *The '''body''' block - run each time the '''condition''' statement evaluates to true.<br /> <br /> &lt;pawn&gt;<br /> for ( /* initialization */ ; /* condition */ ; /* iteration */ )<br /> {<br /> /* body */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> A simple example is a function to sum an array:<br /> &lt;pawn&gt;<br /> int array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};<br /> int sum = SumArray(array, 10);<br /> <br /> int SumArray(const int array[], int count)<br /> {<br /> int total;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> total += array[i];<br /> }<br /> <br /> return total;<br /> }&lt;/pawn&gt;<br /> <br /> Broken down:<br /> *&lt;tt&gt;int i = 0&lt;/tt&gt; - Creates a new variable for the loop, sets it to 0.<br /> *&lt;tt&gt;i &lt; count&lt;/tt&gt; - Only runs the loop if &lt;tt&gt;i&lt;/tt&gt; is less than &lt;tt&gt;count&lt;/tt&gt;. This ensures that the loop stops reading at a certain point. In this case, we don't want to read invalid indexes in the array.<br /> *&lt;tt&gt;i++&lt;/tt&gt; - Increments &lt;tt&gt;i&lt;/tt&gt; by one after each loop. This ensures that the loop doesn't run forever; eventually &lt;tt&gt;i&lt;/tt&gt; will become too big and the loop will end.<br /> <br /> Thus, the &lt;tt&gt;SumArray&lt;/tt&gt; function will loop through each valid index of the array, each time adding that value of the array into a sum. For loops are very common for processing arrays like this.<br /> <br /> ==While Loops==<br /> While loops are less common than for loops but are actually the simplest possible loop. They have only two parts:<br /> *The '''condition''' statement - checked before each loop. The loop terminates when it evaluates to false.<br /> *The '''body''' block - run each time through the loop.<br /> <br /> &lt;pawn&gt;<br /> while ( /* condition */ )<br /> {<br /> /* body */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> As long as the condition expression remains true, the loop will continue. Every for loop can be rewritten as a while loop:<br /> <br /> &lt;pawn&gt;<br /> /* initialization */<br /> while ( /* condition */ )<br /> {<br /> /* body */<br /> /* iteration */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> Here is the previous for loop rewritten as a while loop:<br /> &lt;pawn&gt;<br /> int SumArray(const int array[], int count)<br /> {<br /> int total, i;<br /> <br /> while (i &lt; count)<br /> {<br /> total += array[i];<br /> i++;<br /> }<br /> <br /> return total;<br /> }&lt;/pawn&gt;<br /> <br /> There are also '''do...while''' loops which are even less common. These are the same as while loops except the condition check is AFTER each loop, rather than before. This means the loop is always run at least once. For example:<br /> <br /> &lt;pawn&gt;<br /> do<br /> {<br /> /* body */<br /> }<br /> while ( /* condition */ );<br /> &lt;/pawn&gt;<br /> <br /> ==Loop Control==<br /> There are two cases in which you want to selectively control a loop:<br /> *'''skipping''' one iteration of the loop but continuing as normal, or;<br /> *'''breaking''' the loop entirely before it's finished.<br /> <br /> Let's say you have a function which takes in an array and searches for a matching number. You want it to stop once the number is found:<br /> &lt;pawn&gt;<br /> /**<br /> * Returns the array index where the value is, or -1 if not found.<br /> */<br /> int SearchInArray(const int array[], int count, int value)<br /> {<br /> int index = -1;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> if (array[i] == value)<br /> {<br /> index = i;<br /> break;<br /> }<br /> }<br /> <br /> return index;<br /> }&lt;/pawn&gt;<br /> <br /> Certainly, this function could simply &lt;tt&gt;return i&lt;/tt&gt; instead, but the example shows how &lt;tt&gt;break&lt;/tt&gt; will terminate the loop.<br /> <br /> Similarly, the &lt;tt&gt;continue&lt;/tt&gt; keyword skips an iteration of a loop. For example, let's say we wanted to sum all even numbers:<br /> &lt;pawn&gt;<br /> int SumEvenNumbers(const int array[], int count)<br /> {<br /> int sum;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> /* If divisibility by 2 is 1, we know it's odd */<br /> if (array[i] % 2 == 1)<br /> {<br /> /* Skip the rest of this loop iteration */<br /> continue;<br /> }<br /> sum += array[i];<br /> }<br /> <br /> return sum;<br /> }&lt;/pawn&gt;<br /> <br /> =Scope=<br /> Scope refers to the '''visibility''' of code. That is, code at one level may not be &quot;visible&quot; to code at another level. For example:<br /> <br /> &lt;pawn&gt;<br /> int A, B, C;<br /> <br /> void Function1()<br /> {<br /> int B;<br /> <br /> Function2();<br /> }<br /> <br /> void Function2()<br /> {<br /> int C;<br /> }&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;A&lt;/tt&gt;, &lt;tt&gt;B&lt;/tt&gt;, and &lt;tt&gt;C&lt;/tt&gt; exist at '''global scope'''. They can be seen by any function. However, the &lt;tt&gt;B&lt;/tt&gt; in &lt;tt&gt;Function1&lt;/tt&gt; is not the same variable as the &lt;tt&gt;B&lt;/tt&gt; at the global level. Instead, it is at '''local scope''', and is thus a '''local variable'''.<br /> <br /> Similarly, &lt;tt&gt;Function1&lt;/tt&gt; and &lt;tt&gt;Function2&lt;/tt&gt; know nothing about each other's variables.<br /> <br /> Not only is the variable private to &lt;tt&gt;Function1&lt;/tt&gt;, but it is re-created each time the function is invoked. Imagine this:<br /> &lt;pawn&gt;<br /> void Function1()<br /> {<br /> int B;<br /> <br /> Function1();<br /> }&lt;/pawn&gt;<br /> <br /> In the above example, &lt;tt&gt;Function1&lt;/tt&gt; calls itself. Of course, this is infinite recursion (a bad thing), but the idea is that each time the function runs, there is a new copy of &lt;tt&gt;B&lt;/tt&gt;. When the function ends, &lt;tt&gt;B&lt;/tt&gt; is destroyed, and the value is lost.<br /> <br /> This property can be simplified by saying that a variable's scope is equal to the nesting level it is in. That is, a variable at global scope is visible globally to all functions. A variable at local scope is visible to all code blocks &quot;beneath&quot; its nesting level. For example:<br /> <br /> &lt;pawn&gt;void Function1()<br /> {<br /> int A;<br /> <br /> if (A)<br /> {<br /> A = 5;<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> The above code is valid since A's scope extends throughout the function. The following code, however, is not valid:<br /> &lt;pawn&gt;<br /> void Function1()<br /> {<br /> int A;<br /> <br /> if (A)<br /> {<br /> int B = 5;<br /> }<br /> <br /> B = 5;<br /> }&lt;/pawn&gt;<br /> <br /> Notice that &lt;tt&gt;B&lt;/tt&gt; is declared in a new code block. That means &lt;tt&gt;B&lt;/tt&gt; is only accessible to that code block (and all sub-blocks nested within). As soon as the code block terminates, &lt;tt&gt;B&lt;/tt&gt; is no longer valid.<br /> <br /> =Dynamic Arrays=<br /> Dynamic arrays are arrays which don't have a hardcoded size. For example:<br /> <br /> &lt;pawn&gt;void Function1(int size)<br /> {<br /> int array[size];<br /> <br /> /* Code */<br /> }&lt;/pawn&gt;<br /> <br /> Dynamic arrays can have any expression as their size as long as the expression evaluates to a number larger than 0. Like normal arrays, SourcePawn does not know the array size after it is created; you have to save it if you want it later.<br /> <br /> Dynamic arrays are only valid at the local scope level, since code cannot exist globally.<br /> <br /> =Extended Variable Declarations=<br /> Variables can be declared in more ways than simply &lt;tt&gt;new&lt;/tt&gt;.<br /> <br /> ==decl==<br /> ===Purpose===<br /> By default, all variables in Pawn are initialized to zero. If there is an explicit initializer, the variable is initialized to the expression after the &lt;tt&gt;=&lt;/tt&gt; token. At a local scope, this can be a run-time expense. The &lt;tt&gt;decl&lt;/tt&gt; keyword (which is only valid at local scope) was introduced to let users decide if they want variables initialized or not.<br /> <br /> Note: &lt;tt&gt;decl&lt;/tt&gt; should not be used on single cell variables. There is almost never any benefit.<br /> <br /> ===Explanation===<br /> For example:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> int d;<br /> char blah[512];<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> In this code, &lt;tt&gt;c&lt;/tt&gt; is equal to 5 and &lt;tt&gt;d&lt;/tt&gt; is equal to 0. The run-time expense of this initialization is negligible. However, &lt;tt&gt;blah&lt;/tt&gt; is a large array, and the expense of initializing the entire array to 0s could be detrimental in certain situations. <br /> <br /> Note that &lt;tt&gt;blah&lt;/tt&gt; does not need to be zeroed. In between being declared with &lt;tt&gt;new&lt;/tt&gt; and stored with &lt;tt&gt;Format()&lt;/tt&gt;, &lt;tt&gt;blah&lt;/tt&gt; is never loaded or read. Thus this code would be more efficiently written as:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> int d;<br /> decl String:blah[512];<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> ===Caveats===<br /> The downside to &lt;tt&gt;decl&lt;/tt&gt; is that it means its variables will start with &quot;garbage&quot; contents. For example, if we were to use:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> int d;<br /> decl String:blah[512];<br /> <br /> PrintToServer(&quot;%s&quot;, blah);<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> This code may crash the server, because &lt;tt&gt;blah&lt;/tt&gt; may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> decl d;<br /> decl String:blah[512];<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> The value of &lt;tt&gt;d&lt;/tt&gt; is now undefined. It could be any value, negative or positive. <br /> <br /> Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:<br /> &lt;pawn&gt;<br /> decl String:blah[512];<br /> <br /> blah[0] = '\0';<br /> &lt;/pawn&gt;<br /> <br /> ===Golden Rules===<br /> *'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''<br /> *'''Do not prematurely optimize.''' Likewise, there is no need to use &lt;tt&gt;decl&lt;/tt&gt; on non-arrays, because there is no added expense for initializing a single cell value.<br /> <br /> ===Notes===<br /> This example is NOT as efficient as a &lt;tt&gt;decl&lt;/tt&gt;:<br /> &lt;pawn&gt;<br /> char blah[512] = &quot;a&quot;;<br /> &lt;/pawn&gt;<br /> <br /> Even though the string is only one character, the &lt;tt&gt;new&lt;/tt&gt; operator guarantees the rest of the array will be zeroed as well.<br /> <br /> Also note, it is valid to explicitly initialize a &lt;tt&gt;decl&lt;/tt&gt; '''ONLY''' with strings:<br /> &lt;pawn&gt;decl String:blah[512] = &quot;a&quot;;&lt;/pawn&gt;<br /> <br /> However, any other tag will fail to compile, because the purpose of &lt;tt&gt;decl&lt;/tt&gt; is to avoid any initialization:<br /> &lt;pawn&gt;decl Float:blah[512] = {1.0};&lt;/pawn&gt;<br /> <br /> ==static==<br /> The &lt;tt&gt;static&lt;/tt&gt; keyword is available at global and local scope. It has different meanings in each.<br /> <br /> ===Global static===<br /> A global static variable can only be accessed from within the same file. For example:<br /> <br /> &lt;pawn&gt;//file1.inc<br /> static float g_value1 = 0.15f;<br /> <br /> //file2.inc<br /> static float g_value2 = 0.15f;&lt;/pawn&gt;<br /> <br /> If a plugin includes both of these files, it will not be able to use either &lt;tt&gt;g_value1&lt;/tt&gt; or &lt;tt&gt;g_value2&lt;/tt&gt;. This is a simple information hiding mechanism, and is similar to declaring member variables as &lt;tt&gt;private&lt;/tt&gt; in languages like C++, Java, or C#.<br /> <br /> ===Local static===<br /> A local static variable is a global variable that is only visible from its local lexical scope. For example:<br /> <br /> &lt;pawn&gt;<br /> int MyFunction(inc)<br /> {<br /> static counter = -1;<br /> <br /> counter += inc;<br /> <br /> return counter;<br /> }&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;counter&lt;/tt&gt; is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time &lt;tt&gt;MyFunction&lt;/tt&gt; runs, the &lt;tt&gt;counter&lt;/tt&gt; variable and its storage in memory is the same.<br /> <br /> Take this example:<br /> &lt;pawn&gt;MyFunction(5);<br /> MyFunction(6);<br /> MyFunction(10);&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;counter&lt;/tt&gt; will be &lt;tt&gt;-1 + 5 + 6 + 10&lt;/tt&gt;, or &lt;tt&gt;20&lt;/tt&gt;, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then &lt;tt&gt;static&lt;/tt&gt; is usually not a good idea unless your code is re-entrant. <br /> <br /> The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.<br /> <br /> Note that statics can exist in any local scope:<br /> <br /> &lt;pawn&gt;<br /> int MyFunction(inc)<br /> {<br /> if (inc &gt; 0)<br /> {<br /> static counter;<br /> return (counter += inc);<br /> }<br /> return -1;<br /> }&lt;/pawn&gt;<br /> <br /> [[Category:SourceMod Scripting]]<br /> <br /> {{LanguageSwitch}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Introduction_to_SourcePawn_1.7&diff=10057 2015-11-15T18:37:02Z

<p>Xerox8521: /* Dynamic Arrays */</p> <hr /> <div>This guide is designed to give you a very basic overview to fundamentals of scripting in SourcePawn. [[Pawn]] is a &quot;scripting&quot; language used to embed functionality in other programs. That means it is not a standalone language, like C++ or Java, and its details will differ based on the application. SourcePawn is the version of Pawn used in [[SourceMod]].<br /> <br /> This guide does not tell you how to write SourceMod plugins; it is intended as an overview of the syntax and semantics of the language instead. Read the separate article, [[Introduction to SourceMod Plugins]] for SourceMod API specifics. <br /> <br /> =Non-Programmer Intro=<br /> This section is intended for non-programmers. If you're still confused, you may want to pick up a book on another language, such as PHP, Python, or Java, to get a better idea of what programming is like.<br /> <br /> ==Symbols/Keywords==<br /> A symbol is a series of letters, numbers, and/or underscores, that uniquely represents something. Symbols are case-sensitive, and usually start with a letter.<br /> <br /> There are a few reserved symbols that have special meaning. For example, &lt;tt&gt;if&lt;/tt&gt;, &lt;tt&gt;for&lt;/tt&gt;, and &lt;tt&gt;return&lt;/tt&gt; are special constructs in the language that will explained later. They cannot be used as symbol names.<br /> <br /> ==Variables==<br /> There a few important constructs you should know before you begin to script. The first is a '''variable'''. A variable is a symbol, or name, that holds data. For example, the variable &quot;a&quot; could hold the number &quot;2&quot;, &quot;16&quot;, &quot;0&quot;, et cetera. Since a variable holds data, it also allocates the memory needed to store that data.<br /> <br /> In addition to a name, variables have a '''type'''. A type tells the program how to interpret the data, and how much memory the data will use. Pawn has three types of data that are most commonly used:<br /> * Integers, using the &lt;tt&gt;int&lt;/tt&gt; type. Integer types may store a whole number from -2147483648 to 2147483647.<br /> * Floats, using the &lt;tt&gt;float&lt;/tt&gt; type. Float types may store fractional numbers in a huge range, though they are not as precise as integers.<br /> * Characters, using the &lt;tt&gt;char&lt;/tt&gt; type. Character types store one byte of character information, typically an [http://www.asciitable.com/ ASCII] character.<br /> * Booleans, using the &lt;tt&gt;bool&lt;/tt&gt; type. Booleans store either true or false.<br /> <br /> Example of creating variables and assigning values:<br /> <br /> &lt;pawn&gt;int money = 5400;<br /> float percent = 67.3;<br /> bool enabled = false;<br /> &lt;/pawn&gt;<br /> <br /> ==Functions==<br /> The next important concept is '''functions'''. Functions are symbols or names that perform an action. When you invoke, or call them, they carry out a specific sequence of code and then return a result. There are a few types of functions, but every function is activated the same way. Example:<br /> <br /> &lt;pawn&gt;<br /> show(56); // Calls the &quot;show&quot; function, and gives it the number 56.<br /> enable(); // Calls the &quot;s &quot;enable&quot; function with no values.<br /> bool visible = show(a); //Calls the &quot;show&quot; function, stores its result in a variable.<br /> &lt;/pawn&gt;<br /> <br /> Every piece of data passed to a function is called a '''parameter'''. A function can have any number of parameters (there is a &quot;reasonable&quot; limit of 32 in SourceMod). Parameters will be explained further in the article.<br /> <br /> ==Comments==<br /> Note any text that appears after a &quot;//&quot; is considered a &quot;comment&quot; and is not actual code. There are two comment styles:<br /> *&lt;tt&gt;//&lt;/tt&gt; - Double slash, everything following on that line is ignored.<br /> *&lt;tt&gt;/* */&lt;/tt&gt; - Multi-line comment, everything in between the asterisks is ignored. You cannot nest these.<br /> <br /> <br /> ==Block Coding==<br /> The next concept is block coding. You can group code into &quot;blocks&quot; separated by { and }. This effectively makes one large block of code act as one statement. For example:<br /> <br /> &lt;pawn&gt;{<br /> here;<br /> is;<br /> some;<br /> code;<br /> }&lt;/pawn&gt;<br /> <br /> Block coding using braces is used everywhere in programming. Blocks of code can be nested within each other. It is a good idea to adapt a consistent and readable indentation style early on to prevent spaghetti-looking code.<br /> <br /> =Language Paradigms=<br /> Pawn may seem similar to other languages, like C, but it has fundamental differences. It is not important that you immediately understand these differences, but they may be helpful if you're familiar with another language already.<br /> *'''Pawn is sort of typed.''' Before SourceMod 1.7, Pawn did not have types. Older code and older natives will reflect this by using tags and the &lt;tt&gt;new&lt;/tt&gt; keyword. As of SourceMod 1.7, we recommend that all code use types. For more information see [[SourcePawn Transitional Syntax]].<br /> *'''Pawn is not garbage collected.''' Pawn, as a language, has no built-in memory allocation, and thus has no garbage. If a function allocates memory, you may be responsible for freeing it.<br /> *'''Pawn is not object oriented.''' Pawn does not have structs or objects. As of SourceMod 1.7, it has limited sugaring for treating some data types as objects, but users cannot create their own objects or classes.<br /> *'''Pawn is single-threaded.''' As of this writing, Pawn is not thread safe. <br /> *'''Pawn is compiled.''' Pawn is compiled to an intermediate, machine-independent code, which is stored in a &quot;.smx&quot; file. When loading .smx files, SourceMod translates this code to machine code for the platform and CPU it's running on.<br /> <br /> Early language design decisions were made by ITB CompuPhase. It is designed for low-level embedded devices and is thus very small and very fast.<br /> <br /> =Variables=<br /> Pawn currently supports the following basic variable types:<br /> *&lt;tt&gt;bool&lt;/tt&gt; - true or false.<br /> *&lt;tt&gt;char&lt;/tt&gt; - an 8-bit ASCII character.<br /> *&lt;tt&gt;int&lt;/tt&gt; - a 32-bit signed integer.<br /> *&lt;tt&gt;float&lt;/tt&gt; - a 32-bit IEEE-754 floating point number.<br /> *&lt;tt&gt;Handle&lt;/tt&gt; - the base type of a SourceMod object<br /> <br /> Other types may exist when defined in include files - for example, enums create new types for named integers, and many types derive from &lt;tt&gt;Handle&lt;/tt&gt;.<br /> <br /> Strings, currently, are 0-terminated arrays of &lt;tt&gt;char&lt;/tt&gt;s. They're described a little further ahead.<br /> <br /> ==Declaration==<br /> Below we include some examples of variable declarations, both valid and invalid. Keep in mind that SourcePawn has recently added new syntax, and that's what's documented below. Older code may use older declaration syntax, which is no longer supported.<br /> <br /> &lt;pawn&gt;<br /> int a = 5;<br /> float b = 5.0;<br /> bool c = true;<br /> bool d = false;<br /> &lt;/pawn&gt;<br /> <br /> Invalid variable usage:<br /> &lt;pawn&gt;<br /> int a = 5.0; // Type mismatch. 5.0 is a float.<br /> float b = 5; // Type mismatch. 5 is an integer.<br /> &lt;/pawn&gt;<br /> <br /> If a variable is not assigned upon declaration, it will be set to 0. For example:<br /> &lt;pawn&gt;<br /> int a; // Set to 0<br /> float b; // Set to 0.0<br /> bool c; // Set to false<br /> &lt;/pawn&gt;<br /> <br /> ==Assignment==<br /> Variables can be re-assigned data after they are created. For example:<br /> &lt;pawn&gt;int a;<br /> float b;<br /> bool c;<br /> <br /> a = 5;<br /> b = 5.0;<br /> c = true;<br /> &lt;/pawn&gt;<br /> <br /> =Arrays=<br /> An array is a sequence of data in a list. Arrays are useful for storing multiple pieces of data in one variable, or mapping one type of data to another.<br /> <br /> ==Declaration==<br /> An array is declared using brackets. Some examples of arrays:<br /> &lt;pawn&gt;<br /> int players[32]; // Stores 32 integers.<br /> float origin[3]; // Stores 3 floating point numbers<br /> &lt;/pawn&gt;<br /> <br /> By default, arrays are initialized to 0. You can assign them different default values, however:<br /> &lt;pawn&gt;<br /> int numbers[5] = {1, 2, 3, 4, 5}; // Stores 1, 2, 3, 4, 5.<br /> float origin[3] = {1.0, 2.0, 3.0}; // Stores 1.0, 2.0, 3.0.<br /> &lt;/pawn&gt;<br /> <br /> You can leave out the array size if you're going to pre-assign data to it. For example:<br /> &lt;pawn&gt;<br /> int numbers[] = {1, 3, 5, 7, 9};<br /> &lt;/pawn&gt;<br /> <br /> The compiler will automatically deduce that you intended an array of size 5.<br /> <br /> When array is declared with brackets after its name, Pawn considers that array to have a '''fixed size'''. The size of a fixed-size array is always known. Some arrays can be '''dynamically sized''', by putting the brackets before the name. For example,<br /> <br /> &lt;pawn&gt;<br /> int[] numbers = new int[MaxClients]<br /> &lt;/pawn&gt;<br /> <br /> This creates an array of size &lt;tt&gt;MaxClients&lt;/tt&gt;, which could be anything, so the size of the array is not known until the array is allocated.<br /> <br /> ==Usage==<br /> Using an array is just like using a normal variable. The only difference is the array must be '''indexed'''. Indexing an array means choosing the element which you wish to use.<br /> <br /> For example, here is an example of the above code using indexes:<br /> &lt;pawn&gt;<br /> int numbers[5];<br /> float origin[3];<br /> <br /> numbers[0] = 1;<br /> numbers[1] = 2;<br /> numbers[2] = 3;<br /> numbers[3] = 4;<br /> numbers[4] = 5;<br /> origin[0] = 1.0;<br /> origin[1] = 2.0;<br /> origin[2] = 3.0;<br /> &lt;/pawn&gt;<br /> <br /> Note that the '''index''' is what's in between the brackets. The index always starts from 0. That is, if an array has N elements, its valid indexes are from 0 to N-1. Accessing the data at these indexes works like a normal variable.<br /> <br /> Using an incorrect index will cause an error. For example:<br /> &lt;pawn&gt;<br /> int numbers[5];<br /> <br /> numbers[5] = 20;&lt;/pawn&gt;<br /> <br /> This may look correct, but 5 is not a valid index. The highest valid index is 4.<br /> <br /> You can use any expression as an index. For example:<br /> &lt;pawn&gt;int a, numbers[5];<br /> <br /> a = 1; // Set a = 1<br /> numbers[a] = 4; // Set numbers[1] = 4<br /> numbers[numbers[a]] = 2; // Set numbers[4] = 2<br /> &lt;/pawn&gt;<br /> <br /> Expressions will be discussed in depth later in the article.<br /> <br /> =Strings=<br /> Strings are a construct for storing text (or even raw binary data). A string is just an array of characters, except that the final character must be 0 (called the null terminator). Without a null terminator, Pawn would not know where to stop reading the string. All strings are [http://en.wikipedia.org/wiki/UTF-8 UTF-8] in SourcePawn.<br /> <br /> In general, you must have an idea of how large a string will be before you store it. SourcePawn does not yet have the capability of pre-determining storage space for strings.<br /> <br /> ==Usage==<br /> Strings are usually declared as arrays. For example:<br /> &lt;pawn&gt;<br /> char message[] = &quot;Hello!&quot;;<br /> char clams[6] = &quot;Clams&quot;;<br /> &lt;/pawn&gt;<br /> <br /> These are equivalent to doing:<br /> &lt;pawn&gt;<br /> char message[7];<br /> char clams[6];<br /> <br /> message[0] = 'H';<br /> message[1] = 'e';<br /> message[2] = 'l';<br /> message[3] = 'l';<br /> message[4] = 'o';<br /> message[5] = '!';<br /> message[6] = 0;<br /> clams[0] = 'C';<br /> clams[1] = 'l';<br /> clams[2] = 'a';<br /> clams[3] = 'm';<br /> clams[4] = 's';<br /> clams[5] = 0;<br /> &lt;/pawn&gt;<br /> <br /> Although strings are rarely initialized in this manner, it is very important to remember the concept of the null terminator, which signals the end of a string. The compiler, and most SourceMod functions will automatically null-terminate for you, so it is mainly important when manipulating strings directly.<br /> <br /> Note that a string is enclosed in double-quotes, but a character is enclosed in single quotes.<br /> <br /> ==Characters==<br /> A character of text can be used in either a String or a cell. For example:<br /> &lt;pawn&gt;char text[] = &quot;Crab&quot;;<br /> char clam;<br /> <br /> clam = 'D'; //Set clam to 'D'<br /> text[0] = 'A'; //Change the 'C' to 'A', it is now 'Arab'<br /> clam = text[0]; //Set clam to 'A'<br /> text[1] = clam; //Change the 'r' to 'A', is is now 'AAab'<br /> &lt;/pawn&gt;<br /> <br /> What you can't do is mix character arrays with strings. The internal storage is different. For example:<br /> &lt;pawn&gt;<br /> int clams[] = &quot;Clams&quot;; // Invalid.<br /> int clams[] = {'C', 'l', 'a', 'm', 's', 0}; // Valid, but NOT A STRING.<br /> &lt;/pawn&gt;<br /> <br /> =Functions=<br /> Functions, as stated before, are isolated blocks of code that perform an action. They can be invoked, or '''called''', with '''parameters''' that give specific options.<br /> <br /> There are two types of ways functions are called:<br /> *'''direct call''' - You specifically call a function in your code.<br /> *'''callback''' - The application calls a function in your code, as if it were an event trigger.<br /> <br /> There are six types of functions:<br /> *'''native''': A direct, internal function provided by the application.<br /> *'''public''': A callback function that is visible to the application and other scripts.<br /> *'''normal''': A normal function that only you can call.<br /> *'''static''': The scope of this function is restricted to the current file, can be used in combination with stock.<br /> *'''stock''': A normal function provided by an include file. If unused, it won't be compiled.<br /> *'''forward''': This function is a global event provided by the application. If you implement it, it will be a callback.<br /> <br /> All code in Pawn must exist in functions. This is in contrast to languages like PHP, Perl, and Python which let you write global code. That is because Pawn is a callback-based language: it responds to actions from a parent application, and functions must be written to handle those actions. Although our examples often contain free-floating code, this is purely for demonstration purposes. Free-floating code in our examples implies the code is part of some function.<br /> <br /> ==Declaration==<br /> Unlike variables, functions do not need to be declared before you use them. Functions have two pieces, the '''signature''' and the '''body'''. The signature contains the name of your function and the parameters it will accept. The body is the contents of its code.<br /> <br /> Example of a function:<br /> &lt;pawn&gt;<br /> int AddTwoNumbers(int first, int second)<br /> {<br /> int sum = first + second;<br /> return sum;<br /> }&lt;/pawn&gt;<br /> <br /> This is a simple function. The prototype is this line:<br /> &lt;pawn&gt;int AddTwoNumbers(int first, int second)&lt;/pawn&gt;<br /> <br /> Broken down, it means:<br /> *&lt;tt&gt;int&lt;/tt&gt; - Return value type (integer).<br /> *&lt;tt&gt;AddTwoNumbers&lt;/tt&gt; - Name of the function.<br /> *&lt;tt&gt;int first&lt;/tt&gt; - First parameter, an integer.<br /> *&lt;tt&gt;int second&lt;/tt&gt; - Second parameter, an integer.<br /> <br /> The body is a block of code. It creates a new variable, called &lt;tt&gt;sum&lt;/tt&gt;, and assigns it the value of the two parameters added together (more on expressions later). The important thing to notice is the &lt;tt&gt;return&lt;/tt&gt; statement, which tells the function to end and return a value to the caller of the function. All functions return something on completion, unless they return a special type called &lt;tt&gt;void&lt;/tt&gt;.<br /> <br /> A function can accept any type of input, and it can return any non-array type.<br /> <br /> You can, of course, pass variables to functions:<br /> &lt;pawn&gt;int numbers[3] = {1, 2, 0};<br /> <br /> numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);&lt;/pawn&gt;<br /> <br /> Note that cells are passed '''by value'''. That is, their value cannot be changed by the function. For example:<br /> &lt;pawn&gt;int a = 5;<br /> <br /> ChangeValue(a);<br /> <br /> ChangeValue(b)<br /> {<br /> b = 5;<br /> }&lt;/pawn&gt;<br /> <br /> This code would not change the value of &lt;tt&gt;a&lt;/tt&gt;. That is because a copy of the value in &lt;tt&gt;a&lt;/tt&gt; is passed instead of &lt;tt&gt;a&lt;/tt&gt; itself. <br /> <br /> More examples of functions will be provided throughout the article.<br /> <br /> ==Publics==<br /> Public functions are used to implement callbacks. You should not create a public function unless it is specifically implementing a callback. For example, here are two callbacks from &lt;tt&gt;sourcemod.inc&lt;/tt&gt;:<br /> <br /> &lt;pawn&gt;forward void OnPluginStart();<br /> forward void OnClientDisconnected(int client);&lt;/pawn&gt;<br /> <br /> To implement and receive these two events, you would write functions as such:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> /* Code here */<br /> }<br /> <br /> public void OnClientDisconnected(int client)<br /> {<br /> /* Code here */<br /> }&lt;/pawn&gt;<br /> <br /> The '''public''' keyword signals to the parent application that it should attach the function to the appropriate forwarded event.<br /> <br /> ==Natives==<br /> Natives are builtin functions provided by SourceMod. You can call them as if they were a normal function. For example, SourceMod has the following function:<br /> <br /> &lt;pawn&gt;native float FloatRound(float num);&lt;/pawn&gt;<br /> <br /> It can be called like so:<br /> &lt;pawn&gt;int rounded = FloatRound(5.2); // rounded will be 5&lt;/pawn&gt;<br /> <br /> ==Array Parameters==<br /> You can pass arrays or Strings as parameters. It is important to note that these are passed '''by reference'''. That is, rather than making a copy of the data, the data is referenced directly. There is a simple way of explaining this more concretely.<br /> <br /> &lt;pawn&gt;<br /> int example[] = {1, 2, 3, 4, 5};<br /> <br /> ChangeArray(example, 2, 29);<br /> <br /> void ChangeArray(int[] array, int index, int value)<br /> {<br /> array[index] = value;<br /> }&lt;/pawn&gt;<br /> <br /> The function sets the given index in the array to a given value. When it is run on our example array, it changes index 2 to from the value 3 to 29. I.e.:<br /> &lt;pawn&gt;example[2] = 29;&lt;/pawn&gt;<br /> <br /> Note two important things here. First, arrays are not copied when they are passed to functions - they are passed ''by reference'', so the view of the array is consistent at all times. Second, the brackets changed position in our function signature. This is because our function accepts an array of any size, and since we don't know the size, we must use the dynamic array syntax.<br /> <br /> To prevent an array from being modified in a function, you can mark it as &lt;tt&gt;const&lt;/tt&gt;. This will raise an error on code that attempts to modify it. For example:<br /> <br /> &lt;pawn&gt;void CantChangeArray(const array[], int index, int value)<br /> {<br /> array[index] = value; //Won't compile<br /> }&lt;/pawn&gt;<br /> <br /> It is a good idea to use &lt;tt&gt;const&lt;/tt&gt; in array parameters if you know the array won't be modified; this can prevent coding mistakes.<br /> <br /> =Expressions=<br /> Expressions are exactly the same as they are in mathematics. They are groups of operators/symbols which evaluate to one piece of data. They are often parenthetical (comprised of parenthesis). They contain a strict &quot;order of operations.&quot; They can contain variables, functions, numbers, and expressions themselves can be nested inside other expressions, or even passed as parameters.<br /> <br /> The simplest expression is a single number. For example:<br /> &lt;pawn&gt;<br /> 0; //Returns the number 0<br /> (0); //Returns the number 0 as well<br /> &lt;/pawn&gt;<br /> <br /> Although expressions can return any value, they are also said to either return ''zero or non-zero''. In that sense, ''zero'' is ''false'', and ''non-zero'' is ''true''. For example, -1 is '''true''' in Pawn, since it is non-zero. Do not assume negative numbers are false.<br /> <br /> The order of operations for expressions is similar to C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Here are some example expressions:<br /> &lt;pawn&gt;<br /> 5 + 6; //Evaluates to 11<br /> 5 * 6 + 3; //Evaluates to 33<br /> 5 * (6 + 3); //Evaluates to 45<br /> 5.0 + 2.3; //Evaluates to 7.3<br /> (5 * 6) % 7; //Modulo operator, evaluates to 2<br /> (5 + 3) / 2 * 4 - 9; //Evaluates to -8<br /> &lt;/pawn&gt;<br /> <br /> As noted, expressions can contain variables, or even functions:<br /> &lt;pawn&gt;<br /> int a = 5 * 6;<br /> int b = a * 3; //Evaluates to 90<br /> int c = AddTwoNumbers(a, b) + (a * b);<br /> &lt;/pawn&gt;<br /> <br /> Note: String manipulation routines may be found in the string.inc file located in the include subdirectory. They may be browsed through the [http://docs.sourcemod.net/api/ API Reference] as well.<br /> <br /> ==Operators==<br /> There are a few extra helpful operators in Pawn. The first set simplifies self-aggregation expressions. For example:<br /> &lt;pawn&gt;int a = 5;<br /> <br /> a = a + 5;&lt;/pawn&gt;<br /> <br /> Can be rewritten as:<br /> &lt;pawn&gt;int a = 5;<br /> a += 5;&lt;/pawn&gt;<br /> <br /> This is true of the following operators in Pawn:<br /> *Four-function: *, /, -, +<br /> *Bit-wise: |, &amp;, ^, ~, &lt;&lt;, &gt;&gt;<br /> <br /> Additionally, there are increment/decrement operators:<br /> &lt;pawn&gt;a = a + 1;<br /> a = a - 1;&lt;/pawn&gt;<br /> <br /> Can be simplified as:<br /> &lt;pawn&gt;a++;<br /> a--;&lt;/pawn&gt;<br /> <br /> As an advanced note, the ++ or -- can come before the variable (pre-increment, pre-decrement) or after the variable (post-increment, post-decrement). The difference is in how the rest of the expression containing them sees their result.<br /> <br /> * ''Pre:'' The variable is incremented before evaluation, and the rest of the expression sees the new value.<br /> * ''Post:'' The variable is incremented after evaluation, and the rest of the expression sees the old value.<br /> <br /> In other words, &lt;tt&gt;a++&lt;/tt&gt; evaluates to the value of &lt;tt&gt;a&lt;/tt&gt; while &lt;tt&gt;++a&lt;/tt&gt; evaluates to the value of &lt;tt&gt;a + 1&lt;/tt&gt;. In both cases &lt;tt&gt;a&lt;/tt&gt; is incremented by &lt;tt&gt;1&lt;/tt&gt;.<br /> <br /> For example:<br /> <br /> &lt;pawn&gt;int a = 5;<br /> int b = a++; // b = 5, a = 6 (1)<br /> int c = ++a; // a = 7, c = 7 (2)<br /> &lt;/pawn&gt;<br /> <br /> In (1) &lt;tt&gt;b&lt;/tt&gt; is assigned &lt;tt&gt;a&lt;/tt&gt;'s ''old'' value ''before'' it is incremented to &lt;tt&gt;6&lt;/tt&gt;, but in (2) &lt;tt&gt;c&lt;/tt&gt; is assigned &lt;tt&gt;a&lt;/tt&gt;'s ''int'' value ''after'' it is incremented to &lt;tt&gt;7&lt;/tt&gt;.<br /> <br /> ==Comparison Operators==<br /> There are six operators for comparing two values numerically, and the result is either true (non-zero) or false (zero):<br /> *&lt;tt&gt;a == b&lt;/tt&gt; - True if a and b have the same value.<br /> *&lt;tt&gt;a != b&lt;/tt&gt; - True if a and b have different values.<br /> *&lt;tt&gt;a &amp;gt; b&lt;/tt&gt; - True if a is greater than b<br /> *&lt;tt&gt;a &amp;gt;= b&lt;/tt&gt; - True if a is greater than or equal to b<br /> *&lt;tt&gt;a &amp;lt; b&lt;/tt&gt; - True if a is less than b<br /> *&lt;tt&gt;a &amp;lt;= b&lt;/tt&gt; - True if a is less than or equal to b<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> (1 != 3); //Evaluates to true because 1 is not equal to 3.<br /> (3 + 3 == 6); //Evaluates to true because 3+3 is 6.<br /> (5 - 2 &gt;= 4); //Evaluates to false because 3 is less than 4.<br /> &lt;/pawn&gt;<br /> <br /> Note that these operators do not work on arrays or strings. That is, you cannot compare either using &lt;tt&gt;==&lt;/tt&gt;.<br /> <br /> ==Truth Operators==<br /> These truth values can be combined using three boolean operators:<br /> *&lt;tt&gt;a &amp;&amp; b&lt;/tt&gt; - True if both a and b are true. False if a or b (or both) is false.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;&amp;&amp;&lt;/tt&gt; !! 0 !! 1<br /> |-<br /> ! 0<br /> | 0 || 0<br /> |-<br /> ! 1<br /> | 0 || 1<br /> |}<br /> *&lt;tt&gt;a || b&lt;/tt&gt; - True if a or b (or both) is true. False if both a and b are false.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;&lt;nowiki&gt;||&lt;/nowiki&gt;&lt;/tt&gt; !! 0 !! 1<br /> |-<br /> ! 0<br /> | 0 || 1<br /> |-<br /> ! 1<br /> | 1 || 1<br /> |}<br /> *&lt;tt&gt;!a&lt;/tt&gt; - True if a is false. False if a is true.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;!&lt;/tt&gt; !! 0 !! 1<br /> |- <br /> !<br /> | 1 || 0<br /> |}<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> (1 || 0); //Evaluates to true because the expression 1 is true<br /> (1 &amp;&amp; 0); //Evaluates to false because the expression 0 is false<br /> (!1 || 0); //Evaluates to false because !1 is false.<br /> &lt;/pawn&gt;<br /> <br /> ==Left/Right Values==<br /> Two important concepts are left-hand and right-hand values, or l-values and r-values. An l-value is what appears on the left-hand side of a variable assignment, and an r-value is what appears on the right side of a variable assignment.<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> int a = 5;&lt;/pawn&gt;<br /> <br /> In this example &lt;tt&gt;a&lt;/tt&gt; is an l-value and &lt;tt&gt;5&lt;/tt&gt; is an r-value.<br /> <br /> The rules:<br /> *'''Expressions are never l-values'''.<br /> *'''Variables are both l-values and r-values'''.<br /> <br /> =Conditionals=<br /> Conditional statements let you only run code if a certain condition is matched.<br /> <br /> ==If Statements==<br /> If statements test one or more conditions. For example:<br /> <br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code that will run if the expression was true */<br /> }&lt;/pawn&gt;<br /> <br /> They can be extended to handle more cases as well:<br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code */<br /> }<br /> else if (a == 6)<br /> {<br /> /* Code */<br /> }<br /> else if (a == 7)<br /> {<br /> /* Code */<br /> }&lt;/pawn&gt;<br /> <br /> You can also handle the case of no expression being matched. For example:<br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code */<br /> }<br /> else<br /> {<br /> /* Code that will run if no expressions were true */<br /> }&lt;/pawn&gt;<br /> <br /> ==Switch Statements==<br /> Switch statements are restricted if statements. They test one expression for a series of possible values. For example:<br /> <br /> &lt;pawn&gt;<br /> switch (a)<br /> {<br /> case 5:<br /> {<br /> /* code */<br /> }<br /> case 6:<br /> {<br /> /* code */<br /> }<br /> case 7:<br /> {<br /> /* code */<br /> }<br /> case 8, 9, 10:<br /> {<br /> /* Code */<br /> }<br /> default:<br /> {<br /> /* will run if no case matched */<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> Unlike some other languages, switches are not fall-through. That is, multiple cases will never be run. When a case matches its code is executed, and the switch is then immediately terminated.<br /> <br /> =Loops=<br /> Loops allow you to conveniently repeat a block of code while a given condition remains true. <br /> <br /> ==For Loops==<br /> For loops are loops which have four parts:<br /> *The '''initialization''' statement - run once before the first loop.<br /> *The '''condition''' statement - checks whether the next loop should run, including the first one. The loop terminates when this expression evaluates to false.<br /> *The '''iteration''' statement - run after each loop.<br /> *The '''body''' block - run each time the '''condition''' statement evaluates to true.<br /> <br /> &lt;pawn&gt;<br /> for ( /* initialization */ ; /* condition */ ; /* iteration */ )<br /> {<br /> /* body */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> A simple example is a function to sum an array:<br /> &lt;pawn&gt;<br /> int array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};<br /> int sum = SumArray(array, 10);<br /> <br /> int SumArray(const int array[], int count)<br /> {<br /> int total;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> total += array[i];<br /> }<br /> <br /> return total;<br /> }&lt;/pawn&gt;<br /> <br /> Broken down:<br /> *&lt;tt&gt;int i = 0&lt;/tt&gt; - Creates a new variable for the loop, sets it to 0.<br /> *&lt;tt&gt;i &lt; count&lt;/tt&gt; - Only runs the loop if &lt;tt&gt;i&lt;/tt&gt; is less than &lt;tt&gt;count&lt;/tt&gt;. This ensures that the loop stops reading at a certain point. In this case, we don't want to read invalid indexes in the array.<br /> *&lt;tt&gt;i++&lt;/tt&gt; - Increments &lt;tt&gt;i&lt;/tt&gt; by one after each loop. This ensures that the loop doesn't run forever; eventually &lt;tt&gt;i&lt;/tt&gt; will become too big and the loop will end.<br /> <br /> Thus, the &lt;tt&gt;SumArray&lt;/tt&gt; function will loop through each valid index of the array, each time adding that value of the array into a sum. For loops are very common for processing arrays like this.<br /> <br /> ==While Loops==<br /> While loops are less common than for loops but are actually the simplest possible loop. They have only two parts:<br /> *The '''condition''' statement - checked before each loop. The loop terminates when it evaluates to false.<br /> *The '''body''' block - run each time through the loop.<br /> <br /> &lt;pawn&gt;<br /> while ( /* condition */ )<br /> {<br /> /* body */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> As long as the condition expression remains true, the loop will continue. Every for loop can be rewritten as a while loop:<br /> <br /> &lt;pawn&gt;<br /> /* initialization */<br /> while ( /* condition */ )<br /> {<br /> /* body */<br /> /* iteration */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> Here is the previous for loop rewritten as a while loop:<br /> &lt;pawn&gt;<br /> int SumArray(const int array[], int count)<br /> {<br /> int total, i;<br /> <br /> while (i &lt; count)<br /> {<br /> total += array[i];<br /> i++;<br /> }<br /> <br /> return total;<br /> }&lt;/pawn&gt;<br /> <br /> There are also '''do...while''' loops which are even less common. These are the same as while loops except the condition check is AFTER each loop, rather than before. This means the loop is always run at least once. For example:<br /> <br /> &lt;pawn&gt;<br /> do<br /> {<br /> /* body */<br /> }<br /> while ( /* condition */ );<br /> &lt;/pawn&gt;<br /> <br /> ==Loop Control==<br /> There are two cases in which you want to selectively control a loop:<br /> *'''skipping''' one iteration of the loop but continuing as normal, or;<br /> *'''breaking''' the loop entirely before it's finished.<br /> <br /> Let's say you have a function which takes in an array and searches for a matching number. You want it to stop once the number is found:<br /> &lt;pawn&gt;<br /> /**<br /> * Returns the array index where the value is, or -1 if not found.<br /> */<br /> int SearchInArray(const int array[], int count, int value)<br /> {<br /> int index = -1;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> if (array[i] == value)<br /> {<br /> index = i;<br /> break;<br /> }<br /> }<br /> <br /> return index;<br /> }&lt;/pawn&gt;<br /> <br /> Certainly, this function could simply &lt;tt&gt;return i&lt;/tt&gt; instead, but the example shows how &lt;tt&gt;break&lt;/tt&gt; will terminate the loop.<br /> <br /> Similarly, the &lt;tt&gt;continue&lt;/tt&gt; keyword skips an iteration of a loop. For example, let's say we wanted to sum all even numbers:<br /> &lt;pawn&gt;<br /> int SumEvenNumbers(const int array[], int count)<br /> {<br /> int sum;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> /* If divisibility by 2 is 1, we know it's odd */<br /> if (array[i] % 2 == 1)<br /> {<br /> /* Skip the rest of this loop iteration */<br /> continue;<br /> }<br /> sum += array[i];<br /> }<br /> <br /> return sum;<br /> }&lt;/pawn&gt;<br /> <br /> =Scope=<br /> Scope refers to the '''visibility''' of code. That is, code at one level may not be &quot;visible&quot; to code at another level. For example:<br /> <br /> &lt;pawn&gt;<br /> int A, B, C;<br /> <br /> Function1()<br /> {<br /> int B;<br /> <br /> Function2();<br /> }<br /> <br /> Function2()<br /> {<br /> int C;<br /> }&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;A&lt;/tt&gt;, &lt;tt&gt;B&lt;/tt&gt;, and &lt;tt&gt;C&lt;/tt&gt; exist at '''global scope'''. They can be seen by any function. However, the &lt;tt&gt;B&lt;/tt&gt; in &lt;tt&gt;Function1&lt;/tt&gt; is not the same variable as the &lt;tt&gt;B&lt;/tt&gt; at the global level. Instead, it is at '''local scope''', and is thus a '''local variable'''.<br /> <br /> Similarly, &lt;tt&gt;Function1&lt;/tt&gt; and &lt;tt&gt;Function2&lt;/tt&gt; know nothing about each other's variables.<br /> <br /> Not only is the variable private to &lt;tt&gt;Function1&lt;/tt&gt;, but it is re-created each time the function is invoked. Imagine this:<br /> &lt;pawn&gt;<br /> Function1()<br /> {<br /> int B;<br /> <br /> Function1();<br /> }&lt;/pawn&gt;<br /> <br /> In the above example, &lt;tt&gt;Function1&lt;/tt&gt; calls itself. Of course, this is infinite recursion (a bad thing), but the idea is that each time the function runs, there is a new copy of &lt;tt&gt;B&lt;/tt&gt;. When the function ends, &lt;tt&gt;B&lt;/tt&gt; is destroyed, and the value is lost.<br /> <br /> This property can be simplified by saying that a variable's scope is equal to the nesting level it is in. That is, a variable at global scope is visible globally to all functions. A variable at local scope is visible to all code blocks &quot;beneath&quot; its nesting level. For example:<br /> <br /> &lt;pawn&gt;Function1()<br /> {<br /> int A;<br /> <br /> if (A)<br /> {<br /> A = 5;<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> The above code is valid since A's scope extends throughout the function. The following code, however, is not valid:<br /> &lt;pawn&gt;<br /> Function1()<br /> {<br /> int A;<br /> <br /> if (A)<br /> {<br /> new B = 5;<br /> }<br /> <br /> B = 5;<br /> }&lt;/pawn&gt;<br /> <br /> Notice that &lt;tt&gt;B&lt;/tt&gt; is declared in a new code block. That means &lt;tt&gt;B&lt;/tt&gt; is only accessible to that code block (and all sub-blocks nested within). As soon as the code block terminates, &lt;tt&gt;B&lt;/tt&gt; is no longer valid.<br /> <br /> <br /> =Dynamic Arrays=<br /> Dynamic arrays are arrays which don't have a hardcoded size. For example:<br /> <br /> &lt;pawn&gt;void Function1(int size)<br /> {<br /> int array[size];<br /> <br /> /* Code */<br /> }&lt;/pawn&gt;<br /> <br /> Dynamic arrays can have any expression as their size as long as the expression evaluates to a number larger than 0. Like normal arrays, SourcePawn does not know the array size after it is created; you have to save it if you want it later.<br /> <br /> Dynamic arrays are only valid at the local scope level, since code cannot exist globally.<br /> <br /> =Extended Variable Declarations=<br /> Variables can be declared in more ways than simply &lt;tt&gt;new&lt;/tt&gt;.<br /> <br /> ==decl==<br /> ===Purpose===<br /> By default, all variables in Pawn are initialized to zero. If there is an explicit initializer, the variable is initialized to the expression after the &lt;tt&gt;=&lt;/tt&gt; token. At a local scope, this can be a run-time expense. The &lt;tt&gt;decl&lt;/tt&gt; keyword (which is only valid at local scope) was introduced to let users decide if they want variables initialized or not.<br /> <br /> Note: &lt;tt&gt;decl&lt;/tt&gt; should not be used on single cell variables. There is almost never any benefit.<br /> <br /> ===Explanation===<br /> For example:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> int d;<br /> char blah[512];<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> In this code, &lt;tt&gt;c&lt;/tt&gt; is equal to 5 and &lt;tt&gt;d&lt;/tt&gt; is equal to 0. The run-time expense of this initialization is negligible. However, &lt;tt&gt;blah&lt;/tt&gt; is a large array, and the expense of initializing the entire array to 0s could be detrimental in certain situations. <br /> <br /> Note that &lt;tt&gt;blah&lt;/tt&gt; does not need to be zeroed. In between being declared with &lt;tt&gt;new&lt;/tt&gt; and stored with &lt;tt&gt;Format()&lt;/tt&gt;, &lt;tt&gt;blah&lt;/tt&gt; is never loaded or read. Thus this code would be more efficiently written as:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> int d;<br /> decl String:blah[512];<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> ===Caveats===<br /> The downside to &lt;tt&gt;decl&lt;/tt&gt; is that it means its variables will start with &quot;garbage&quot; contents. For example, if we were to use:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> int d;<br /> decl String:blah[512];<br /> <br /> PrintToServer(&quot;%s&quot;, blah);<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> This code may crash the server, because &lt;tt&gt;blah&lt;/tt&gt; may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> decl d;<br /> decl String:blah[512];<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> The value of &lt;tt&gt;d&lt;/tt&gt; is now undefined. It could be any value, negative or positive. <br /> <br /> Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:<br /> &lt;pawn&gt;<br /> decl String:blah[512];<br /> <br /> blah[0] = '\0';<br /> &lt;/pawn&gt;<br /> <br /> ===Golden Rules===<br /> *'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''<br /> *'''Do not prematurely optimize.''' Likewise, there is no need to use &lt;tt&gt;decl&lt;/tt&gt; on non-arrays, because there is no added expense for initializing a single cell value.<br /> <br /> ===Notes===<br /> This example is NOT as efficient as a &lt;tt&gt;decl&lt;/tt&gt;:<br /> &lt;pawn&gt;<br /> char blah[512] = &quot;a&quot;;<br /> &lt;/pawn&gt;<br /> <br /> Even though the string is only one character, the &lt;tt&gt;new&lt;/tt&gt; operator guarantees the rest of the array will be zeroed as well.<br /> <br /> Also note, it is valid to explicitly initialize a &lt;tt&gt;decl&lt;/tt&gt; '''ONLY''' with strings:<br /> &lt;pawn&gt;decl String:blah[512] = &quot;a&quot;;&lt;/pawn&gt;<br /> <br /> However, any other tag will fail to compile, because the purpose of &lt;tt&gt;decl&lt;/tt&gt; is to avoid any initialization:<br /> &lt;pawn&gt;decl Float:blah[512] = {1.0};&lt;/pawn&gt;<br /> <br /> ==static==<br /> The &lt;tt&gt;static&lt;/tt&gt; keyword is available at global and local scope. It has different meanings in each.<br /> <br /> ===Global static===<br /> A global static variable can only be accessed from within the same file. For example:<br /> <br /> &lt;pawn&gt;//file1.inc<br /> static float g_value1 = 0.15f;<br /> <br /> //file2.inc<br /> static float g_value2 = 0.15f;&lt;/pawn&gt;<br /> <br /> If a plugin includes both of these files, it will not be able to use either &lt;tt&gt;g_value1&lt;/tt&gt; or &lt;tt&gt;g_value2&lt;/tt&gt;. This is a simple information hiding mechanism, and is similar to declaring member variables as &lt;tt&gt;private&lt;/tt&gt; in languages like C++, Java, or C#.<br /> <br /> ===Local static===<br /> A local static variable is a global variable that is only visible from its local lexical scope. For example:<br /> <br /> &lt;pawn&gt;<br /> int MyFunction(inc)<br /> {<br /> static counter = -1;<br /> <br /> counter += inc;<br /> <br /> return counter;<br /> }&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;counter&lt;/tt&gt; is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time &lt;tt&gt;MyFunction&lt;/tt&gt; runs, the &lt;tt&gt;counter&lt;/tt&gt; variable and its storage in memory is the same.<br /> <br /> Take this example:<br /> &lt;pawn&gt;MyFunction(5);<br /> MyFunction(6);<br /> MyFunction(10);&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;counter&lt;/tt&gt; will be &lt;tt&gt;-1 + 5 + 6 + 10&lt;/tt&gt;, or &lt;tt&gt;20&lt;/tt&gt;, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then &lt;tt&gt;static&lt;/tt&gt; is usually not a good idea unless your code is re-entrant. <br /> <br /> The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.<br /> <br /> Note that statics can exist in any local scope:<br /> <br /> &lt;pawn&gt;<br /> int MyFunction(inc)<br /> {<br /> if (inc &gt; 0)<br /> {<br /> static counter;<br /> return (counter += inc);<br /> }<br /> return -1;<br /> }&lt;/pawn&gt;<br /> <br /> [[Category:SourceMod Scripting]]<br /> <br /> {{LanguageSwitch}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Introduction_to_SourcePawn_1.7&diff=10056 2015-11-15T18:36:25Z

<p>Xerox8521: /* Loop Control */</p> <hr /> <div>This guide is designed to give you a very basic overview to fundamentals of scripting in SourcePawn. [[Pawn]] is a &quot;scripting&quot; language used to embed functionality in other programs. That means it is not a standalone language, like C++ or Java, and its details will differ based on the application. SourcePawn is the version of Pawn used in [[SourceMod]].<br /> <br /> This guide does not tell you how to write SourceMod plugins; it is intended as an overview of the syntax and semantics of the language instead. Read the separate article, [[Introduction to SourceMod Plugins]] for SourceMod API specifics. <br /> <br /> =Non-Programmer Intro=<br /> This section is intended for non-programmers. If you're still confused, you may want to pick up a book on another language, such as PHP, Python, or Java, to get a better idea of what programming is like.<br /> <br /> ==Symbols/Keywords==<br /> A symbol is a series of letters, numbers, and/or underscores, that uniquely represents something. Symbols are case-sensitive, and usually start with a letter.<br /> <br /> There are a few reserved symbols that have special meaning. For example, &lt;tt&gt;if&lt;/tt&gt;, &lt;tt&gt;for&lt;/tt&gt;, and &lt;tt&gt;return&lt;/tt&gt; are special constructs in the language that will explained later. They cannot be used as symbol names.<br /> <br /> ==Variables==<br /> There a few important constructs you should know before you begin to script. The first is a '''variable'''. A variable is a symbol, or name, that holds data. For example, the variable &quot;a&quot; could hold the number &quot;2&quot;, &quot;16&quot;, &quot;0&quot;, et cetera. Since a variable holds data, it also allocates the memory needed to store that data.<br /> <br /> In addition to a name, variables have a '''type'''. A type tells the program how to interpret the data, and how much memory the data will use. Pawn has three types of data that are most commonly used:<br /> * Integers, using the &lt;tt&gt;int&lt;/tt&gt; type. Integer types may store a whole number from -2147483648 to 2147483647.<br /> * Floats, using the &lt;tt&gt;float&lt;/tt&gt; type. Float types may store fractional numbers in a huge range, though they are not as precise as integers.<br /> * Characters, using the &lt;tt&gt;char&lt;/tt&gt; type. Character types store one byte of character information, typically an [http://www.asciitable.com/ ASCII] character.<br /> * Booleans, using the &lt;tt&gt;bool&lt;/tt&gt; type. Booleans store either true or false.<br /> <br /> Example of creating variables and assigning values:<br /> <br /> &lt;pawn&gt;int money = 5400;<br /> float percent = 67.3;<br /> bool enabled = false;<br /> &lt;/pawn&gt;<br /> <br /> ==Functions==<br /> The next important concept is '''functions'''. Functions are symbols or names that perform an action. When you invoke, or call them, they carry out a specific sequence of code and then return a result. There are a few types of functions, but every function is activated the same way. Example:<br /> <br /> &lt;pawn&gt;<br /> show(56); // Calls the &quot;show&quot; function, and gives it the number 56.<br /> enable(); // Calls the &quot;s &quot;enable&quot; function with no values.<br /> bool visible = show(a); //Calls the &quot;show&quot; function, stores its result in a variable.<br /> &lt;/pawn&gt;<br /> <br /> Every piece of data passed to a function is called a '''parameter'''. A function can have any number of parameters (there is a &quot;reasonable&quot; limit of 32 in SourceMod). Parameters will be explained further in the article.<br /> <br /> ==Comments==<br /> Note any text that appears after a &quot;//&quot; is considered a &quot;comment&quot; and is not actual code. There are two comment styles:<br /> *&lt;tt&gt;//&lt;/tt&gt; - Double slash, everything following on that line is ignored.<br /> *&lt;tt&gt;/* */&lt;/tt&gt; - Multi-line comment, everything in between the asterisks is ignored. You cannot nest these.<br /> <br /> <br /> ==Block Coding==<br /> The next concept is block coding. You can group code into &quot;blocks&quot; separated by { and }. This effectively makes one large block of code act as one statement. For example:<br /> <br /> &lt;pawn&gt;{<br /> here;<br /> is;<br /> some;<br /> code;<br /> }&lt;/pawn&gt;<br /> <br /> Block coding using braces is used everywhere in programming. Blocks of code can be nested within each other. It is a good idea to adapt a consistent and readable indentation style early on to prevent spaghetti-looking code.<br /> <br /> =Language Paradigms=<br /> Pawn may seem similar to other languages, like C, but it has fundamental differences. It is not important that you immediately understand these differences, but they may be helpful if you're familiar with another language already.<br /> *'''Pawn is sort of typed.''' Before SourceMod 1.7, Pawn did not have types. Older code and older natives will reflect this by using tags and the &lt;tt&gt;new&lt;/tt&gt; keyword. As of SourceMod 1.7, we recommend that all code use types. For more information see [[SourcePawn Transitional Syntax]].<br /> *'''Pawn is not garbage collected.''' Pawn, as a language, has no built-in memory allocation, and thus has no garbage. If a function allocates memory, you may be responsible for freeing it.<br /> *'''Pawn is not object oriented.''' Pawn does not have structs or objects. As of SourceMod 1.7, it has limited sugaring for treating some data types as objects, but users cannot create their own objects or classes.<br /> *'''Pawn is single-threaded.''' As of this writing, Pawn is not thread safe. <br /> *'''Pawn is compiled.''' Pawn is compiled to an intermediate, machine-independent code, which is stored in a &quot;.smx&quot; file. When loading .smx files, SourceMod translates this code to machine code for the platform and CPU it's running on.<br /> <br /> Early language design decisions were made by ITB CompuPhase. It is designed for low-level embedded devices and is thus very small and very fast.<br /> <br /> =Variables=<br /> Pawn currently supports the following basic variable types:<br /> *&lt;tt&gt;bool&lt;/tt&gt; - true or false.<br /> *&lt;tt&gt;char&lt;/tt&gt; - an 8-bit ASCII character.<br /> *&lt;tt&gt;int&lt;/tt&gt; - a 32-bit signed integer.<br /> *&lt;tt&gt;float&lt;/tt&gt; - a 32-bit IEEE-754 floating point number.<br /> *&lt;tt&gt;Handle&lt;/tt&gt; - the base type of a SourceMod object<br /> <br /> Other types may exist when defined in include files - for example, enums create new types for named integers, and many types derive from &lt;tt&gt;Handle&lt;/tt&gt;.<br /> <br /> Strings, currently, are 0-terminated arrays of &lt;tt&gt;char&lt;/tt&gt;s. They're described a little further ahead.<br /> <br /> ==Declaration==<br /> Below we include some examples of variable declarations, both valid and invalid. Keep in mind that SourcePawn has recently added new syntax, and that's what's documented below. Older code may use older declaration syntax, which is no longer supported.<br /> <br /> &lt;pawn&gt;<br /> int a = 5;<br /> float b = 5.0;<br /> bool c = true;<br /> bool d = false;<br /> &lt;/pawn&gt;<br /> <br /> Invalid variable usage:<br /> &lt;pawn&gt;<br /> int a = 5.0; // Type mismatch. 5.0 is a float.<br /> float b = 5; // Type mismatch. 5 is an integer.<br /> &lt;/pawn&gt;<br /> <br /> If a variable is not assigned upon declaration, it will be set to 0. For example:<br /> &lt;pawn&gt;<br /> int a; // Set to 0<br /> float b; // Set to 0.0<br /> bool c; // Set to false<br /> &lt;/pawn&gt;<br /> <br /> ==Assignment==<br /> Variables can be re-assigned data after they are created. For example:<br /> &lt;pawn&gt;int a;<br /> float b;<br /> bool c;<br /> <br /> a = 5;<br /> b = 5.0;<br /> c = true;<br /> &lt;/pawn&gt;<br /> <br /> =Arrays=<br /> An array is a sequence of data in a list. Arrays are useful for storing multiple pieces of data in one variable, or mapping one type of data to another.<br /> <br /> ==Declaration==<br /> An array is declared using brackets. Some examples of arrays:<br /> &lt;pawn&gt;<br /> int players[32]; // Stores 32 integers.<br /> float origin[3]; // Stores 3 floating point numbers<br /> &lt;/pawn&gt;<br /> <br /> By default, arrays are initialized to 0. You can assign them different default values, however:<br /> &lt;pawn&gt;<br /> int numbers[5] = {1, 2, 3, 4, 5}; // Stores 1, 2, 3, 4, 5.<br /> float origin[3] = {1.0, 2.0, 3.0}; // Stores 1.0, 2.0, 3.0.<br /> &lt;/pawn&gt;<br /> <br /> You can leave out the array size if you're going to pre-assign data to it. For example:<br /> &lt;pawn&gt;<br /> int numbers[] = {1, 3, 5, 7, 9};<br /> &lt;/pawn&gt;<br /> <br /> The compiler will automatically deduce that you intended an array of size 5.<br /> <br /> When array is declared with brackets after its name, Pawn considers that array to have a '''fixed size'''. The size of a fixed-size array is always known. Some arrays can be '''dynamically sized''', by putting the brackets before the name. For example,<br /> <br /> &lt;pawn&gt;<br /> int[] numbers = new int[MaxClients]<br /> &lt;/pawn&gt;<br /> <br /> This creates an array of size &lt;tt&gt;MaxClients&lt;/tt&gt;, which could be anything, so the size of the array is not known until the array is allocated.<br /> <br /> ==Usage==<br /> Using an array is just like using a normal variable. The only difference is the array must be '''indexed'''. Indexing an array means choosing the element which you wish to use.<br /> <br /> For example, here is an example of the above code using indexes:<br /> &lt;pawn&gt;<br /> int numbers[5];<br /> float origin[3];<br /> <br /> numbers[0] = 1;<br /> numbers[1] = 2;<br /> numbers[2] = 3;<br /> numbers[3] = 4;<br /> numbers[4] = 5;<br /> origin[0] = 1.0;<br /> origin[1] = 2.0;<br /> origin[2] = 3.0;<br /> &lt;/pawn&gt;<br /> <br /> Note that the '''index''' is what's in between the brackets. The index always starts from 0. That is, if an array has N elements, its valid indexes are from 0 to N-1. Accessing the data at these indexes works like a normal variable.<br /> <br /> Using an incorrect index will cause an error. For example:<br /> &lt;pawn&gt;<br /> int numbers[5];<br /> <br /> numbers[5] = 20;&lt;/pawn&gt;<br /> <br /> This may look correct, but 5 is not a valid index. The highest valid index is 4.<br /> <br /> You can use any expression as an index. For example:<br /> &lt;pawn&gt;int a, numbers[5];<br /> <br /> a = 1; // Set a = 1<br /> numbers[a] = 4; // Set numbers[1] = 4<br /> numbers[numbers[a]] = 2; // Set numbers[4] = 2<br /> &lt;/pawn&gt;<br /> <br /> Expressions will be discussed in depth later in the article.<br /> <br /> =Strings=<br /> Strings are a construct for storing text (or even raw binary data). A string is just an array of characters, except that the final character must be 0 (called the null terminator). Without a null terminator, Pawn would not know where to stop reading the string. All strings are [http://en.wikipedia.org/wiki/UTF-8 UTF-8] in SourcePawn.<br /> <br /> In general, you must have an idea of how large a string will be before you store it. SourcePawn does not yet have the capability of pre-determining storage space for strings.<br /> <br /> ==Usage==<br /> Strings are usually declared as arrays. For example:<br /> &lt;pawn&gt;<br /> char message[] = &quot;Hello!&quot;;<br /> char clams[6] = &quot;Clams&quot;;<br /> &lt;/pawn&gt;<br /> <br /> These are equivalent to doing:<br /> &lt;pawn&gt;<br /> char message[7];<br /> char clams[6];<br /> <br /> message[0] = 'H';<br /> message[1] = 'e';<br /> message[2] = 'l';<br /> message[3] = 'l';<br /> message[4] = 'o';<br /> message[5] = '!';<br /> message[6] = 0;<br /> clams[0] = 'C';<br /> clams[1] = 'l';<br /> clams[2] = 'a';<br /> clams[3] = 'm';<br /> clams[4] = 's';<br /> clams[5] = 0;<br /> &lt;/pawn&gt;<br /> <br /> Although strings are rarely initialized in this manner, it is very important to remember the concept of the null terminator, which signals the end of a string. The compiler, and most SourceMod functions will automatically null-terminate for you, so it is mainly important when manipulating strings directly.<br /> <br /> Note that a string is enclosed in double-quotes, but a character is enclosed in single quotes.<br /> <br /> ==Characters==<br /> A character of text can be used in either a String or a cell. For example:<br /> &lt;pawn&gt;char text[] = &quot;Crab&quot;;<br /> char clam;<br /> <br /> clam = 'D'; //Set clam to 'D'<br /> text[0] = 'A'; //Change the 'C' to 'A', it is now 'Arab'<br /> clam = text[0]; //Set clam to 'A'<br /> text[1] = clam; //Change the 'r' to 'A', is is now 'AAab'<br /> &lt;/pawn&gt;<br /> <br /> What you can't do is mix character arrays with strings. The internal storage is different. For example:<br /> &lt;pawn&gt;<br /> int clams[] = &quot;Clams&quot;; // Invalid.<br /> int clams[] = {'C', 'l', 'a', 'm', 's', 0}; // Valid, but NOT A STRING.<br /> &lt;/pawn&gt;<br /> <br /> =Functions=<br /> Functions, as stated before, are isolated blocks of code that perform an action. They can be invoked, or '''called''', with '''parameters''' that give specific options.<br /> <br /> There are two types of ways functions are called:<br /> *'''direct call''' - You specifically call a function in your code.<br /> *'''callback''' - The application calls a function in your code, as if it were an event trigger.<br /> <br /> There are six types of functions:<br /> *'''native''': A direct, internal function provided by the application.<br /> *'''public''': A callback function that is visible to the application and other scripts.<br /> *'''normal''': A normal function that only you can call.<br /> *'''static''': The scope of this function is restricted to the current file, can be used in combination with stock.<br /> *'''stock''': A normal function provided by an include file. If unused, it won't be compiled.<br /> *'''forward''': This function is a global event provided by the application. If you implement it, it will be a callback.<br /> <br /> All code in Pawn must exist in functions. This is in contrast to languages like PHP, Perl, and Python which let you write global code. That is because Pawn is a callback-based language: it responds to actions from a parent application, and functions must be written to handle those actions. Although our examples often contain free-floating code, this is purely for demonstration purposes. Free-floating code in our examples implies the code is part of some function.<br /> <br /> ==Declaration==<br /> Unlike variables, functions do not need to be declared before you use them. Functions have two pieces, the '''signature''' and the '''body'''. The signature contains the name of your function and the parameters it will accept. The body is the contents of its code.<br /> <br /> Example of a function:<br /> &lt;pawn&gt;<br /> int AddTwoNumbers(int first, int second)<br /> {<br /> int sum = first + second;<br /> return sum;<br /> }&lt;/pawn&gt;<br /> <br /> This is a simple function. The prototype is this line:<br /> &lt;pawn&gt;int AddTwoNumbers(int first, int second)&lt;/pawn&gt;<br /> <br /> Broken down, it means:<br /> *&lt;tt&gt;int&lt;/tt&gt; - Return value type (integer).<br /> *&lt;tt&gt;AddTwoNumbers&lt;/tt&gt; - Name of the function.<br /> *&lt;tt&gt;int first&lt;/tt&gt; - First parameter, an integer.<br /> *&lt;tt&gt;int second&lt;/tt&gt; - Second parameter, an integer.<br /> <br /> The body is a block of code. It creates a new variable, called &lt;tt&gt;sum&lt;/tt&gt;, and assigns it the value of the two parameters added together (more on expressions later). The important thing to notice is the &lt;tt&gt;return&lt;/tt&gt; statement, which tells the function to end and return a value to the caller of the function. All functions return something on completion, unless they return a special type called &lt;tt&gt;void&lt;/tt&gt;.<br /> <br /> A function can accept any type of input, and it can return any non-array type.<br /> <br /> You can, of course, pass variables to functions:<br /> &lt;pawn&gt;int numbers[3] = {1, 2, 0};<br /> <br /> numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);&lt;/pawn&gt;<br /> <br /> Note that cells are passed '''by value'''. That is, their value cannot be changed by the function. For example:<br /> &lt;pawn&gt;int a = 5;<br /> <br /> ChangeValue(a);<br /> <br /> ChangeValue(b)<br /> {<br /> b = 5;<br /> }&lt;/pawn&gt;<br /> <br /> This code would not change the value of &lt;tt&gt;a&lt;/tt&gt;. That is because a copy of the value in &lt;tt&gt;a&lt;/tt&gt; is passed instead of &lt;tt&gt;a&lt;/tt&gt; itself. <br /> <br /> More examples of functions will be provided throughout the article.<br /> <br /> ==Publics==<br /> Public functions are used to implement callbacks. You should not create a public function unless it is specifically implementing a callback. For example, here are two callbacks from &lt;tt&gt;sourcemod.inc&lt;/tt&gt;:<br /> <br /> &lt;pawn&gt;forward void OnPluginStart();<br /> forward void OnClientDisconnected(int client);&lt;/pawn&gt;<br /> <br /> To implement and receive these two events, you would write functions as such:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> /* Code here */<br /> }<br /> <br /> public void OnClientDisconnected(int client)<br /> {<br /> /* Code here */<br /> }&lt;/pawn&gt;<br /> <br /> The '''public''' keyword signals to the parent application that it should attach the function to the appropriate forwarded event.<br /> <br /> ==Natives==<br /> Natives are builtin functions provided by SourceMod. You can call them as if they were a normal function. For example, SourceMod has the following function:<br /> <br /> &lt;pawn&gt;native float FloatRound(float num);&lt;/pawn&gt;<br /> <br /> It can be called like so:<br /> &lt;pawn&gt;int rounded = FloatRound(5.2); // rounded will be 5&lt;/pawn&gt;<br /> <br /> ==Array Parameters==<br /> You can pass arrays or Strings as parameters. It is important to note that these are passed '''by reference'''. That is, rather than making a copy of the data, the data is referenced directly. There is a simple way of explaining this more concretely.<br /> <br /> &lt;pawn&gt;<br /> int example[] = {1, 2, 3, 4, 5};<br /> <br /> ChangeArray(example, 2, 29);<br /> <br /> void ChangeArray(int[] array, int index, int value)<br /> {<br /> array[index] = value;<br /> }&lt;/pawn&gt;<br /> <br /> The function sets the given index in the array to a given value. When it is run on our example array, it changes index 2 to from the value 3 to 29. I.e.:<br /> &lt;pawn&gt;example[2] = 29;&lt;/pawn&gt;<br /> <br /> Note two important things here. First, arrays are not copied when they are passed to functions - they are passed ''by reference'', so the view of the array is consistent at all times. Second, the brackets changed position in our function signature. This is because our function accepts an array of any size, and since we don't know the size, we must use the dynamic array syntax.<br /> <br /> To prevent an array from being modified in a function, you can mark it as &lt;tt&gt;const&lt;/tt&gt;. This will raise an error on code that attempts to modify it. For example:<br /> <br /> &lt;pawn&gt;void CantChangeArray(const array[], int index, int value)<br /> {<br /> array[index] = value; //Won't compile<br /> }&lt;/pawn&gt;<br /> <br /> It is a good idea to use &lt;tt&gt;const&lt;/tt&gt; in array parameters if you know the array won't be modified; this can prevent coding mistakes.<br /> <br /> =Expressions=<br /> Expressions are exactly the same as they are in mathematics. They are groups of operators/symbols which evaluate to one piece of data. They are often parenthetical (comprised of parenthesis). They contain a strict &quot;order of operations.&quot; They can contain variables, functions, numbers, and expressions themselves can be nested inside other expressions, or even passed as parameters.<br /> <br /> The simplest expression is a single number. For example:<br /> &lt;pawn&gt;<br /> 0; //Returns the number 0<br /> (0); //Returns the number 0 as well<br /> &lt;/pawn&gt;<br /> <br /> Although expressions can return any value, they are also said to either return ''zero or non-zero''. In that sense, ''zero'' is ''false'', and ''non-zero'' is ''true''. For example, -1 is '''true''' in Pawn, since it is non-zero. Do not assume negative numbers are false.<br /> <br /> The order of operations for expressions is similar to C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Here are some example expressions:<br /> &lt;pawn&gt;<br /> 5 + 6; //Evaluates to 11<br /> 5 * 6 + 3; //Evaluates to 33<br /> 5 * (6 + 3); //Evaluates to 45<br /> 5.0 + 2.3; //Evaluates to 7.3<br /> (5 * 6) % 7; //Modulo operator, evaluates to 2<br /> (5 + 3) / 2 * 4 - 9; //Evaluates to -8<br /> &lt;/pawn&gt;<br /> <br /> As noted, expressions can contain variables, or even functions:<br /> &lt;pawn&gt;<br /> int a = 5 * 6;<br /> int b = a * 3; //Evaluates to 90<br /> int c = AddTwoNumbers(a, b) + (a * b);<br /> &lt;/pawn&gt;<br /> <br /> Note: String manipulation routines may be found in the string.inc file located in the include subdirectory. They may be browsed through the [http://docs.sourcemod.net/api/ API Reference] as well.<br /> <br /> ==Operators==<br /> There are a few extra helpful operators in Pawn. The first set simplifies self-aggregation expressions. For example:<br /> &lt;pawn&gt;int a = 5;<br /> <br /> a = a + 5;&lt;/pawn&gt;<br /> <br /> Can be rewritten as:<br /> &lt;pawn&gt;int a = 5;<br /> a += 5;&lt;/pawn&gt;<br /> <br /> This is true of the following operators in Pawn:<br /> *Four-function: *, /, -, +<br /> *Bit-wise: |, &amp;, ^, ~, &lt;&lt;, &gt;&gt;<br /> <br /> Additionally, there are increment/decrement operators:<br /> &lt;pawn&gt;a = a + 1;<br /> a = a - 1;&lt;/pawn&gt;<br /> <br /> Can be simplified as:<br /> &lt;pawn&gt;a++;<br /> a--;&lt;/pawn&gt;<br /> <br /> As an advanced note, the ++ or -- can come before the variable (pre-increment, pre-decrement) or after the variable (post-increment, post-decrement). The difference is in how the rest of the expression containing them sees their result.<br /> <br /> * ''Pre:'' The variable is incremented before evaluation, and the rest of the expression sees the new value.<br /> * ''Post:'' The variable is incremented after evaluation, and the rest of the expression sees the old value.<br /> <br /> In other words, &lt;tt&gt;a++&lt;/tt&gt; evaluates to the value of &lt;tt&gt;a&lt;/tt&gt; while &lt;tt&gt;++a&lt;/tt&gt; evaluates to the value of &lt;tt&gt;a + 1&lt;/tt&gt;. In both cases &lt;tt&gt;a&lt;/tt&gt; is incremented by &lt;tt&gt;1&lt;/tt&gt;.<br /> <br /> For example:<br /> <br /> &lt;pawn&gt;int a = 5;<br /> int b = a++; // b = 5, a = 6 (1)<br /> int c = ++a; // a = 7, c = 7 (2)<br /> &lt;/pawn&gt;<br /> <br /> In (1) &lt;tt&gt;b&lt;/tt&gt; is assigned &lt;tt&gt;a&lt;/tt&gt;'s ''old'' value ''before'' it is incremented to &lt;tt&gt;6&lt;/tt&gt;, but in (2) &lt;tt&gt;c&lt;/tt&gt; is assigned &lt;tt&gt;a&lt;/tt&gt;'s ''int'' value ''after'' it is incremented to &lt;tt&gt;7&lt;/tt&gt;.<br /> <br /> ==Comparison Operators==<br /> There are six operators for comparing two values numerically, and the result is either true (non-zero) or false (zero):<br /> *&lt;tt&gt;a == b&lt;/tt&gt; - True if a and b have the same value.<br /> *&lt;tt&gt;a != b&lt;/tt&gt; - True if a and b have different values.<br /> *&lt;tt&gt;a &amp;gt; b&lt;/tt&gt; - True if a is greater than b<br /> *&lt;tt&gt;a &amp;gt;= b&lt;/tt&gt; - True if a is greater than or equal to b<br /> *&lt;tt&gt;a &amp;lt; b&lt;/tt&gt; - True if a is less than b<br /> *&lt;tt&gt;a &amp;lt;= b&lt;/tt&gt; - True if a is less than or equal to b<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> (1 != 3); //Evaluates to true because 1 is not equal to 3.<br /> (3 + 3 == 6); //Evaluates to true because 3+3 is 6.<br /> (5 - 2 &gt;= 4); //Evaluates to false because 3 is less than 4.<br /> &lt;/pawn&gt;<br /> <br /> Note that these operators do not work on arrays or strings. That is, you cannot compare either using &lt;tt&gt;==&lt;/tt&gt;.<br /> <br /> ==Truth Operators==<br /> These truth values can be combined using three boolean operators:<br /> *&lt;tt&gt;a &amp;&amp; b&lt;/tt&gt; - True if both a and b are true. False if a or b (or both) is false.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;&amp;&amp;&lt;/tt&gt; !! 0 !! 1<br /> |-<br /> ! 0<br /> | 0 || 0<br /> |-<br /> ! 1<br /> | 0 || 1<br /> |}<br /> *&lt;tt&gt;a || b&lt;/tt&gt; - True if a or b (or both) is true. False if both a and b are false.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;&lt;nowiki&gt;||&lt;/nowiki&gt;&lt;/tt&gt; !! 0 !! 1<br /> |-<br /> ! 0<br /> | 0 || 1<br /> |-<br /> ! 1<br /> | 1 || 1<br /> |}<br /> *&lt;tt&gt;!a&lt;/tt&gt; - True if a is false. False if a is true.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;!&lt;/tt&gt; !! 0 !! 1<br /> |- <br /> !<br /> | 1 || 0<br /> |}<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> (1 || 0); //Evaluates to true because the expression 1 is true<br /> (1 &amp;&amp; 0); //Evaluates to false because the expression 0 is false<br /> (!1 || 0); //Evaluates to false because !1 is false.<br /> &lt;/pawn&gt;<br /> <br /> ==Left/Right Values==<br /> Two important concepts are left-hand and right-hand values, or l-values and r-values. An l-value is what appears on the left-hand side of a variable assignment, and an r-value is what appears on the right side of a variable assignment.<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> int a = 5;&lt;/pawn&gt;<br /> <br /> In this example &lt;tt&gt;a&lt;/tt&gt; is an l-value and &lt;tt&gt;5&lt;/tt&gt; is an r-value.<br /> <br /> The rules:<br /> *'''Expressions are never l-values'''.<br /> *'''Variables are both l-values and r-values'''.<br /> <br /> =Conditionals=<br /> Conditional statements let you only run code if a certain condition is matched.<br /> <br /> ==If Statements==<br /> If statements test one or more conditions. For example:<br /> <br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code that will run if the expression was true */<br /> }&lt;/pawn&gt;<br /> <br /> They can be extended to handle more cases as well:<br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code */<br /> }<br /> else if (a == 6)<br /> {<br /> /* Code */<br /> }<br /> else if (a == 7)<br /> {<br /> /* Code */<br /> }&lt;/pawn&gt;<br /> <br /> You can also handle the case of no expression being matched. For example:<br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code */<br /> }<br /> else<br /> {<br /> /* Code that will run if no expressions were true */<br /> }&lt;/pawn&gt;<br /> <br /> ==Switch Statements==<br /> Switch statements are restricted if statements. They test one expression for a series of possible values. For example:<br /> <br /> &lt;pawn&gt;<br /> switch (a)<br /> {<br /> case 5:<br /> {<br /> /* code */<br /> }<br /> case 6:<br /> {<br /> /* code */<br /> }<br /> case 7:<br /> {<br /> /* code */<br /> }<br /> case 8, 9, 10:<br /> {<br /> /* Code */<br /> }<br /> default:<br /> {<br /> /* will run if no case matched */<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> Unlike some other languages, switches are not fall-through. That is, multiple cases will never be run. When a case matches its code is executed, and the switch is then immediately terminated.<br /> <br /> =Loops=<br /> Loops allow you to conveniently repeat a block of code while a given condition remains true. <br /> <br /> ==For Loops==<br /> For loops are loops which have four parts:<br /> *The '''initialization''' statement - run once before the first loop.<br /> *The '''condition''' statement - checks whether the next loop should run, including the first one. The loop terminates when this expression evaluates to false.<br /> *The '''iteration''' statement - run after each loop.<br /> *The '''body''' block - run each time the '''condition''' statement evaluates to true.<br /> <br /> &lt;pawn&gt;<br /> for ( /* initialization */ ; /* condition */ ; /* iteration */ )<br /> {<br /> /* body */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> A simple example is a function to sum an array:<br /> &lt;pawn&gt;<br /> int array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};<br /> int sum = SumArray(array, 10);<br /> <br /> int SumArray(const int array[], int count)<br /> {<br /> int total;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> total += array[i];<br /> }<br /> <br /> return total;<br /> }&lt;/pawn&gt;<br /> <br /> Broken down:<br /> *&lt;tt&gt;int i = 0&lt;/tt&gt; - Creates a new variable for the loop, sets it to 0.<br /> *&lt;tt&gt;i &lt; count&lt;/tt&gt; - Only runs the loop if &lt;tt&gt;i&lt;/tt&gt; is less than &lt;tt&gt;count&lt;/tt&gt;. This ensures that the loop stops reading at a certain point. In this case, we don't want to read invalid indexes in the array.<br /> *&lt;tt&gt;i++&lt;/tt&gt; - Increments &lt;tt&gt;i&lt;/tt&gt; by one after each loop. This ensures that the loop doesn't run forever; eventually &lt;tt&gt;i&lt;/tt&gt; will become too big and the loop will end.<br /> <br /> Thus, the &lt;tt&gt;SumArray&lt;/tt&gt; function will loop through each valid index of the array, each time adding that value of the array into a sum. For loops are very common for processing arrays like this.<br /> <br /> ==While Loops==<br /> While loops are less common than for loops but are actually the simplest possible loop. They have only two parts:<br /> *The '''condition''' statement - checked before each loop. The loop terminates when it evaluates to false.<br /> *The '''body''' block - run each time through the loop.<br /> <br /> &lt;pawn&gt;<br /> while ( /* condition */ )<br /> {<br /> /* body */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> As long as the condition expression remains true, the loop will continue. Every for loop can be rewritten as a while loop:<br /> <br /> &lt;pawn&gt;<br /> /* initialization */<br /> while ( /* condition */ )<br /> {<br /> /* body */<br /> /* iteration */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> Here is the previous for loop rewritten as a while loop:<br /> &lt;pawn&gt;<br /> int SumArray(const int array[], int count)<br /> {<br /> int total, i;<br /> <br /> while (i &lt; count)<br /> {<br /> total += array[i];<br /> i++;<br /> }<br /> <br /> return total;<br /> }&lt;/pawn&gt;<br /> <br /> There are also '''do...while''' loops which are even less common. These are the same as while loops except the condition check is AFTER each loop, rather than before. This means the loop is always run at least once. For example:<br /> <br /> &lt;pawn&gt;<br /> do<br /> {<br /> /* body */<br /> }<br /> while ( /* condition */ );<br /> &lt;/pawn&gt;<br /> <br /> ==Loop Control==<br /> There are two cases in which you want to selectively control a loop:<br /> *'''skipping''' one iteration of the loop but continuing as normal, or;<br /> *'''breaking''' the loop entirely before it's finished.<br /> <br /> Let's say you have a function which takes in an array and searches for a matching number. You want it to stop once the number is found:<br /> &lt;pawn&gt;<br /> /**<br /> * Returns the array index where the value is, or -1 if not found.<br /> */<br /> int SearchInArray(const int array[], int count, int value)<br /> {<br /> int index = -1;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> if (array[i] == value)<br /> {<br /> index = i;<br /> break;<br /> }<br /> }<br /> <br /> return index;<br /> }&lt;/pawn&gt;<br /> <br /> Certainly, this function could simply &lt;tt&gt;return i&lt;/tt&gt; instead, but the example shows how &lt;tt&gt;break&lt;/tt&gt; will terminate the loop.<br /> <br /> Similarly, the &lt;tt&gt;continue&lt;/tt&gt; keyword skips an iteration of a loop. For example, let's say we wanted to sum all even numbers:<br /> &lt;pawn&gt;<br /> int SumEvenNumbers(const int array[], int count)<br /> {<br /> int sum;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> /* If divisibility by 2 is 1, we know it's odd */<br /> if (array[i] % 2 == 1)<br /> {<br /> /* Skip the rest of this loop iteration */<br /> continue;<br /> }<br /> sum += array[i];<br /> }<br /> <br /> return sum;<br /> }&lt;/pawn&gt;<br /> <br /> =Scope=<br /> Scope refers to the '''visibility''' of code. That is, code at one level may not be &quot;visible&quot; to code at another level. For example:<br /> <br /> &lt;pawn&gt;<br /> int A, B, C;<br /> <br /> Function1()<br /> {<br /> int B;<br /> <br /> Function2();<br /> }<br /> <br /> Function2()<br /> {<br /> int C;<br /> }&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;A&lt;/tt&gt;, &lt;tt&gt;B&lt;/tt&gt;, and &lt;tt&gt;C&lt;/tt&gt; exist at '''global scope'''. They can be seen by any function. However, the &lt;tt&gt;B&lt;/tt&gt; in &lt;tt&gt;Function1&lt;/tt&gt; is not the same variable as the &lt;tt&gt;B&lt;/tt&gt; at the global level. Instead, it is at '''local scope''', and is thus a '''local variable'''.<br /> <br /> Similarly, &lt;tt&gt;Function1&lt;/tt&gt; and &lt;tt&gt;Function2&lt;/tt&gt; know nothing about each other's variables.<br /> <br /> Not only is the variable private to &lt;tt&gt;Function1&lt;/tt&gt;, but it is re-created each time the function is invoked. Imagine this:<br /> &lt;pawn&gt;<br /> Function1()<br /> {<br /> int B;<br /> <br /> Function1();<br /> }&lt;/pawn&gt;<br /> <br /> In the above example, &lt;tt&gt;Function1&lt;/tt&gt; calls itself. Of course, this is infinite recursion (a bad thing), but the idea is that each time the function runs, there is a new copy of &lt;tt&gt;B&lt;/tt&gt;. When the function ends, &lt;tt&gt;B&lt;/tt&gt; is destroyed, and the value is lost.<br /> <br /> This property can be simplified by saying that a variable's scope is equal to the nesting level it is in. That is, a variable at global scope is visible globally to all functions. A variable at local scope is visible to all code blocks &quot;beneath&quot; its nesting level. For example:<br /> <br /> &lt;pawn&gt;Function1()<br /> {<br /> int A;<br /> <br /> if (A)<br /> {<br /> A = 5;<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> The above code is valid since A's scope extends throughout the function. The following code, however, is not valid:<br /> &lt;pawn&gt;<br /> Function1()<br /> {<br /> int A;<br /> <br /> if (A)<br /> {<br /> new B = 5;<br /> }<br /> <br /> B = 5;<br /> }&lt;/pawn&gt;<br /> <br /> Notice that &lt;tt&gt;B&lt;/tt&gt; is declared in a new code block. That means &lt;tt&gt;B&lt;/tt&gt; is only accessible to that code block (and all sub-blocks nested within). As soon as the code block terminates, &lt;tt&gt;B&lt;/tt&gt; is no longer valid.<br /> <br /> <br /> =Dynamic Arrays=<br /> Dynamic arrays are arrays which don't have a hardcoded size. For example:<br /> <br /> &lt;pawn&gt;Function1(size)<br /> {<br /> int array[size];<br /> <br /> /* Code */<br /> }&lt;/pawn&gt;<br /> <br /> Dynamic arrays can have any expression as their size as long as the expression evaluates to a number larger than 0. Like normal arrays, SourcePawn does not know the array size after it is created; you have to save it if you want it later.<br /> <br /> Dynamic arrays are only valid at the local scope level, since code cannot exist globally.<br /> <br /> =Extended Variable Declarations=<br /> Variables can be declared in more ways than simply &lt;tt&gt;new&lt;/tt&gt;.<br /> <br /> ==decl==<br /> ===Purpose===<br /> By default, all variables in Pawn are initialized to zero. If there is an explicit initializer, the variable is initialized to the expression after the &lt;tt&gt;=&lt;/tt&gt; token. At a local scope, this can be a run-time expense. The &lt;tt&gt;decl&lt;/tt&gt; keyword (which is only valid at local scope) was introduced to let users decide if they want variables initialized or not.<br /> <br /> Note: &lt;tt&gt;decl&lt;/tt&gt; should not be used on single cell variables. There is almost never any benefit.<br /> <br /> ===Explanation===<br /> For example:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> int d;<br /> char blah[512];<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> In this code, &lt;tt&gt;c&lt;/tt&gt; is equal to 5 and &lt;tt&gt;d&lt;/tt&gt; is equal to 0. The run-time expense of this initialization is negligible. However, &lt;tt&gt;blah&lt;/tt&gt; is a large array, and the expense of initializing the entire array to 0s could be detrimental in certain situations. <br /> <br /> Note that &lt;tt&gt;blah&lt;/tt&gt; does not need to be zeroed. In between being declared with &lt;tt&gt;new&lt;/tt&gt; and stored with &lt;tt&gt;Format()&lt;/tt&gt;, &lt;tt&gt;blah&lt;/tt&gt; is never loaded or read. Thus this code would be more efficiently written as:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> int d;<br /> decl String:blah[512];<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> ===Caveats===<br /> The downside to &lt;tt&gt;decl&lt;/tt&gt; is that it means its variables will start with &quot;garbage&quot; contents. For example, if we were to use:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> int d;<br /> decl String:blah[512];<br /> <br /> PrintToServer(&quot;%s&quot;, blah);<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> This code may crash the server, because &lt;tt&gt;blah&lt;/tt&gt; may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> decl d;<br /> decl String:blah[512];<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> The value of &lt;tt&gt;d&lt;/tt&gt; is now undefined. It could be any value, negative or positive. <br /> <br /> Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:<br /> &lt;pawn&gt;<br /> decl String:blah[512];<br /> <br /> blah[0] = '\0';<br /> &lt;/pawn&gt;<br /> <br /> ===Golden Rules===<br /> *'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''<br /> *'''Do not prematurely optimize.''' Likewise, there is no need to use &lt;tt&gt;decl&lt;/tt&gt; on non-arrays, because there is no added expense for initializing a single cell value.<br /> <br /> ===Notes===<br /> This example is NOT as efficient as a &lt;tt&gt;decl&lt;/tt&gt;:<br /> &lt;pawn&gt;<br /> char blah[512] = &quot;a&quot;;<br /> &lt;/pawn&gt;<br /> <br /> Even though the string is only one character, the &lt;tt&gt;new&lt;/tt&gt; operator guarantees the rest of the array will be zeroed as well.<br /> <br /> Also note, it is valid to explicitly initialize a &lt;tt&gt;decl&lt;/tt&gt; '''ONLY''' with strings:<br /> &lt;pawn&gt;decl String:blah[512] = &quot;a&quot;;&lt;/pawn&gt;<br /> <br /> However, any other tag will fail to compile, because the purpose of &lt;tt&gt;decl&lt;/tt&gt; is to avoid any initialization:<br /> &lt;pawn&gt;decl Float:blah[512] = {1.0};&lt;/pawn&gt;<br /> <br /> ==static==<br /> The &lt;tt&gt;static&lt;/tt&gt; keyword is available at global and local scope. It has different meanings in each.<br /> <br /> ===Global static===<br /> A global static variable can only be accessed from within the same file. For example:<br /> <br /> &lt;pawn&gt;//file1.inc<br /> static float g_value1 = 0.15f;<br /> <br /> //file2.inc<br /> static float g_value2 = 0.15f;&lt;/pawn&gt;<br /> <br /> If a plugin includes both of these files, it will not be able to use either &lt;tt&gt;g_value1&lt;/tt&gt; or &lt;tt&gt;g_value2&lt;/tt&gt;. This is a simple information hiding mechanism, and is similar to declaring member variables as &lt;tt&gt;private&lt;/tt&gt; in languages like C++, Java, or C#.<br /> <br /> ===Local static===<br /> A local static variable is a global variable that is only visible from its local lexical scope. For example:<br /> <br /> &lt;pawn&gt;<br /> int MyFunction(inc)<br /> {<br /> static counter = -1;<br /> <br /> counter += inc;<br /> <br /> return counter;<br /> }&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;counter&lt;/tt&gt; is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time &lt;tt&gt;MyFunction&lt;/tt&gt; runs, the &lt;tt&gt;counter&lt;/tt&gt; variable and its storage in memory is the same.<br /> <br /> Take this example:<br /> &lt;pawn&gt;MyFunction(5);<br /> MyFunction(6);<br /> MyFunction(10);&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;counter&lt;/tt&gt; will be &lt;tt&gt;-1 + 5 + 6 + 10&lt;/tt&gt;, or &lt;tt&gt;20&lt;/tt&gt;, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then &lt;tt&gt;static&lt;/tt&gt; is usually not a good idea unless your code is re-entrant. <br /> <br /> The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.<br /> <br /> Note that statics can exist in any local scope:<br /> <br /> &lt;pawn&gt;<br /> int MyFunction(inc)<br /> {<br /> if (inc &gt; 0)<br /> {<br /> static counter;<br /> return (counter += inc);<br /> }<br /> return -1;<br /> }&lt;/pawn&gt;<br /> <br /> [[Category:SourceMod Scripting]]<br /> <br /> {{LanguageSwitch}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Introduction_to_SourcePawn_1.7&diff=10055 2015-11-15T18:35:46Z

<p>Xerox8521: /* While Loops */</p> <hr /> <div>This guide is designed to give you a very basic overview to fundamentals of scripting in SourcePawn. [[Pawn]] is a &quot;scripting&quot; language used to embed functionality in other programs. That means it is not a standalone language, like C++ or Java, and its details will differ based on the application. SourcePawn is the version of Pawn used in [[SourceMod]].<br /> <br /> This guide does not tell you how to write SourceMod plugins; it is intended as an overview of the syntax and semantics of the language instead. Read the separate article, [[Introduction to SourceMod Plugins]] for SourceMod API specifics. <br /> <br /> =Non-Programmer Intro=<br /> This section is intended for non-programmers. If you're still confused, you may want to pick up a book on another language, such as PHP, Python, or Java, to get a better idea of what programming is like.<br /> <br /> ==Symbols/Keywords==<br /> A symbol is a series of letters, numbers, and/or underscores, that uniquely represents something. Symbols are case-sensitive, and usually start with a letter.<br /> <br /> There are a few reserved symbols that have special meaning. For example, &lt;tt&gt;if&lt;/tt&gt;, &lt;tt&gt;for&lt;/tt&gt;, and &lt;tt&gt;return&lt;/tt&gt; are special constructs in the language that will explained later. They cannot be used as symbol names.<br /> <br /> ==Variables==<br /> There a few important constructs you should know before you begin to script. The first is a '''variable'''. A variable is a symbol, or name, that holds data. For example, the variable &quot;a&quot; could hold the number &quot;2&quot;, &quot;16&quot;, &quot;0&quot;, et cetera. Since a variable holds data, it also allocates the memory needed to store that data.<br /> <br /> In addition to a name, variables have a '''type'''. A type tells the program how to interpret the data, and how much memory the data will use. Pawn has three types of data that are most commonly used:<br /> * Integers, using the &lt;tt&gt;int&lt;/tt&gt; type. Integer types may store a whole number from -2147483648 to 2147483647.<br /> * Floats, using the &lt;tt&gt;float&lt;/tt&gt; type. Float types may store fractional numbers in a huge range, though they are not as precise as integers.<br /> * Characters, using the &lt;tt&gt;char&lt;/tt&gt; type. Character types store one byte of character information, typically an [http://www.asciitable.com/ ASCII] character.<br /> * Booleans, using the &lt;tt&gt;bool&lt;/tt&gt; type. Booleans store either true or false.<br /> <br /> Example of creating variables and assigning values:<br /> <br /> &lt;pawn&gt;int money = 5400;<br /> float percent = 67.3;<br /> bool enabled = false;<br /> &lt;/pawn&gt;<br /> <br /> ==Functions==<br /> The next important concept is '''functions'''. Functions are symbols or names that perform an action. When you invoke, or call them, they carry out a specific sequence of code and then return a result. There are a few types of functions, but every function is activated the same way. Example:<br /> <br /> &lt;pawn&gt;<br /> show(56); // Calls the &quot;show&quot; function, and gives it the number 56.<br /> enable(); // Calls the &quot;s &quot;enable&quot; function with no values.<br /> bool visible = show(a); //Calls the &quot;show&quot; function, stores its result in a variable.<br /> &lt;/pawn&gt;<br /> <br /> Every piece of data passed to a function is called a '''parameter'''. A function can have any number of parameters (there is a &quot;reasonable&quot; limit of 32 in SourceMod). Parameters will be explained further in the article.<br /> <br /> ==Comments==<br /> Note any text that appears after a &quot;//&quot; is considered a &quot;comment&quot; and is not actual code. There are two comment styles:<br /> *&lt;tt&gt;//&lt;/tt&gt; - Double slash, everything following on that line is ignored.<br /> *&lt;tt&gt;/* */&lt;/tt&gt; - Multi-line comment, everything in between the asterisks is ignored. You cannot nest these.<br /> <br /> <br /> ==Block Coding==<br /> The next concept is block coding. You can group code into &quot;blocks&quot; separated by { and }. This effectively makes one large block of code act as one statement. For example:<br /> <br /> &lt;pawn&gt;{<br /> here;<br /> is;<br /> some;<br /> code;<br /> }&lt;/pawn&gt;<br /> <br /> Block coding using braces is used everywhere in programming. Blocks of code can be nested within each other. It is a good idea to adapt a consistent and readable indentation style early on to prevent spaghetti-looking code.<br /> <br /> =Language Paradigms=<br /> Pawn may seem similar to other languages, like C, but it has fundamental differences. It is not important that you immediately understand these differences, but they may be helpful if you're familiar with another language already.<br /> *'''Pawn is sort of typed.''' Before SourceMod 1.7, Pawn did not have types. Older code and older natives will reflect this by using tags and the &lt;tt&gt;new&lt;/tt&gt; keyword. As of SourceMod 1.7, we recommend that all code use types. For more information see [[SourcePawn Transitional Syntax]].<br /> *'''Pawn is not garbage collected.''' Pawn, as a language, has no built-in memory allocation, and thus has no garbage. If a function allocates memory, you may be responsible for freeing it.<br /> *'''Pawn is not object oriented.''' Pawn does not have structs or objects. As of SourceMod 1.7, it has limited sugaring for treating some data types as objects, but users cannot create their own objects or classes.<br /> *'''Pawn is single-threaded.''' As of this writing, Pawn is not thread safe. <br /> *'''Pawn is compiled.''' Pawn is compiled to an intermediate, machine-independent code, which is stored in a &quot;.smx&quot; file. When loading .smx files, SourceMod translates this code to machine code for the platform and CPU it's running on.<br /> <br /> Early language design decisions were made by ITB CompuPhase. It is designed for low-level embedded devices and is thus very small and very fast.<br /> <br /> =Variables=<br /> Pawn currently supports the following basic variable types:<br /> *&lt;tt&gt;bool&lt;/tt&gt; - true or false.<br /> *&lt;tt&gt;char&lt;/tt&gt; - an 8-bit ASCII character.<br /> *&lt;tt&gt;int&lt;/tt&gt; - a 32-bit signed integer.<br /> *&lt;tt&gt;float&lt;/tt&gt; - a 32-bit IEEE-754 floating point number.<br /> *&lt;tt&gt;Handle&lt;/tt&gt; - the base type of a SourceMod object<br /> <br /> Other types may exist when defined in include files - for example, enums create new types for named integers, and many types derive from &lt;tt&gt;Handle&lt;/tt&gt;.<br /> <br /> Strings, currently, are 0-terminated arrays of &lt;tt&gt;char&lt;/tt&gt;s. They're described a little further ahead.<br /> <br /> ==Declaration==<br /> Below we include some examples of variable declarations, both valid and invalid. Keep in mind that SourcePawn has recently added new syntax, and that's what's documented below. Older code may use older declaration syntax, which is no longer supported.<br /> <br /> &lt;pawn&gt;<br /> int a = 5;<br /> float b = 5.0;<br /> bool c = true;<br /> bool d = false;<br /> &lt;/pawn&gt;<br /> <br /> Invalid variable usage:<br /> &lt;pawn&gt;<br /> int a = 5.0; // Type mismatch. 5.0 is a float.<br /> float b = 5; // Type mismatch. 5 is an integer.<br /> &lt;/pawn&gt;<br /> <br /> If a variable is not assigned upon declaration, it will be set to 0. For example:<br /> &lt;pawn&gt;<br /> int a; // Set to 0<br /> float b; // Set to 0.0<br /> bool c; // Set to false<br /> &lt;/pawn&gt;<br /> <br /> ==Assignment==<br /> Variables can be re-assigned data after they are created. For example:<br /> &lt;pawn&gt;int a;<br /> float b;<br /> bool c;<br /> <br /> a = 5;<br /> b = 5.0;<br /> c = true;<br /> &lt;/pawn&gt;<br /> <br /> =Arrays=<br /> An array is a sequence of data in a list. Arrays are useful for storing multiple pieces of data in one variable, or mapping one type of data to another.<br /> <br /> ==Declaration==<br /> An array is declared using brackets. Some examples of arrays:<br /> &lt;pawn&gt;<br /> int players[32]; // Stores 32 integers.<br /> float origin[3]; // Stores 3 floating point numbers<br /> &lt;/pawn&gt;<br /> <br /> By default, arrays are initialized to 0. You can assign them different default values, however:<br /> &lt;pawn&gt;<br /> int numbers[5] = {1, 2, 3, 4, 5}; // Stores 1, 2, 3, 4, 5.<br /> float origin[3] = {1.0, 2.0, 3.0}; // Stores 1.0, 2.0, 3.0.<br /> &lt;/pawn&gt;<br /> <br /> You can leave out the array size if you're going to pre-assign data to it. For example:<br /> &lt;pawn&gt;<br /> int numbers[] = {1, 3, 5, 7, 9};<br /> &lt;/pawn&gt;<br /> <br /> The compiler will automatically deduce that you intended an array of size 5.<br /> <br /> When array is declared with brackets after its name, Pawn considers that array to have a '''fixed size'''. The size of a fixed-size array is always known. Some arrays can be '''dynamically sized''', by putting the brackets before the name. For example,<br /> <br /> &lt;pawn&gt;<br /> int[] numbers = new int[MaxClients]<br /> &lt;/pawn&gt;<br /> <br /> This creates an array of size &lt;tt&gt;MaxClients&lt;/tt&gt;, which could be anything, so the size of the array is not known until the array is allocated.<br /> <br /> ==Usage==<br /> Using an array is just like using a normal variable. The only difference is the array must be '''indexed'''. Indexing an array means choosing the element which you wish to use.<br /> <br /> For example, here is an example of the above code using indexes:<br /> &lt;pawn&gt;<br /> int numbers[5];<br /> float origin[3];<br /> <br /> numbers[0] = 1;<br /> numbers[1] = 2;<br /> numbers[2] = 3;<br /> numbers[3] = 4;<br /> numbers[4] = 5;<br /> origin[0] = 1.0;<br /> origin[1] = 2.0;<br /> origin[2] = 3.0;<br /> &lt;/pawn&gt;<br /> <br /> Note that the '''index''' is what's in between the brackets. The index always starts from 0. That is, if an array has N elements, its valid indexes are from 0 to N-1. Accessing the data at these indexes works like a normal variable.<br /> <br /> Using an incorrect index will cause an error. For example:<br /> &lt;pawn&gt;<br /> int numbers[5];<br /> <br /> numbers[5] = 20;&lt;/pawn&gt;<br /> <br /> This may look correct, but 5 is not a valid index. The highest valid index is 4.<br /> <br /> You can use any expression as an index. For example:<br /> &lt;pawn&gt;int a, numbers[5];<br /> <br /> a = 1; // Set a = 1<br /> numbers[a] = 4; // Set numbers[1] = 4<br /> numbers[numbers[a]] = 2; // Set numbers[4] = 2<br /> &lt;/pawn&gt;<br /> <br /> Expressions will be discussed in depth later in the article.<br /> <br /> =Strings=<br /> Strings are a construct for storing text (or even raw binary data). A string is just an array of characters, except that the final character must be 0 (called the null terminator). Without a null terminator, Pawn would not know where to stop reading the string. All strings are [http://en.wikipedia.org/wiki/UTF-8 UTF-8] in SourcePawn.<br /> <br /> In general, you must have an idea of how large a string will be before you store it. SourcePawn does not yet have the capability of pre-determining storage space for strings.<br /> <br /> ==Usage==<br /> Strings are usually declared as arrays. For example:<br /> &lt;pawn&gt;<br /> char message[] = &quot;Hello!&quot;;<br /> char clams[6] = &quot;Clams&quot;;<br /> &lt;/pawn&gt;<br /> <br /> These are equivalent to doing:<br /> &lt;pawn&gt;<br /> char message[7];<br /> char clams[6];<br /> <br /> message[0] = 'H';<br /> message[1] = 'e';<br /> message[2] = 'l';<br /> message[3] = 'l';<br /> message[4] = 'o';<br /> message[5] = '!';<br /> message[6] = 0;<br /> clams[0] = 'C';<br /> clams[1] = 'l';<br /> clams[2] = 'a';<br /> clams[3] = 'm';<br /> clams[4] = 's';<br /> clams[5] = 0;<br /> &lt;/pawn&gt;<br /> <br /> Although strings are rarely initialized in this manner, it is very important to remember the concept of the null terminator, which signals the end of a string. The compiler, and most SourceMod functions will automatically null-terminate for you, so it is mainly important when manipulating strings directly.<br /> <br /> Note that a string is enclosed in double-quotes, but a character is enclosed in single quotes.<br /> <br /> ==Characters==<br /> A character of text can be used in either a String or a cell. For example:<br /> &lt;pawn&gt;char text[] = &quot;Crab&quot;;<br /> char clam;<br /> <br /> clam = 'D'; //Set clam to 'D'<br /> text[0] = 'A'; //Change the 'C' to 'A', it is now 'Arab'<br /> clam = text[0]; //Set clam to 'A'<br /> text[1] = clam; //Change the 'r' to 'A', is is now 'AAab'<br /> &lt;/pawn&gt;<br /> <br /> What you can't do is mix character arrays with strings. The internal storage is different. For example:<br /> &lt;pawn&gt;<br /> int clams[] = &quot;Clams&quot;; // Invalid.<br /> int clams[] = {'C', 'l', 'a', 'm', 's', 0}; // Valid, but NOT A STRING.<br /> &lt;/pawn&gt;<br /> <br /> =Functions=<br /> Functions, as stated before, are isolated blocks of code that perform an action. They can be invoked, or '''called''', with '''parameters''' that give specific options.<br /> <br /> There are two types of ways functions are called:<br /> *'''direct call''' - You specifically call a function in your code.<br /> *'''callback''' - The application calls a function in your code, as if it were an event trigger.<br /> <br /> There are six types of functions:<br /> *'''native''': A direct, internal function provided by the application.<br /> *'''public''': A callback function that is visible to the application and other scripts.<br /> *'''normal''': A normal function that only you can call.<br /> *'''static''': The scope of this function is restricted to the current file, can be used in combination with stock.<br /> *'''stock''': A normal function provided by an include file. If unused, it won't be compiled.<br /> *'''forward''': This function is a global event provided by the application. If you implement it, it will be a callback.<br /> <br /> All code in Pawn must exist in functions. This is in contrast to languages like PHP, Perl, and Python which let you write global code. That is because Pawn is a callback-based language: it responds to actions from a parent application, and functions must be written to handle those actions. Although our examples often contain free-floating code, this is purely for demonstration purposes. Free-floating code in our examples implies the code is part of some function.<br /> <br /> ==Declaration==<br /> Unlike variables, functions do not need to be declared before you use them. Functions have two pieces, the '''signature''' and the '''body'''. The signature contains the name of your function and the parameters it will accept. The body is the contents of its code.<br /> <br /> Example of a function:<br /> &lt;pawn&gt;<br /> int AddTwoNumbers(int first, int second)<br /> {<br /> int sum = first + second;<br /> return sum;<br /> }&lt;/pawn&gt;<br /> <br /> This is a simple function. The prototype is this line:<br /> &lt;pawn&gt;int AddTwoNumbers(int first, int second)&lt;/pawn&gt;<br /> <br /> Broken down, it means:<br /> *&lt;tt&gt;int&lt;/tt&gt; - Return value type (integer).<br /> *&lt;tt&gt;AddTwoNumbers&lt;/tt&gt; - Name of the function.<br /> *&lt;tt&gt;int first&lt;/tt&gt; - First parameter, an integer.<br /> *&lt;tt&gt;int second&lt;/tt&gt; - Second parameter, an integer.<br /> <br /> The body is a block of code. It creates a new variable, called &lt;tt&gt;sum&lt;/tt&gt;, and assigns it the value of the two parameters added together (more on expressions later). The important thing to notice is the &lt;tt&gt;return&lt;/tt&gt; statement, which tells the function to end and return a value to the caller of the function. All functions return something on completion, unless they return a special type called &lt;tt&gt;void&lt;/tt&gt;.<br /> <br /> A function can accept any type of input, and it can return any non-array type.<br /> <br /> You can, of course, pass variables to functions:<br /> &lt;pawn&gt;int numbers[3] = {1, 2, 0};<br /> <br /> numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);&lt;/pawn&gt;<br /> <br /> Note that cells are passed '''by value'''. That is, their value cannot be changed by the function. For example:<br /> &lt;pawn&gt;int a = 5;<br /> <br /> ChangeValue(a);<br /> <br /> ChangeValue(b)<br /> {<br /> b = 5;<br /> }&lt;/pawn&gt;<br /> <br /> This code would not change the value of &lt;tt&gt;a&lt;/tt&gt;. That is because a copy of the value in &lt;tt&gt;a&lt;/tt&gt; is passed instead of &lt;tt&gt;a&lt;/tt&gt; itself. <br /> <br /> More examples of functions will be provided throughout the article.<br /> <br /> ==Publics==<br /> Public functions are used to implement callbacks. You should not create a public function unless it is specifically implementing a callback. For example, here are two callbacks from &lt;tt&gt;sourcemod.inc&lt;/tt&gt;:<br /> <br /> &lt;pawn&gt;forward void OnPluginStart();<br /> forward void OnClientDisconnected(int client);&lt;/pawn&gt;<br /> <br /> To implement and receive these two events, you would write functions as such:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> /* Code here */<br /> }<br /> <br /> public void OnClientDisconnected(int client)<br /> {<br /> /* Code here */<br /> }&lt;/pawn&gt;<br /> <br /> The '''public''' keyword signals to the parent application that it should attach the function to the appropriate forwarded event.<br /> <br /> ==Natives==<br /> Natives are builtin functions provided by SourceMod. You can call them as if they were a normal function. For example, SourceMod has the following function:<br /> <br /> &lt;pawn&gt;native float FloatRound(float num);&lt;/pawn&gt;<br /> <br /> It can be called like so:<br /> &lt;pawn&gt;int rounded = FloatRound(5.2); // rounded will be 5&lt;/pawn&gt;<br /> <br /> ==Array Parameters==<br /> You can pass arrays or Strings as parameters. It is important to note that these are passed '''by reference'''. That is, rather than making a copy of the data, the data is referenced directly. There is a simple way of explaining this more concretely.<br /> <br /> &lt;pawn&gt;<br /> int example[] = {1, 2, 3, 4, 5};<br /> <br /> ChangeArray(example, 2, 29);<br /> <br /> void ChangeArray(int[] array, int index, int value)<br /> {<br /> array[index] = value;<br /> }&lt;/pawn&gt;<br /> <br /> The function sets the given index in the array to a given value. When it is run on our example array, it changes index 2 to from the value 3 to 29. I.e.:<br /> &lt;pawn&gt;example[2] = 29;&lt;/pawn&gt;<br /> <br /> Note two important things here. First, arrays are not copied when they are passed to functions - they are passed ''by reference'', so the view of the array is consistent at all times. Second, the brackets changed position in our function signature. This is because our function accepts an array of any size, and since we don't know the size, we must use the dynamic array syntax.<br /> <br /> To prevent an array from being modified in a function, you can mark it as &lt;tt&gt;const&lt;/tt&gt;. This will raise an error on code that attempts to modify it. For example:<br /> <br /> &lt;pawn&gt;void CantChangeArray(const array[], int index, int value)<br /> {<br /> array[index] = value; //Won't compile<br /> }&lt;/pawn&gt;<br /> <br /> It is a good idea to use &lt;tt&gt;const&lt;/tt&gt; in array parameters if you know the array won't be modified; this can prevent coding mistakes.<br /> <br /> =Expressions=<br /> Expressions are exactly the same as they are in mathematics. They are groups of operators/symbols which evaluate to one piece of data. They are often parenthetical (comprised of parenthesis). They contain a strict &quot;order of operations.&quot; They can contain variables, functions, numbers, and expressions themselves can be nested inside other expressions, or even passed as parameters.<br /> <br /> The simplest expression is a single number. For example:<br /> &lt;pawn&gt;<br /> 0; //Returns the number 0<br /> (0); //Returns the number 0 as well<br /> &lt;/pawn&gt;<br /> <br /> Although expressions can return any value, they are also said to either return ''zero or non-zero''. In that sense, ''zero'' is ''false'', and ''non-zero'' is ''true''. For example, -1 is '''true''' in Pawn, since it is non-zero. Do not assume negative numbers are false.<br /> <br /> The order of operations for expressions is similar to C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Here are some example expressions:<br /> &lt;pawn&gt;<br /> 5 + 6; //Evaluates to 11<br /> 5 * 6 + 3; //Evaluates to 33<br /> 5 * (6 + 3); //Evaluates to 45<br /> 5.0 + 2.3; //Evaluates to 7.3<br /> (5 * 6) % 7; //Modulo operator, evaluates to 2<br /> (5 + 3) / 2 * 4 - 9; //Evaluates to -8<br /> &lt;/pawn&gt;<br /> <br /> As noted, expressions can contain variables, or even functions:<br /> &lt;pawn&gt;<br /> int a = 5 * 6;<br /> int b = a * 3; //Evaluates to 90<br /> int c = AddTwoNumbers(a, b) + (a * b);<br /> &lt;/pawn&gt;<br /> <br /> Note: String manipulation routines may be found in the string.inc file located in the include subdirectory. They may be browsed through the [http://docs.sourcemod.net/api/ API Reference] as well.<br /> <br /> ==Operators==<br /> There are a few extra helpful operators in Pawn. The first set simplifies self-aggregation expressions. For example:<br /> &lt;pawn&gt;int a = 5;<br /> <br /> a = a + 5;&lt;/pawn&gt;<br /> <br /> Can be rewritten as:<br /> &lt;pawn&gt;int a = 5;<br /> a += 5;&lt;/pawn&gt;<br /> <br /> This is true of the following operators in Pawn:<br /> *Four-function: *, /, -, +<br /> *Bit-wise: |, &amp;, ^, ~, &lt;&lt;, &gt;&gt;<br /> <br /> Additionally, there are increment/decrement operators:<br /> &lt;pawn&gt;a = a + 1;<br /> a = a - 1;&lt;/pawn&gt;<br /> <br /> Can be simplified as:<br /> &lt;pawn&gt;a++;<br /> a--;&lt;/pawn&gt;<br /> <br /> As an advanced note, the ++ or -- can come before the variable (pre-increment, pre-decrement) or after the variable (post-increment, post-decrement). The difference is in how the rest of the expression containing them sees their result.<br /> <br /> * ''Pre:'' The variable is incremented before evaluation, and the rest of the expression sees the new value.<br /> * ''Post:'' The variable is incremented after evaluation, and the rest of the expression sees the old value.<br /> <br /> In other words, &lt;tt&gt;a++&lt;/tt&gt; evaluates to the value of &lt;tt&gt;a&lt;/tt&gt; while &lt;tt&gt;++a&lt;/tt&gt; evaluates to the value of &lt;tt&gt;a + 1&lt;/tt&gt;. In both cases &lt;tt&gt;a&lt;/tt&gt; is incremented by &lt;tt&gt;1&lt;/tt&gt;.<br /> <br /> For example:<br /> <br /> &lt;pawn&gt;int a = 5;<br /> int b = a++; // b = 5, a = 6 (1)<br /> int c = ++a; // a = 7, c = 7 (2)<br /> &lt;/pawn&gt;<br /> <br /> In (1) &lt;tt&gt;b&lt;/tt&gt; is assigned &lt;tt&gt;a&lt;/tt&gt;'s ''old'' value ''before'' it is incremented to &lt;tt&gt;6&lt;/tt&gt;, but in (2) &lt;tt&gt;c&lt;/tt&gt; is assigned &lt;tt&gt;a&lt;/tt&gt;'s ''int'' value ''after'' it is incremented to &lt;tt&gt;7&lt;/tt&gt;.<br /> <br /> ==Comparison Operators==<br /> There are six operators for comparing two values numerically, and the result is either true (non-zero) or false (zero):<br /> *&lt;tt&gt;a == b&lt;/tt&gt; - True if a and b have the same value.<br /> *&lt;tt&gt;a != b&lt;/tt&gt; - True if a and b have different values.<br /> *&lt;tt&gt;a &amp;gt; b&lt;/tt&gt; - True if a is greater than b<br /> *&lt;tt&gt;a &amp;gt;= b&lt;/tt&gt; - True if a is greater than or equal to b<br /> *&lt;tt&gt;a &amp;lt; b&lt;/tt&gt; - True if a is less than b<br /> *&lt;tt&gt;a &amp;lt;= b&lt;/tt&gt; - True if a is less than or equal to b<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> (1 != 3); //Evaluates to true because 1 is not equal to 3.<br /> (3 + 3 == 6); //Evaluates to true because 3+3 is 6.<br /> (5 - 2 &gt;= 4); //Evaluates to false because 3 is less than 4.<br /> &lt;/pawn&gt;<br /> <br /> Note that these operators do not work on arrays or strings. That is, you cannot compare either using &lt;tt&gt;==&lt;/tt&gt;.<br /> <br /> ==Truth Operators==<br /> These truth values can be combined using three boolean operators:<br /> *&lt;tt&gt;a &amp;&amp; b&lt;/tt&gt; - True if both a and b are true. False if a or b (or both) is false.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;&amp;&amp;&lt;/tt&gt; !! 0 !! 1<br /> |-<br /> ! 0<br /> | 0 || 0<br /> |-<br /> ! 1<br /> | 0 || 1<br /> |}<br /> *&lt;tt&gt;a || b&lt;/tt&gt; - True if a or b (or both) is true. False if both a and b are false.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;&lt;nowiki&gt;||&lt;/nowiki&gt;&lt;/tt&gt; !! 0 !! 1<br /> |-<br /> ! 0<br /> | 0 || 1<br /> |-<br /> ! 1<br /> | 1 || 1<br /> |}<br /> *&lt;tt&gt;!a&lt;/tt&gt; - True if a is false. False if a is true.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;!&lt;/tt&gt; !! 0 !! 1<br /> |- <br /> !<br /> | 1 || 0<br /> |}<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> (1 || 0); //Evaluates to true because the expression 1 is true<br /> (1 &amp;&amp; 0); //Evaluates to false because the expression 0 is false<br /> (!1 || 0); //Evaluates to false because !1 is false.<br /> &lt;/pawn&gt;<br /> <br /> ==Left/Right Values==<br /> Two important concepts are left-hand and right-hand values, or l-values and r-values. An l-value is what appears on the left-hand side of a variable assignment, and an r-value is what appears on the right side of a variable assignment.<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> int a = 5;&lt;/pawn&gt;<br /> <br /> In this example &lt;tt&gt;a&lt;/tt&gt; is an l-value and &lt;tt&gt;5&lt;/tt&gt; is an r-value.<br /> <br /> The rules:<br /> *'''Expressions are never l-values'''.<br /> *'''Variables are both l-values and r-values'''.<br /> <br /> =Conditionals=<br /> Conditional statements let you only run code if a certain condition is matched.<br /> <br /> ==If Statements==<br /> If statements test one or more conditions. For example:<br /> <br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code that will run if the expression was true */<br /> }&lt;/pawn&gt;<br /> <br /> They can be extended to handle more cases as well:<br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code */<br /> }<br /> else if (a == 6)<br /> {<br /> /* Code */<br /> }<br /> else if (a == 7)<br /> {<br /> /* Code */<br /> }&lt;/pawn&gt;<br /> <br /> You can also handle the case of no expression being matched. For example:<br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code */<br /> }<br /> else<br /> {<br /> /* Code that will run if no expressions were true */<br /> }&lt;/pawn&gt;<br /> <br /> ==Switch Statements==<br /> Switch statements are restricted if statements. They test one expression for a series of possible values. For example:<br /> <br /> &lt;pawn&gt;<br /> switch (a)<br /> {<br /> case 5:<br /> {<br /> /* code */<br /> }<br /> case 6:<br /> {<br /> /* code */<br /> }<br /> case 7:<br /> {<br /> /* code */<br /> }<br /> case 8, 9, 10:<br /> {<br /> /* Code */<br /> }<br /> default:<br /> {<br /> /* will run if no case matched */<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> Unlike some other languages, switches are not fall-through. That is, multiple cases will never be run. When a case matches its code is executed, and the switch is then immediately terminated.<br /> <br /> =Loops=<br /> Loops allow you to conveniently repeat a block of code while a given condition remains true. <br /> <br /> ==For Loops==<br /> For loops are loops which have four parts:<br /> *The '''initialization''' statement - run once before the first loop.<br /> *The '''condition''' statement - checks whether the next loop should run, including the first one. The loop terminates when this expression evaluates to false.<br /> *The '''iteration''' statement - run after each loop.<br /> *The '''body''' block - run each time the '''condition''' statement evaluates to true.<br /> <br /> &lt;pawn&gt;<br /> for ( /* initialization */ ; /* condition */ ; /* iteration */ )<br /> {<br /> /* body */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> A simple example is a function to sum an array:<br /> &lt;pawn&gt;<br /> int array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};<br /> int sum = SumArray(array, 10);<br /> <br /> int SumArray(const int array[], int count)<br /> {<br /> int total;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> total += array[i];<br /> }<br /> <br /> return total;<br /> }&lt;/pawn&gt;<br /> <br /> Broken down:<br /> *&lt;tt&gt;int i = 0&lt;/tt&gt; - Creates a new variable for the loop, sets it to 0.<br /> *&lt;tt&gt;i &lt; count&lt;/tt&gt; - Only runs the loop if &lt;tt&gt;i&lt;/tt&gt; is less than &lt;tt&gt;count&lt;/tt&gt;. This ensures that the loop stops reading at a certain point. In this case, we don't want to read invalid indexes in the array.<br /> *&lt;tt&gt;i++&lt;/tt&gt; - Increments &lt;tt&gt;i&lt;/tt&gt; by one after each loop. This ensures that the loop doesn't run forever; eventually &lt;tt&gt;i&lt;/tt&gt; will become too big and the loop will end.<br /> <br /> Thus, the &lt;tt&gt;SumArray&lt;/tt&gt; function will loop through each valid index of the array, each time adding that value of the array into a sum. For loops are very common for processing arrays like this.<br /> <br /> ==While Loops==<br /> While loops are less common than for loops but are actually the simplest possible loop. They have only two parts:<br /> *The '''condition''' statement - checked before each loop. The loop terminates when it evaluates to false.<br /> *The '''body''' block - run each time through the loop.<br /> <br /> &lt;pawn&gt;<br /> while ( /* condition */ )<br /> {<br /> /* body */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> As long as the condition expression remains true, the loop will continue. Every for loop can be rewritten as a while loop:<br /> <br /> &lt;pawn&gt;<br /> /* initialization */<br /> while ( /* condition */ )<br /> {<br /> /* body */<br /> /* iteration */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> Here is the previous for loop rewritten as a while loop:<br /> &lt;pawn&gt;<br /> int SumArray(const int array[], int count)<br /> {<br /> int total, i;<br /> <br /> while (i &lt; count)<br /> {<br /> total += array[i];<br /> i++;<br /> }<br /> <br /> return total;<br /> }&lt;/pawn&gt;<br /> <br /> There are also '''do...while''' loops which are even less common. These are the same as while loops except the condition check is AFTER each loop, rather than before. This means the loop is always run at least once. For example:<br /> <br /> &lt;pawn&gt;<br /> do<br /> {<br /> /* body */<br /> }<br /> while ( /* condition */ );<br /> &lt;/pawn&gt;<br /> <br /> ==Loop Control==<br /> There are two cases in which you want to selectively control a loop:<br /> *'''skipping''' one iteration of the loop but continuing as normal, or;<br /> *'''breaking''' the loop entirely before it's finished.<br /> <br /> Let's say you have a function which takes in an array and searches for a matching number. You want it to stop once the number is found:<br /> &lt;pawn&gt;<br /> /**<br /> * Returns the array index where the value is, or -1 if not found.<br /> */<br /> SearchInArray(const array[], count, value)<br /> {<br /> int index = -1;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> if (array[i] == value)<br /> {<br /> index = i;<br /> break;<br /> }<br /> }<br /> <br /> return index;<br /> }&lt;/pawn&gt;<br /> <br /> Certainly, this function could simply &lt;tt&gt;return i&lt;/tt&gt; instead, but the example shows how &lt;tt&gt;break&lt;/tt&gt; will terminate the loop.<br /> <br /> Similarly, the &lt;tt&gt;continue&lt;/tt&gt; keyword skips an iteration of a loop. For example, let's say we wanted to sum all even numbers:<br /> &lt;pawn&gt;<br /> int SumEvenNumbers(const array[], count)<br /> {<br /> int sum;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> /* If divisibility by 2 is 1, we know it's odd */<br /> if (array[i] % 2 == 1)<br /> {<br /> /* Skip the rest of this loop iteration */<br /> continue;<br /> }<br /> sum += array[i];<br /> }<br /> <br /> return sum;<br /> }&lt;/pawn&gt;<br /> <br /> =Scope=<br /> Scope refers to the '''visibility''' of code. That is, code at one level may not be &quot;visible&quot; to code at another level. For example:<br /> <br /> &lt;pawn&gt;<br /> int A, B, C;<br /> <br /> Function1()<br /> {<br /> int B;<br /> <br /> Function2();<br /> }<br /> <br /> Function2()<br /> {<br /> int C;<br /> }&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;A&lt;/tt&gt;, &lt;tt&gt;B&lt;/tt&gt;, and &lt;tt&gt;C&lt;/tt&gt; exist at '''global scope'''. They can be seen by any function. However, the &lt;tt&gt;B&lt;/tt&gt; in &lt;tt&gt;Function1&lt;/tt&gt; is not the same variable as the &lt;tt&gt;B&lt;/tt&gt; at the global level. Instead, it is at '''local scope''', and is thus a '''local variable'''.<br /> <br /> Similarly, &lt;tt&gt;Function1&lt;/tt&gt; and &lt;tt&gt;Function2&lt;/tt&gt; know nothing about each other's variables.<br /> <br /> Not only is the variable private to &lt;tt&gt;Function1&lt;/tt&gt;, but it is re-created each time the function is invoked. Imagine this:<br /> &lt;pawn&gt;<br /> Function1()<br /> {<br /> int B;<br /> <br /> Function1();<br /> }&lt;/pawn&gt;<br /> <br /> In the above example, &lt;tt&gt;Function1&lt;/tt&gt; calls itself. Of course, this is infinite recursion (a bad thing), but the idea is that each time the function runs, there is a new copy of &lt;tt&gt;B&lt;/tt&gt;. When the function ends, &lt;tt&gt;B&lt;/tt&gt; is destroyed, and the value is lost.<br /> <br /> This property can be simplified by saying that a variable's scope is equal to the nesting level it is in. That is, a variable at global scope is visible globally to all functions. A variable at local scope is visible to all code blocks &quot;beneath&quot; its nesting level. For example:<br /> <br /> &lt;pawn&gt;Function1()<br /> {<br /> int A;<br /> <br /> if (A)<br /> {<br /> A = 5;<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> The above code is valid since A's scope extends throughout the function. The following code, however, is not valid:<br /> &lt;pawn&gt;<br /> Function1()<br /> {<br /> int A;<br /> <br /> if (A)<br /> {<br /> new B = 5;<br /> }<br /> <br /> B = 5;<br /> }&lt;/pawn&gt;<br /> <br /> Notice that &lt;tt&gt;B&lt;/tt&gt; is declared in a new code block. That means &lt;tt&gt;B&lt;/tt&gt; is only accessible to that code block (and all sub-blocks nested within). As soon as the code block terminates, &lt;tt&gt;B&lt;/tt&gt; is no longer valid.<br /> <br /> <br /> =Dynamic Arrays=<br /> Dynamic arrays are arrays which don't have a hardcoded size. For example:<br /> <br /> &lt;pawn&gt;Function1(size)<br /> {<br /> int array[size];<br /> <br /> /* Code */<br /> }&lt;/pawn&gt;<br /> <br /> Dynamic arrays can have any expression as their size as long as the expression evaluates to a number larger than 0. Like normal arrays, SourcePawn does not know the array size after it is created; you have to save it if you want it later.<br /> <br /> Dynamic arrays are only valid at the local scope level, since code cannot exist globally.<br /> <br /> =Extended Variable Declarations=<br /> Variables can be declared in more ways than simply &lt;tt&gt;new&lt;/tt&gt;.<br /> <br /> ==decl==<br /> ===Purpose===<br /> By default, all variables in Pawn are initialized to zero. If there is an explicit initializer, the variable is initialized to the expression after the &lt;tt&gt;=&lt;/tt&gt; token. At a local scope, this can be a run-time expense. The &lt;tt&gt;decl&lt;/tt&gt; keyword (which is only valid at local scope) was introduced to let users decide if they want variables initialized or not.<br /> <br /> Note: &lt;tt&gt;decl&lt;/tt&gt; should not be used on single cell variables. There is almost never any benefit.<br /> <br /> ===Explanation===<br /> For example:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> int d;<br /> char blah[512];<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> In this code, &lt;tt&gt;c&lt;/tt&gt; is equal to 5 and &lt;tt&gt;d&lt;/tt&gt; is equal to 0. The run-time expense of this initialization is negligible. However, &lt;tt&gt;blah&lt;/tt&gt; is a large array, and the expense of initializing the entire array to 0s could be detrimental in certain situations. <br /> <br /> Note that &lt;tt&gt;blah&lt;/tt&gt; does not need to be zeroed. In between being declared with &lt;tt&gt;new&lt;/tt&gt; and stored with &lt;tt&gt;Format()&lt;/tt&gt;, &lt;tt&gt;blah&lt;/tt&gt; is never loaded or read. Thus this code would be more efficiently written as:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> int d;<br /> decl String:blah[512];<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> ===Caveats===<br /> The downside to &lt;tt&gt;decl&lt;/tt&gt; is that it means its variables will start with &quot;garbage&quot; contents. For example, if we were to use:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> int d;<br /> decl String:blah[512];<br /> <br /> PrintToServer(&quot;%s&quot;, blah);<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> This code may crash the server, because &lt;tt&gt;blah&lt;/tt&gt; may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> decl d;<br /> decl String:blah[512];<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> The value of &lt;tt&gt;d&lt;/tt&gt; is now undefined. It could be any value, negative or positive. <br /> <br /> Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:<br /> &lt;pawn&gt;<br /> decl String:blah[512];<br /> <br /> blah[0] = '\0';<br /> &lt;/pawn&gt;<br /> <br /> ===Golden Rules===<br /> *'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''<br /> *'''Do not prematurely optimize.''' Likewise, there is no need to use &lt;tt&gt;decl&lt;/tt&gt; on non-arrays, because there is no added expense for initializing a single cell value.<br /> <br /> ===Notes===<br /> This example is NOT as efficient as a &lt;tt&gt;decl&lt;/tt&gt;:<br /> &lt;pawn&gt;<br /> char blah[512] = &quot;a&quot;;<br /> &lt;/pawn&gt;<br /> <br /> Even though the string is only one character, the &lt;tt&gt;new&lt;/tt&gt; operator guarantees the rest of the array will be zeroed as well.<br /> <br /> Also note, it is valid to explicitly initialize a &lt;tt&gt;decl&lt;/tt&gt; '''ONLY''' with strings:<br /> &lt;pawn&gt;decl String:blah[512] = &quot;a&quot;;&lt;/pawn&gt;<br /> <br /> However, any other tag will fail to compile, because the purpose of &lt;tt&gt;decl&lt;/tt&gt; is to avoid any initialization:<br /> &lt;pawn&gt;decl Float:blah[512] = {1.0};&lt;/pawn&gt;<br /> <br /> ==static==<br /> The &lt;tt&gt;static&lt;/tt&gt; keyword is available at global and local scope. It has different meanings in each.<br /> <br /> ===Global static===<br /> A global static variable can only be accessed from within the same file. For example:<br /> <br /> &lt;pawn&gt;//file1.inc<br /> static float g_value1 = 0.15f;<br /> <br /> //file2.inc<br /> static float g_value2 = 0.15f;&lt;/pawn&gt;<br /> <br /> If a plugin includes both of these files, it will not be able to use either &lt;tt&gt;g_value1&lt;/tt&gt; or &lt;tt&gt;g_value2&lt;/tt&gt;. This is a simple information hiding mechanism, and is similar to declaring member variables as &lt;tt&gt;private&lt;/tt&gt; in languages like C++, Java, or C#.<br /> <br /> ===Local static===<br /> A local static variable is a global variable that is only visible from its local lexical scope. For example:<br /> <br /> &lt;pawn&gt;<br /> int MyFunction(inc)<br /> {<br /> static counter = -1;<br /> <br /> counter += inc;<br /> <br /> return counter;<br /> }&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;counter&lt;/tt&gt; is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time &lt;tt&gt;MyFunction&lt;/tt&gt; runs, the &lt;tt&gt;counter&lt;/tt&gt; variable and its storage in memory is the same.<br /> <br /> Take this example:<br /> &lt;pawn&gt;MyFunction(5);<br /> MyFunction(6);<br /> MyFunction(10);&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;counter&lt;/tt&gt; will be &lt;tt&gt;-1 + 5 + 6 + 10&lt;/tt&gt;, or &lt;tt&gt;20&lt;/tt&gt;, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then &lt;tt&gt;static&lt;/tt&gt; is usually not a good idea unless your code is re-entrant. <br /> <br /> The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.<br /> <br /> Note that statics can exist in any local scope:<br /> <br /> &lt;pawn&gt;<br /> int MyFunction(inc)<br /> {<br /> if (inc &gt; 0)<br /> {<br /> static counter;<br /> return (counter += inc);<br /> }<br /> return -1;<br /> }&lt;/pawn&gt;<br /> <br /> [[Category:SourceMod Scripting]]<br /> <br /> {{LanguageSwitch}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=Introduction_to_SourcePawn_1.7&diff=10054 2015-11-15T18:35:19Z

<p>Xerox8521: /* For Loops */</p> <hr /> <div>This guide is designed to give you a very basic overview to fundamentals of scripting in SourcePawn. [[Pawn]] is a &quot;scripting&quot; language used to embed functionality in other programs. That means it is not a standalone language, like C++ or Java, and its details will differ based on the application. SourcePawn is the version of Pawn used in [[SourceMod]].<br /> <br /> This guide does not tell you how to write SourceMod plugins; it is intended as an overview of the syntax and semantics of the language instead. Read the separate article, [[Introduction to SourceMod Plugins]] for SourceMod API specifics. <br /> <br /> =Non-Programmer Intro=<br /> This section is intended for non-programmers. If you're still confused, you may want to pick up a book on another language, such as PHP, Python, or Java, to get a better idea of what programming is like.<br /> <br /> ==Symbols/Keywords==<br /> A symbol is a series of letters, numbers, and/or underscores, that uniquely represents something. Symbols are case-sensitive, and usually start with a letter.<br /> <br /> There are a few reserved symbols that have special meaning. For example, &lt;tt&gt;if&lt;/tt&gt;, &lt;tt&gt;for&lt;/tt&gt;, and &lt;tt&gt;return&lt;/tt&gt; are special constructs in the language that will explained later. They cannot be used as symbol names.<br /> <br /> ==Variables==<br /> There a few important constructs you should know before you begin to script. The first is a '''variable'''. A variable is a symbol, or name, that holds data. For example, the variable &quot;a&quot; could hold the number &quot;2&quot;, &quot;16&quot;, &quot;0&quot;, et cetera. Since a variable holds data, it also allocates the memory needed to store that data.<br /> <br /> In addition to a name, variables have a '''type'''. A type tells the program how to interpret the data, and how much memory the data will use. Pawn has three types of data that are most commonly used:<br /> * Integers, using the &lt;tt&gt;int&lt;/tt&gt; type. Integer types may store a whole number from -2147483648 to 2147483647.<br /> * Floats, using the &lt;tt&gt;float&lt;/tt&gt; type. Float types may store fractional numbers in a huge range, though they are not as precise as integers.<br /> * Characters, using the &lt;tt&gt;char&lt;/tt&gt; type. Character types store one byte of character information, typically an [http://www.asciitable.com/ ASCII] character.<br /> * Booleans, using the &lt;tt&gt;bool&lt;/tt&gt; type. Booleans store either true or false.<br /> <br /> Example of creating variables and assigning values:<br /> <br /> &lt;pawn&gt;int money = 5400;<br /> float percent = 67.3;<br /> bool enabled = false;<br /> &lt;/pawn&gt;<br /> <br /> ==Functions==<br /> The next important concept is '''functions'''. Functions are symbols or names that perform an action. When you invoke, or call them, they carry out a specific sequence of code and then return a result. There are a few types of functions, but every function is activated the same way. Example:<br /> <br /> &lt;pawn&gt;<br /> show(56); // Calls the &quot;show&quot; function, and gives it the number 56.<br /> enable(); // Calls the &quot;s &quot;enable&quot; function with no values.<br /> bool visible = show(a); //Calls the &quot;show&quot; function, stores its result in a variable.<br /> &lt;/pawn&gt;<br /> <br /> Every piece of data passed to a function is called a '''parameter'''. A function can have any number of parameters (there is a &quot;reasonable&quot; limit of 32 in SourceMod). Parameters will be explained further in the article.<br /> <br /> ==Comments==<br /> Note any text that appears after a &quot;//&quot; is considered a &quot;comment&quot; and is not actual code. There are two comment styles:<br /> *&lt;tt&gt;//&lt;/tt&gt; - Double slash, everything following on that line is ignored.<br /> *&lt;tt&gt;/* */&lt;/tt&gt; - Multi-line comment, everything in between the asterisks is ignored. You cannot nest these.<br /> <br /> <br /> ==Block Coding==<br /> The next concept is block coding. You can group code into &quot;blocks&quot; separated by { and }. This effectively makes one large block of code act as one statement. For example:<br /> <br /> &lt;pawn&gt;{<br /> here;<br /> is;<br /> some;<br /> code;<br /> }&lt;/pawn&gt;<br /> <br /> Block coding using braces is used everywhere in programming. Blocks of code can be nested within each other. It is a good idea to adapt a consistent and readable indentation style early on to prevent spaghetti-looking code.<br /> <br /> =Language Paradigms=<br /> Pawn may seem similar to other languages, like C, but it has fundamental differences. It is not important that you immediately understand these differences, but they may be helpful if you're familiar with another language already.<br /> *'''Pawn is sort of typed.''' Before SourceMod 1.7, Pawn did not have types. Older code and older natives will reflect this by using tags and the &lt;tt&gt;new&lt;/tt&gt; keyword. As of SourceMod 1.7, we recommend that all code use types. For more information see [[SourcePawn Transitional Syntax]].<br /> *'''Pawn is not garbage collected.''' Pawn, as a language, has no built-in memory allocation, and thus has no garbage. If a function allocates memory, you may be responsible for freeing it.<br /> *'''Pawn is not object oriented.''' Pawn does not have structs or objects. As of SourceMod 1.7, it has limited sugaring for treating some data types as objects, but users cannot create their own objects or classes.<br /> *'''Pawn is single-threaded.''' As of this writing, Pawn is not thread safe. <br /> *'''Pawn is compiled.''' Pawn is compiled to an intermediate, machine-independent code, which is stored in a &quot;.smx&quot; file. When loading .smx files, SourceMod translates this code to machine code for the platform and CPU it's running on.<br /> <br /> Early language design decisions were made by ITB CompuPhase. It is designed for low-level embedded devices and is thus very small and very fast.<br /> <br /> =Variables=<br /> Pawn currently supports the following basic variable types:<br /> *&lt;tt&gt;bool&lt;/tt&gt; - true or false.<br /> *&lt;tt&gt;char&lt;/tt&gt; - an 8-bit ASCII character.<br /> *&lt;tt&gt;int&lt;/tt&gt; - a 32-bit signed integer.<br /> *&lt;tt&gt;float&lt;/tt&gt; - a 32-bit IEEE-754 floating point number.<br /> *&lt;tt&gt;Handle&lt;/tt&gt; - the base type of a SourceMod object<br /> <br /> Other types may exist when defined in include files - for example, enums create new types for named integers, and many types derive from &lt;tt&gt;Handle&lt;/tt&gt;.<br /> <br /> Strings, currently, are 0-terminated arrays of &lt;tt&gt;char&lt;/tt&gt;s. They're described a little further ahead.<br /> <br /> ==Declaration==<br /> Below we include some examples of variable declarations, both valid and invalid. Keep in mind that SourcePawn has recently added new syntax, and that's what's documented below. Older code may use older declaration syntax, which is no longer supported.<br /> <br /> &lt;pawn&gt;<br /> int a = 5;<br /> float b = 5.0;<br /> bool c = true;<br /> bool d = false;<br /> &lt;/pawn&gt;<br /> <br /> Invalid variable usage:<br /> &lt;pawn&gt;<br /> int a = 5.0; // Type mismatch. 5.0 is a float.<br /> float b = 5; // Type mismatch. 5 is an integer.<br /> &lt;/pawn&gt;<br /> <br /> If a variable is not assigned upon declaration, it will be set to 0. For example:<br /> &lt;pawn&gt;<br /> int a; // Set to 0<br /> float b; // Set to 0.0<br /> bool c; // Set to false<br /> &lt;/pawn&gt;<br /> <br /> ==Assignment==<br /> Variables can be re-assigned data after they are created. For example:<br /> &lt;pawn&gt;int a;<br /> float b;<br /> bool c;<br /> <br /> a = 5;<br /> b = 5.0;<br /> c = true;<br /> &lt;/pawn&gt;<br /> <br /> =Arrays=<br /> An array is a sequence of data in a list. Arrays are useful for storing multiple pieces of data in one variable, or mapping one type of data to another.<br /> <br /> ==Declaration==<br /> An array is declared using brackets. Some examples of arrays:<br /> &lt;pawn&gt;<br /> int players[32]; // Stores 32 integers.<br /> float origin[3]; // Stores 3 floating point numbers<br /> &lt;/pawn&gt;<br /> <br /> By default, arrays are initialized to 0. You can assign them different default values, however:<br /> &lt;pawn&gt;<br /> int numbers[5] = {1, 2, 3, 4, 5}; // Stores 1, 2, 3, 4, 5.<br /> float origin[3] = {1.0, 2.0, 3.0}; // Stores 1.0, 2.0, 3.0.<br /> &lt;/pawn&gt;<br /> <br /> You can leave out the array size if you're going to pre-assign data to it. For example:<br /> &lt;pawn&gt;<br /> int numbers[] = {1, 3, 5, 7, 9};<br /> &lt;/pawn&gt;<br /> <br /> The compiler will automatically deduce that you intended an array of size 5.<br /> <br /> When array is declared with brackets after its name, Pawn considers that array to have a '''fixed size'''. The size of a fixed-size array is always known. Some arrays can be '''dynamically sized''', by putting the brackets before the name. For example,<br /> <br /> &lt;pawn&gt;<br /> int[] numbers = new int[MaxClients]<br /> &lt;/pawn&gt;<br /> <br /> This creates an array of size &lt;tt&gt;MaxClients&lt;/tt&gt;, which could be anything, so the size of the array is not known until the array is allocated.<br /> <br /> ==Usage==<br /> Using an array is just like using a normal variable. The only difference is the array must be '''indexed'''. Indexing an array means choosing the element which you wish to use.<br /> <br /> For example, here is an example of the above code using indexes:<br /> &lt;pawn&gt;<br /> int numbers[5];<br /> float origin[3];<br /> <br /> numbers[0] = 1;<br /> numbers[1] = 2;<br /> numbers[2] = 3;<br /> numbers[3] = 4;<br /> numbers[4] = 5;<br /> origin[0] = 1.0;<br /> origin[1] = 2.0;<br /> origin[2] = 3.0;<br /> &lt;/pawn&gt;<br /> <br /> Note that the '''index''' is what's in between the brackets. The index always starts from 0. That is, if an array has N elements, its valid indexes are from 0 to N-1. Accessing the data at these indexes works like a normal variable.<br /> <br /> Using an incorrect index will cause an error. For example:<br /> &lt;pawn&gt;<br /> int numbers[5];<br /> <br /> numbers[5] = 20;&lt;/pawn&gt;<br /> <br /> This may look correct, but 5 is not a valid index. The highest valid index is 4.<br /> <br /> You can use any expression as an index. For example:<br /> &lt;pawn&gt;int a, numbers[5];<br /> <br /> a = 1; // Set a = 1<br /> numbers[a] = 4; // Set numbers[1] = 4<br /> numbers[numbers[a]] = 2; // Set numbers[4] = 2<br /> &lt;/pawn&gt;<br /> <br /> Expressions will be discussed in depth later in the article.<br /> <br /> =Strings=<br /> Strings are a construct for storing text (or even raw binary data). A string is just an array of characters, except that the final character must be 0 (called the null terminator). Without a null terminator, Pawn would not know where to stop reading the string. All strings are [http://en.wikipedia.org/wiki/UTF-8 UTF-8] in SourcePawn.<br /> <br /> In general, you must have an idea of how large a string will be before you store it. SourcePawn does not yet have the capability of pre-determining storage space for strings.<br /> <br /> ==Usage==<br /> Strings are usually declared as arrays. For example:<br /> &lt;pawn&gt;<br /> char message[] = &quot;Hello!&quot;;<br /> char clams[6] = &quot;Clams&quot;;<br /> &lt;/pawn&gt;<br /> <br /> These are equivalent to doing:<br /> &lt;pawn&gt;<br /> char message[7];<br /> char clams[6];<br /> <br /> message[0] = 'H';<br /> message[1] = 'e';<br /> message[2] = 'l';<br /> message[3] = 'l';<br /> message[4] = 'o';<br /> message[5] = '!';<br /> message[6] = 0;<br /> clams[0] = 'C';<br /> clams[1] = 'l';<br /> clams[2] = 'a';<br /> clams[3] = 'm';<br /> clams[4] = 's';<br /> clams[5] = 0;<br /> &lt;/pawn&gt;<br /> <br /> Although strings are rarely initialized in this manner, it is very important to remember the concept of the null terminator, which signals the end of a string. The compiler, and most SourceMod functions will automatically null-terminate for you, so it is mainly important when manipulating strings directly.<br /> <br /> Note that a string is enclosed in double-quotes, but a character is enclosed in single quotes.<br /> <br /> ==Characters==<br /> A character of text can be used in either a String or a cell. For example:<br /> &lt;pawn&gt;char text[] = &quot;Crab&quot;;<br /> char clam;<br /> <br /> clam = 'D'; //Set clam to 'D'<br /> text[0] = 'A'; //Change the 'C' to 'A', it is now 'Arab'<br /> clam = text[0]; //Set clam to 'A'<br /> text[1] = clam; //Change the 'r' to 'A', is is now 'AAab'<br /> &lt;/pawn&gt;<br /> <br /> What you can't do is mix character arrays with strings. The internal storage is different. For example:<br /> &lt;pawn&gt;<br /> int clams[] = &quot;Clams&quot;; // Invalid.<br /> int clams[] = {'C', 'l', 'a', 'm', 's', 0}; // Valid, but NOT A STRING.<br /> &lt;/pawn&gt;<br /> <br /> =Functions=<br /> Functions, as stated before, are isolated blocks of code that perform an action. They can be invoked, or '''called''', with '''parameters''' that give specific options.<br /> <br /> There are two types of ways functions are called:<br /> *'''direct call''' - You specifically call a function in your code.<br /> *'''callback''' - The application calls a function in your code, as if it were an event trigger.<br /> <br /> There are six types of functions:<br /> *'''native''': A direct, internal function provided by the application.<br /> *'''public''': A callback function that is visible to the application and other scripts.<br /> *'''normal''': A normal function that only you can call.<br /> *'''static''': The scope of this function is restricted to the current file, can be used in combination with stock.<br /> *'''stock''': A normal function provided by an include file. If unused, it won't be compiled.<br /> *'''forward''': This function is a global event provided by the application. If you implement it, it will be a callback.<br /> <br /> All code in Pawn must exist in functions. This is in contrast to languages like PHP, Perl, and Python which let you write global code. That is because Pawn is a callback-based language: it responds to actions from a parent application, and functions must be written to handle those actions. Although our examples often contain free-floating code, this is purely for demonstration purposes. Free-floating code in our examples implies the code is part of some function.<br /> <br /> ==Declaration==<br /> Unlike variables, functions do not need to be declared before you use them. Functions have two pieces, the '''signature''' and the '''body'''. The signature contains the name of your function and the parameters it will accept. The body is the contents of its code.<br /> <br /> Example of a function:<br /> &lt;pawn&gt;<br /> int AddTwoNumbers(int first, int second)<br /> {<br /> int sum = first + second;<br /> return sum;<br /> }&lt;/pawn&gt;<br /> <br /> This is a simple function. The prototype is this line:<br /> &lt;pawn&gt;int AddTwoNumbers(int first, int second)&lt;/pawn&gt;<br /> <br /> Broken down, it means:<br /> *&lt;tt&gt;int&lt;/tt&gt; - Return value type (integer).<br /> *&lt;tt&gt;AddTwoNumbers&lt;/tt&gt; - Name of the function.<br /> *&lt;tt&gt;int first&lt;/tt&gt; - First parameter, an integer.<br /> *&lt;tt&gt;int second&lt;/tt&gt; - Second parameter, an integer.<br /> <br /> The body is a block of code. It creates a new variable, called &lt;tt&gt;sum&lt;/tt&gt;, and assigns it the value of the two parameters added together (more on expressions later). The important thing to notice is the &lt;tt&gt;return&lt;/tt&gt; statement, which tells the function to end and return a value to the caller of the function. All functions return something on completion, unless they return a special type called &lt;tt&gt;void&lt;/tt&gt;.<br /> <br /> A function can accept any type of input, and it can return any non-array type.<br /> <br /> You can, of course, pass variables to functions:<br /> &lt;pawn&gt;int numbers[3] = {1, 2, 0};<br /> <br /> numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);&lt;/pawn&gt;<br /> <br /> Note that cells are passed '''by value'''. That is, their value cannot be changed by the function. For example:<br /> &lt;pawn&gt;int a = 5;<br /> <br /> ChangeValue(a);<br /> <br /> ChangeValue(b)<br /> {<br /> b = 5;<br /> }&lt;/pawn&gt;<br /> <br /> This code would not change the value of &lt;tt&gt;a&lt;/tt&gt;. That is because a copy of the value in &lt;tt&gt;a&lt;/tt&gt; is passed instead of &lt;tt&gt;a&lt;/tt&gt; itself. <br /> <br /> More examples of functions will be provided throughout the article.<br /> <br /> ==Publics==<br /> Public functions are used to implement callbacks. You should not create a public function unless it is specifically implementing a callback. For example, here are two callbacks from &lt;tt&gt;sourcemod.inc&lt;/tt&gt;:<br /> <br /> &lt;pawn&gt;forward void OnPluginStart();<br /> forward void OnClientDisconnected(int client);&lt;/pawn&gt;<br /> <br /> To implement and receive these two events, you would write functions as such:<br /> <br /> &lt;pawn&gt;public void OnPluginStart()<br /> {<br /> /* Code here */<br /> }<br /> <br /> public void OnClientDisconnected(int client)<br /> {<br /> /* Code here */<br /> }&lt;/pawn&gt;<br /> <br /> The '''public''' keyword signals to the parent application that it should attach the function to the appropriate forwarded event.<br /> <br /> ==Natives==<br /> Natives are builtin functions provided by SourceMod. You can call them as if they were a normal function. For example, SourceMod has the following function:<br /> <br /> &lt;pawn&gt;native float FloatRound(float num);&lt;/pawn&gt;<br /> <br /> It can be called like so:<br /> &lt;pawn&gt;int rounded = FloatRound(5.2); // rounded will be 5&lt;/pawn&gt;<br /> <br /> ==Array Parameters==<br /> You can pass arrays or Strings as parameters. It is important to note that these are passed '''by reference'''. That is, rather than making a copy of the data, the data is referenced directly. There is a simple way of explaining this more concretely.<br /> <br /> &lt;pawn&gt;<br /> int example[] = {1, 2, 3, 4, 5};<br /> <br /> ChangeArray(example, 2, 29);<br /> <br /> void ChangeArray(int[] array, int index, int value)<br /> {<br /> array[index] = value;<br /> }&lt;/pawn&gt;<br /> <br /> The function sets the given index in the array to a given value. When it is run on our example array, it changes index 2 to from the value 3 to 29. I.e.:<br /> &lt;pawn&gt;example[2] = 29;&lt;/pawn&gt;<br /> <br /> Note two important things here. First, arrays are not copied when they are passed to functions - they are passed ''by reference'', so the view of the array is consistent at all times. Second, the brackets changed position in our function signature. This is because our function accepts an array of any size, and since we don't know the size, we must use the dynamic array syntax.<br /> <br /> To prevent an array from being modified in a function, you can mark it as &lt;tt&gt;const&lt;/tt&gt;. This will raise an error on code that attempts to modify it. For example:<br /> <br /> &lt;pawn&gt;void CantChangeArray(const array[], int index, int value)<br /> {<br /> array[index] = value; //Won't compile<br /> }&lt;/pawn&gt;<br /> <br /> It is a good idea to use &lt;tt&gt;const&lt;/tt&gt; in array parameters if you know the array won't be modified; this can prevent coding mistakes.<br /> <br /> =Expressions=<br /> Expressions are exactly the same as they are in mathematics. They are groups of operators/symbols which evaluate to one piece of data. They are often parenthetical (comprised of parenthesis). They contain a strict &quot;order of operations.&quot; They can contain variables, functions, numbers, and expressions themselves can be nested inside other expressions, or even passed as parameters.<br /> <br /> The simplest expression is a single number. For example:<br /> &lt;pawn&gt;<br /> 0; //Returns the number 0<br /> (0); //Returns the number 0 as well<br /> &lt;/pawn&gt;<br /> <br /> Although expressions can return any value, they are also said to either return ''zero or non-zero''. In that sense, ''zero'' is ''false'', and ''non-zero'' is ''true''. For example, -1 is '''true''' in Pawn, since it is non-zero. Do not assume negative numbers are false.<br /> <br /> The order of operations for expressions is similar to C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Here are some example expressions:<br /> &lt;pawn&gt;<br /> 5 + 6; //Evaluates to 11<br /> 5 * 6 + 3; //Evaluates to 33<br /> 5 * (6 + 3); //Evaluates to 45<br /> 5.0 + 2.3; //Evaluates to 7.3<br /> (5 * 6) % 7; //Modulo operator, evaluates to 2<br /> (5 + 3) / 2 * 4 - 9; //Evaluates to -8<br /> &lt;/pawn&gt;<br /> <br /> As noted, expressions can contain variables, or even functions:<br /> &lt;pawn&gt;<br /> int a = 5 * 6;<br /> int b = a * 3; //Evaluates to 90<br /> int c = AddTwoNumbers(a, b) + (a * b);<br /> &lt;/pawn&gt;<br /> <br /> Note: String manipulation routines may be found in the string.inc file located in the include subdirectory. They may be browsed through the [http://docs.sourcemod.net/api/ API Reference] as well.<br /> <br /> ==Operators==<br /> There are a few extra helpful operators in Pawn. The first set simplifies self-aggregation expressions. For example:<br /> &lt;pawn&gt;int a = 5;<br /> <br /> a = a + 5;&lt;/pawn&gt;<br /> <br /> Can be rewritten as:<br /> &lt;pawn&gt;int a = 5;<br /> a += 5;&lt;/pawn&gt;<br /> <br /> This is true of the following operators in Pawn:<br /> *Four-function: *, /, -, +<br /> *Bit-wise: |, &amp;, ^, ~, &lt;&lt;, &gt;&gt;<br /> <br /> Additionally, there are increment/decrement operators:<br /> &lt;pawn&gt;a = a + 1;<br /> a = a - 1;&lt;/pawn&gt;<br /> <br /> Can be simplified as:<br /> &lt;pawn&gt;a++;<br /> a--;&lt;/pawn&gt;<br /> <br /> As an advanced note, the ++ or -- can come before the variable (pre-increment, pre-decrement) or after the variable (post-increment, post-decrement). The difference is in how the rest of the expression containing them sees their result.<br /> <br /> * ''Pre:'' The variable is incremented before evaluation, and the rest of the expression sees the new value.<br /> * ''Post:'' The variable is incremented after evaluation, and the rest of the expression sees the old value.<br /> <br /> In other words, &lt;tt&gt;a++&lt;/tt&gt; evaluates to the value of &lt;tt&gt;a&lt;/tt&gt; while &lt;tt&gt;++a&lt;/tt&gt; evaluates to the value of &lt;tt&gt;a + 1&lt;/tt&gt;. In both cases &lt;tt&gt;a&lt;/tt&gt; is incremented by &lt;tt&gt;1&lt;/tt&gt;.<br /> <br /> For example:<br /> <br /> &lt;pawn&gt;int a = 5;<br /> int b = a++; // b = 5, a = 6 (1)<br /> int c = ++a; // a = 7, c = 7 (2)<br /> &lt;/pawn&gt;<br /> <br /> In (1) &lt;tt&gt;b&lt;/tt&gt; is assigned &lt;tt&gt;a&lt;/tt&gt;'s ''old'' value ''before'' it is incremented to &lt;tt&gt;6&lt;/tt&gt;, but in (2) &lt;tt&gt;c&lt;/tt&gt; is assigned &lt;tt&gt;a&lt;/tt&gt;'s ''int'' value ''after'' it is incremented to &lt;tt&gt;7&lt;/tt&gt;.<br /> <br /> ==Comparison Operators==<br /> There are six operators for comparing two values numerically, and the result is either true (non-zero) or false (zero):<br /> *&lt;tt&gt;a == b&lt;/tt&gt; - True if a and b have the same value.<br /> *&lt;tt&gt;a != b&lt;/tt&gt; - True if a and b have different values.<br /> *&lt;tt&gt;a &amp;gt; b&lt;/tt&gt; - True if a is greater than b<br /> *&lt;tt&gt;a &amp;gt;= b&lt;/tt&gt; - True if a is greater than or equal to b<br /> *&lt;tt&gt;a &amp;lt; b&lt;/tt&gt; - True if a is less than b<br /> *&lt;tt&gt;a &amp;lt;= b&lt;/tt&gt; - True if a is less than or equal to b<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> (1 != 3); //Evaluates to true because 1 is not equal to 3.<br /> (3 + 3 == 6); //Evaluates to true because 3+3 is 6.<br /> (5 - 2 &gt;= 4); //Evaluates to false because 3 is less than 4.<br /> &lt;/pawn&gt;<br /> <br /> Note that these operators do not work on arrays or strings. That is, you cannot compare either using &lt;tt&gt;==&lt;/tt&gt;.<br /> <br /> ==Truth Operators==<br /> These truth values can be combined using three boolean operators:<br /> *&lt;tt&gt;a &amp;&amp; b&lt;/tt&gt; - True if both a and b are true. False if a or b (or both) is false.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;&amp;&amp;&lt;/tt&gt; !! 0 !! 1<br /> |-<br /> ! 0<br /> | 0 || 0<br /> |-<br /> ! 1<br /> | 0 || 1<br /> |}<br /> *&lt;tt&gt;a || b&lt;/tt&gt; - True if a or b (or both) is true. False if both a and b are false.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;&lt;nowiki&gt;||&lt;/nowiki&gt;&lt;/tt&gt; !! 0 !! 1<br /> |-<br /> ! 0<br /> | 0 || 1<br /> |-<br /> ! 1<br /> | 1 || 1<br /> |}<br /> *&lt;tt&gt;!a&lt;/tt&gt; - True if a is false. False if a is true.<br /> {| border=&quot;1&quot; cellpadding=&quot;2&quot; cellspacing=&quot;0&quot; align=&quot;center&quot;<br /> ! &lt;tt&gt;!&lt;/tt&gt; !! 0 !! 1<br /> |- <br /> !<br /> | 1 || 0<br /> |}<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> (1 || 0); //Evaluates to true because the expression 1 is true<br /> (1 &amp;&amp; 0); //Evaluates to false because the expression 0 is false<br /> (!1 || 0); //Evaluates to false because !1 is false.<br /> &lt;/pawn&gt;<br /> <br /> ==Left/Right Values==<br /> Two important concepts are left-hand and right-hand values, or l-values and r-values. An l-value is what appears on the left-hand side of a variable assignment, and an r-value is what appears on the right side of a variable assignment.<br /> <br /> For example:<br /> &lt;pawn&gt;<br /> int a = 5;&lt;/pawn&gt;<br /> <br /> In this example &lt;tt&gt;a&lt;/tt&gt; is an l-value and &lt;tt&gt;5&lt;/tt&gt; is an r-value.<br /> <br /> The rules:<br /> *'''Expressions are never l-values'''.<br /> *'''Variables are both l-values and r-values'''.<br /> <br /> =Conditionals=<br /> Conditional statements let you only run code if a certain condition is matched.<br /> <br /> ==If Statements==<br /> If statements test one or more conditions. For example:<br /> <br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code that will run if the expression was true */<br /> }&lt;/pawn&gt;<br /> <br /> They can be extended to handle more cases as well:<br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code */<br /> }<br /> else if (a == 6)<br /> {<br /> /* Code */<br /> }<br /> else if (a == 7)<br /> {<br /> /* Code */<br /> }&lt;/pawn&gt;<br /> <br /> You can also handle the case of no expression being matched. For example:<br /> &lt;pawn&gt;<br /> if (a == 5)<br /> {<br /> /* Code */<br /> }<br /> else<br /> {<br /> /* Code that will run if no expressions were true */<br /> }&lt;/pawn&gt;<br /> <br /> ==Switch Statements==<br /> Switch statements are restricted if statements. They test one expression for a series of possible values. For example:<br /> <br /> &lt;pawn&gt;<br /> switch (a)<br /> {<br /> case 5:<br /> {<br /> /* code */<br /> }<br /> case 6:<br /> {<br /> /* code */<br /> }<br /> case 7:<br /> {<br /> /* code */<br /> }<br /> case 8, 9, 10:<br /> {<br /> /* Code */<br /> }<br /> default:<br /> {<br /> /* will run if no case matched */<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> Unlike some other languages, switches are not fall-through. That is, multiple cases will never be run. When a case matches its code is executed, and the switch is then immediately terminated.<br /> <br /> =Loops=<br /> Loops allow you to conveniently repeat a block of code while a given condition remains true. <br /> <br /> ==For Loops==<br /> For loops are loops which have four parts:<br /> *The '''initialization''' statement - run once before the first loop.<br /> *The '''condition''' statement - checks whether the next loop should run, including the first one. The loop terminates when this expression evaluates to false.<br /> *The '''iteration''' statement - run after each loop.<br /> *The '''body''' block - run each time the '''condition''' statement evaluates to true.<br /> <br /> &lt;pawn&gt;<br /> for ( /* initialization */ ; /* condition */ ; /* iteration */ )<br /> {<br /> /* body */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> A simple example is a function to sum an array:<br /> &lt;pawn&gt;<br /> int array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};<br /> int sum = SumArray(array, 10);<br /> <br /> int SumArray(const int array[], int count)<br /> {<br /> int total;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> total += array[i];<br /> }<br /> <br /> return total;<br /> }&lt;/pawn&gt;<br /> <br /> Broken down:<br /> *&lt;tt&gt;int i = 0&lt;/tt&gt; - Creates a new variable for the loop, sets it to 0.<br /> *&lt;tt&gt;i &lt; count&lt;/tt&gt; - Only runs the loop if &lt;tt&gt;i&lt;/tt&gt; is less than &lt;tt&gt;count&lt;/tt&gt;. This ensures that the loop stops reading at a certain point. In this case, we don't want to read invalid indexes in the array.<br /> *&lt;tt&gt;i++&lt;/tt&gt; - Increments &lt;tt&gt;i&lt;/tt&gt; by one after each loop. This ensures that the loop doesn't run forever; eventually &lt;tt&gt;i&lt;/tt&gt; will become too big and the loop will end.<br /> <br /> Thus, the &lt;tt&gt;SumArray&lt;/tt&gt; function will loop through each valid index of the array, each time adding that value of the array into a sum. For loops are very common for processing arrays like this.<br /> <br /> ==While Loops==<br /> While loops are less common than for loops but are actually the simplest possible loop. They have only two parts:<br /> *The '''condition''' statement - checked before each loop. The loop terminates when it evaluates to false.<br /> *The '''body''' block - run each time through the loop.<br /> <br /> &lt;pawn&gt;<br /> while ( /* condition */ )<br /> {<br /> /* body */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> As long as the condition expression remains true, the loop will continue. Every for loop can be rewritten as a while loop:<br /> <br /> &lt;pawn&gt;<br /> /* initialization */<br /> while ( /* condition */ )<br /> {<br /> /* body */<br /> /* iteration */<br /> }<br /> &lt;/pawn&gt;<br /> <br /> Here is the previous for loop rewritten as a while loop:<br /> &lt;pawn&gt;<br /> SumArray(const array[], count)<br /> {<br /> int total, i;<br /> <br /> while (i &lt; count)<br /> {<br /> total += array[i];<br /> i++;<br /> }<br /> <br /> return total;<br /> }&lt;/pawn&gt;<br /> <br /> There are also '''do...while''' loops which are even less common. These are the same as while loops except the condition check is AFTER each loop, rather than before. This means the loop is always run at least once. For example:<br /> <br /> &lt;pawn&gt;<br /> do<br /> {<br /> /* body */<br /> }<br /> while ( /* condition */ );<br /> &lt;/pawn&gt;<br /> <br /> ==Loop Control==<br /> There are two cases in which you want to selectively control a loop:<br /> *'''skipping''' one iteration of the loop but continuing as normal, or;<br /> *'''breaking''' the loop entirely before it's finished.<br /> <br /> Let's say you have a function which takes in an array and searches for a matching number. You want it to stop once the number is found:<br /> &lt;pawn&gt;<br /> /**<br /> * Returns the array index where the value is, or -1 if not found.<br /> */<br /> SearchInArray(const array[], count, value)<br /> {<br /> int index = -1;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> if (array[i] == value)<br /> {<br /> index = i;<br /> break;<br /> }<br /> }<br /> <br /> return index;<br /> }&lt;/pawn&gt;<br /> <br /> Certainly, this function could simply &lt;tt&gt;return i&lt;/tt&gt; instead, but the example shows how &lt;tt&gt;break&lt;/tt&gt; will terminate the loop.<br /> <br /> Similarly, the &lt;tt&gt;continue&lt;/tt&gt; keyword skips an iteration of a loop. For example, let's say we wanted to sum all even numbers:<br /> &lt;pawn&gt;<br /> int SumEvenNumbers(const array[], count)<br /> {<br /> int sum;<br /> <br /> for (int i = 0; i &lt; count; i++)<br /> {<br /> /* If divisibility by 2 is 1, we know it's odd */<br /> if (array[i] % 2 == 1)<br /> {<br /> /* Skip the rest of this loop iteration */<br /> continue;<br /> }<br /> sum += array[i];<br /> }<br /> <br /> return sum;<br /> }&lt;/pawn&gt;<br /> <br /> =Scope=<br /> Scope refers to the '''visibility''' of code. That is, code at one level may not be &quot;visible&quot; to code at another level. For example:<br /> <br /> &lt;pawn&gt;<br /> int A, B, C;<br /> <br /> Function1()<br /> {<br /> int B;<br /> <br /> Function2();<br /> }<br /> <br /> Function2()<br /> {<br /> int C;<br /> }&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;A&lt;/tt&gt;, &lt;tt&gt;B&lt;/tt&gt;, and &lt;tt&gt;C&lt;/tt&gt; exist at '''global scope'''. They can be seen by any function. However, the &lt;tt&gt;B&lt;/tt&gt; in &lt;tt&gt;Function1&lt;/tt&gt; is not the same variable as the &lt;tt&gt;B&lt;/tt&gt; at the global level. Instead, it is at '''local scope''', and is thus a '''local variable'''.<br /> <br /> Similarly, &lt;tt&gt;Function1&lt;/tt&gt; and &lt;tt&gt;Function2&lt;/tt&gt; know nothing about each other's variables.<br /> <br /> Not only is the variable private to &lt;tt&gt;Function1&lt;/tt&gt;, but it is re-created each time the function is invoked. Imagine this:<br /> &lt;pawn&gt;<br /> Function1()<br /> {<br /> int B;<br /> <br /> Function1();<br /> }&lt;/pawn&gt;<br /> <br /> In the above example, &lt;tt&gt;Function1&lt;/tt&gt; calls itself. Of course, this is infinite recursion (a bad thing), but the idea is that each time the function runs, there is a new copy of &lt;tt&gt;B&lt;/tt&gt;. When the function ends, &lt;tt&gt;B&lt;/tt&gt; is destroyed, and the value is lost.<br /> <br /> This property can be simplified by saying that a variable's scope is equal to the nesting level it is in. That is, a variable at global scope is visible globally to all functions. A variable at local scope is visible to all code blocks &quot;beneath&quot; its nesting level. For example:<br /> <br /> &lt;pawn&gt;Function1()<br /> {<br /> int A;<br /> <br /> if (A)<br /> {<br /> A = 5;<br /> }<br /> }&lt;/pawn&gt;<br /> <br /> The above code is valid since A's scope extends throughout the function. The following code, however, is not valid:<br /> &lt;pawn&gt;<br /> Function1()<br /> {<br /> int A;<br /> <br /> if (A)<br /> {<br /> new B = 5;<br /> }<br /> <br /> B = 5;<br /> }&lt;/pawn&gt;<br /> <br /> Notice that &lt;tt&gt;B&lt;/tt&gt; is declared in a new code block. That means &lt;tt&gt;B&lt;/tt&gt; is only accessible to that code block (and all sub-blocks nested within). As soon as the code block terminates, &lt;tt&gt;B&lt;/tt&gt; is no longer valid.<br /> <br /> <br /> =Dynamic Arrays=<br /> Dynamic arrays are arrays which don't have a hardcoded size. For example:<br /> <br /> &lt;pawn&gt;Function1(size)<br /> {<br /> int array[size];<br /> <br /> /* Code */<br /> }&lt;/pawn&gt;<br /> <br /> Dynamic arrays can have any expression as their size as long as the expression evaluates to a number larger than 0. Like normal arrays, SourcePawn does not know the array size after it is created; you have to save it if you want it later.<br /> <br /> Dynamic arrays are only valid at the local scope level, since code cannot exist globally.<br /> <br /> =Extended Variable Declarations=<br /> Variables can be declared in more ways than simply &lt;tt&gt;new&lt;/tt&gt;.<br /> <br /> ==decl==<br /> ===Purpose===<br /> By default, all variables in Pawn are initialized to zero. If there is an explicit initializer, the variable is initialized to the expression after the &lt;tt&gt;=&lt;/tt&gt; token. At a local scope, this can be a run-time expense. The &lt;tt&gt;decl&lt;/tt&gt; keyword (which is only valid at local scope) was introduced to let users decide if they want variables initialized or not.<br /> <br /> Note: &lt;tt&gt;decl&lt;/tt&gt; should not be used on single cell variables. There is almost never any benefit.<br /> <br /> ===Explanation===<br /> For example:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> int d;<br /> char blah[512];<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> In this code, &lt;tt&gt;c&lt;/tt&gt; is equal to 5 and &lt;tt&gt;d&lt;/tt&gt; is equal to 0. The run-time expense of this initialization is negligible. However, &lt;tt&gt;blah&lt;/tt&gt; is a large array, and the expense of initializing the entire array to 0s could be detrimental in certain situations. <br /> <br /> Note that &lt;tt&gt;blah&lt;/tt&gt; does not need to be zeroed. In between being declared with &lt;tt&gt;new&lt;/tt&gt; and stored with &lt;tt&gt;Format()&lt;/tt&gt;, &lt;tt&gt;blah&lt;/tt&gt; is never loaded or read. Thus this code would be more efficiently written as:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> int d;<br /> decl String:blah[512];<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> ===Caveats===<br /> The downside to &lt;tt&gt;decl&lt;/tt&gt; is that it means its variables will start with &quot;garbage&quot; contents. For example, if we were to use:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> int d;<br /> decl String:blah[512];<br /> <br /> PrintToServer(&quot;%s&quot;, blah);<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> This code may crash the server, because &lt;tt&gt;blah&lt;/tt&gt; may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:<br /> <br /> &lt;pawn&gt;<br /> int c = 5;<br /> decl d;<br /> decl String:blah[512];<br /> <br /> Format(blah, sizeof(blah), &quot;%d %d&quot;, c, d);<br /> &lt;/pawn&gt;<br /> <br /> The value of &lt;tt&gt;d&lt;/tt&gt; is now undefined. It could be any value, negative or positive. <br /> <br /> Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:<br /> &lt;pawn&gt;<br /> decl String:blah[512];<br /> <br /> blah[0] = '\0';<br /> &lt;/pawn&gt;<br /> <br /> ===Golden Rules===<br /> *'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''<br /> *'''Do not prematurely optimize.''' Likewise, there is no need to use &lt;tt&gt;decl&lt;/tt&gt; on non-arrays, because there is no added expense for initializing a single cell value.<br /> <br /> ===Notes===<br /> This example is NOT as efficient as a &lt;tt&gt;decl&lt;/tt&gt;:<br /> &lt;pawn&gt;<br /> char blah[512] = &quot;a&quot;;<br /> &lt;/pawn&gt;<br /> <br /> Even though the string is only one character, the &lt;tt&gt;new&lt;/tt&gt; operator guarantees the rest of the array will be zeroed as well.<br /> <br /> Also note, it is valid to explicitly initialize a &lt;tt&gt;decl&lt;/tt&gt; '''ONLY''' with strings:<br /> &lt;pawn&gt;decl String:blah[512] = &quot;a&quot;;&lt;/pawn&gt;<br /> <br /> However, any other tag will fail to compile, because the purpose of &lt;tt&gt;decl&lt;/tt&gt; is to avoid any initialization:<br /> &lt;pawn&gt;decl Float:blah[512] = {1.0};&lt;/pawn&gt;<br /> <br /> ==static==<br /> The &lt;tt&gt;static&lt;/tt&gt; keyword is available at global and local scope. It has different meanings in each.<br /> <br /> ===Global static===<br /> A global static variable can only be accessed from within the same file. For example:<br /> <br /> &lt;pawn&gt;//file1.inc<br /> static float g_value1 = 0.15f;<br /> <br /> //file2.inc<br /> static float g_value2 = 0.15f;&lt;/pawn&gt;<br /> <br /> If a plugin includes both of these files, it will not be able to use either &lt;tt&gt;g_value1&lt;/tt&gt; or &lt;tt&gt;g_value2&lt;/tt&gt;. This is a simple information hiding mechanism, and is similar to declaring member variables as &lt;tt&gt;private&lt;/tt&gt; in languages like C++, Java, or C#.<br /> <br /> ===Local static===<br /> A local static variable is a global variable that is only visible from its local lexical scope. For example:<br /> <br /> &lt;pawn&gt;<br /> int MyFunction(inc)<br /> {<br /> static counter = -1;<br /> <br /> counter += inc;<br /> <br /> return counter;<br /> }&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;counter&lt;/tt&gt; is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time &lt;tt&gt;MyFunction&lt;/tt&gt; runs, the &lt;tt&gt;counter&lt;/tt&gt; variable and its storage in memory is the same.<br /> <br /> Take this example:<br /> &lt;pawn&gt;MyFunction(5);<br /> MyFunction(6);<br /> MyFunction(10);&lt;/pawn&gt;<br /> <br /> In this example, &lt;tt&gt;counter&lt;/tt&gt; will be &lt;tt&gt;-1 + 5 + 6 + 10&lt;/tt&gt;, or &lt;tt&gt;20&lt;/tt&gt;, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then &lt;tt&gt;static&lt;/tt&gt; is usually not a good idea unless your code is re-entrant. <br /> <br /> The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.<br /> <br /> Note that statics can exist in any local scope:<br /> <br /> &lt;pawn&gt;<br /> int MyFunction(inc)<br /> {<br /> if (inc &gt; 0)<br /> {<br /> static counter;<br /> return (counter += inc);<br /> }<br /> return -1;<br /> }&lt;/pawn&gt;<br /> <br /> [[Category:SourceMod Scripting]]<br /> <br /> {{LanguageSwitch}}</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=SourceMod_SDK&diff=10031 2015-10-03T16:48:01Z

<p>Xerox8521: /* Further Reading */</p> <hr /> <div>The SourceMod SDK is the Software Development Kit for writing SourceMod Extensions and Plugins. This article briefly introduces it.<br /> <br /> =Directory Structure=<br /> *'''configs''': Configuration files that SourceMod uses<br /> *'''editor''': Editor related files<br /> **'''Pawn Studio''': [http://sourceforge.net/projects/pawnstudio Official IDE for SourceMod]<br /> **'''crimson''': Drop-in syntax highlighting for [http://www.crimsoneditor.com/ Crimson Editor]<br /> **'''textpad''': Drop-in syntax highlighting for [http://www.textpad.com/ TextPad]<br /> **'''ultraedit''': Drop-in syntax highlighting for [http://www.ultraedit.com/ UltraEdit/UEStudio]<br /> *'''extensions''': Publicly open-sourced extensions.<br /> **'''geoip''': GeoIP extension.<br /> **'''threader''': Threading extension.<br /> *'''plugins''': SourceMod plugin implementations.<br /> **'''include''': Include files and their documentation.<br /> *'''public''': Public interface files.<br /> **'''doxygen''': The SDK Doxygen file.<br /> **'''extensions''': Public interface files that come from extensions.<br /> **'''licenses''': License information.<br /> **'''sample_ext''': A sample extension.<br /> **'''sourcepawn''': SourcePawn header files.<br /> *'''sourcepawn''': SourcePawn files.<br /> **'''compiler''': SourcePawn compiler source code.<br /> *'''translations''': Translation files.<br /> <br /> =Further Reading=<br /> *For writing extensions, see [[Writing Extensions]].<br /> *For documentation, see [[SourceMod Documentation]].<br /> *For the nightly source code tree, see [https://github.com/alliedmodders/sourcemod SourceMod Central].<br /> <br /> [[Category:SourceMod Development]]</div>

Xerox8521 https://wiki.alliedmods.net/index.php?title=SourceMod_SDK&diff=10030 2015-10-03T16:46:52Z

<p>Xerox8521: /* Further Reading */</p> <hr /> <div>The SourceMod SDK is the Software Development Kit for writing SourceMod Extensions and Plugins. This article briefly introduces it.<br /> <br /> =Directory Structure=<br /> *'''configs''': Configuration files that SourceMod uses<br /> *'''editor''': Editor related files<br /> **'''Pawn Studio''': [http://sourceforge.net/projects/pawnstudio Official IDE for SourceMod]<br /> **'''crimson''': Drop-in syntax highlighting for [http://www.crimsoneditor.com/ Crimson Editor]<br /> **'''textpad''': Drop-in syntax highlighting for [http://www.textpad.com/ TextPad]<br /> **'''ultraedit''': Drop-in syntax highlighting for [http://www.ultraedit.com/ UltraEdit/UEStudio]<br /> *'''extensions''': Publicly open-sourced extensions.<br /> **'''geoip''': GeoIP extension.<br /> **'''threader''': Threading extension.<br /> *'''plugins''': SourceMod plugin implementations.<br /> **'''include''': Include files and their documentation.<br /> *'''public''': Public interface files.<br /> **'''doxygen''': The SDK Doxygen file.<br /> **'''extensions''': Public interface files that come from extensions.<br /> **'''licenses''': License information.<br /> **'''sample_ext''': A sample extension.<br /> **'''sourcepawn''': SourcePawn header files.<br /> *'''sourcepawn''': SourcePawn files.<br /> **'''compiler''': SourcePawn compiler source code.<br /> *'''translations''': Translation files.<br /> <br /> =Further Reading=<br /> *For writing extensions, see [[Writing Extensions]].<br /> *For documentation, see [https://wiki.alliedmods.net/SourceMod_Documentation https://wiki.alliedmods.net/SourceMod_Documentation].<br /> *For the nightly source code tree, see [https://github.com/alliedmodders/sourcemod SourceMod Central].<br /> <br /> [[Category:SourceMod Development]]</div>

Xerox8521