First Plugin

Welcome to the Plugify Python Language Module Plugin Development Guide. This guide will walk you through the process of creating your first plugin using Python within the Plugify framework. Whether you’re a game modder, software engineer, or plugin developer, this tutorial will help you understand the fundamental concepts and steps necessary to build a fully functional plugin.

What is Plugify?

Plugify is a modular plugin framework that enables developers to extend applications by integrating external plugins dynamically. It provides a structured approach to plugin development with clear guidelines on plugin structure, dependency management, and API exposure.

Why Use Python?

The Python Language Module allows developers to create plugins using Python, a language known for its simplicity and readability. Python plugins do not require compilation, making them easy to develop and deploy. Plugify ensures that your plugin integrates smoothly with the core framework by following a standardized plugin structure and API.

What You’ll Learn

In this guide, you will:

1. Set up the directory structure for your plugin.
2. Define a plugin manifest (.pplugin file) to register your plugin in the Plugify ecosystem.
3. Write the Python code for your plugin using the provided API.
4. Run and test your plugin.

By the end of this tutorial, you’ll have a working Python plugin that can be loaded into the Plugify framework. Let’s get started!

Directory Structure

To ensure seamless integration with the Plugify framework, your plugin must follow a specific directory structure. Each plugin should be placed inside its own folder within the plugins/ directory. The folder name must match the plugin’s name and follow these rules:

1. Allowed Characters: Alphanumeric (A-Z, a-z, 0-9), special characters ($, #, @, -).
2. Spaces are NOT allowed in the folder name.
3. The .pplugin configuration file must have the same name as the plugin folder.

Example Directory Layout

Breakdown of the Structure

• res/plugins/ – The main directory where all plugins are stored.
• python_example_plugin/ – Each plugin has its own dedicated folder. The folder name must match the .pplugin file name.
• python_example_plugin.py – The Python script containing the plugin code.
• python_example_plugin.pplugin – The configuration file that defines metadata about the plugin.

By following this structure, Plugify can correctly detect, load, and manage plugins across different platforms.

The Plugin Manifest

Each plugin in the Plugify framework requires a manifest file with the .pplugin extension. This file is a JSON-based configuration that provides essential metadata about the plugin, ensuring that it can be properly identified, loaded, and managed.

Key Responsibilities of the Manifest File:

• Defines the plugin version and author details.
• Specifies the entry point for execution.
• Lists dependencies required by the plugin.
• Declares exported methods available for external interaction.

Example of a Manifest File

{
  "$schema": "https://raw.githubusercontent.com/untrustedmodders/plugify/refs/heads/main/schemas/plugin.schema.json",
  "fileVersion": 1,
  "version": "0.1.0",
  "friendlyName": "PythonExamplePlugin",
  "description": "An example of a Python plugin. This can be used as a starting point when creating your own plugin.",
  "createdBy": "untrustedmodders",
  "createdByURL": "https://github.com/untrustedmodders/",
  "docsURL": "https://github.com/orgs/untrustedmodders/README.md",
  "downloadURL": "https://github.com/orgs/untrustedmodders/example-repo.zip",
  "updateURL": "https://github.com/untrustedmodders/plugify/issues",
  "entryPoint": "python_example_plugin.ExamplePlugin",
  "supportedPlatforms": [],
  "languageModule": {
    "name": "python3"
  },
  "dependencies": [],
  "exportedMethods": []
}

Key Fields Explained

• entryPoint: Specifies the module path and class name of the plugin. For example, if your plugin is in python_example_plugin.py and the class is ExamplePlugin, the entry point should be python_example_plugin.ExamplePlugin.
• languageModule: Should be set to python3 for Python plugins.
• dependencies: Lists other required plugins, ensuring correct load order.
• exportedMethods: Functions exposed by the plugin for external interaction.

Why is the Manifest File Important?

• Ensures Compatibility – Defines supported versions and platforms.
• Enables Modularity – Lists dependencies for structured plugin loading.
• Facilitates Integration – Allows other plugins to call exposed methods.

By following this manifest structure, Plugify can efficiently load and manage plugins, ensuring seamless functionality across different projects.

Writing the Plugin Code

Creating a plugin for Plugify is straightforward. You can either use the pre-built Python plugin template available in our repository or write your plugin from scratch.

Using the Plugin Template

The easiest way to get started is by downloading the Python plugin template from our repository. It contains all the necessary files, including:

• A preconfigured project structure
• A sample implementation
• The required plugify package

Just clone the repository, and your environment will be ready for development.

Writing a Plugin from Scratch

If you prefer to build your plugin manually, follow these steps:

Setting Up Your Plugin

Each plugin must extend the plugify.plugin.Plugin class and optionally implement lifecycle methods (plugin_start, plugin_update, plugin_end).

Plugin Code Structure

Here is a basic example of a Python plugin implementation:

from plugify.plugin import Plugin

class ExamplePlugin(Plugin):
    def plugin_start(self):
        print("Python: OnPluginStart")

    def plugin_update(self, dt):
        print("Python: OnPluginUpdate")

    def plugin_end(self):
        print("Python: OnPluginEnd")

Understanding Plugin Lifecycle Methods

Each plugin can define the following lifecycle methods, which Plugify will call at specific times:

Running and Testing the Plugin

Once you have written your plugin, the next step is to run and test it within the Plugify system. To do this, follow these steps:

Placing the Plugin in the Correct Directory

Ensure your plugin is correctly structured inside the plugins/ folder. Your plugin directory should contain:

Once the plugin folder and manifest file are correctly placed, Plugify will automatically detect and attempt to load the plugin.

Verifying Plugin Load Status

You can check if your plugin loaded successfully by using terminal commands provided by Plugify. These commands allow you to query the status of plugins and troubleshoot potential issues.

• List all loaded plugins:

plg plugins

This will display all currently loaded plugins. If your plugin is listed, it means Plugify successfully recognized and initialized it.

• Query specific plugin information:

plg plugin python_example_plugin

This command retrieves detailed information about a specific plugin, including its version, dependencies, and supported platforms.

Debugging Issues

If your plugin isn't working as expected:

• Check the console logs for detailed error messages.
• Ensure all dependencies are properly installed and compatible with the game/platform.
• Verify the entry point in the .pplugin manifest matches the actual module and class name.
• Enable debug logging if necessary, to get more details about the issue.

Once your plugin loads and functions correctly, it's ready for use! Would you like additional information on debugging techniques?

Conclusion

This guide covered the essential steps to create a Python plugin for the Plugify Python Language Module, including setting up the project, writing the plugin code, configuring the manifest, and running the plugin. Following these guidelines ensures smooth integration into the Plugify ecosystem.