src/interfaces/npc_addon.py

"""
NPC Addon interface and base class for the MMORPG game.
"""

from abc import ABC, abstractmethod
from typing import Dict, Any, Optional
import gradio as gr


# Global registry for self-contained addons
_addon_registry = {}


class NPCAddon(ABC):
    """Base class for NPC add-ons with auto-registration support"""
    
    def __init__(self):
        """Initialize and auto-register the addon"""
        # Auto-register this addon when instantiated
        _addon_registry[self.addon_id] = self
    
    @property
    @abstractmethod
    def addon_id(self) -> str:
        """Unique identifier for this add-on"""
        pass
    
    @property
    @abstractmethod
    def addon_name(self) -> str:
        """Display name for this add-on"""
        pass
    
    @property
    def npc_config(self) -> Optional[Dict[str, Any]]:
        """
        Optional NPC configuration for auto-placement in world.
        Return None if this addon doesn't need an NPC in the world.
        
        Expected format:
        {
            'id': 'unique_npc_id',
            'name': 'Display Name',
            'x': 100, 'y': 200,  # World position
            'char': '🎯',         # Character emoji
            'type': 'addon',      # NPC type
            'description': 'Optional description'
        }
        """
        return None
    
    @property
    def ui_tab_name(self) -> Optional[str]:
        """
        Optional UI tab name. Return None if no UI tab needed.
        If provided, get_interface() will be used to create the tab content.
        """
        return None
    
    @abstractmethod
    def get_interface(self) -> gr.Component:
        """Return Gradio interface for this add-on"""
        pass
    
    @abstractmethod
    def handle_command(self, player_id: str, command: str) -> str:
        """Handle player commands via private messages"""
        pass
    
    def on_startup(self):
        """Called when the addon is loaded during game startup"""
        pass
    
    def on_shutdown(self):
        """Called when the addon is unloaded during game shutdown"""
        pass


def get_registered_addons() -> Dict[str, NPCAddon]:
    """Get all registered addons"""
    return _addon_registry.copy()


def clear_addon_registry():
    """Clear the addon registry (used for testing)"""
    global _addon_registry
    _addon_registry = {}
    
def list_active_addons() -> list:
    """Return all currently registered addon IDs."""
    return list(_addon_registry.keys())

def remove_addon(addon_id: str) -> bool:
    """Unregister and shut down an addon by its ID."""
    addon = _addon_registry.pop(addon_id, None)
    if addon:
        try:
            addon.on_shutdown()
        except Exception:
            pass
        return True
    return False