A fork of JJMumblebot which is a complete mess
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
JJMumbleBot/docs/wiki/general/plugins.html

83 lines
4.6 KiB

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>JJMumbleBot - Plugins</title>
<link rel="stylesheet" href="https://bootswatch.com/4/darkly/bootstrap.css" crossorigin="anonymous">
<link rel="stylesheet" href="https://duckboss.github.io/JJMumbleBot/css/content-pages.css" crossorigin="anonymous">
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
<script src="https://duckboss.github.io/JJMumbleBot/js/insert_html.js"></script>
</head>
<body>
<nav id="table_of_contents"></nav>
<div class="main-content">
<h2 id="page-title">Plugin System</h2>
<hr>
<p>
<b>Plugins are a way to expand the functionality of JJMumbleBot.</b> <br>
JJMumbleBot comes built-in with the <a href="https://duckboss.github.io/JJMumbleBot/wiki/plugins/core/bot_commands_plugin.html"><b>Bot Commands Plugin</b></a>,
<a href="https://duckboss.github.io/JJMumbleBot/wiki/plugins/extensions/images_plugin.html"><b>Images Plugin</b></a>, <a
href="https://duckboss.github.io/JJMumbleBot/wiki/plugins/extensions/media_plugin.html"><b>Media Plugin</b></a> and more.
<br>
</p>
<h2>Creating Custom Plugins</h2>
<p>
<b>Plugins are easy to create with the provided 'plugin_template.py' file.</b> <br>
Every plugin must be named 'Plugin' and derive from the PluginBase class and implement its methods.<br> Using the
<code>plugin_template.py</code> file is highly recommended to quickly create functional plugins for JJMumbleBot.<br>
<b>All custom plugins must be placed in the plugins/extensions/ directory.</b><br>
<div>
<p><b>If you are a developer looking to make a JJMumbleBot plugin, but don't know where to start</b>,<br/>
then generate a template plugin like so: <code>python3 JJMumbleBot/utility/plugin_template_generator.py my_example_plugin</code>.<br/>
This plugin will be generated in the <code>JJMumbleBot/user_generated/</code>directory, and must be placed in the <code>JJMumbleBot/plugins/extensions/</code>directory to work.</p>
</div>
<b> Basic Steps: </b><br>
<ol>
<li>Create a python file and create a class with the name 'Plugin' that derives from the PluginBase class.<br><i>Look
at the <code>plugin_template.py</code> file for more information.</i></li>
<li>Implement all the methods from the <b><code>PluginBase</code> abstract class</b>.</li>
<li>Use the <code>__init__ constructor</code> to initialize the plugin.</li>
<li>Create a method per command in the format: <code>cmd_mycommand</code> to process commands from users</li>
<ul>
<li>Be sure to prefix every command method with <code>cmd_</code> before your command name</li>
<li>You're provided with the user's text in every plugin to use.</li>
<li>If you need to reference the mumble instance, use the instance from the global_access script.</li>
</ul>
<li>Use the <b>quit method</b> to stop any processes created by the plugin and clean-up other code before the bot
quits
</li>
</ol>
<b>Take a look at the built-in plugins to get a good idea of how the plugin-system works.</b><br>
</p>
<h2> Advanced features: </h2>
<h4> Plugin callback system: Allows plugin callbacks for mumble server events. </h4>
Is it a system that all plugins can use to directly interface with mumble server events such as receiving audio,
messages, user connection/disconnection, etc.<br>
For example, if you want a plugin to execute some code in response to a user connecting to the server, that is now
possible!
<br>
<b>Simple Setup</b>
<ul>
<li>Create a method:<br>
<code>def my_plugin_method(self): ... </code>
</li>
<li>Import the global_settings script:<br>
<code>from JJMumbleBot.settings import global_settings</code>
</li>
<li>Register the plugin method to the core callbacks of the global_settings script:<br>
<code>global_settings.core_callbacks.append_to_callback(callback_type, my_plugin_method)</code>
</li>
</ul>
<h3> Extra plugin repository: </h3>
<a href="https://github.com/DuckBoss/JJMumbleBot-PluginLibrary">JJMumbleBot-PluginLibrary</a>
</div>
<footer></footer>
</body>
</html>