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: 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: 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: 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: 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: 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:


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: darope@0:

darope@0:


darope@0: darope@0: darope@0: