# vi: set ts=4 sw=4 :
# vim: set tw=75 :

Configuration
=============

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.  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.  Description is a (short)
description of the plugin (whitespace _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	My simple bot
	win32 dlls/mybot.dll	My simple bot
	#linux dlls/admin-wd_i386.so	Adminmod (wd)
	linux /tmp/mm_stub_i386.so	Stub plugin
	linux dlls/mm_trace_i386.so	API trace
	linux dlls/mm_admin_i386.so	Adminmod

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, 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").


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
      refresh                - load/unload any new/deleted/updated plugins
      list                   - list plugins currently loaded
      cmds                   - list console cmds registered by plugins
      cvars                  - list cvars registered by plugins
      pause <plugin>         - pause a loaded, running plugin
      unpause <plugin>       - unpause a previously paused plugin
      unload <plugin>        - unload a loaded plugin
      force_unload <plugin>  - forcibly unload a loaded plugin
      reload <plugin>        - unload a plugin and load it again
      retry <plugin>         - retry a plugin that previously failed to load, etc
      clear <plugin>         - clear a failed plugin from the list
      info <plugin>          - show all information about a plugin

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

For instance with:

   meta list
   Currently loaded plugins:
         description      stat pend  file             name         vers    ld  unl
    [ 1] Stub plugin      RUN   -    mm_stub_i386.so  stub         v0.9    ANY Pau
    [ 2] API trace        RUN   -    mm_trace_i386.s  Trace HLSDK  v0.9    ANY Pau
    [ 3] Adminmod         RUN   -    mm_admin.so      adminmod     v2.11   Sta Sta
   3 plugins, 3 running

You could then do any of the following to unload the Stub plugin:
   meta unload 2
   meta unload api
   meta unload trace
   meta unload mm_trace

Here's some other example output:

   meta info 
   meta info admin
            name: adminmod
            desc: Adminmod
          status: running
          action: none
        filename: dlls/mm_admin.so
            file: mm_admin.so
        pathname: /home/willday/test/cstrike/dlls/mm_admin.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 for Counter-Strike
      script_file                            0.000000  cstrike/dlls/admin.amx
      help_file                              0.000000  adminmod_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 for Counter-Strike
    [ 19] Adminmod       script_file                  0.000000  cstrike/dlls/admin.amx
    [ 20] Adminmod       help_file                    0.000000  adminmod_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
    [ 2] API trace        RUN   -    mm_trace_i386.s  Trace HLSDK  v0.9    ANY Pau
    [ 3] Adminmod         RUN   -    mm_admin.so      adminmod     v2.11   Sta Sta
   2 plugins, 2 running
   
   meta load stub
   Loaded plugin 'stub' successfully
   Currently loaded plugins:
         description      stat pend  file             name         vers    ld  unl
    [ 1] stub             RUN   -    mm_stub_i386.so  stub         v0.9    ANY Pau
    [ 2] API trace        RUN   -    mm_trace_i386.s  Trace HLSDK  v0.9    ANY Pau
    [ 3] Adminmod         RUN   -    mm_admin.so      adminmod     v2.11   Sta Sta
   3 plugins, 3 running

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