darope@0:
darope@0:
darope@0:
darope@0:
darope@0:
darope@0: Coding for Metamod
darope@0:
darope@0:
darope@0:
darope@0: Coding for Metamod
darope@0:
darope@0:
darope@0:
darope@0:
darope@0: Compiling
darope@0:
darope@0:
darope@0: You'll need the Half-Life SDK, of course. In particular you'll need HL SDK
darope@0: version 2.3. You can find the original SDK 2.3 at the Valve Editing Resource Center (VERC),
darope@249: and a modified version of SDK 2.3 at metamod.org/files/sdk.
darope@0:
darope@0:
darope@0:
darope@0: Operation
darope@0:
darope@0:
darope@0: The basic operation is, for each api call:
darope@0:
darope@0:
darope@0: - iterate through list of plugins
darope@0:
- for each plugin, if it provides this api call, then call the function
darope@0: in the plugin
darope@0:
- call the "real" function (in the game dll, or from the engine)
darope@0:
- for each plugin, check for a "post" version of the function, and call
darope@0: if present
darope@0:
darope@0:
darope@0: Also, for any api call, each plugin has the opportunity to replace the
darope@0: real routine, in two ways:
darope@0:
darope@0:
darope@0: - prevent the real routine from being called (SUPERCEDE).
darope@0:
- allow the real routine to be called, but change the value that's
darope@0: returned (OVERRIDE)
darope@0:
darope@0:
darope@0: Thus after each plugin is called, its META_RESULT flag is
darope@0: checked, and action taken appropriately. Note that supercede/override only
darope@0: affects the _real_ routine; other plugins will still be called.
darope@0:
darope@0: In addition to the SUPERCEDE and
darope@0: OVERRIDE flags, there are two additional flags a plugin can
darope@0: return:
darope@0:
darope@0:
darope@0: - HANDLED ("I did something here")
darope@0:
- IGNORED ("I didn't really do anything")
darope@0:
darope@0:
darope@0: These aren't used by Metamod itself, but could be used by plugins to
darope@0: get an idea if a previous plugin did anything.
darope@0:
darope@0: Note that each routine needs to set its
darope@0: META_RESULT value before returning. Plugin routines that
darope@0: do not set a value will be reported as errors in the logs.
darope@0:
darope@0:
darope@0:
darope@0: Plugin coding requirements
darope@0:
darope@0:
darope@0: Plugins must provide the following standard HLSDK exported function:
darope@0:
darope@0:
darope@0: void GiveFnptrsToDll(enginefuncs_t* pengfuncsFromEngine, globalvars_t *pGlobals);
darope@0:
darope@0:
darope@0: As well as the following new functions:
darope@0:
darope@0:
darope@0: void Meta_Init(void); (optional)
darope@0: int Meta_Query(char *interfaceVersion, plugin_info_t **pinfo, mutil_funcs_t *pMetaUtilFuncs);
darope@0: int Meta_Attach(PLUG_LOADTIME now, META_FUNCTIONS *pFunctionTable, meta_globals_t *pMGlobals, gamedll_funcs_t *pGamedllFuncs);
darope@0: int Meta_Detach(PLUG_LOADTIME now, PL_UNLOAD_REASON reason);
darope@0:
darope@0:
darope@0: Also, it must provide at least one function returning a standard HL
darope@0: function table, from either the following standard HLSDK functions:
darope@0:
darope@0:
darope@0: int GetEntityAPI( DLL_FUNCTIONS *pFunctionTable, int interfaceVersion );
darope@0: int GetEntityAPI2( DLL_FUNCTIONS *pFunctionTable, int *interfaceVersion );
darope@0: int GetNewDLLFunctions( NEW_DLL_FUNCTIONS *pNewFunctionTable, int *interfaceVersion );
darope@0:
darope@0:
darope@0: or from the following new functions:
darope@0:
darope@0:
darope@0: int GetEntityAPI_Post(DLL_FUNCTIONS *pFunctionTable, int interfaceVersion);
darope@0: int GetEntityAPI2_Post(DLL_FUNCTIONS *pFunctionTable, int *interfaceVersion ;
darope@0: int GetNewDLLFunctions_Post(NEW_DLL_FUNCTIONS *pNewFunctionTable, int *interfaceVersion);
darope@0:
darope@0: int GetEngineFunctions(enginefuncs_t *pengfuncsFromEngine, int *interfaceVersion);
darope@0: int GetEngineFunctions_Post(enginefuncs_t *pengfuncsFromEngine, int *interfaceVersion);
darope@0:
darope@0:
darope@0: Thus, it needs to have (at least):
darope@0:
darope@0: GiveFnptrsToDll
darope@0: Meta_Query
darope@0: Meta_Attach
darope@0: Meta_Detach
darope@0: <one or more Get function>
darope@0:
darope@0:
darope@0: See the "stub_plugin" for an example of bare
darope@0: minimum code. See "trace_plugin" for an example of
darope@0: more complete functionality.
darope@0:
darope@0:
Also, if the plugin needs to use LINK_ENTITY_TO_CLASS,
darope@0: support for the particular entity(ies) has to be added explicitly to
darope@0: Metamod (linkfunc.cpp), just as it does for entities in game DLLs.
darope@0:
darope@0:
darope@0:
darope@0: Operation Details
darope@0:
darope@0:
darope@0:
These are the valid META_RESULT values a plugin routine can
darope@0: specify:
darope@0:
darope@0:
darope@0:
darope@0: MRES_IGNORED
darope@0:
The plugin did nothing. This could be used to tell a subsequent
darope@0: plugin that the some situation hasn't been handled yet. This would be
darope@0: recognized only by other plugins; Metamod itself doesn't do anything
darope@0: special for this situation. Unless otherwise specified by a later
darope@0: plugin, execution of routine in the gameDLL will take place. This is
darope@0: valid in both normal and post routines.
darope@0:
darope@0: MRES_HANDLED
darope@0:
The plugin handled the situation, or did something with the
darope@0: information. Again, this could be used to tell a subsequent plugin
darope@0: that some situation has already been taken care of, and is not
darope@0: recognized specially by Metamod. Unless otherwise specified by a later
darope@0: plugin, execution of routine in the gameDLL will take place. This is
darope@0: valid in both normal and post routines.
darope@0:
darope@0: MRES_OVERRIDE
darope@0:
The plugin is providing a return value for the routine, which
darope@0: should be used in place of the return value from the gameDLL's routine
darope@0: (the plugin "overrides" the gameDLL's return value).
darope@0: Unless otherwise specified by a later plugin, the gameDLL routine will
darope@0: still be called. Note this only makes sense for non-void routines.
darope@0: This is valid in both normal and post routines.
darope@0:
darope@0: MRES_SUPERCEDE
darope@0:
The plugin has performed sufficient actions for the routine, and
darope@0: the gameDLL's routine should not be called (the plugin
darope@0: "supercedes" the gameDLL's routine, more or less replacing it
darope@0: entirely). Any return value for the routine should be specified as
darope@0: well by the plugin. Note this is only valid for normal routines, as
darope@0: post routines cannot prevent calling the gameDLL's routine (as it has
darope@0: already happened!). Also note, this doesn't prevent subsequent plugins
darope@0: from being called for this routine; it supercedes only
darope@0: the gameDLL.
darope@0:
darope@0:
darope@0: As the plugins are called, a running status is kept of the "highest" meta
darope@0: status so far, in the order (lowest to highets) shown above. After calling
darope@0: all the "normal" routines, the status is checked to see if the gameDLL's
darope@0: routine should be called - ie, it will not be called if one (or more) of
darope@0: the plugin's has specified META_SUPERCEDE. The gameDLL's
darope@0: routine is then called, or skipped, as appropriate. Then, all the "post"
darope@0: routines are called in the same manner (except
darope@0: META_SUPERCEDE is no longer a valid meta result).
darope@0:
darope@0: Last, if any plugins specified META_OVERRIDE or
darope@0: META_SUPERCEDE, the return value given by the
darope@0: last such plugin is returned as the routine's return code to
darope@0: the engine (assuming a non-void routine). Thus, the order of the plugins
darope@0: as specified in the metamod.ini does have a possible
darope@0: effect.
darope@0:
darope@0:
darope@0:
darope@0:
darope@0: Available Macros
darope@0:
darope@0:
darope@0: The meta_api.h
darope@0: header that describes the Metamod API functions, types, and structures also
darope@0: includes several macros that can be of help when coding a plugin.
darope@0:
darope@0:
darope@0:
darope@0: SET_META_RESULT(result)
darope@0:
Sets the META_RESULT for the plugin.
darope@0:
darope@0: RETURN_META(result)
darope@0:
Sets the META_RESULT for the plugin, and then calls
darope@0: return. This assumes a void function.
darope@0:
darope@0: RETURN_META_VALUE(result, value)
darope@0:
Sets the META_RESULT for the plugin, and then returns the
darope@0: given value. This assumes a non-void function, and
darope@0: it doesn't matter the particular type of the return value.
darope@0:
darope@0: META_RESULT_STATUS
darope@0:
Gives the current status of META_RESULT for this routine
darope@0: from plugins so far. It will return the "highest" result so far, in
darope@0: the order of lesser to greater: IGNORED, HANDLED,
darope@0: OVERRIDE, SUPERCEDE (see also above Operation Details)
darope@0:
darope@0: META_RESULT_PREVIOUS
darope@0:
Gives the META_RESULT of the previous plugin.
darope@0:
darope@0: META_RESULT_ORIG_RET(type)
darope@0:
Gives the "original" return value for the routine, ie the return
darope@0: value of the routine from gameDLL. The type for the routine's return
darope@0: value must be specified in the macro; this is used as a cast for
darope@0: assignment. Note this is only valid in a "post" routine.
darope@0:
darope@0: META_RESULT_OVERRIDE_RET(type)
darope@0:
Gives the return value from any previous plugin that specified
darope@0: META_OVERRIDE or META_SUPERCEDE. The
darope@0: type for the routine's return value must be specified in the macro;
darope@0: this is used as a cast for assignment. This should only be used after
darope@0: checking the META_RESULT to see if there's actually an override value
darope@0: available.
darope@0:
darope@0: MDLL_*(args)
darope@0:
Calls a given DLLAPI routine in the gameDLL. For instance,
darope@0: MDLL_GameDLLInit(args), MDLL_Spawn(args),
darope@0: etc.
darope@0:
darope@0: MNEW_*(args)
darope@0:
Calls a given NEWAPI routine in the gameDLL. For instance,
darope@0: MNEW_GameShutdown(args), etc.
darope@0:
darope@0:
darope@0:
darope@0:
darope@0:
darope@0: Utility Callback Functions
darope@0:
darope@0:
darope@0: In version 1.05, Metamod began providing a set of utility functions to
darope@0: plugins to centralize functionality, reduce code reuse, and to provide some
darope@0: convenience in plugin coding. Presently, only a few functions are
darope@0: provided. More are added as I find the time, and identify some advantage
darope@0: to having them (either for my own plugins, or by others' request for their
darope@0: plugins).
darope@0:
darope@0:
Note the PLID keyword passed to each function. This is
darope@0: basically a "plugin id" to indicate to Metamod which plugin is calling the
darope@0: function (else it's difficult to tell), and is a macro that should be
darope@0: specified verbatim with each call. (Currently, the macro is merely the
darope@0: plugin_info struct pointer returned by the plugin via Meta_Query;
darope@0: in the future this could change to some other identifier.)
darope@0:
darope@0:
darope@0:
darope@0: void LOG_CONSOLE(PLID, char *fmt, ...)
darope@0:
Print a message line on the console. Message is specified as a
darope@0: printf style format string and arguments. A trailing newline
darope@0: is provided by the routine and should not be specified in the string
darope@0: (unless you want two newlines).
darope@0:
darope@0: void LOG_MESSAGE(PLID, char *fmt, ...)
darope@0:
Print a message line in the server logs. Message is specified as a
darope@0: printf style format string and arguments. A trailing newline
darope@0: is provided by the routine and should not be specified in the string.
darope@0: Log message is prefixed by the logtag string in the plugin's
darope@0: "info" struct, surrounded by brackets. For instance:
darope@0: L 04/17/2001 - 18:00:35: [TraceAPI] Tracing Engine routine 'RegUserMsg'
darope@0:
darope@0: void LOG_ERROR(PLID, char *fmt, ...)
darope@0:
As in LOG_MESSAGE above, only marked as well with the
darope@0: string "ERROR:". For example:
darope@0:
L 04/17/2001 - 18:03:13: [TraceAPI] ERROR: malloc failed
darope@0:
darope@0: void LOG_DEVELOPER(PLID, char *fmt, ...)
darope@0:
As in LOG_MESSAGE above, only message will be logged only
darope@0: if cvar developer is set to 1; message is marked as well with
darope@0: the string "dev:". For example:
darope@0:
L 04/17/2001 - 18:03:13: [TraceAPI] dev: called: GiveFnptrsToDll
darope@0:
darope@0: void CENTER_SAY(PLID, char *fmt, ...)
darope@0:
Prints a message on the center of all players' screens. This is
darope@0: like the "centersay" of AdminMod, with pretty_say enabled, with the
darope@0: same defaults (green, and a 10 second fade-in). A message is logged as
darope@0: well, ie: [added in 1.06]
darope@0:
L 04/17/2001 - 15:44:52: [WDMISC] (centersay) random set up us the bomb!
darope@0:
darope@0: void CENTER_SAY_PARMS(PLID, hudtextparms_t tparms, char *fmt, ...)
darope@0:
As in CENTER_SAY above, but allows specifying all the
darope@0: parameters. (see SDK dlls/util.h for the struct
darope@0: hudtextparms_t). [added in 1.06]
darope@0:
darope@0: void CENTER_SAY_VARARGS(PLID, hudtextparms_t tparms, char *fmt, va_list ap)
darope@0:
As in CENTER_SAY_PARMS above, only the message is passed
darope@0: as a vsnprintf style varargs format string and args list.
darope@0: This is included merely because both the previous CENTER_SAY functions
darope@0: actually call this, and it was convenient to include it as well.
darope@0: [added in 1.06]
darope@0:
darope@0: qboolean CALL_GAME_ENTITY(PLID, char *entStr, entvars_t *pev)
darope@0:
Calls an entity function in the gameDLL. For instance, a bot usually
darope@0: needs to call the player entity function.
darope@0: [added in 1.09]
darope@0:
darope@0: int GET_USER_MSG_ID(PLID, const char *name, int *size)
darope@0:
Returns the id number corresponding to the given message name, of
darope@0: those messages registered by the gamedll with RegUserMsg, optionally
darope@0: returning the registered size of the message as well. This is to
darope@0: allow things like bots to access the name/id mapping without having to
darope@0: catch RegUserMsg themselves, and thus have to be loaded at startup.
darope@0: [added in 1.11]
darope@0:
darope@0: const char * GET_USER_MSG_NAME(PLID, int msgid, int *size)
darope@0:
Returns the name corresponding to the given msgid number, of those
darope@0: messages registered by the gamedll with RegUserMsg, optionally
darope@0: returning the registered size of the message as well. It will return
darope@0: guess-names for any builtin Engine messages that it knows about
darope@0: (SVC_TEMPENTITY, etc). The returned string is presumed to be
darope@0: a compile-time constant string, stored in the text segment of the
darope@0: gamedll.
darope@0: [added in 1.11]
darope@0:
darope@0: const char * GET_PLUGIN_PATH(PLID)
darope@0:
Returns the full pathname of the loaded dll/so file for the calling
darope@0: plugin. The returned string is a pointer to a static buffer, and should be
darope@0: copied by the caller to local storage.
darope@0: [added in 1.12]
darope@0:
darope@0: const char * GET_GAME_INFO(PLID, ginfo_t type)
darope@0:
Returns various string-based information about the running
darope@0: game/MOD/gamedll. The given type can be one of:
darope@0:
darope@0: - GINFO_NAME - short name of game, from "-game" argument to hlds (ie "cstrike")
darope@0:
- GINFO_DESC - long name of game, from autodetection (ie "Counter-Strike")
darope@0:
- GINFO_GAMEDIR - game directory, full pathname (ie "/usr/local/half-life/cstrike")
darope@0:
- GINFO_DLL_FULLPATH - full pathname of the game dll (ie "/usr/local/half-life/cstrike/dlls/cs_i386.so")
darope@0:
- GINFO_DLL_FILENAME - bare filename of the gamedll (ie "cs_i386.so")
darope@0:
darope@0: The returned string is a pointer to a static buffer, and should be
darope@0: copied by the caller to local storage.
darope@0: [added in 1.14]
darope@248:
darope@248: int LOAD_PLUGIN(PLID, const char *name, PLUG_LOADTIME now, void **handle)
darope@248:
Attempts to load a plugin as if "meta load <name>" was passed. If
darope@248: handle is passed, it will be NULL on failure or contain the DLL handle on success.
darope@248: Returns 0 for success, non-zero Metamod error value for failure.
darope@248: [added in 1.18]
darope@248:
darope@248: int UNLOAD_PLUGIN(PLID, const char *name, PLUG_LOADTIME now, PL_UNLOAD_REASON reason)
darope@248:
Attempts to unload a plugin given by name. A plugin cannot unload itself.
darope@248: Returns 0 for success, non-zero Metamod error value for failure.
darope@248: [added in 1.18]
darope@248:
darope@248: int UNLOAD_PLUGIN_BY_HANDLE(PLID, void *handle, PLUG_LOADTIME now, PL_UNLOAD_REASON reason)
darope@248:
Attempts to unload a plugin given by the DLL handle from LOAD_PLUGIN. A plugin cannot unload itself.
darope@248: Returns 0 for success, non-zero Metamod error value for failure.
darope@248: [added in 1.18]
darope@248:
darope@248: const char *IS_QUERYING_CLIENT_CVAR(PLID, const edict_t
darope@249: *player) OBSOLETE
darope@248:
Returns the current cvar name that a client is being queried for,
darope@248: NULL if no queries are in session.
darope@248: [added in 1.18]
darope@249:
This function is considered obsolete as the new method of
darope@249: querying a client's cvar (added in hlsdk-2.3-p3/MM 1.18.1) is much more
darope@249: reliable than the old one and doesn't need this function anymore. It is
darope@249: strongly recommended to not use this function and the old
darope@249: QueryClientCvar() and CvarValue() functions anymore, but only use the
darope@249: new QueryClientCvar2() and CvarValue2() functions.
darope@249:
Note: This function can only be used in conjunction with the
darope@249: old QueryClientCvar() function. Use with the new QueryClientCvar2()
darope@249: function is not needed and therefor undefined, i.e. it doesn't return
darope@249: anything meaningful when used in conjunction with it.
darope@250:
darope@250: int MAKE_REQUEST_ID(PLID)
darope@250:
Returns a unique integer that can be passed to the ClientCvarQuery2
darope@250: engine function. The integer is designed to be identifiable from
darope@250: requests the GameDLL might make, and also unique among plugins.
darope@250: [added in 1.19]
darope@250:
darope@250: void *GET_HOOK_TABLES(PLID, enginefuncs_t **, DLL_FUNCTIONS **, NEW_DLL_FUNCTIONS **)
darope@250:
darope@250:
Returns pointers to tables that contain the Metamod hook functions. These can be used
darope@250: to make engine or GameDLL calls that are interceptable by other plugins. Use with caution,
darope@250: as calling a hook from a hook can lead to infinite recursion in some scenarios.
darope@250: [added in 1.19]
darope@0:
darope@0:
darope@0:
darope@0:
darope@0: Plugin Loading
darope@0:
darope@0:
darope@0: (this is some rough notes I intend to fill in in the future)
darope@0:
darope@0: Plugins are loaded when the engine calls GiveFnptrsToDll().
darope@0: The config file is parsed, and for each valid plugin (uncommented, platform
darope@0: relevant), the operation is:
darope@0:
darope@0:
darope@0: - dlopen() the file, store the handle
darope@0:
- dlsym() and call:
darope@0:
darope@0: Meta_Init (if present)
darope@0: GiveFnptrsToDll
darope@0: Meta_Query
darope@0: Meta_Attach
darope@0:
darope@0: - if present, call function pointers, and store resulting function table:
darope@0:
darope@0: GetEntityAPI
darope@0: GetEntityAPI2
darope@0: GetNewDLLFunctions
darope@0:
darope@0: GetEntityAPI_Post
darope@0: GetEntityAPI2_Post
darope@0: GetNewDLLFunctions_Post
darope@0:
darope@0: GetEngineFunctions
darope@0: GetEngineFunctions_Post
darope@0:
darope@0:
darope@0:
darope@0:
darope@0:
darope@0:
darope@0:
darope@0: