Introduction

DragonLord's plugin system allows you to extend the game with custom features, locations, quests, and more. Plugins are modular, secure, and easy to distribute.

Getting Started

Prerequisites

• Basic knowledge of PHP
• Understanding of JSON
• Familiarity with the game's structure (optional but helpful)

Plugin Requirements

• PHP 7.4 or higher
• Valid plugin.json manifest
• Proper folder structure
• Version compatibility with game

Plugin Structure

Every plugin must follow a specific folder structure. Here's the standard layout:

Plugin Manifest (plugin.json)

The manifest file defines your plugin's metadata, requirements, hooks, and permissions.

Required Fields

Optional Fields - Detailed

Version Compatibility

The game_version object ensures your plugin works with compatible game versions:

"game_version": {
  "min": "1.0.0",        // Minimum game version required
  "max": "2.0.0",        // Maximum game version supported (optional)
  "api_version": "1.0"   // Required plugin API version
}

• min: Plugin requires this game version or higher. Use semantic versioning (e.g., "1.0.0")
• max: (Optional) Plugin only supports up to this game version. Useful when breaking changes are introduced
• api_version: Plugin API version. Currently "1.0". This ensures compatibility with the plugin system itself

Dependencies

The requires object allows your plugin to depend on other plugins:

"requires": {
  "dependencies": [
    "another-plugin-id",
    "yet-another-plugin"
  ]
}

• dependencies: Array of plugin IDs that must be installed and enabled before this plugin can work
• Dependencies are checked during installation and plugin loading
• If a dependency is missing or disabled, the plugin will not load

Configuration Schema

The config object defines settings that admins can configure in the admin portal:

"config": {
  "api_key": {
    "type": "string",
    "required": true,
    "label": "API Key",
    "description": "Your API key for external service",
    "secret": true,
    "default": ""
  },
  "enabled": {
    "type": "boolean",
    "default": true,
    "label": "Enable Feature",
    "description": "Turn this feature on or off"
  },
  "max_items": {
    "type": "number",
    "default": 10,
    "min": 1,
    "max": 100,
    "label": "Maximum Items",
    "description": "Maximum number of items allowed"
  },
  "theme_color": {
    "type": "string",
    "default": "#667eea",
    "label": "Theme Color",
    "description": "Color theme for the plugin UI"
  }
}

Configuration Field Options

Example Manifest

{
  "id": "my-awesome-plugin",
  "name": "My Awesome Plugin",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "Adds awesome features to the game",
  "type": "location_extension",
  "target_location": "town",
  "game_version": {
    "min": "1.0.0",
    "api_version": "1.0"
  },
  "requires": {
    "dependencies": []
  },
  "hooks": {
    "location_services_init": "hooks/location_services.php",
    "location_service_action": "hooks/service_action.php"
  },
  "permissions": {
    "execute_hooks": ["location_services_init", "location_service_action"]
  },
  "config": {
    "setting1": {
      "type": "string",
      "default": "value",
      "description": "Setting description"
    }
  }
}

Plugin Types

Location Extension

Adds new services to existing game locations.

{
  "type": "location_extension",
  "target_location": "town"
}

Quest Pack

Adds new quests to the game.

{
  "type": "quest_pack"
}

Asset Pack

Provides new icons, images, or other assets.

{
  "type": "asset_pack"
}

Hooks System

Hooks allow plugins to interact with the game at specific points. Register hooks in your manifest:

"hooks": {
  "location_services_init": "hooks/location_services.php",
  "location_service_action": "hooks/service_action.php"
}

Available Hooks

Hook Handler Example

<?php
/**
 * Location Services Hook
 * Adds a library service to town
 */

// $data contains location info and existing services
$locationKey = $data['location_key'] ?? '';

if ($locationKey === 'town') {
    // Add library service
    $data['services']['library'] = [
        'name' => 'Library',
        'description' => 'Study ancient tomes',
        'icon' => 'book'
    ];
}

return $data;
?>

Service Action Response Format

When handling service actions, your hook must return a properly formatted response:

// For 'view' action - show modal with actions
$data['handled'] = true;
$data['result'] = [
    'success' => true,
    'service' => 'library',
    'name' => 'Library',
    'description' => 'Study ancient tomes...',
    'modal_config' => [...],
    'actions' => [...]
];

// For action execution (e.g., 'research', 'study')
$data['handled'] = true;
$data['result'] = [
    'success' => true,
    'message' => 'You gained 25 experience!',
    'player' => [
        'gold' => $updatedGold,
        'experience' => $updatedExp
    ],
    'exp_gain' => 25,
    'gold_spent' => 10
];

// For errors
$data['handled'] = true;
$data['result'] = [
    'success' => false,
    'message' => 'You need 10 gold to study.'
];

Response Fields

Permissions

Plugins must declare permissions for security. The sandbox system enforces these restrictions.

Permission Types - Detailed

1. execute_hooks

Lists which hooks your plugin is allowed to execute. This is the most common permission type.

"permissions": {
  "execute_hooks": [
    "location_services_init",
    "location_service_action"
  ]
}

• Must match hook names exactly as registered in your hooks object
• If a hook is not listed here, it will not execute even if registered
• This is a security measure to prevent unauthorized hook execution

2. file_system

Controls file system access for reading and writing files.

"permissions": {
  "file_system": {
    "read": [
      "/plugins/{plugin_id}/assets",
      "/public/icons"
    ],
    "write": [
      "/plugins/{plugin_id}/cache"
    ]
  }
}

• read: Array of paths the plugin can read from
• write: Array of paths the plugin can write to
• Use {plugin_id} placeholder for plugin-specific paths
• Paths are relative to the game root directory
• Plugins can always read their own hook files (automatic permission)

3. database

Controls database table access for reading and writing data.

"permissions": {
  "database": {
    "read": ["players", "items"],
    "write": ["custom_plugin_table"]
  }
}

• read: Array of table names the plugin can SELECT from
• write: Array of table names the plugin can INSERT/UPDATE/DELETE
• Table names must match exactly (case-sensitive)
• Consider creating plugin-specific tables for data storage

Example Permissions

"permissions": {
  "execute_hooks": [
    "location_services_init",
    "location_service_action"
  ],
  "file_system": {
    "read": ["/plugins/{plugin_id}/assets"],
    "write": []
  },
  "database": {
    "read": ["players"],
    "write": []
  }
}

Assets & Icons

Plugins can include custom icons, images, and other assets. Place them in the assets/ directory.

Folder Structure

Using Assets in Hooks

Reference assets using relative paths from the plugin directory:

$data['result'] = [
    'success' => true,
    'modal_config' => [
        'icon' => 'assets/icon.png',
        'image' => 'assets/header.jpg'
    ],
    'actions' => [
        'action1' => [
            'name' => 'Action',
            'icon' => 'assets/action-icon.png'
        ]
    ]
];

Asset Path Resolution

Asset paths are resolved in the following priority order:

1. Full URLs: If path starts with http:// or https://, used as-is

   'icon' => 'https://example.com/my-icon.png'

2. Absolute paths: If path starts with /, relative to game base path

   'icon' => '/public/icons/custom.png'

3. Relative paths: Otherwise, resolved as plugins/{plugin-id}/assets/{path}

   'icon' => 'assets/library-icon.png'
   // Resolves to: plugins/location-extension-library/assets/library-icon.png

Modal Customization Options

When returning service data, you can customize the modal appearance:

$data['result'] = [
    'success' => true,
    'service' => 'library',
    'name' => 'Library',
    'description' => 'Study ancient tomes and research knowledge.',
    'modal_config' => [
        // Service icon (48x48px recommended)
        'icon' => 'assets/library-icon.png',
        
        // Header background image (optional)
        'image' => 'assets/library-header.jpg',
        
        // Custom header text color
        'header_color' => '#8B4513',
        
        // Modal width
        'max_width' => '700px',
        
        // Show/hide player gold display
        'show_gold' => true,
        
        // Custom HTML content (injected before actions)
        'custom_html' => '<div class="custom-stats">...</div>'
    ],
    'actions' => [
        'research' => [
            'name' => 'Research',
            'description' => 'Spend 10 gold to gain 25 experience',
            'cost' => 10,
            'icon' => 'assets/research-icon.png',
            // Optional: fully custom HTML for this action
            // 'custom_html' => '<div>Custom action HTML</div>'
        ]
    ]
];

Modal Config Options Reference

Action Options Reference

Complete Examples

Location Extension Plugin

See the example plugin: plugins/location-extension-library/

This plugin adds a Library service to Town with research actions.

Complete Location Extension Example

{
  "id": "location-extension-library",
  "name": "Town Library Extension",
  "version": "1.0.2",
  "author": "DragonLord Team",
  "description": "Adds a Library service to Town with research actions",
  "type": "location_extension",
  "target_location": "town",
  "game_version": {
    "min": "0.9.0",
    "api_version": "1.0"
  },
  "permissions": {
    "execute_hooks": [
      "location_services_init",
      "location_service_action"
    ]
  },
  "hooks": {
    "location_services_init": "hooks/location_services.php",
    "location_service_action": "hooks/service_action.php"
  }
}

Advanced Hook Example

Here's a complete service action handler with error handling and player updates:

<?php
/**
 * Service Action Hook Handler
 * Handles Library service actions
 */

// Only handle library service
if ($data['service'] === 'library') {
    $action = $data['action'];
    $playerId = $data['player_id'];
    
    // Get database instance
    if (!class_exists('Database')) {
        require_once __DIR__ . '/../../../../includes/database.php';
    }
    $db = Database::getInstance();
    
    // Get player data
    $player = $db->fetchOne("SELECT * FROM players WHERE id = ?", [$playerId]);
    if (!$player) {
        $data['handled'] = true;
        $data['result'] = ['success' => false, 'message' => 'Player not found'];
        return $data;
    }
    
    switch ($action) {
        case 'research':
        case 'study':
            $expGain = 25;
            $goldCost = 10;
            
            // Validate player has enough gold
            if ($player['gold'] < $goldCost) {
                $data['handled'] = true;
                $data['result'] = [
                    'success' => false,
                    'message' => "You need {$goldCost} gold to study at the library."
                ];
                return $data;
            }
            
            // Update player stats
            $db->query(
                "UPDATE players SET gold = gold - ?, experience = experience + ? WHERE id = ?",
                [$goldCost, $expGain, $playerId]
            );
            
            // Get updated player data
            $updatedPlayer = $db->fetchOne("SELECT * FROM players WHERE id = ?", [$playerId]);
            
            $data['handled'] = true;
            $data['result'] = [
                'success' => true,
                'message' => "You spend time studying ancient tomes. You gain {$expGain} experience!",
                'exp_gain' => $expGain,
                'gold_spent' => $goldCost,
                'player' => [
                    'gold' => $updatedPlayer['gold'],
                    'experience' => $updatedPlayer['experience']
                ]
            ];
            break;
            
        case 'view':
        case 'info':
            $data['handled'] = true;
            $data['result'] = [
                'success' => true,
                'service' => 'library',
                'name' => 'Library',
                'description' => 'Study ancient tomes and research knowledge to gain experience.',
                'modal_config' => [
                    'header_color' => '#8B4513',
                    'max_width' => '700px'
                ],
                'actions' => [
                    'research' => [
                        'name' => 'Research',
                        'description' => 'Spend 10 gold to gain 25 experience',
                        'cost' => 10
                    ],
                    'study' => [
                        'name' => 'Study',
                        'description' => 'Spend 10 gold to gain 25 experience',
                        'cost' => 10
                    ]
                ]
            ];
            break;
            
        default:
            $data['handled'] = true;
            $data['result'] = ['success' => false, 'message' => 'Unknown library action'];
    }
}

return $data;
?>

Creating Your First Plugin

1. Create a folder with your plugin ID (e.g., my-first-plugin)
2. Create plugin.json with required fields
3. Create hooks/ directory and add hook handlers
4. Add assets/ if needed
5. Test locally by uploading via admin portal
6. Create ZIP file with proper structure
7. Upload to marketplace

Advanced Topics

Accessing Game Systems

In your hook files, you can access core game systems:

// Database access
if (!class_exists('Database')) {
    require_once __DIR__ . '/../../../../includes/database.php';
}
$db = Database::getInstance();

// Get player data
$player = $db->fetchOne("SELECT * FROM players WHERE id = ?", [$playerId]);

// Update player
$db->query("UPDATE players SET gold = gold - ? WHERE id = ?", [$amount, $playerId]);

// Plugin configuration
$pluginManager = PluginManager::getInstance();
$config = $pluginManager->getPluginConfig('your-plugin-id');
$apiKey = $config['api_key'] ?? '';

Error Handling

Always handle errors gracefully in your hooks:

try {
    // Your plugin logic
    $result = performAction();
    
    $data['handled'] = true;
    $data['result'] = [
        'success' => true,
        'message' => 'Action completed successfully'
    ];
} catch (Exception $e) {
    error_log("Plugin error: " . $e->getMessage());
    
    $data['handled'] = true;
    $data['result'] = [
        'success' => false,
        'message' => 'An error occurred. Please try again.'
    ];
}

return $data;

Best Practices

• Validate Input: Always validate player data and parameters before processing
• Check Permissions: Verify player has required resources (gold, items, etc.)
• Update Player Data: Return updated player stats in response for UI refresh
• Use Transactions: For complex operations, use database transactions
• Log Important Events: Use error_log() for debugging (remove in production)
• Sanitize Output: Escape user input to prevent XSS attacks
• Test Thoroughly: Test all code paths, error cases, and edge cases

Common Patterns

Pattern 1: Conditional Service Addition

// Only add service to specific location
if ($data['location_key'] === 'town') {
    $data['services']['my_service'] = [
        'name' => 'My Service',
        'description' => 'Service description',
        'icon' => 'custom-icon'
    ];
}
return $data;

Pattern 2: Configuration-Based Behavior

// Get plugin configuration
$pluginManager = PluginManager::getInstance();
$config = $pluginManager->getPluginConfig('your-plugin-id');

$enabled = $config['enabled'] ?? true;
$maxItems = $config['max_items'] ?? 10;

if ($enabled) {
    // Plugin logic using $maxItems
}

Pattern 3: Player State Validation

// Check player state before action
$player = $db->fetchOne("SELECT * FROM players WHERE id = ?", [$playerId]);

if ($player['gold'] < $requiredGold) {
    $data['handled'] = true;
    $data['result'] = [
        'success' => false,
        'message' => "You need {$requiredGold} gold for this action."
    ];
    return $data;
}

// Proceed with action...

Testing Your Plugin

1. Local Testing: Upload via admin portal and test all functionality
2. Error Testing: Test error cases (insufficient gold, missing items, etc.)
3. Edge Cases: Test with boundary values and unusual inputs
4. Multiple Players: Test with different player accounts
5. Plugin Conflicts: Test with other plugins enabled
6. Version Compatibility: Test with different game versions if applicable

Publishing Your Plugin

Preparing Your Plugin

1. Test thoroughly - Test all functionality locally
2. Check version compatibility - Ensure your plugin works with current game version
3. Document your plugin - Include a README.md
4. Create ZIP file - Include all files in correct structure

ZIP File Structure

Your ZIP should contain either:

• Option 1: Plugin files directly in root (plugin.json at root)
• Option 2: Single folder containing all plugin files

# Correct structure (Option 1)
my-plugin.zip
  ├── plugin.json
  ├── hooks/
  │   └── service_action.php
  └── assets/
      ├── icon.png
      ├── header.jpg
      └── action-icons/
          └── research.png

# Also correct (Option 2)
my-plugin.zip
  └── my-plugin/
      ├── plugin.json
      ├── hooks/
      │   └── service_action.php
      └── assets/
          ├── icon.png
          └── header.jpg

Uploading to Marketplace

1. Log in to the marketplace
2. Go to your Dashboard
3. Click "Upload Plugin"
4. Select your ZIP file
5. Wait for validation
6. Plugin will be reviewed and approved

Additional Resources

• Plugin Manifest Documentation - See the "Manifest File" section above
• Modal Customization & Assets - See the "Assets & Icons" section above
• Hooks System - See the "Hooks System" section above
• Permissions & Security - See the "Permissions" section above
• Example plugins in plugins/ directory of your game installation