<h1>plugins<aclass="headerlink" href="#plugins" title="Link to this heading">¶</a></h1>
<p>This page contains tutorials about the <aclass="reference internal" href="../modules/plugins.html#module-plugins" title="plugins"><codeclass="xref py py-mod docutils literal notranslate"><spanclass="pre">plugins</span></code></a> package.</p>
<sectionid="plugininfo">
<h2>PluginInfo<aclass="headerlink" href="#plugininfo" title="Link to this heading">¶</a></h2>
<p>For every plugin a <aclass="reference internal" href="../modules/plugins.info.html#plugins.info.PluginInfo" title="plugins.info.PluginInfo"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">plugins.info.PluginInfo</span></code></a> instance can be retrieved,
even if the plugin isn’t loaded. The <aclass="reference internal" href="../modules/plugins.info.html#plugins.info.PluginInfo" title="plugins.info.PluginInfo"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">plugins.info.PluginInfo</span></code></a> instance
is created based on a file called <codeclass="docutils literal notranslate"><spanclass="pre">info.ini</span></code> that has to reside in the
plugin’s main directory. This file is completely optional. So, if it doesn’t
exist, the <aclass="reference internal" href="../modules/plugins.info.html#plugins.info.PluginInfo" title="plugins.info.PluginInfo"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">plugins.info.PluginInfo</span></code></a> instance will still be created,
but it won’t contain much more information beside the name of the plugin.</p>
<p>Here is an example <codeclass="docutils literal notranslate"><spanclass="pre">info.ini</span></code> file containing the most basic options:</p>
<divclass="highlight-ini notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># A verbose name of the plugin.</span>
<spanclass="c1"># If this option is not defined, the plugin's name will be used, all</span>
<spanclass="c1"># underscores are replaced with spaces and the first letter of every word is</span>
<spanclass="c1"># A description of what the plugin does.</span>
<spanclass="c1"># If this option is not defined, the plugin info will contain 'None'.</span>
<spanclass="na">description</span><spanclass="w"></span><spanclass="o">=</span><spanclass="w"></span><spanclass="s">"Adds paintball effects to the game."</span>
<spanclass="c1"># Version of the plugin.</span>
<spanclass="c1"># If this option is not defined, the plugin info will contain 'unversioned'.</span>
<p>You can also note which permissions are defined by your plugin. This helps
server owners to configure their authorization settings properly. See the
example below:</p>
<divclass="highlight-ini notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Permissions defined by the plugin.</span>
<spanclass="c1"># If this option is not defined, the plugin info will contain an empty list.</span>
<spanclass="k">[permissions]</span>
<spanclass="w"></span><spanclass="na">admin.kick</span><spanclass="w"></span><spanclass="o">=</span><spanclass="w"></span><spanclass="s">"Ability to kick a player."</span>
<spanclass="w"></span><spanclass="na">admin.ban</span><spanclass="w"></span><spanclass="o">=</span><spanclass="w"></span><spanclass="s">"Ability to ban a player."</span>
</pre></div>
</div>
<p>As soon as a plugin is being loaded, a public console variable is created that
<p>Since those are custom options, they are not displayed when the list of loaded
plugins is printed (e.g. via <codeclass="docutils literal notranslate"><spanclass="pre">sp</span><spanclass="pre">plugin</span><spanclass="pre">list</span></code>). If you want to change that
behaviour, you can define the <codeclass="docutils literal notranslate"><spanclass="pre">display_in_listing</span></code> option:</p>
<h3>Retrieving a PluginInfo instance<aclass="headerlink" href="#retrieving-a-plugininfo-instance" title="Link to this heading">¶</a></h3>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>If you retrieve a <aclass="reference internal" href="../modules/plugins.info.html#plugins.info.PluginInfo" title="plugins.info.PluginInfo"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">plugins.info.PluginInfo</span></code></a> instance of a plugin
that isn’t loaded, the <aclass="reference internal" href="../modules/plugins.info.html#plugins.info.PluginInfo" title="plugins.info.PluginInfo"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">plugins.info.PluginInfo</span></code></a> instance is
recreated everytime you retrieve it. Only loaded plugins will cache the
instance.</p>
</div>
<p>The following example will show how to retrieve a
<aclass="reference internal" href="../modules/plugins.info.html#plugins.info.PluginInfo" title="plugins.info.PluginInfo"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">plugins.info.PluginInfo</span></code></a> instance for a specific plugin.</p>
<p>You can also use this snippet outside of your plugin’s main file (e.g. in
other sub-modules or sub-packages).</p>
</section>
</section>
<sectionid="adding-sub-plugins">
<h2>Adding sub-plugins<aclass="headerlink" href="#adding-sub-plugins" title="Link to this heading">¶</a></h2>
<p>Adding sub-plugins to your plugin is done a very few steps. All you actually
need is a new instance of the <aclass="reference internal" href="../modules/plugins.manager.html#plugins.manager.PluginManager" title="plugins.manager.PluginManager"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">plugins.manager.PluginManager</span></code></a> class.
This instance allows you to load plugins from a specific directory.</p>
<p>Imagine your plugin resides in <codeclass="docutils literal notranslate"><spanclass="pre">../addons/source-python/plugins/my_plugin</span></code>
and within that directory you have created a new directory called <codeclass="docutils literal notranslate"><spanclass="pre">plugins</span></code>,
which should contain all sub-plugins of <codeclass="docutils literal notranslate"><spanclass="pre">my_plugin</span></code>. Then the plugin manager
<p>However, this doesn’t print any messages like Source.Python does when you load
a plugin via <codeclass="docutils literal notranslate"><spanclass="pre">sp</span><spanclass="pre">plugin</span><spanclass="pre">load</span></code>. If you would like to have those messages as
well, without implementing them on your own, you can simply create an instance
of <codeclass="docutils literal notranslate"><spanclass="pre">plugins.command.SubCommandManager</span></code>.</p>
<p>Now you can also load your sub-plugins using <codeclass="docutils literal notranslate"><spanclass="pre">my_plugin</span><spanclass="pre">plugin</span><spanclass="pre">load</span></code> and
unload them using <codeclass="docutils literal notranslate"><spanclass="pre">my_plugin</span><spanclass="pre">plugin</span><spanclass="pre">unload</span></code>.</p>
<p>There is only one last thing left to do. If your main plugin is being
unloaded, you should also unload all of your sub-plugins. It doesn’t cause any
problems with Source.Python if you don’t do that, because Source.Python also