Command Overloading Plan Update

[WenoxGB]

Executive Summary

The SkyblockCore plugin currently uses PocketMine-MP's (PMMP) basic Command class for all command handling. While functional for simple commands, this system lacks advanced features like parameter overloading, type validation, and complex argument parsing. The original plan was to integrate the Commando virion to address these limitations. However, PMMP's recent PR #6837 introduces native command overloading capabilities, making third-party solutions like Commando unnecessary. This document outlines the decision to abandon the Commando integration and prepare for PMMP's native implementation.

Current State Analysis

Existing Command System

• Framework: PMMP's standard Command class
• Capabilities:
  • Basic command registration and execution
  • Simple permission checking
  • Manual argument parsing via explode() or similar
• Limitations:
  • No built-in parameter overloading
  • Manual type validation required
  • Error-prone argument handling
  • Limited tab completion support
  • No automatic help generation for complex commands

Command Inventory

The plugin contains multiple command classes across different categories:

Player Commands (src/Biswajit/Core/Commands/player/):

• BankCommand.php
• HubCommand.php
• IslandCommand.php
• JoinCommand.php
• TopBankCommand.php
• TopMoneyCommand.php
• VisitCommand.php
• WeatherCommand.php

Staff Commands (src/Biswajit/Core/Commands/Staff/):

• EconomyCommand.php
• MultiWorld.php
• SetEntityCommand.php

These commands currently handle arguments manually and would benefit significantly from proper overloading support.

Background & Context

The Commando Plan

• Original Intent: Integrate Commando virion for advanced command features
• Benefits Expected:
  • Robust parameter overloading
  • Automatic type validation
  • Better error handling
  • Enhanced tab completion
  • Cleaner command definitions

PMMP's Native Solution

• PR #6837: Command Overloading Implementation
• Status: In development, not yet in stable release
• Features: Native command overloading system integrated into PMMP core
• Impact: Makes external virions like Commando redundant for this functionality

Strategic Decision

Abandon Commando Integration

Rationale:

• Avoid Redundant Work: Implementing Commando now would require complete refactoring when PMMP's native system becomes available
• Dependency Reduction: Using PMMP's native system eliminates additional virion dependencies
• Performance: Native implementations are typically more optimized
• Maintenance: Fewer external dependencies to monitor and update
• Future-Proofing: Aligns with PMMP's development direction

Adopt PMMP Native System

Plan: Wait for PR #6837 to reach stable release, then migrate to PMMP's built-in command overloading.

Implementation Timeline

Phase 1: Monitoring (Current)

• Track PR #6837 progress on GitHub
• Monitor PMMP release notes for command overloading features
• Maintain current basic command system
• Avoid adding Commando or similar dependencies

Phase 2: Preparation (Pre-Release)

• Analyze CommandOverload and CommandParameter classes
• Review PMMP documentation for new API
• Plan migration strategy for existing commands
• Identify commands that will benefit most from overloading

Phase 3: Migration (Post-Release)

• Update PMMP dependency to version with command overloading
• Refactor command classes to use native overloading
• Implement proper parameter validation
• Enhance tab completion and help systems
• Comprehensive testing of all commands

Phase 4: Optimization (Post-Migration)

• Remove any temporary workarounds
• Optimize command performance
• Update documentation
• Consider additional command features enabled by overloading

Technical Details

Current Command Structure

class ExampleCommand extends Command {
    public function execute(CommandSender $sender, string $label, array $args): bool {
        // Manual argument parsing
        if (count($args) < 1) {
            $sender->sendMessage("Usage: /example <param>");
            return false;
        }
        $param = $args[0];
        // Manual validation...
    }
}

Future Command Structure (with PMMP native overloading)

class ExampleCommand extends Command {
    public function __construct() {
        parent::__construct("example", "Example command");
        $this->setOverloads([
            new CommandOverload(false, [
                CommandParameter::standard("param", AvailableCommandsPacket::ARG_TYPE_STRING, 0, true)
            ])
        ]);
    }

    public function execute(CommandSender $sender, string $label, array $args): bool {
        // Automatic parameter handling
        $param = $args["param"] ?? null;
        // Built-in validation...
    }
}

Risk Assessment

High Priority Risks

• API Changes: PMMP's implementation might differ from expected
• Breaking Changes: Potential incompatibility with existing command logic
• Timeline Uncertainty: Unknown release date for PR #6837

Mitigation Strategies

• Incremental Migration: Migrate commands gradually rather than all at once
• Backward Compatibility: Ensure fallback mechanisms during transition
• Testing: Comprehensive testing before and after migration
• Documentation: Keep detailed records of changes

Success Metrics

Technical Metrics

• All commands successfully migrated to native overloading
• No performance degradation
• Improved error handling and user experience
• Reduced code complexity in command classes

User Experience Metrics

• Better command feedback and validation messages
• Enhanced tab completion
• More intuitive command usage
• Reduced command-related support requests

Dependencies & Prerequisites

External Dependencies

• PMMP version with command overloading (currently in PR #6837)
• bedrock-protocol package updates
• Potential composer.json updates

Internal Prerequisites

• Command class refactoring plan
• Testing framework for command validation
• Documentation updates
• Team training on new API

Communication Plan

Internal Communication

• Regular updates on PR #6837 status
• Team discussions on migration approach
• Code review sessions for refactored commands

External Communication

• Update plugin documentation
• Inform server administrators of upcoming changes
• Provide migration guides if breaking changes occur

Contingency Plans

If PMMP Native System Delays

• Evaluate alternative virions (with caution)
• Implement lightweight custom overloading solution
• Continue with current basic system

If Migration Issues Arise

• Rollback procedures for problematic commands
• Gradual migration instead of big-bang approach
• Temporary dual implementation during transition

Conclusion

The decision to abandon Commando integration in favor of PMMP's native command overloading system represents a strategic alignment with the platform's development direction. While it requires patience during the waiting period, it will ultimately provide a more robust, maintainable, and future-proof command system for the SkyblockCore plugin.

References

• PMMP PR #6837: Firebombing of commands for the first time in 10 years pmmp/PocketMine-MP#6837
• PMMP Command Documentation: https://github.com/pmmp/PocketMine-MP/wiki/Commands
• Bedrock Protocol Command Classes: pocketmine/bedrock-protocol/src/types/command/

---

Document Version: 1.0
Last Updated: 18/10/25
Author: PixelForge-Studio
Reviewers: @WenoxGB
Status: Active - Monitoring PMMP PR #6837