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 */
50 #include <usermessages>
57 * Declare this as a struct in your plugin to expose its information.
60 * public Plugin:myinfo =
69 * Called when the plugin is fully initialized and all known external references are resolved.
70 * This is called even if the plugin type is "private."
71 * @note Errors in this function will cause the plugin to stop running.
75 forward OnPluginStart();
78 * Called before OnPluginStart, in case the plugin wants to check for load failure.
79 * This is called even if the plugin type is "private." Any natives from modules are
80 * not available at this point. Thus, this forward should only be used for explicit
81 * pre-emptive things, such as adding dynamic natives, or setting certain types of load filters.
83 * @note It is not safe to call externally resolved natives until OnPluginStart().
84 * @note Any sort of RTE in this function will cause the plugin to fail loading.
86 * @param myself Handle to the plugin.
87 * @param late Whether or not the plugin was loaded "late" (after map load).
88 * @param error Error message buffer in case load failed.
89 * @param err_max Maximum number of characters for error message buffer.
90 * @return True if load success, false otherwise.
92 forward bool:AskPluginLoad(Handle:myself, bool:late, String:error[], err_max);
95 * Called when the plugin is about to be unloaded.
99 forward OnPluginEnd();
102 * Called when the plugin's pause status is changing.
104 * @param pause True if the plugin is being paused, false otherwise.
107 forward OnPluginPauseChange(bool:pause);
110 * Called before every server frame. Note that you should avoid
111 * doing expensive computations here, and you should declare large
112 * local arrays using 'decl' instead of 'new'.
114 forward OnGameFrame();
117 * Called when the map is loaded.
119 * @note This used to be OnServerLoad(), which is now deprecated.
120 * Plugins still using the old forward will work.
122 forward OnMapStart();
125 * Called right before a map ends.
130 * Called when the map has loaded, servercfgfile (server.cfg) has been
131 * executed, and all plugin configs are done executing. This is the best
132 * place to inialize plugin functions which are based on cvar data.
134 * @note This will always be called once and only once per map. It will be
135 * called after OnMapStart().
139 forward OnConfigsExecuted();
142 * @deprecated Use OnConfigsExecuted() instead.
144 #pragma deprecated Use OnConfigsExecuted() instead
145 forward OnServerCfg();
148 * Called after all plugins have been loaded.
150 forward OnAllPluginsLoaded();
153 * Returns the calling plugin's Handle.
155 * @return Handle of the calling plugin.
157 native Handle:GetMyHandle();
160 * Returns an iterator that can be used to search through plugins.
162 * @return Handle to iterate with. Must be closed via
164 * @error Invalid Handle.
166 native Handle:GetPluginIterator();
169 * Returns whether there are more plugins available in the iterator.
171 * @param iter Handle to the plugin iterator.
172 * @return True on more plugins, false otherwise.
173 * @error Invalid Handle.
175 native bool:MorePlugins(Handle:iter);
178 * Returns the current plugin in the iterator and advances the iterator.
180 * @param iter Handle to the plugin iterator.
181 * @return Current plugin the iterator is at, before
182 * the iterator is advanced.
183 * @error Invalid Handle.
185 native Handle:ReadPlugin(Handle:iter);
188 * Returns a plugin's status.
190 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
191 * @return Status code for the plugin.
192 * @error Invalid Handle.
194 native PluginStatus:GetPluginStatus(Handle:plugin);
197 * Retrieves a plugin's file name relative to the plugins folder.
199 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
200 * @param buffer Buffer to the store the file name.
201 * @param maxlength Maximum length of the name buffer.
203 * @error Invalid Handle.
205 native GetPluginFilename(Handle:plugin, String:buffer[], maxlength);
208 * Retrieves whether or not a plugin is being debugged.
210 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
211 * @return True if being debugged, false otherwise.
212 * @error Invalid Handle.
214 native bool:IsPluginDebugging(Handle:hndl);
217 * Retrieves a plugin's public info.
219 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
220 * @param info Plugin info property to retrieve.
221 * @param buffer Buffer to store info in.
222 * @param maxlength Maximum length of buffer.
223 * @return True on success, false if property is not available.
224 * @error Invalid Handle.
226 native bool:GetPluginInfo(Handle:plugin, PluginInfo:info, String:buffer[], maxlength);
229 * Causes the plugin to enter a failed state. An error will be thrown and
230 * the plugin will be paused until it is unloaded or reloaded.
232 * @param string Message to print.
234 * @error Always throws SP_ERROR_ABORT.
236 native SetFailState(const String:string[]);
239 * Aborts the current callback and throws an error. This function
240 * does not return in that no code is executed following it.
242 * @param format String format.
243 * @param ... Format arguments.
247 native ThrowError(const String:fmt[], any:...);
250 * Logs a plugin message to the SourceMod logs.
252 * @param format String format.
253 * @param ... Format arguments.
256 native LogMessage(const String:format[], any:...);
259 * Logs a plugin error message to the SourceMod logs.
261 * @param format String format.
262 * @param ... Format arguments.
265 native LogError(const String:format[], any:...);
268 * Gets the system time as a unix timestamp.
270 * @param bigStamp Optional array to store the 64bit timestamp in.
271 * @return 32bit timestamp (number of seconds since unix epoch).
273 native GetTime(bigStamp[2]={0,0});
276 * Format date and time.
278 * @param buffer Destination string buffer.
279 * @param maxlength Maximum length of output string buffer.
280 * @param format Formatting rules.
281 * @param stamp Optional time stamp.
284 native FormatTime(String:buffer[], maxlength, const String:format[], stamp=-1);
287 * Loads a game config file.
289 * @param file File to load. The path must be relative to the 'gamedata' folder under the config folder
290 * and the extension should be omitted.
291 * @return A handle to the game config file or INVALID_HANDLE in failure.
293 native Handle:LoadGameConfigFile(const String:file[]);
296 * Returns an offset value.
298 * @param gc Game config handle.
299 * @param key Key to retrieve from the offset section.
300 * @return An offset, or -1 on failure.
302 native GameConfGetOffset(Handle:gc, const String:key[]);
305 * Gets the value of a key from the "Keys" section.
307 * @param gc Game config handle.
308 * @param key Key to retrieve from the Keys section.
309 * @param buffer Destination string buffer.
310 * @param maxlen Maximum length of output string buffer.
311 * @return True if key existed, false otherwise.
313 native bool:GameConfGetKeyValue(Handle:gc, const String:key[], String:buffer[], maxlen);
316 * Returns the operating system's "tick count," which is a number of
317 * milliseconds since the operating system loaded. This can be used
318 * for basic benchmarks.
320 * @return Tick count in milliseconds.
322 native GetSysTickCount();
325 * Specifies that the given config file should be executed after plugin load.
326 * OnConfigsExecuted() will not be called until the config file has executed,
327 * but it will be called if the execution fails.
329 * @param autoCreate If true, and the config file does not exist, such a config
330 * file will be automatically created and populated with
331 * information from the plugin's registered cvars.
332 * @param name Name of the config file, excluding the .cfg extension.
333 * If empty, <plugin.filename.cfg> is assumed.
334 * @param folder Folder under cfg/ to use. By default this is "sourcemod."
337 native AutoExecConfig(bool:autoCreate=true, const String:name[]="", const String:folder[]="sourcemod");
340 * Sets a native as optional, such that if it is unloaded, removed,
341 * or otherwise non-existent, the plugin will still work. Calling
342 * removed natives results in a run-time error.
344 * @param name Native name.
347 native MarkNativeAsOptional(const String:name[]);
350 * Registers a library name for identifying as a dependency to
353 * @param name Library name.
356 native RegPluginLibrary(const String:name[]);
359 * Returns whether a library exists.
361 * @param name Library name.
362 * @return True if exists, false otherwise.
364 native bool:LibraryExists(const String:name[]);
367 * Called after a library (plugin) is added that the
368 * current plugin references optionally.
370 * @param name Library name.
372 forward OnLibraryAdded(const String:name[]);
375 * Called right before a library (plugin) is removed that the
376 * current plugin references optionally.
378 * @param name Library name.
380 forward OnLibraryRemoved(const String:name[]);
