Setting up the environment
==========================
This page will get you started for creating a MO2 python plugin. If you have troubles getting
everything setup, feel free to come by our discord server at `https://discord.gg/cYwdcxj <https://discord.gg/cYwdcxj>`_.
Required tools
--------------
It is possible to write a MO2 python plugin using any text editor, but this guide will focus on
`Visual Studio Code <https://code.visualstudio.com/>`_.
This guide assumes that:
- You have `Visual Studio Code <https://code.visualstudio.com/>`_ installed with the
`Python extension <https://marketplace.visualstudio.com/items?itemName=ms-python.python>`_.
- You have Python installed: https://www.python.org/downloads/.
- You must use the Python version that used by MO2.
You can check the ``pythonXX.dll`` in the MO2 installation folder to find the Python version used by MO2 (``python38.dll`` means Python 3.8).
- You obviously need a valid MO2 installation: https://github.com/modorganizer2/modorganizer/releases
- This guide is written for MO2 ≥ 2.3.0.
**Note:** In the following, I will refer to the MO2 installation directory as ``$MO2DIR``. So if you
installed MO2 at ``C:\MO2`` and you are asked to copy a file to ``$MO2DIR/plugins``, it refers to ``C:\MO2\plugins``.
Preparation
-----------
**Note:** This part is optional but highly recommended if you want a proper environment to work with.
Everything here is written to be as simple as possible but you can of course adapt it to your preferences:
use a python virtual environment, use workspace settings instead of global ones, etc.
1. Get the ``mobase`` stubs
...........................
``mobase`` is the MO2 Python module. The module is written in C++ and thus cannot be read directly by tools such
as ``flake8`` or ``mypy``.
Instead, we provide `stubs <https://stackoverflow.com/questions/59051631/what-is-the-use-of-stub-files-pyi-in-python>`_
which can be used for auto-completion or type-checking.
You can install the stubs for ``mobase`` using ``pip``:
.. code::
pip install mobase-stubs
This will install the stubs for ``mobase`` but also for PyQt5, which is heavily used by MO2.
2. Configure Visual Studio Code for ``mobase``
..............................................
We are going to configure Visual Studio Code to have auto-completion and linting (error and type checking)
for the MO2 Python module.
Open ``settings.json`` (Ctrl+Shift+P, then "Open Settings (JSON)"), and add the following entries:
.. code-block:: json-object
"python.linting.enabled": true,
"python.linting.mypyEnabled": true,
"python.linting.flake8Enabled": true,
3. [Optional] Configure ``black`` to auto-format your source files
..................................................................
This step is optional for your own plugin but recent MO2 plugins use ``black``
to get consistent formatting.
You can install ``black`` with ``pip``:
.. code::
pip install black flake8-black
To configure Visual Studio Code to auto-format your code with ``black`` when saving, open ``settings.json``
(Ctrl+Shift+P, then "Open Settings (JSON)"), and add the following entries:
.. code-block:: json-object
"editor.formatOnSave": true,
"editor.formatOnPaste": true,
"python.formatting.provider": "black",
4. [Optional] Automatically reload plugins during development
.............................................................
This section is optional and requires you to already have written a "working"
plugin (a plugin that MO2 can load).
Since MO2 2.4 alpha 6, a new command has been added to ``ModOrganizer.exe`` to
reload plugins during execution.
If your plugin is named "My Plugin", you can use the following command to reload
it while MO2 is running:
.. code::
$MO2DIR\ModOrganizer.exe reload-plugin "My Plugin"
If you are using Visual Studio Code, you can send this command to MO2 automatically
after saving files from your project.
1. Create a "reload plugin" task in Visual Studio Code (Ctrl+Shift+P then
``Tasks: Configure task`` or open ``.vscode/tasks.json``) using the following
snippet (replace the name and directory as needed):
.. code:: javascript
// .vscode/tasks.json
{
// See https://go.microsoft.com/fwlink/?LinkId=733558
// for the documentation about the tasks.json format
"version": "2.0.0",
"tasks": [
{
"label": "reload plugin",
"type": "shell",
"command": "$MO2DIR/ModOrganizer.exe",
"args": [
"reload-plugin", "My Plugin"
]
}
]
}
2. Install the `Trigger Task on Save <https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.triggertaskonsave>`_
extension from Visual Studio Code marketplace.
3. Add the following to your Visual Studio Code settings (``.vscode/settings.json``)
.. code:: javascript
// .vscode/settings.json
{
"triggerTaskOnSave.on": true,
"triggerTaskOnSave.tasks": {
"reload plugin": [
"*.py"
]
}
}
Testing the setup
-----------------
Create a new Python file in Visual Studio Code, and paste the following content (if you create
the file in ``$MO2DIR\plugins``, do not forget to delete it after since it is not a valid
plugin):
.. code-block:: python
import mobase
class MyPlugin(mobase.IPluginTool):
def __init__(self):
super().__init__()
def init(self, organizer: mobase.IOrganizer) -> bool:
organizer.dow # (1)
return True
def name(self) -> int:
return 0
def createPlugin() -> mobase.IPlugin:
return MyPlugin()
If your setup is valid, here is what you should have.
- You should see the following (with the errors underlined):
.. image:: images/check-setup-1.png
- If you press ``Ctrl+Space`` after ``.down`` (1), you should see the following
meaning that auto-complete is working:
.. image:: images/check-setup-2.png
- In the error window (click |error-window| on the status bar), you should see
the 3 following errors:
.. image:: images/check-setup-3.png
If everything is as above, you can delete the test file and move on to writing
your own plugin!
.. |error-window| image:: images/error-window.png