Plugin

Plugin System

Neodyme features a plugin system that allows you to extend server functionality without modifying the core codebase. Plugins are JavaScript modules loaded dynamically at server startup.

Configuration

The plugin system is controlled via the server.properties file:

plugins=true    # Enable/disable plugin loading

When plugins=true, the server automatically scans the plugins/ directory at startup and loads all valid .js files.

---

Architecture

How It Works

The PluginManager is a static class that manages the complete plugin lifecycle:

Server startup
       |
       v
PluginManager.load()
       |
       v
Scan plugins/ directory
       |
       v
For each .js file:
  1. Clear require cache (hot-reload)
  2. Import plugin class
  3. Instantiate (new PluginClass())
  4. Validate (name + init required)
  5. Call init(pluginManager)
  6. If success: add to active plugins list
       |
       v
Plugins active and ready

Loading Mechanism

The PluginManager uses require.cache to enable hot-reload:

// Cache is cleared before each load
delete require.cache[require.resolve(pluginPath)];
const PluginClass = require(pluginPath);
const plugin = new PluginClass();

This means you can modify a plugin and reload it without restarting the server.

---

Plugin Structure

Properties and Methods

Element	Type	Required	Description
name	string	Yes	Unique plugin identifier
version	string	No	Plugin version (default: "1.0.0")
description	string	No	Plugin description
dependencies	array	No	List of required plugins
init(pluginManager)	async function	Yes	Initialization method
shutdown()	async function	No	Cleanup method

Minimal Template

class MyPlugin {
    name = "MyPlugin";
    version = "1.0.0";
    description = "My plugin description";

    async init(pluginManager) {
        // Initialization code
        // Return true = success, false = failure
        return true;
    }

    async shutdown() {
        // Resource cleanup (optional but recommended)
    }
}

module.exports = MyPlugin;

Validation

The PluginManager checks two mandatory conditions:

1. plugin.name: must be defined and non-empty
2. plugin.init: must be a function

If either condition is not met, the plugin is rejected with the error "Invalid plugin structure".

---

PluginManager API

Available Methods

Method	Description	Return
PluginManager.load()	Load all plugins from plugins/ directory	void
PluginManager.loadPlugin(name)	Load a specific plugin by filename	boolean
PluginManager.reloadPlugin(name)	Reload a plugin (shutdown + load)	boolean
PluginManager.reload()	Reload all plugins	void
PluginManager.unload()	Unload all plugins	void
PluginManager.unloadAll()	Alias for unload()	void
PluginManager.getPlugins()	Return list of active plugins	array

Usage Within a Plugin

async init(pluginManager) {
    // Store reference for later use
    this.pluginManager = pluginManager;

    // Access other loaded plugins
    const plugins = PluginManager.getPlugins();
    const otherPlugin = plugins.find(p => p.name === "OtherPlugin");

    if (otherPlugin) {
        // Interact with the other plugin
        otherPlugin.someMethod();
    }

    return true;
}

---

Available Services

Plugins have access to Neodyme's internal services:

LoggerService

const LoggerService = require('../src/service/logger/logger-service');

LoggerService.log('info', 'Informational message');
LoggerService.log('success', 'Operation successful');
LoggerService.log('warn', 'Warning message');
LoggerService.log('error', 'Error detected');

ConfigManager

const ConfigManager = require('../src/manager/config-manager');

// Read a value from server.properties
const debug = ConfigManager.get('debug');
const port = ConfigManager.get('port');
const discordBot = ConfigManager.get('discordBot');

Discord Integration

If discordBot=true or discordWebhook=true in the configuration, the PluginManager automatically logs that the plugin supports Discord:

async init(pluginManager) {
    if (ConfigManager.get('discordBot')) {
        // Initialize Discord bot
    }

    if (ConfigManager.get('discordWebhook')) {
        // Initialize webhooks
    }

    return true;
}

---

Lifecycle

Initialization Phase

1. Server starts
2. PluginManager.load() is called
3. plugins/ directory is scanned
4. Each .js file is processed:
   - Module is imported
   - Instance is created
   - init() is called with pluginManager as parameter
   - If init() returns true: plugin is added to the list
   - If init() returns false: plugin is ignored
5. Total loaded plugins count is displayed

Unloading Phase

1. Server stops OR reload is requested
2. PluginManager.unload() is called
3. For each active plugin:
   - If shutdown() exists: it is called
   - Plugin is removed from the list
4. Plugin list is cleared

Hot-Reloading a Plugin

1. reloadPlugin("MyPlugin") is called
2. Plugin is found in the list
3. shutdown() is called (if defined)
4. Plugin is removed from the list
5. loadPlugin("MyPlugin") is called
6. require cache is cleared
7. Module is re-imported
8. init() is called

---

Examples

Basic Plugin

const LoggerService = require('../src/service/logger/logger-service');

class HelloPlugin {
    name = "HelloPlugin";
    version = "1.0.0";
    description = "Demo plugin";

    async init(pluginManager) {
        LoggerService.log('success', 'HelloPlugin initialized');
        return true;
    }

    async shutdown() {
        LoggerService.log('info', 'HelloPlugin stopped');
    }
}

module.exports = HelloPlugin;

Plugin with Periodic Tasks

const LoggerService = require('../src/service/logger/logger-service');

class SchedulerPlugin {
    name = "SchedulerPlugin";
    version = "1.0.0";

    constructor() {
        this.intervals = [];
    }

    async init(pluginManager) {
        // Task executed every 5 minutes
        const interval = setInterval(() => {
            this.periodicTask();
        }, 5 * 60 * 1000);

        this.intervals.push(interval);
        LoggerService.log('success', 'SchedulerPlugin started');
        return true;
    }

    periodicTask() {
        LoggerService.log('info', 'Periodic task executed');
    }

    async shutdown() {
        // Important: clean up intervals
        this.intervals.forEach(interval => clearInterval(interval));
        this.intervals = [];
        LoggerService.log('info', 'SchedulerPlugin stopped, intervals cleaned up');
    }
}

module.exports = SchedulerPlugin;

Plugin with Dependencies

const LoggerService = require('../src/service/logger/logger-service');
const PluginManager = require('../src/manager/plugin-manager');

class DependentPlugin {
    name = "DependentPlugin";
    version = "1.0.0";
    dependencies = ["DatabasePlugin", "CachePlugin"];

    async init(pluginManager) {
        // Check that dependencies are loaded
        const plugins = PluginManager.getPlugins();

        for (const dep of this.dependencies) {
            const found = plugins.find(p => p.name === dep);
            if (!found) {
                LoggerService.log('error', `Missing dependency: ${dep}`);
                return false;
            }
        }

        LoggerService.log('success', 'All dependencies found');
        return true;
    }
}

module.exports = DependentPlugin;

Discord Plugin

const LoggerService = require('../src/service/logger/logger-service');
const ConfigManager = require('../src/manager/config-manager');

class DiscordPlugin {
    name = "DiscordPlugin";
    version = "2.0.0";
    description = "Discord integration for Neodyme";

    async init(pluginManager) {
        this.botEnabled = ConfigManager.get('discordBot');
        this.webhookEnabled = ConfigManager.get('discordWebhook');

        if (this.botEnabled) {
            await this.initBot();
        }

        if (this.webhookEnabled) {
            await this.initWebhook();
        }

        if (!this.botEnabled && !this.webhookEnabled) {
            LoggerService.log('warn', 'DiscordPlugin: no integration enabled');
        }

        return true;
    }

    async initBot() {
        // Bot initialization logic
        LoggerService.log('info', 'Discord bot initialized');
    }

    async initWebhook() {
        // Webhook initialization logic
        LoggerService.log('info', 'Discord webhooks initialized');
    }

    async shutdown() {
        // Clean disconnect
        LoggerService.log('info', 'DiscordPlugin disconnected');
    }
}

module.exports = DiscordPlugin;

---

Best Practices

Error Handling

Always wrap initialization code in a try-catch:

async init(pluginManager) {
    try {
        // Initialization code
        await this.connectToDatabase();
        await this.loadConfig();
        return true;
    } catch (error) {
        LoggerService.log('error', `${this.name}: ${error.message}`);
        return false;
    }
}

Resource Cleanup

Always implement shutdown() if your plugin uses:

• Intervals or timeouts
• Database connections
• WebSocket connections
• Open files
• Event listeners

Relative Paths

Use path.join and __dirname for file paths:

const path = require('path');

async init(pluginManager) {
    const configPath = path.join(__dirname, 'config.json');
    // ...
}

Appropriate Logging

Use the correct log level:

• info: general information
• success: successful operations
• warn: abnormal but non-blocking situations
• error: errors requiring attention

---

Troubleshooting

Plugin Not Loading

Symptom	Probable Cause	Solution
"Invalid plugin structure"	name or init missing	Verify required properties are defined
Syntax error	Invalid JavaScript code	Check file syntax
"Plugin file does not exist"	Wrong filename	Verify file is in plugins/
init() returns false	Initialization failure	Check logs for details

Plugin Not Reloading

Hot-reload requires:

1. File must be in the plugins/ directory
2. Name passed to reloadPlugin() must exactly match the plugin's name
3. JavaScript file must have the same name as the plugin (without .js extension)

Memory Leaks

If your server consumes increasing memory:

1. Verify shutdown() cleans up all intervals/timeouts
2. Verify event listeners are removed
3. Verify connections are closed

---

Directory Structure

neodyme/
  plugins/                  # Plugins directory
    MyPlugin.js             # Plugin file
    AnotherPlugin.js
  src/
    manager/
      plugin-manager.js     # Plugin manager
    service/
      logger/
        logger-service.js   # Logging service

---

Community Plugins

See all available plugins