3 * =============================================================================
4 * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
5 * =============================================================================
7 * This file is part of the SourceMod/SourcePawn SDK.
9 * This program is free software; you can redistribute it and/or modify it under
10 * the terms of the GNU General Public License, version 3.0, as published by the
11 * Free Software Foundation.
13 * This program is distributed in the hope that it will be useful, but WITHOUT
14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
18 * You should have received a copy of the GNU General Public License along with
19 * this program. If not, see <http://www.gnu.org/licenses/>.
21 * As a special exception, AlliedModders LLC gives you permission to link the
22 * code of this program (as well as its derivative works) to "Half-Life 2," the
23 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
24 * by the Valve Corporation. You must obey the GNU General Public License in
25 * all respects for all other code used. Additionally, AlliedModders LLC grants
26 * this exception to all derivative works. AlliedModders LLC defines further
27 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
28 * or <http://www.sourcemod.net/license.php>.
33 #if defined _sourcemod_included
36 #define _sourcemod_included
39 * Plugin public information.
43 const String:name[], /**< Plugin Name */
44 const String:description[], /**< Plugin Description */
45 const String:author[], /**< Plugin Author */
46 const String:version[], /**< Plugin Version */
47 const String:url[], /**< Plugin URL */
67 #include <usermessages>
73 #include <commandfilters>
76 * Declare this as a struct in your plugin to expose its information.
79 * public Plugin:myinfo =
88 * Called when the plugin is fully initialized and all known external references are resolved.
89 * This is called even if the plugin type is "private."
90 * @note Errors in this function will cause the plugin to stop running.
94 forward OnPluginStart();
97 * Called before OnPluginStart, in case the plugin wants to check for load failure.
98 * This is called even if the plugin type is "private." Any natives from modules are
99 * not available at this point. Thus, this forward should only be used for explicit
100 * pre-emptive things, such as adding dynamic natives, or setting certain types of load filters.
102 * @note It is not safe to call externally resolved natives until OnPluginStart().
103 * @note Any sort of RTE in this function will cause the plugin to fail loading.
105 * @param myself Handle to the plugin.
106 * @param late Whether or not the plugin was loaded "late" (after map load).
107 * @param error Error message buffer in case load failed.
108 * @param err_max Maximum number of characters for error message buffer.
109 * @return True if load success, false otherwise.
111 forward bool:AskPluginLoad(Handle:myself, bool:late, String:error[], err_max);
114 * Called when the plugin is about to be unloaded.
118 forward OnPluginEnd();
121 * Called when the plugin's pause status is changing.
123 * @param pause True if the plugin is being paused, false otherwise.
126 forward OnPluginPauseChange(bool:pause);
129 * Called before every server frame. Note that you should avoid
130 * doing expensive computations here, and you should declare large
131 * local arrays using 'decl' instead of 'new'.
133 forward OnGameFrame();
136 * Called when the map is loaded.
138 * @note This used to be OnServerLoad(), which is now deprecated.
139 * Plugins still using the old forward will work.
141 forward OnMapStart();
144 * Called right before a map ends.
149 * Called when the map has loaded, servercfgfile (server.cfg) has been
150 * executed, and all plugin configs are done executing. This is the best
151 * place to inialize plugin functions which are based on cvar data.
153 * @note This will always be called once and only once per map. It will be
154 * called after OnMapStart().
158 forward OnConfigsExecuted();
161 * @deprecated Use OnConfigsExecuted() instead.
163 #pragma deprecated Use OnConfigsExecuted() instead
164 forward OnServerCfg();
167 * Called after all plugins have been loaded.
169 forward OnAllPluginsLoaded();
172 * Called when an action is going to be logged.
174 * @param source Handle to the object logging the action, or INVALID_HANDLE
175 * if Core is logging the action.
176 * @param ident Type of object logging the action (plugin, ext, or core).
177 * @param client Client the action is from; 0 for server, -1 if not applicable.
178 * @param target Client the action is targetting, or -1 if not applicable.
179 * @param message Message that is being logged.
180 * @return Plugin_Continue will cause Core to defaulty log the message.
181 * Plugin_Handled will stop Core from logging the message.
182 * Plugin_Stop is the same as Handled, but prevents any other
183 * plugins from handling the message.
185 forward Action:OnLogAction(Handle:source,
189 const String:message[]);
192 * Returns the calling plugin's Handle.
194 * @return Handle of the calling plugin.
196 native Handle:GetMyHandle();
199 * Returns an iterator that can be used to search through plugins.
201 * @return Handle to iterate with. Must be closed via
203 * @error Invalid Handle.
205 native Handle:GetPluginIterator();
208 * Returns whether there are more plugins available in the iterator.
210 * @param iter Handle to the plugin iterator.
211 * @return True on more plugins, false otherwise.
212 * @error Invalid Handle.
214 native bool:MorePlugins(Handle:iter);
217 * Returns the current plugin in the iterator and advances the iterator.
219 * @param iter Handle to the plugin iterator.
220 * @return Current plugin the iterator is at, before
221 * the iterator is advanced.
222 * @error Invalid Handle.
224 native Handle:ReadPlugin(Handle:iter);
227 * Returns a plugin's status.
229 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
230 * @return Status code for the plugin.
231 * @error Invalid Handle.
233 native PluginStatus:GetPluginStatus(Handle:plugin);
236 * Retrieves a plugin's file name relative to the plugins folder.
238 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
239 * @param buffer Buffer to the store the file name.
240 * @param maxlength Maximum length of the name buffer.
242 * @error Invalid Handle.
244 native GetPluginFilename(Handle:plugin, String:buffer[], maxlength);
247 * Retrieves whether or not a plugin is being debugged.
249 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
250 * @return True if being debugged, false otherwise.
251 * @error Invalid Handle.
253 native bool:IsPluginDebugging(Handle:hndl);
256 * Retrieves a plugin's public info.
258 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
259 * @param info Plugin info property to retrieve.
260 * @param buffer Buffer to store info in.
261 * @param maxlength Maximum length of buffer.
262 * @return True on success, false if property is not available.
263 * @error Invalid Handle.
265 native bool:GetPluginInfo(Handle:plugin, PluginInfo:info, String:buffer[], maxlength);
268 * Causes the plugin to enter a failed state. An error will be thrown and
269 * the plugin will be paused until it is unloaded or reloaded.
271 * @param string Message to print.
273 * @error Always throws SP_ERROR_ABORT.
275 native SetFailState(const String:string[]);
278 * Aborts the current callback and throws an error. This function
279 * does not return in that no code is executed following it.
281 * @param format String format.
282 * @param ... Format arguments.
286 native ThrowError(const String:fmt[], any:...);
289 * Logs a plugin message to the SourceMod logs. The log message will be
290 * prefixed by the plugin's logtag (filename).
292 * @param format String format.
293 * @param ... Format arguments.
296 native LogMessage(const String:format[], any:...);
299 * Logs a message to the SourceMod logs without any plugin logtag. This is
300 * useful for re-routing messages from other plugins, for example, messages
303 * @param format String format.
304 * @param ... Format arguments.
307 native LogMessageEx(const String:format[], any:...);
310 * Logs a message to any file. The log message will be in the normal
311 * SourceMod format, with the plugin logtag prepended.
313 * @param file File to write the log message in.
314 * @param format String format.
315 * @param ... Format arguments.
317 * @error File could not be opened/written.
319 native LogToFile(const String:file[], const String:format[], any:...);
322 * Same as LogToFile(), except no plugin logtag is prepended.
324 * @param file File to write the log message in.
325 * @param format String format.
326 * @param ... Format arguments.
328 * @error File could not be opened/written.
330 native LogToFileEx(const String:file[], const String:format[], any:...);
333 * Logs an action from a command or event whereby interception and routing may
334 * be important. This is intended to be a logging version of ShowActivity().
336 * @param client Client performing the action, 0 for server, or -1 if not
338 * @param target Client being targetted, or -1 if not applicable.
339 * @param message Message format.
340 * @param ... Message formatting parameters.
343 native LogAction(client, target, const String:message[], any:...);
346 * Logs a plugin error message to the SourceMod logs.
348 * @param format String format.
349 * @param ... Format arguments.
352 native LogError(const String:format[], any:...);
355 * Gets the system time as a unix timestamp.
357 * @param bigStamp Optional array to store the 64bit timestamp in.
358 * @return 32bit timestamp (number of seconds since unix epoch).
360 native GetTime(bigStamp[2]={0,0});
363 * Produces a date and/or time string value for a timestamp.
365 * See this URL for valid parameters:
366 * http://opengroup.org/onlinepubs/007908799/xsh/strftime.html
368 * @param buffer Destination string buffer.
369 * @param maxlength Maximum length of output string buffer.
370 * @param format Formatting rules (passing NULL_STRING will use the rules defined in sm_datetime_format).
371 * @param stamp Optional time stamp.
373 * @error Buffer too small or invalid time format.
375 native FormatTime(String:buffer[], maxlength, const String:format[], stamp=-1);
378 * Loads a game config file.
380 * @param file File to load. The path must be relative to the 'gamedata' folder under the config folder
381 * and the extension should be omitted.
382 * @return A handle to the game config file or INVALID_HANDLE in failure.
384 native Handle:LoadGameConfigFile(const String:file[]);
387 * Returns an offset value.
389 * @param gc Game config handle.
390 * @param key Key to retrieve from the offset section.
391 * @return An offset, or -1 on failure.
393 native GameConfGetOffset(Handle:gc, const String:key[]);
396 * Gets the value of a key from the "Keys" section.
398 * @param gc Game config handle.
399 * @param key Key to retrieve from the Keys section.
400 * @param buffer Destination string buffer.
401 * @param maxlen Maximum length of output string buffer.
402 * @return True if key existed, false otherwise.
404 native bool:GameConfGetKeyValue(Handle:gc, const String:key[], String:buffer[], maxlen);
407 * Returns the operating system's "tick count," which is a number of
408 * milliseconds since the operating system loaded. This can be used
409 * for basic benchmarks.
411 * @return Tick count in milliseconds.
413 native GetSysTickCount();
416 * Specifies that the given config file should be executed after plugin load.
417 * OnConfigsExecuted() will not be called until the config file has executed,
418 * but it will be called if the execution fails.
420 * @param autoCreate If true, and the config file does not exist, such a config
421 * file will be automatically created and populated with
422 * information from the plugin's registered cvars.
423 * @param name Name of the config file, excluding the .cfg extension.
424 * If empty, <plugin.filename.cfg> is assumed.
425 * @param folder Folder under cfg/ to use. By default this is "sourcemod."
428 native AutoExecConfig(bool:autoCreate=true, const String:name[]="", const String:folder[]="sourcemod");
431 * Sets a native as optional, such that if it is unloaded, removed,
432 * or otherwise non-existent, the plugin will still work. Calling
433 * removed natives results in a run-time error.
435 * @param name Native name.
438 native MarkNativeAsOptional(const String:name[]);
441 * Registers a library name for identifying as a dependency to
444 * @param name Library name.
447 native RegPluginLibrary(const String:name[]);
450 * Returns whether a library exists. This function should be considered
451 * expensive; it should only be called on plugin to determine availability
452 * of resources. Use OnLibraryAdded()/OnLibraryRemoved() to detect changes
453 * in optional resources.
455 * @param name Library name of a plugin or extension.
456 * @return True if exists, false otherwise.
458 native bool:LibraryExists(const String:name[]);
461 * Returns the status of an extension, by filename.
463 * @param name Extension name (like "sdktools.ext").
464 * @param error Optional error message buffer.
465 * @param maxlength Length of optional error message buffer.
466 * @return -2 if the extension was not found.
467 * -1 if the extension was found but failed to load.
468 * 0 if the extension loaded but reported an error.
469 * 1 if the extension is running without error.
471 native GetExtensionFileStatus(const String:name[], String:error[]="", maxlength=0);
474 * Called after a library is added that the current plugin references
475 * optionally. A library is either a plugin name or extension name, as
476 * exposed via its include file.
478 * @param name Library name.
480 forward OnLibraryAdded(const String:name[]);
483 * Called right before a library is removed that the current plugin references
484 * optionally. A library is either a plugin name or extension name, as
485 * exposed via its include file.
487 * @param name Library name.
489 forward OnLibraryRemoved(const String:name[]);
