First Plugin

Welcome to the Plugify C# Language Module Plugin Development Guide. This guide will walk you through the process of creating your first plugin using C# 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 C#?

The C# Language Module allows developers to create plugins using the .NET framework, providing a robust and modern programming environment. By leveraging .NET assemblies, developers can extend applications with ease while maintaining flexibility and performance. 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 C# code for your plugin using the provided API.
4. Manage dependencies to ensure correct plugin initialization.
5. Compile and package your plugin into a .NET assembly.

By the end of this tutorial, you’ll have a working C# 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.
• plugin_name/ – Each plugin has its own dedicated folder. The folder name must match the .pplugin file name.
• bin/ – This subfolder contains the compiled plugin binaries (.dll for all platforms).
• plugin_name.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": "PluginCSharp",
  "description": "An example of a C# 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": "bin/plugin_name.dll",
  "supportedPlatforms": [],
  "languageModule": {
    "name": "csharp"
  },
  "dependencies": [],
  "exportedMethods": []
}

Key Fields Explained

• entryPoint: Specifies the location of the compiled plugin binary (.dll).
• languageModule: Should be set to csharp for C# 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 C# 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 C# plugin template from our repository. It contains all the necessary files, including:

• A preconfigured project structure
• A sample implementation
• The required Plugify NuGet 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 class and optionally implement lifecycle methods (OnPluginStart, OnPluginUpdate, OnPluginEnd).

Plugin Code Structure

Here is a basic example of a C# plugin implementation:

using System;
using Plugify;

namespace ExamplePlugin
{
    public class SamplePlugin : Plugin
    {
        void OnPluginStart()
        {
            Console.WriteLine($"{Name}: OnStart");
        }

        void OnPluginUpdate(float dt)
        {
            Console.WriteLine($"{Name}: OnUpdate");
        }

        void OnPluginEnd()
        {
            Console.WriteLine($"{Name}: OnEnd");
        }
    }
}

Understanding Plugin Lifecycle Methods

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

Dependency Management

Dependency management in Plugify ensures that plugins are loaded in the correct order based on their dependencies. The system uses Topological Sorting to determine the appropriate sequence, preventing initialization issues when plugins rely on other plugins.

How Dependencies Work

Each plugin can declare its dependencies inside the dependencies field of its plugin manifest (.pplugin file). The Plugify core will:

• Analyze the dependencies listed in each plugin's manifest.
• Sort the plugins using Topological Sorting, ensuring dependencies are loaded before dependent plugins.
• Validate platform compatibility and requested versions.

Dependency Representation

Dependencies are declared using the following JSON format inside the dependencies field of the plugin manifest:

"dependencies": [
    {
        "name": "polyhook",
        "optional": false,
        "supportedPlatforms": ["windows", "linux"],
        "requestedVersion": "0.1.0"
    }
]

Explanation of Fields

Building the Plugin

To build your plugin, you need to compile it into a .NET assembly (.dll). You can use Visual Studio, Rider, or VSCode for this purpose.

Using Visual Studio or Rider

1. Open your project in Visual Studio or Rider.
2. Right-click on the project and select Build.
3. The compiled .dll file will be located in the bin/Debug/net9.0 or bin/Release/net9.0 folder.

Using VSCode

1. Open a terminal in your project directory.
2. Run the following command:
   dotnet build
   

3. The compiled .dll file will be located in the bin/Debug/net9.0 or bin/Release/net9.0 folder.

Running and Testing the Plugin

Once you have built 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 example_plugin

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

Handling Plugin Load Failures

If your plugin manager fails to load, Plugify will provide error messages in the console. You can also explicitly query the plugins status using:

plg list

This command will show whether the plugin failed to initialize and, if so, provide a reason (e.g., missing dependencies, incorrect entry point, or runtime errors).

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 plugin binary location.
• 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 C# plugin for the Plugify C# Language Module, including setting up the project, writing the plugin code, configuring the manifest, and building the plugin into a .NET assembly. Following these guidelines ensures smooth integration into the Plugify ecosystem.