Начало работы для разработчиков

CactusLib создан, чтобы сделать разработку плагинов для Exteragram простой и приятной. Следуя этому руководству, вы сможете быстро создать свой первый плагин.

1. Настройка окружения

Убедитесь, что вы настроили среду для разработки плагинов, как описано в официальной документации Exteragram. Вам понадобится установленный Python и Chaquopy.

2. Импорт CactusLib

Первый шаг в коде вашего плагина — импортировать необходимые компоненты из CactusLib. CactusLib должен быть установлен в вашем Exteragram.

try:
    # Главный класс-обертка и декораторы
    from cactuslib import CactusUtils, command, uri, message_uri
except (ImportError, ModuleNotFoundError):
    # Если CactusLib не найден, лучше прервать загрузку плагина.
    raise Exception("Необходим CactusLib. Пожалуйста, установите его.")

3. Создание класса плагина

Ваш основной класс плагина обязательно должен наследоваться от CactusUtils.Plugin (или его псевдонимов CactusUtils.CactusModule, CactusUtils.CactusPlugin). Это дает вашему плагину доступ ко всем утилитам.

__name__ = "Мой Первый Плагин"
__description__ = "Плагин, который приветствует мир."
__id__ = "my_first_plugin"
__version__ = "1.0"
__author__ = "@MyUsername"

# ... импорты ...

class MyFirstPlugin(CactusUtils.Plugin):
    # Здесь будет логика вашего плагина
    pass

4. «Hello, World!»

Давайте создадим простую команду, которая будет отправлять «Hello, World!» в ответ. Для этого мы используем декоратор @command.

# ... метаданные и импорты ...

class MyFirstPlugin(CactusUtils.Plugin):
    def on_plugin_load(self):
        # Обязательно вызывайте родительский метод! Это критически важно.
        super().on_plugin_load()
        
        # Этот метод вызывается при загрузке плагина
        self.info("Мой первый плагин успешно загружен!")
    
    def on_plugin_unload(self):
        # Обязательно вызывайте родительский метод! Это критически важно.
        super().on_plugin_unload()

        # Этот метод вызывается при выгрузке плагина
        self.info("Мой первый плагин успешно выгружен!")

    @command(doc="Отправляет приветствие")
    def hello(self, cmd: CactusUtils.Command):
        # cmd - это объект с информацией о вызванной команде
        # cmd.answer() - это удобный метод для ответа в тот же чат
        cmd.answer("Hello, World from MyFirstPlugin!")

        return HookResult(strategy=HookStrategy.CANCEL)

Разбор кода:

  • on_plugin_load(): Специальный метод, который вызывается один раз при загрузке плагина. Идеальное место для инициализации.

  • on_plugin_unload(): Аналогично on_plugin_load(), но вызывается при выгрузке плагина.

  • self.info("..."): Метод для вывода сообщения в logcat с префиксом [my_first_plugin] [INFO].

  • @command(...): Декоратор, который превращает обычный метод Python в команду, доступную пользователю.

    • doc="...": Описание команды, которое будет видно в меню .chelp.

  • hello(self, cmd: CactusUtils.Command):

    • self: Стандартный экземпляр класса.

    • cmd: Объект CactusUtils.Command, содержащий всю информацию о вызове: аргументы, исходное сообщение, ID чата и т.д.

  • cmd.answer("..."): Встроенный метод для отправки ответного сообщения. Он автоматически определяет, куда нужно отправить ответ.

Теперь, если вы установите этот плагин и напишете в чате .hello, бот ответит вам Hello, World from MyFirstPlugin!.