Using Metamod
=-=-=-=-=-=-=

Installation
============

If you have installed Adminmod (www.adminmod.org/) 2.50 or later, then the
AM installer has already installed metamod for you. If you only want to
upgrade your metamod with a more recent version, simply grab the
metamod.dll (win32) or metamod_i386.so (linux) file and replace the file
currently on your system.

If you want to install metamod by hand, here's what you have to do:


  - Install the metamod file (.dll for win32, or .so for linux) to the
    "dlls" directory under your game directory. For instance, if you were
    running Counter-Strike, under win32 you would have:

        half-life/cstrike/dlls/metamod.dll

  - Edit the "liblist.gam" file in your game directory, replacing the game
    dll filename with the metamod dll filename. For instance with
    Counter-Strike, you would change:

        gamedll "dlls\mp.dll"
        gamedll_linux "dlls/cs_i386.so"

    to:

        gamedll "dlls\metamod.dll"
        gamedll_linux "dlls/metamod_i386.so"

    Note that it's only really necessary to change the line corresponding
    to your OS (win32 or linux); you can leave the other line unchanged,
    or you can change it - it doesn't matter.


Configuration: metamod.ini
==============

Plugins are described in a file "metamod.ini", in the game directory, and
each line describes a plugin to load:

    <platform> <filepath> [<description>]

Fields are whitespace delimited (tabs/spaces).

  - Platform is a keyword, either "linux" or "win32".

  - Filepath is a path to the DLL/so file. Relative paths are from the
    game dir; absolute paths are also valid. Paths should use unix-style
    forward slashes (/) and not backward slashes (\), even on windows
    platforms.

  - Description is an optional description of the plugin, used in place of
    the plugin's internal name in log messages and console output.
    Whitespace in the description _is_ allowed; quoting is unnecessary.

Comments are recognized at _only_ the beginning of a line, and can be in
either shell style ("#") or c++ style ("//").

For instance, in "cstrike/metamod.ini" these are all valid lines:

    // linux    dlls/mybot.so
    # win32     dlls/mybot-old.dll         Mybot old
    win32       dlls/mybot.dll             Mybot current
    linux       dlls/mm_stub_i386.so
    win32       dlls/mm_stub_i386.dll
    linux       dlls/mm_trace_i386.so
    win32       dlls/mm_trace_i386.dll
    linux       dlls/admin_MM.so
    win32       dlls/admin_MM.dll

Note that order in the metamod.ini file _is_ significant.

The file is re-read at changelevel, as well as on demand (via "meta
refresh" console command; see below). When the file is re-read, it will:

  - load any new plugins added to the file
  - unload any plugins that have been deleted from the file. This is only
    applicable to plugins loaded _from the inifile_. If the plugin was
    loaded from the console, it will not be unloaded during a refresh,
    whether it's in the inifile or not.
  - reload any plugin whose file on disk has been updated since it was
    loaded. Note this appears to be only useful under linux, as under
    Windows you cannot rename or overwrite an open DLL, so it doesn't look
    a loaded plugin could ever have a newer file on disk. Oh well.

The game dll is auto-detected, along the same lines AdminMod operated
(looking at the "gamedir"); see "metagame.ini" below if you want to use a
"bot" DLL.

You can override the name of this file by specifying it via the +localinfo
field "mm_pluginsfile".


Configuration: metaexec.cfg
==============

This is an optional file containing server commands or cvar settings, and
which is read by the server just after loading the initial plugins (from
metamod.ini).

This is necessary for plugins that need to have settings specified prior
to early API routines like ServerActivate, since autoexec.cfg is read too
early and server.cfg is read to late. In particular, I found this
necessary for the Trace plugin, in order to trace routines like RegUserMsg
which are called during ServerActivate.

You can override the name of this file by specifying it via the +localinfo
field "mm_execcfg".


Configuration: metagame.ini
==============

NOTE! This file is deprecated in favor of using +localinfo field "
mm_gamedll".

This is a file specifying a DLL to be loaded instead of the normal
gameDLL, and is necessary for things like most "bot" DLL's, which need to
sit between the HL engine and the game DLL. Syntax is merely:

    <filepath>

where filepath is the pathname of the DLL, relative to the gamedir. For
example:

    dlls/HPB_bot.dll

Note, paths should use unix-style forward slashes (/) and not backward
slashes (\), even on windows platforms.

With previous versions of AdminMod (2.10 and earlier), this same
functionality was provided by the file "admin.ini".


Configuration: +localinfo
========================

Several of metamod's configuration options can be specified by the
"+localinfo" facility on the hlds command line. This is similar to the
"setinfo" console command, where the syntax is:

    +localinfo <field> <value>

Current localinfo fields recognized by metamod:

  - mm_gamedll - specifies a game or Bot DLL to be used instead of the
    normal gameDLL. This replaces using the metagame.ini file.

  - mm_pluginsfile - specifies a file listing the metamod plugins to load,
    instead of using the file metamod.ini.

  - mm_execcfg - specifies a file containing cvar or other configs to be
    exec'd after loading the plugins, instead of using the file
    metaexec.cfg.

  - mm_debug - specifies an initial meta_debug value.

Some examples are:

        ./hlds_run -game cstrike +localinfo mm_gamedll dlls/pod_bot.so
        ./hlds_run -game cstrike +localinfo mm_pluginsfile mylist.ini
        ./hlds_run -game cstrike +localinfo mm_execcfg mysettings.cfg
        ./hlds_run -game cstrike +localinfo mm_debug 7

Note, paths should use unix-style forward slashes (/) and not backward
slashes (\), even on windows platforms.


Commands
========

All console command functionality is provide by a single command "meta",
with multiple sub-commands:

   usage: meta <command> [<arguments>]
   valid commands are:
      version                - display metamod version info
      list                   - list plugins currently loaded
      cmds                   - list console cmds registered by plugins
      cvars                  - list cvars registered by plugins
      refresh                - load/unload any new/deleted/updated plugins
      load <name>            - find and load a plugin with the given name
      unload <plugin>        - unload a loaded plugin
      reload <plugin>        - unload a plugin and load it again
      info <plugin>          - show all information about a plugin
      pause <plugin>         - pause a loaded, running plugin
      unpause <plugin>       - unpause a previously paused plugin
      retry <plugin>         - retry a plugin that previously failed its action
      clear <plugin>         - clear a failed plugin from the list
      force_unload <plugin>  - forcibly unload a loaded plugin

where <plugin> can be either the plugin index number, or a non-ambiguous
prefix string matching description or file.

Also, a single cvar is available:
   meta_debug       - set debugging level

For instance with:

   Currently loaded plugins:
         description       stat pend  file               vers    src  load  unlod
    [ 1] Trace HLSDK API   RUN   -    mm_trace_i386.so   v0.90   ini  ANY   Pause
    [ 2] adminmod          RUN   -    admin_MM.so        v2.11   ini  Start Start
    [ 3] stub              RUN   -    mm_stub_i386.so    v0.90   ini  ANY   Pause
   2 plugins, 2 running

You could then do any of the following to unload the API Trace plugin:
   meta unload 1
   meta unload trace
   meta unload mm_trace


Plugin Loading/Unloading Process
================================

Through the process of loading and unloading, a plugin can be in one of
several different states ('stat' column in the 'meta list' output):

  - BADFILE - The plugin file couldn't be found, or it doesn't appear to
    be a valid metamod plugin.
  - OPENED - The plugin file was found, and is a valid metamod plugin, and
    is ready to be loaded.
  - FAILED - The plugin file attempted to load or unload, but couldn't
    complete for some reason.
  - RUNNING - The plugin file was loaded and is active and running.
  - PAUSED - The plugin file was loaded, but has been temporarily
    disabled.

Also through the operation process, a plugin can have a pending "action"
to next take (indicated by the 'pend' column in the 'meta list' output),
and can be one of:

  - LOAD - Open and look at the plugin file.
  - ATTACH - Attach the plugin to the running game; ie activate it
  - UNLOAD - Remove the plugin from the running game and close the file
  - RELOAD - Unload/close and re-open/load the plugin, for instance when
    the plugin file has changed.


Example Output
==============

Here's some other example output:

   meta info admin
            name: adminmod
            desc: Adminmod
          status: running
          action: none
        filename: dlls/admin_MM.so
            file: admin_MM.so
        pathname: /home/willday/test/cstrike/dlls/admin_MM.so
           index: 3
          source: ini file
        loadable: at server startup
      unloadable: at server startup
         version: 2.11
            date: 2001/02/04
          author: Alfred Reynolds <alfred@mazuma.net.au>
             url: http://www.adminmod.org/
          logtag: ADMIN
     last loaded: Mon Feb  5 02:06:34 2001
   DLLAPI functions:
      GameDLLInit
      DispatchThink
      ClientConnect
      ClientCommand
      ClientUserInfoChanged
      ServerActivate
   6 functions (dllapi)
   No DLLAPI-Post functions.
   No NEWAPI functions.
   No NEWAPI-Post functions.
   No Engine functions.
   No Engine-Post functions.
   Registered commands:
      admin_command
   1 commands
   Registered cvars:                      float value  string value
      users_file                             0.000000  users.ini
      maps_file                              0.000000  mapvote.txt
      default_access                         1.000000  1
      ips_file                               0.000000  0
      reserve_slots                          1.000000  1
      reserve_slots_msg                      0.000000  0
      admin_debug                            1.000000  1
      password_field                         0.000000  admin_password
      alarm_message                          0.000000  0
      alarm_time                             0.000000  0
      use_regex                              1.000000  1
      models_password_field                  0.000000  0
      models_file                            0.000000  models.ini
      models_kick_msg                        0.000000  Invalid model
      script_file                            0.000000  cstrike/dlls/admin.amx
      help_file                              0.000000  admin_help.txt
      vote_freq                            360.000000  360
      encrypt_password                       1.000000  1
      pretty_say                             1.000000  1
      admin_mod_version                      2.110000  2.11
      reserve_type                           1.000000  1
      map_ratio                             60.000000  60
      kick_ratio                            75.000000  75
      words_file                             0.000000  0
      password_timeout                    1800.000000  1800
      file_access_read                       0.000000  0
      file_access_write                      0.000000  0
      public_slots_free                     20.000000  20.000000
      allow_client_exec                      0.000000  0
      admin_balance_teams                    0.000000  0
   30 cvars

   meta cmds
   Registered plugin commands:
          plugin              command
    [  1] API trace           trace_version
    [  2] API trace           trace
    [  3] API trace           untrace
    [  4] API trace           showtrace
    [  5] Adminmod            admin_command
   5 commands, 5 available

   meta cvars
   Registered plugin cvars:
          plugin      cvar                   float value  string value
    [  1] API trace   trace_debug               3.000000  3.000000
    [  2] API trace   trace_dllapi              8.000000  8
    [  3] API trace   trace_newapi              0.000000  0
    [  4] API trace   trace_engine              8.000000  8
    [  5] Adminmod    users_file                0.000000  users.ini
    [  6] Adminmod    maps_file                 0.000000  mapvote.txt
    [  7] Adminmod    default_access            1.000000  1
    [  8] Adminmod    ips_file                  0.000000  0
    [  9] Adminmod    reserve_slots             1.000000  1
    [ 10] Adminmod    reserve_slots_msg         0.000000  0
    [ 11] Adminmod    admin_debug               1.000000  1
    [ 12] Adminmod    password_field            0.000000  admin_password
    [ 13] Adminmod    alarm_message             0.000000  0
    [ 14] Adminmod    alarm_time                0.000000  0
    [ 15] Adminmod    use_regex                 1.000000  1
    [ 16] Adminmod    models_password_fiel      0.000000  0
    [ 17] Adminmod    models_file               0.000000  models.ini
    [ 18] Adminmod    models_kick_msg           0.000000  Invalid model
    [ 19] Adminmod    script_file               0.000000  cstrike/dlls/admin.amx
    [ 20] Adminmod    help_file                 0.000000  admin_help.txt
    [ 21] Adminmod    vote_freq               360.000000  360
    [ 22] Adminmod    encrypt_password          1.000000  1
    [ 23] Adminmod    pretty_say                1.000000  1
    [ 24] Adminmod    admin_mod_version         2.110000  2.11
    [ 25] Adminmod    reserve_type              1.000000  1
    [ 26] Adminmod    map_ratio                60.000000  60
    [ 27] Adminmod    kick_ratio               75.000000  75
    [ 28] Adminmod    words_file                0.000000  0
    [ 29] Adminmod    password_timeout       1800.000000  1800
    [ 30] Adminmod    file_access_read          0.000000  0
    [ 31] Adminmod    file_access_write         0.000000  0
    [ 32] Adminmod    public_slots_free        20.000000  20.000000
    [ 33] Adminmod    allow_client_exec         0.000000  0
    [ 34] Adminmod    admin_balance_teams       0.000000  0
   34 cvars, 34 available

   meta unload stub
   Unloaded plugin 'Stub plugin'
   Currently loaded plugins:
         description   stat pend  file             name         vers    ld  unl
    [ 1] Trace HLSDK API   RUN   -    mm_trace_i386.so   v0.90   ini  ANY   Pause
    [ 2] adminmod          RUN   -    admin_MM.so        v2.11   ini  Start Start
   2 plugins, 2 running

   meta load stub
   Loaded plugin 'stub' successfully
   Currently loaded plugins:
         description       stat pend  file               vers    src  load  unlod
    [ 1] Trace HLSDK API   RUN   -    mm_trace_i386.so   v0.90   ini  ANY   Pause
    [ 2] adminmod          RUN   -    admin_MM.so        v2.11   ini  Start Start
    [ 3] stub              RUN   -    mm_stub_i386.so    v0.90   cmd  ANY   Pause
   3 plugins, 3 running
