Migrate from MCDR 1.x to 2.x
============================

Migrating from MCDR 1.x to MCDR 2.x is easier than migrating from 0.x for most plugins. Some of the MCDR 1.x plugins can work as expected without any modification

Other than plugins, the permission / configuration parts of MCDR has no changes, so you can just continuously use your MCDR 1.x files

Plugin
------

The most changes between MCDR 1.x and MCDR 2.x is the plugin system

Metadata
^^^^^^^^

You can no longer use :class:`RText <mcdreforged.minecraft.rtext.text.RTextBase>` instance as the value of your plugin metadata. 
``name`` and ``description`` fields in :class:`RText <mcdreforged.minecraft.rtext.text.RTextBase>` class will be automatically converted into ``str`` for compatibility

This changes is to ensure the consistence between :ref:`plugin_dev/plugin_format:Solo Plugin` (the plugin format before MCDR 2.x)
and :ref:`plugin_dev/plugin_format:Multi file Plugin` which use a ``.json`` file to declare their metadata

Event
^^^^^

There are several changes to plugin event about plugin lifecycle to make the lifecycle more complete

- ``Plugin Removed`` event is removed
- ``Plugin Unload`` event will be dispatched when MCDR stopped

With that the plugin lifecycle can be covered with 2 events, :ref:`plugin_dev/event:Plugin Loaded` and :ref:`plugin_dev/event:Plugin Unloaded`

Modules
^^^^^^^

Due to how MCDR 2.x plugin loading logic works, you can no longer places your external libs modules into your ``plugin/`` folder and import them, 
since MCDR will not append the plugin folders into ``sys.path`` any more

For example, the following codes with the given files structure won't work in MCDR 2.x, although it works in 1.x

.. code-block::

    plugins/
        my_lib/
            __init__.py
            my_tool.py
        my_plugin.py

.. code-block:: python

    # my_plugin.py
    from my_lib import do_something

    do_something()

To resolve this issue, you can reorganize your plugin file structure into the :ref:`plugin_dev/plugin_format:Multi file Plugin`
format and insert your lib your multi file plugin

ServerInterface
^^^^^^^^^^^^^^^

APIs used for plugin registry operation related to current plugin in :class:`~mcdreforged.plugin.si.server_interface.ServerInterface`
class is now split to a derived class :class:`~mcdreforged.plugin.si.plugin_server_interface.PluginServerInterface`, other general MCDR control APIs are not affects

For example, these APIs are moved to :class:`~mcdreforged.plugin.si.plugin_server_interface.PluginServerInterface`

* :meth:`~mcdreforged.plugin.si.plugin_server_interface.PluginServerInterface.register_event_listener`
* :meth:`~mcdreforged.plugin.si.plugin_server_interface.PluginServerInterface.get_data_folder`
* :meth:`~mcdreforged.plugin.si.plugin_server_interface.PluginServerInterface.get_data_folder`
* ...

But these APIs are not affected

* :meth:`~mcdreforged.plugin.si.server_interface.ServerInterface.start`
* :meth:`~mcdreforged.plugin.si.server_interface.ServerInterface.execute`
* :meth:`~mcdreforged.plugin.si.server_interface.ServerInterface.get_plugin_list`
* :meth:`~mcdreforged.plugin.si.server_interface.ServerInterface.get_permission_level`
* ...

When invoking the event listener callback of you plugin, MCDR will send a :class:`~mcdreforged.plugin.si.plugin_server_interface.PluginServerInterface`
as the first parameter, so the usability of the server interface API is not affected

These changes should not affect your plugin's runnability, but it will probably mess up the type checking code inspect in your IDE to make the IDE displays a warning

Command
^^^^^^^

The original :class:`~mcdreforged.command.builder.nodes.basic.ArgumentNode` class is now split into
:class:`~mcdreforged.command.builder.nodes.basic.AbstractNode` and :class:`~mcdreforged.command.builder.nodes.basic.ArgumentNode`.
Most of the functionalities are inside :class:`~mcdreforged.command.builder.nodes.basic.AbstractNode`,
but the name field is moved to :class:`~mcdreforged.command.builder.nodes.basic.ArgumentNode`

For your custom command node classes, you might only need to change some related type hints