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.
112 * This function will be called on each mapchange.
114 forward OnServerLoad();
117 * Returns the calling plugin's Handle.
119 * @return Handle of the calling plugin.
121 native Handle:GetMyHandle();
124 * Returns an iterator that can be used to search through plugins.
126 * @return Handle to iterate with. Must be closed via
128 * @error Invalid Handle.
130 native Handle:GetPluginIterator();
133 * Returns whether there are more plugins available in the iterator.
135 * @param iter Handle to the plugin iterator.
136 * @return True on more plugins, false otherwise.
137 * @error Invalid Handle.
139 native bool:MorePlugins(Handle:iter);
142 * Returns the current plugin in the iterator and advances the iterator.
144 * @param iter Handle to the plugin iterator.
145 * @return Current plugin the iterator is at, before
146 * the iterator is advanced.
147 * @error Invalid Handle.
149 native Handle:ReadPlugin(Handle:iter);
152 * Returns a plugin's status.
154 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
155 * @return Status code for the plugin.
156 * @error Invalid Handle.
158 native PluginStatus:GetPluginStatus(Handle:plugin);
161 * Retrieves a plugin's file name relative to the plugins folder.
163 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
164 * @param buffer Buffer to the store the file name.
165 * @param maxlength Maximum length of the name buffer.
167 * @error Invalid Handle.
169 native GetPluginFilename(Handle:plugin, String:buffer[], maxlength);
172 * Retrieves whether or not a plugin is being debugged.
174 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
175 * @return True if being debugged, false otherwise.
176 * @error Invalid Handle.
178 native bool:IsPluginDebugging(Handle:hndl);
181 * Retrieves a plugin's public info.
183 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
184 * @param info Plugin info property to retrieve.
185 * @param buffer Buffer to store info in.
186 * @param maxlength Maximum length of buffer.
187 * @return True on success, false if property is not available.
188 * @error Invalid Handle.
190 native bool:GetPluginInfo(Handle:plugin, PluginInfo:info, String:buffer[], maxlength);
193 * Aborts the current callback and throws an error. This function
194 * does not return in that no code is executed following it.
196 * @param format String format.
197 * @param ... Format arguments.
201 native ThrowError(const String:fmt[], any:...);
204 * Logs a generic message to the HL2 logs.
206 * @param format String format.
207 * @param ... Format arguments.
210 native LogToGame(const String:format[], any:...);
213 * Logs a plugin message to the SourceMod logs.
215 * @param format String format.
216 * @param ... Format arguments.
219 native LogMessage(const String:format[], any:...);
222 * Logs a plugin error message to the SourceMod logs.
224 * @param format String format.
225 * @param ... Format arguments.
228 native LogError(const String:format[], any:...);
231 * Gets the system time as a unix timestamp.
233 * @param bigStamp Optional array to store the 64bit timestamp in.
234 * @return 32bit timestamp (number of seconds since unix epoch).
236 native GetTime(bigStamp[2]={0,0});
239 * Sets the seed value for the global Half-Life 2 Random Stream
241 * @param seed Seed value.
244 native SetRandomSeed(seed);
247 * Returns a random floating point number from the Half-Life 2 Random Stream
249 * @param fMin Minimum random bound.
250 * @param fMax Maximum random bound.
251 * @return A random number between (inclusive) fMin and fMax.
253 native Float:GetRandomFloat(Float:fMin=0.0, Float:fMax=1.0);
256 * Returns a random number from the Half-Life 2 Random Stream
258 * @param nmin Minimum random bound.
259 * @param nmax Maximum random bound.
260 * @return A random number between (inclusive) nmin and nmax.
262 native GetRandomInt(nmin, nmax);
265 * Returns whether a map is valid or not.
267 * @param Map name, excluding .bsp extension.
268 * @return True if valid, false otherwise.
270 native bool:IsMapValid(const String:map[]);
273 * Returns whether the server is dedicated.
275 * @return True if dedicated, false otherwise.
277 native bool:IsDedicatedServer();
280 * Returns a high-precision time value for profiling the engine.
282 * @return A floating point time value.
284 native Float:GetEngineTime();
287 * Returns the game time based on the game tick.
289 * @return Game tick time.
291 native Float:GetGameTime();
294 * Returns the game description from the mod.
296 * @param buffer Buffer to store the description.
297 * @param maxlength Maximum size of the buffer.
298 * @param original If true, retrieves the original game description,
299 * ignoring any potential hooks from plugins.
300 * @return Number of bytes written to the buffer (UTF-8 safe).
302 native GetGameDescription(String:buffer[], maxlength, bool:original=false);
305 * Returns the current map name.
307 * @param buffer Buffer to store map name.
308 * @param maxlength Maximum length of buffer.
309 * @return Number of bytes written (UTF-8 safe).
311 native GetCurrentMap(String:buffer[], maxlength);
314 * Precaches a given model.
316 * @param model Name of the model to precache.
317 * @param preload If preload is true the file will be precached before level startup.
318 * @return Returns the model index, 0 for error.
320 native PrecacheModel(const String:model[], bool:preload=false);
323 * Precaches a given sentence file.
325 * @param file Name of the sentence file to precache.
326 * @param preload If preload is true the file will be precached before level startup.
327 * @return Returns a sentence file index.
329 native PrecacheSentenceFile(const String:file[], bool:preload=false);
332 * Precaches a given decal.
334 * @param decal Name of the decal to precache.
335 * @param preload If preload is true the file will be precached before level startup.
336 * @return Returns a decal index.
338 native PrecacheDecal(const String:decal[], bool:preload=false);
341 * Precaches a given generic file.
343 * @param generic Name of the generic file to precache.
344 * @param preload If preload is true the file will be precached before level startup.
345 * @return Returns a generic file index.
347 native PrecacheGeneric(const String:generic[], bool:preload=false);
350 * Returns if a given model is precached.
352 * @param model Name of the model to check.
353 * @return True if precached, false otherwise.
355 native bool:IsModelPrecached(const String:model[]);
358 * Returns if a given decal is precached.
360 * @param decal Name of the decal to check.
361 * @return True if precached, false otherwise.
363 native bool:IsDecalPrecached(const String:decal[]);
366 * Returns if a given generic file is precached.
368 * @param decal Name of the generic file to check.
369 * @return True if precached, false otherwise.
371 native bool:IsGenericPrecached(const String:generic[]);
374 * Precaches a given sound.
376 * @param sound Name of the sound to precache.
377 * @param preload If preload is true the file will be precached before level startup.
378 * @return True if successfully precached, false otherwise.
380 native bool:PrecacheSound(const String:sound[], bool:preload=false);
383 * Returns if a given sound is precached.
385 * @param sound Name of the sound to check.
386 * @return True if precached, false otherwise.
388 native bool:IsSoundPrecached(const String:sound[]);
391 * Executes a client command on the server without being networked.
393 * @param client Index of the client.
394 * @param fmt Format of the client command.
395 * @param ... Format parameters
397 * @error Invalid client index, or client not connected.
399 native FakeClientCommand(client, const String:fmt[], any:...);
