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>
75 * Declare this as a struct in your plugin to expose its information.
78 * public Plugin:myinfo =
87 * Called when the plugin is fully initialized and all known external references are resolved.
88 * This is called even if the plugin type is "private."
89 * @note Errors in this function will cause the plugin to stop running.
93 forward OnPluginStart();
96 * Called before OnPluginStart, in case the plugin wants to check for load failure.
97 * This is called even if the plugin type is "private." Any natives from modules are
98 * not available at this point. Thus, this forward should only be used for explicit
99 * pre-emptive things, such as adding dynamic natives, or setting certain types of load filters.
101 * @note It is not safe to call externally resolved natives until OnPluginStart().
102 * @note Any sort of RTE in this function will cause the plugin to fail loading.
104 * @param myself Handle to the plugin.
105 * @param late Whether or not the plugin was loaded "late" (after map load).
106 * @param error Error message buffer in case load failed.
107 * @param err_max Maximum number of characters for error message buffer.
108 * @return True if load success, false otherwise.
110 forward bool:AskPluginLoad(Handle:myself, bool:late, String:error[], err_max);
113 * Called when the plugin is about to be unloaded.
117 forward OnPluginEnd();
120 * Called when the plugin's pause status is changing.
122 * @param pause True if the plugin is being paused, false otherwise.
125 forward OnPluginPauseChange(bool:pause);
128 * Called before every server frame. Note that you should avoid
129 * doing expensive computations here, and you should declare large
130 * local arrays using 'decl' instead of 'new'.
132 forward OnGameFrame();
135 * Called when the map is loaded.
137 * @note This used to be OnServerLoad(), which is now deprecated.
138 * Plugins still using the old forward will work.
140 forward OnMapStart();
143 * Called right before a map ends.
148 * Called when the map has loaded, servercfgfile (server.cfg) has been
149 * executed, and all plugin configs are done executing. This is the best
150 * place to inialize plugin functions which are based on cvar data.
152 * @note This will always be called once and only once per map. It will be
153 * called after OnMapStart().
157 forward OnConfigsExecuted();
160 * @deprecated Use OnConfigsExecuted() instead.
162 #pragma deprecated Use OnConfigsExecuted() instead
163 forward OnServerCfg();
166 * Called after all plugins have been loaded.
168 forward OnAllPluginsLoaded();
171 * Called when an action is going to be logged.
173 * @param source Handle to the object logging the action, or INVALID_HANDLE
174 * if Core is logging the action.
175 * @param ident Type of object logging the action (plugin, ext, or core).
176 * @param client Client the action is from; 0 for server, -1 if not applicable.
177 * @param target Client the action is targetting, or -1 if not applicable.
178 * @param message Message that is being logged.
179 * @return Plugin_Continue will cause Core to defaulty log the message.
180 * Plugin_Handled will stop Core from logging the message.
181 * Plugin_Stop is the same as Handled, but prevents any other
182 * plugins from handling the message.
184 forward Action:OnLogAction(Handle:source,
188 const String:message[]);
191 * Returns the calling plugin's Handle.
193 * @return Handle of the calling plugin.
195 native Handle:GetMyHandle();
198 * Returns an iterator that can be used to search through plugins.
200 * @return Handle to iterate with. Must be closed via
202 * @error Invalid Handle.
204 native Handle:GetPluginIterator();
207 * Returns whether there are more plugins available in the iterator.
209 * @param iter Handle to the plugin iterator.
210 * @return True on more plugins, false otherwise.
211 * @error Invalid Handle.
213 native bool:MorePlugins(Handle:iter);
216 * Returns the current plugin in the iterator and advances the iterator.
218 * @param iter Handle to the plugin iterator.
219 * @return Current plugin the iterator is at, before
220 * the iterator is advanced.
221 * @error Invalid Handle.
223 native Handle:ReadPlugin(Handle:iter);
226 * Returns a plugin's status.
228 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
229 * @return Status code for the plugin.
230 * @error Invalid Handle.
232 native PluginStatus:GetPluginStatus(Handle:plugin);
235 * Retrieves a plugin's file name relative to the plugins folder.
237 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
238 * @param buffer Buffer to the store the file name.
239 * @param maxlength Maximum length of the name buffer.
241 * @error Invalid Handle.
243 native GetPluginFilename(Handle:plugin, String:buffer[], maxlength);
246 * Retrieves whether or not a plugin is being debugged.
248 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
249 * @return True if being debugged, false otherwise.
250 * @error Invalid Handle.
252 native bool:IsPluginDebugging(Handle:hndl);
255 * Retrieves a plugin's public info.
257 * @param plugin Plugin Handle (INVALID_HANDLE uses the calling plugin).
258 * @param info Plugin info property to retrieve.
259 * @param buffer Buffer to store info in.
260 * @param maxlength Maximum length of buffer.
261 * @return True on success, false if property is not available.
262 * @error Invalid Handle.
264 native bool:GetPluginInfo(Handle:plugin, PluginInfo:info, String:buffer[], maxlength);
267 * Causes the plugin to enter a failed state. An error will be thrown and
268 * the plugin will be paused until it is unloaded or reloaded.
270 * @param string Message to print.
272 * @error Always throws SP_ERROR_ABORT.
274 native SetFailState(const String:string[]);
277 * Aborts the current callback and throws an error. This function
278 * does not return in that no code is executed following it.
280 * @param format String format.
281 * @param ... Format arguments.
285 native ThrowError(const String:fmt[], any:...);
288 * Logs a plugin message to the SourceMod logs. The log message will be
289 * prefixed by the plugin's logtag (filename).
291 * @param format String format.
292 * @param ... Format arguments.
295 native LogMessage(const String:format[], any:...);
298 * Logs a message to the SourceMod logs without any plugin logtag. This is
299 * useful for re-routing messages from other plugins, for example, messages
302 * @param format String format.
303 * @param ... Format arguments.
306 native LogMessageEx(const String:format[], any:...);
309 * Logs a message to any file. The log message will be in the normal
310 * SourceMod format, with the plugin logtag prepended.
312 * @param file File to write the log message in.
313 * @param format String format.
314 * @param ... Format arguments.
316 * @error File could not be opened/written.
318 native LogToFile(const String:file[], const String:format[], any:...);
321 * Same as LogToFile(), except no plugin logtag is prepended.
323 * @param file File to write the log message in.
324 * @param format String format.
325 * @param ... Format arguments.
327 * @error File could not be opened/written.
329 native LogToFileEx(const String:file[], const String:format[], any:...);
332 * Logs an action from a command or event whereby interception and routing may
333 * be important. This is intended to be a logging version of ShowActivity().
335 * @param client Client performing the action, 0 for server, or -1 if not
337 * @param target Client being targetted, or -1 if not applicable.
338 * @param message Message format.
339 * @param ... Message formatting parameters.
342 native LogAction(client, target, const String:message[], any:...);
345 * Logs a plugin error message to the SourceMod logs.
347 * @param format String format.
348 * @param ... Format arguments.
351 native LogError(const String:format[], any:...);
354 * Gets the system time as a unix timestamp.
356 * @param bigStamp Optional array to store the 64bit timestamp in.
357 * @return 32bit timestamp (number of seconds since unix epoch).
359 native GetTime(bigStamp[2]={0,0});
362 * Produces a date and/or time string value for a timestamp.
364 * See this URL for valid parameters:
365 * http://opengroup.org/onlinepubs/007908799/xsh/strftime.html
367 * @param buffer Destination string buffer.
368 * @param maxlength Maximum length of output string buffer.
369 * @param format Formatting rules (passing NULL_STRING will use the rules defined in sm_datetime_format).
370 * @param stamp Optional time stamp.
372 * @error Buffer too small or invalid time format.
374 native FormatTime(String:buffer[], maxlength, const String:format[], stamp=-1);
377 * Loads a game config file.
379 * @param file File to load. The path must be relative to the 'gamedata' folder under the config folder
380 * and the extension should be omitted.
381 * @return A handle to the game config file or INVALID_HANDLE in failure.
383 native Handle:LoadGameConfigFile(const String:file[]);
386 * Returns an offset value.
388 * @param gc Game config handle.
389 * @param key Key to retrieve from the offset section.
390 * @return An offset, or -1 on failure.
392 native GameConfGetOffset(Handle:gc, const String:key[]);
395 * Gets the value of a key from the "Keys" section.
397 * @param gc Game config handle.
398 * @param key Key to retrieve from the Keys section.
399 * @param buffer Destination string buffer.
400 * @param maxlen Maximum length of output string buffer.
401 * @return True if key existed, false otherwise.
403 native bool:GameConfGetKeyValue(Handle:gc, const String:key[], String:buffer[], maxlen);
406 * Returns the operating system's "tick count," which is a number of
407 * milliseconds since the operating system loaded. This can be used
408 * for basic benchmarks.
410 * @return Tick count in milliseconds.
412 native GetSysTickCount();
415 * Specifies that the given config file should be executed after plugin load.
416 * OnConfigsExecuted() will not be called until the config file has executed,
417 * but it will be called if the execution fails.
419 * @param autoCreate If true, and the config file does not exist, such a config
420 * file will be automatically created and populated with
421 * information from the plugin's registered cvars.
422 * @param name Name of the config file, excluding the .cfg extension.
423 * If empty, <plugin.filename.cfg> is assumed.
424 * @param folder Folder under cfg/ to use. By default this is "sourcemod."
427 native AutoExecConfig(bool:autoCreate=true, const String:name[]="", const String:folder[]="sourcemod");
430 * Sets a native as optional, such that if it is unloaded, removed,
431 * or otherwise non-existent, the plugin will still work. Calling
432 * removed natives results in a run-time error.
434 * @param name Native name.
437 native MarkNativeAsOptional(const String:name[]);
440 * Registers a library name for identifying as a dependency to
443 * @param name Library name.
446 native RegPluginLibrary(const String:name[]);
449 * Returns whether a library exists. This function should be considered
450 * expensive; it should only be called on plugin to determine availability
451 * of resources. Use OnLibraryAdded()/OnLibraryRemoved() to detect changes
452 * in optional resources.
454 * @param name Library name of a plugin or extension.
455 * @return True if exists, false otherwise.
457 native bool:LibraryExists(const String:name[]);
460 * Returns the status of an extension, by filename.
462 * @param name Extension name (like "sdktools.ext").
463 * @param error Optional error message buffer.
464 * @param maxlength Length of optional error message buffer.
465 * @return -2 if the extension was not found.
466 * -1 if the extension was found but failed to load.
467 * 0 if the extension loaded but reported an error.
468 * 1 if the extension is running without error.
470 native GetExtensionFileStatus(const String:name[], String:error[]="", maxlength=0);
473 * Called after a library is added that the current plugin references
474 * optionally. A library is either a plugin name or extension name, as
475 * exposed via its include file.
477 * @param name Library name.
479 forward OnLibraryAdded(const String:name[]);
482 * Called right before a library is removed that the current plugin references
483 * optionally. A library is either a plugin name or extension name, as
484 * exposed via its include file.
486 * @param name Library name.
488 forward OnLibraryRemoved(const String:name[]);
