3 * ===============================================================
4 * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
5 * ===============================================================
7 * This file is part of the SourceMod/SourcePawn SDK. This file may only be used
8 * or modified under the Terms and Conditions of its License Agreement, which is found
9 * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins
10 * may change at any time. To view the latest information, see:
11 * http://www.sourcemod.net/license.php
16 #if defined _sourcemod_included
19 #define _sourcemod_included
22 * Plugin public information.
26 const String:name[], /**< Plugin Name */
27 const String:description[], /**< Plugin Description */
28 const String:author[], /**< Plugin Author */
29 const String:version[], /**< Plugin Version */
30 const String:url[], /**< Plugin URL */
43 #include <usermessages>
49 * Declare this as a struct in your plugin to expose its information.
52 * public Plugin:myinfo =
61 * Called when the plugin is fully initialized and all known external references are resolved.
62 * This is called even if the plugin type is "private."
63 * @note Errors in this function will cause the plugin to stop running.
67 forward OnPluginStart();
70 * Called before OnPluginStart, in case the plugin wants to check for load failure.
71 * This is called even if the plugin type is "private." Any natives from modules are
72 * not available at this point. Thus, this forward should only be used for explicit
73 * pre-emptive things, such as adding dynamic natives, or setting certain types of load filters.
75 * @note It is not safe to call externally resolved natives until OnPluginStart().
76 * @note Any sort of RTE in this function will cause the plugin to fail loading.
78 * @param myself Handle to the plugin.
79 * @param late Whether or not the plugin was loaded "late" (after map load).
80 * @param error Error message buffer in case load failed.
81 * @param err_max Maximum number of characters for error message buffer.
82 * @return True if load success, false otherwise.
84 forward bool:AskPluginLoad(Handle:myself, bool:late, String:error[], err_max);
87 * Called when the plugin is about to be unloaded.
91 forward OnPluginEnd();
94 * Called when the plugin's pause status is changing.
96 * @param pause True if the plugin is being paused, false otherwise.
99 forward OnPluginPauseChange(bool:pause);
102 * Called before every server frame. Note that you should avoid
103 * doing expensive computations here, and you should declare large
104 * local arrays using 'decl' instead of 'new'.
106 forward OnGameFrame();
109 * Called when the map is loaded and configs have been parsed.
110 * Note that commands are processed per-frame, and thus config
111 * files may not be fully loaded until a few seconds later.
113 forward OnServerLoad();
116 * Returns the calling plugin's Handle.
118 * @return Handle of the calling plugin.
120 native Handle:GetMyHandle();
123 * Returns an iterator that can be used to search through plugins.
125 * @return Handle to iterate with. Must be closed via
127 * @error Invalid Handle.
129 native Handle:GetPluginIterator();
132 * Returns whether there are more plugins available in the iterator.
134 * @param iter Handle to the plugin iterator.
135 * @return True on more plugins, false otherwise.
136 * @error Invalid Handle.
138 native bool:MorePlugins(Handle:iter);
141 * Returns the current plugin in the iterator and advances the iterator.
143 * @param iter Handle to the plugin iterator.
144 * @return Current plugin the iterator is at, before
145 * the iterator is advanced.
146 * @error Invalid Handle.
148 native Handle:ReadPlugin(Handle:iter);
151 * Returns a plugin's status.
153 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
154 * @return Status code for the plugin.
155 * @error Invalid Handle.
157 native PluginStatus:GetPluginStatus(Handle:plugin);
160 * Retrieves a plugin's file name relative to the plugins folder.
162 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
163 * @param buffer Buffer to the store the file name.
164 * @param maxlength Maximum length of the name buffer.
166 * @error Invalid Handle.
168 native GetPluginFilename(Handle:plugin, String:buffer[], maxlength);
171 * Retrieves whether or not a plugin is being debugged.
173 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
174 * @return True if being debugged, false otherwise.
175 * @error Invalid Handle.
177 native bool:IsPluginDebugging(Handle:hndl);
180 * Retrieves a plugin's public info.
182 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
183 * @param info Plugin info property to retrieve.
184 * @param buffer Buffer to store info in.
185 * @param maxlength Maximum length of buffer.
186 * @return True on success, false if property is not available.
187 * @error Invalid Handle.
189 native bool:GetPluginInfo(Handle:plugin, PluginInfo:info, String:buffer[], maxlength);
192 * Aborts the current callback and throws an error. This function
193 * does not return in that no code is executed following it.
195 * @param format String format.
196 * @param ... Format arguments.
200 native ThrowError(const String:fmt[], any:...);
203 * Logs a generic message to the HL2 logs.
205 * @param format String format.
206 * @param ... Format arguments.
209 native LogToGame(const String:format[], any:...);
212 * Logs a plugin message to the SourceMod logs.
214 * @param format String format.
215 * @param ... Format arguments.
218 native LogMessage(const String:format[], any:...);
221 * Logs a plugin error message to the SourceMod logs.
223 * @param format String format.
224 * @param ... Format arguments.
227 native LogError(const String:format[], any:...);
230 * Gets the system time as a unix timestamp.
232 * @param bigStamp Optional array to store the 64bit timestamp in.
233 * @return 32bit timestamp (number of seconds since unix epoch).
235 native GetTime(bigStamp[2]={0,0});
238 * Sets the seed value for the global Half-Life 2 Random Stream
240 * @param seed Seed value.
243 native SetRandomSeed(seed);
246 * Returns a random floating point number from the Half-Life 2 Random Stream
248 * @param fMin Minimum random bound.
249 * @param fMax Maximum random bound.
250 * @return A random number between (inclusive) fMin and fMax.
252 native Float:GetRandomFloat(Float:fMin=0.0, Float:fMax=1.0);
255 * Returns a random number from the Half-Life 2 Random Stream
257 * @param nmin Minimum random bound.
258 * @param nmax Maximum random bound.
259 * @return A random number between (inclusive) nmin and nmax.
261 native GetRandomInt(nmin, nmax);
264 * Returns whether a map is valid or not.
266 * @param Map name, excluding .bsp extension.
267 * @return True if valid, false otherwise.
269 native bool:IsMapValid(const String:map[]);
272 * Returns whether the server is dedicated.
274 * @return True if dedicated, false otherwise.
276 native bool:IsDedicatedServer();
279 * Returns a high-precision time value for profiling the engine.
281 * @return A floating point time value.
283 native Float:GetEngineTime();
286 * Returns the game time based on the game tick.
288 * @return Game tick time.
290 native Float:GetGameTime();
293 * Returns the game description from the mod.
295 * @param buffer Buffer to store the description.
296 * @param maxlength Maximum size of the buffer.
297 * @param original If true, retrieves the original game description,
298 * ignoring any potential hooks from plugins.
299 * @return Number of bytes written to the buffer (UTF-8 safe).
301 native GetGameDescription(String:buffer[], maxlength, bool:original=false);
304 * Returns the current map name.
306 * @param buffer Buffer to store map name.
307 * @param maxlength Maximum length of buffer.
308 * @return Number of bytes written (UTF-8 safe).
310 native GetCurrentMap(String:buffer[], maxlength);
