endstone-clans-api 1.0.0__py2.py3-none-any.whl

endstone_clans_api/__init__.py

@@ -0,0 +1,53 @@
+from endstone.plugin import PluginManager
+from .main import ClansApiPlugin
+from .types import Clan
+from .database import Database as ClansDatabase
+from .api import ClansApi
+from .events import (
+    ClanEvent,
+    ClanCancellableEvent,
+    ClanCreateEvent,
+    ClanDeleteEvent,
+    ClanJoinEvent,
+    ClanLeaveEvent,
+    ClanKickEvent,
+    ClanRenameEvent,
+    ClanInviteEvent,
+    clan_event_handler,
+)
+from typing import cast
+
+def get_clans_api(plugin_manager: PluginManager) -> ClansApi | None:
+    """
+    Get the ClansApi object the plugin uses. Will return None if an error occours.
+
+    ## Note: Make sure you call this in on_enable or something similar. Internally, what this returns (ClansApiPlugin._api) is unset until the plugin's on_load() method gets called by the PluginManager
+    """
+    try:
+        plugin = cast(ClansApiPlugin, plugin_manager.get_plugin("ClansApiPlugin"))
+        # I don't trust how it returns "Plugin." For all I know, this could return
+        # Plugin | None, just like get_player.
+        if not plugin:
+            return None
+
+        return plugin.api
+    except Exception:
+        return None
+
+__all__ = [
+    "ClansApiPlugin",
+    "Clan",
+    "ClansDatabase",
+    "ClansApi",
+    "get_clans_api",
+    "ClanEvent",
+    "ClanCancellableEvent",
+    "ClanCreateEvent",
+    "ClanDeleteEvent",
+    "ClanJoinEvent",
+    "ClanLeaveEvent",
+    "ClanKickEvent",
+    "ClanRenameEvent",
+    "ClanInviteEvent",
+    "clan_event_handler",
+    ]

endstone_clans_api/api.py

@@ -0,0 +1,29 @@
+from .types import Clan
+from .database import Database
+from .events import ClanEventManager, ClanEvent
+from endstone.plugin import PluginManager
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+   from .main import ClansApiPlugin 
+
+class ClansApi:
+    # I _should_ go for a service, but it's confusing, and services do
+    # not provide type hints for the end user's langage server so it's
+    # better if I provide it as a function somewhere.
+
+    def __init__(self, clans_api_plugin: 'ClansApiPlugin'):
+        self.plugin = clans_api_plugin
+        self._event_manager = ClanEventManager(clans_api_plugin)
+
+    @property
+    def db(self) -> Database:
+        return self.plugin.db
+
+    def register_events(self, listener: Any) -> None:
+        """Registers clan event handlers."""
+        self._event_manager.register_events(listener)
+
+    def call_event(self, event: ClanEvent) -> None:
+        """Calls clan event handlers."""
+        self._event_manager.call_event(event)

endstone_clans_api/commands.py

@@ -0,0 +1,430 @@
+from endstone import Logger
+from endstone.scheduler import Scheduler
+from endstone.form import MessageForm, ModalForm, Toggle
+from .database import Database
+from abc import ABC
+from typing import TYPE_CHECKING, Callable, TypeVar
+from endstone.command import CommandSender, Command
+from endstone.asyncio import submit
+from endstone import Player
+from typing import Awaitable
+import concurrent.futures
+import time
+import json
+from .events import (
+    ClanCreateEvent,
+    ClanDeleteEvent,
+    ClanJoinEvent,
+    ClanLeaveEvent,
+    ClanKickEvent,
+    ClanRenameEvent,
+    ClanInviteEvent,
+)
+
+if TYPE_CHECKING:
+    from .main import ClansConfig, ClansApiPlugin
+    from .api import ClansApi
+
+_T = TypeVar("_T")
+
+class Subcommands(ABC):
+    # def a_function(self, sender: CommandSender, command: Command, args: list[str]) -> bool: ...
+    # { "a": self.a_function }
+    # ^ this is what we're asking for (the dict)
+    # This should also accept unbound methods (methods that aren't object.method, but rather method(object)), but
+    # we won't be using unbound methods anyways so it doesn't matter
+    subcommand_map: dict[str, Callable[[CommandSender, Command, list[str]], bool]]
+    plugin: 'ClansApiPlugin'
+
+    @property
+    def config(self) -> 'ClansConfig':
+        return self.plugin.config
+
+    @property
+    def messages(self) -> dict[str, str]:
+        return self.plugin.config.messages
+
+    @property
+    def db(self) -> Database:
+        return self.plugin.db
+
+    @property
+    def scheduler(self) -> Scheduler:
+        return self.plugin.server.scheduler
+
+    @property
+    def logger(self) -> Logger:
+        return self.plugin.logger
+
+    def _handle_future_result(self, future) -> None:
+        try:
+            future.result()
+        except Exception as e:
+            self.logger.error(str(e))
+
+    def _submit_and_handle_future_result(self, coro: Awaitable[_T]) -> concurrent.futures.Future[_T]:
+        future = submit(coro)
+        future.add_done_callback(self._handle_future_result)
+        return future
+
+class ClansCommands(Subcommands):
+    def help(self, sender: CommandSender, command: Command, args: list[str]):
+        help_messages = self.plugin.config.help
+
+        sender.send_message(self.messages.get("help_header", ""))
+        for subcommand in self.subcommand_map:
+            if subcommand in help_messages:
+                description = help_messages.get(subcommand)
+            else:
+                description = "[no description]"
+            sender.send_message(f"{subcommand} - {description}")
+
+        return True
+
+    def create(self, sender: CommandSender, command: Command, args: list[str]):
+        if not isinstance(sender, Player):
+            sender.send_error_message(self.messages.get("not_a_player", "Only players can use this command."))
+            return True
+
+        if len(args) == 0:
+            sender.send_error_message(self.messages.get("usage_create", "Usage: /clan create <name: str>"))
+            return True
+
+        clan_name = " ".join(args)
+
+        async def create_task():
+            try:
+                xuid = int(sender.xuid)
+                member_clan = self.db.get_member_clan(xuid)
+                if member_clan:
+                    self.scheduler.run_task(self.plugin, lambda: sender.send_error_message(self.messages.get("already_in_clan", "already in clan")))
+                    return
+
+                from .types import _Clan
+                temp_clan = _Clan(self.plugin, clan_name, xuid)
+                event = ClanCreateEvent(temp_clan, sender)
+                self.api.call_event(event)
+                if event.cancelled:
+                    return
+
+                try:
+                    self.db.create_clan(clan_name, xuid)
+                    msg = self.messages.get("clan_created", "clan created")
+                    msg = msg.replace("[clan_name]", clan_name)
+                    self.scheduler.run_task(self.plugin, lambda: sender.send_message(msg))
+                except RuntimeError as e:
+                    self.scheduler.run_task(self.plugin, lambda: sender.send_error_message(str(e)))
+            except Exception as e:
+                # What is the point
+                raise e
+
+        self._submit_and_handle_future_result(create_task())
+        return True
+
+    def rename(self, sender: CommandSender, command: Command, args: list[str]):
+        if not isinstance(sender, Player):
+            sender.send_error_message(self.messages.get("not_a_player", "Only players can use this command."))
+            return True
+
+        if len(args) == 0:
+            sender.send_error_message(self.messages.get("usage_create", "Usage: /clan rename <name: str>"))
+            return True
+
+        player = sender
+
+        async def rename_task():
+            try:
+                xuid = int(player.xuid)
+                clan = self.db.get_member_clan(xuid)
+                
+                if not clan:
+                    self.scheduler.run_task(self.plugin, lambda: sender.send_error_message(self.messages.get("not_in_clan", "not in clan")))
+                    return
+
+                if clan.owner_xuid != xuid:
+                    self.scheduler.run_task(self.plugin, lambda: sender.send_error_message(self.messages.get("not_the_owner", "not the owner")))
+                    return
+
+                try:
+                    new_name = " ".join(args)
+
+                    event = ClanRenameEvent(clan, clan.display_name, new_name)
+                    self.api.call_event(event)
+                    if event.cancelled:
+                        return
+
+                    self.db.rename_clan(xuid, new_name)
+                    msg = self.messages.get("clan_renamed", "clan renamed to [clan_name]")
+                    msg = msg.replace("[clan_name]", new_name)
+                    self.scheduler.run_task(self.plugin, lambda: sender.send_message(msg))
+                except RuntimeError as e:
+                    self.scheduler.run_task(self.plugin, lambda: sender.send_error_message(str(e)))
+                    
+            except Exception as e:
+                raise e
+
+        self._submit_and_handle_future_result(rename_task())
+        return True
+
+    def config_command(self, sender: CommandSender, command: Command, args: list[str]):
+        if not isinstance(sender, Player):
+            sender.send_error_message(self.messages.get("not_a_player", "Only players can use this command."))
+            return True
+
+        player = sender
+
+        async def config_task():
+            xuid = int(player.xuid)
+            # Default to "true" if not set
+            allow_invites_str = self.db.get_player_preference(xuid, "allow_invites")
+            allow_invites = allow_invites_str.lower() == "true" if allow_invites_str else True
+
+            def on_form_submit(p: Player, data_json: str):
+                try:
+                    data = json.loads(data_json)
+                    new_allow_invites = data[0]
+                    
+                    async def save_task():
+                        self.db.set_player_preference(int(p.xuid), "allow_invites", str(new_allow_invites).lower())
+                        self.scheduler.run_task(self.plugin, lambda: p.send_message(self.plugin.config.config_form.get("success", "Preferences updated!")))
+                    
+                    submit(save_task())
+                except Exception as e:
+                    self.logger.error(f"Error handling config form submission: {e}")
+
+            form = ModalForm(
+                title=self.plugin.config.config_form.get("title", "Clan Preferences"),
+                on_submit=on_form_submit
+            )
+            form.add_control(Toggle(
+                label=self.plugin.config.config_form.get("allow_invites", "Allow Clan Invitations"), 
+                default_value=allow_invites
+            ))
+            
+            self.scheduler.run_task(self.plugin, lambda: player.send_form(form))
+
+        submit(config_task())
+        return True
+
+    def invite(self, sender: CommandSender, command: Command, args: list[str]):
+        if not isinstance(sender, Player):
+            sender.send_error_message(self.messages.get("not_a_player", "Only players can use this command."))
+            return True
+
+        if len(args) == 0:
+            sender.send_error_message(self.messages.get("usage_invite", "Usage: /clan invite <player: player>"))
+            return True
+
+        target_name = args[0]
+        target = self.plugin.server.get_player(target_name)
+        if not target:
+            msg = self.messages.get("player_not_found", "Player [player_name] not found.")
+            msg = msg.replace("[player_name]", target_name)
+            sender.send_error_message(msg)
+            return True
+
+        player = sender
+
+        async def invite_task():
+            try:
+                xuid = int(player.xuid)
+                clan = self.db.get_member_clan(xuid)
+                
+                if not clan:
+                    self.scheduler.run_task(self.plugin, lambda: sender.send_error_message(self.messages.get("not_in_clan", "not in clan")))
+                    return
+
+                if clan.owner_xuid != xuid:
+                    self.scheduler.run_task(self.plugin, lambda: sender.send_error_message(self.messages.get("not_the_owner", "not the owner")))
+                    return
+
+                target_xuid = int(target.xuid)
+                target_clan = self.db.get_member_clan(target_xuid)
+                if target_clan:
+                    msg = self.messages.get("player_already_in_clan", "[player_name] is already in a clan.")
+                    msg = msg.replace("[player_name]", target.name)
+                    self.scheduler.run_task(self.plugin, lambda: sender.send_error_message(msg))
+                    return
+
+                allow_invites_str = self.db.get_player_preference(target_xuid, "allow_invites")
+                allow_invites = allow_invites_str.lower() == "true" if allow_invites_str else True
+                if not allow_invites:
+                    msg = self.messages.get("privacy_no_invites", "[player_name] does not allow clan invitations.")
+                    msg = msg.replace("[player_name]", target.name)
+                    self.scheduler.run_task(self.plugin, lambda: sender.send_error_message(msg))
+                    return
+
+                event = ClanInviteEvent(clan, player, target)
+                self.api.call_event(event)
+                if event.cancelled:
+                    return
+
+                cooldown_key = (str(xuid), str(target_xuid))
+                now = time.time()
+                if cooldown_key in self.plugin.invite_cooldowns:
+                    if now - self.plugin.invite_cooldowns[cooldown_key] < self.plugin.config.invite_cooldown:
+                        msg = self.messages.get("invite_cooldown", "You must wait before inviting [player_name] again.")
+                        msg = msg.replace("[player_name]", target.name)
+                        self.scheduler.run_task(self.plugin, lambda: sender.send_error_message(msg))
+                        return
+
+                def on_form_submit(p: Player, index: int):
+                    if index == 0:
+                        async def accept_task():
+                            if self.db.get_member_clan(int(p.xuid)):
+                                return
+                            
+                            join_event = ClanJoinEvent(clan, p)
+                            self.api.call_event(join_event)
+                            if join_event.cancelled:
+                                return
+
+                            self.db.add_member(clan.owner_xuid, int(p.xuid))
+                            
+                            def finalize_acceptance():
+                                msg = self.messages.get("invite_accepted", "You have joined [clan_name]!")
+                                msg = msg.replace("[clan_name]", clan.display_name)
+                                p.send_message(msg)
+                                
+                                inviter = self.plugin.server.get_player(player.name)
+                                if inviter:
+                                    inviter.send_message(f"{p.name} joined your clan.")
+                                    
+                            self.scheduler.run_task(self.plugin, finalize_acceptance)
+                        
+                        submit(accept_task())
+                    else:
+                        self.plugin.invite_cooldowns[cooldown_key] = time.time()
+                        
+                        def notify_decline():
+                            msg = self.messages.get("invite_declined", "[player_name] declined your invitation.")
+                            msg = msg.replace("[player_name]", p.name)
+                            inviter = self.plugin.server.get_player(player.name)
+                            if inviter:
+                                inviter.send_message(msg)
+                                
+                        self.scheduler.run_task(self.plugin, notify_decline)
+
+                form = MessageForm(
+                    title=self.messages.get("invite_received_title", "Clan Invitation"),
+                    content=self.messages.get("invite_received_content", "[player_name] invited you to join [clan_name].")
+                    .replace("[player_name]", player.name)
+                    .replace("[clan_name]", clan.display_name),
+                    button1=self.messages.get("invite_yes", "Yes"),
+                    button2=self.messages.get("invite_no", "No"),
+                    on_submit=on_form_submit
+                )
+                
+                self.scheduler.run_task(self.plugin, lambda: target.send_form(form))
+                
+                msg = self.messages.get("invite_sent", "Invitation sent to [player_name].")
+                msg = msg.replace("[player_name]", target.name)
+                self.scheduler.run_task(self.plugin, lambda: sender.send_message(msg))
+
+            except Exception as e:
+                raise e
+
+        self._submit_and_handle_future_result(invite_task())
+        return True
+
+    def kick(self, sender: CommandSender, command: Command, args: list[str]):
+        if not isinstance(sender, Player):
+            sender.send_error_message(self.messages.get("not_a_player", "Only players can use this command."))
+            return True
+
+        if len(args) == 0:
+            sender.send_error_message(self.messages.get("usage_kick", "Usage: /clan kick <player: player>"))
+            return True
+
+        target_name = args[0]
+        target = self.plugin.server.get_player(target_name)
+        if not target:
+            msg = self.messages.get("player_not_found", "Player [player_name] not found.")
+            msg = msg.replace("[player_name]", target_name)
+            sender.send_error_message(msg)
+            return True
+
+        async def kick_task():
+            xuid = int(sender.xuid)
+            clan = self.db.get_clan_by_xuid(xuid)
+            target_xuid = int(target.xuid)
+            
+            if not clan or target_xuid not in clan.members_xuids or xuid == target_xuid:
+                self.scheduler.run_task(self.plugin, lambda: sender.send_error_message(self.messages.get("cannot_kick", "Cannot kick this player.")))
+                return
+
+            event = ClanKickEvent(clan, target, sender)
+            self.api.call_event(event)
+            if event.cancelled:
+                return
+
+            self.db.remove_member(xuid, target_xuid)
+            
+            def notify():
+                msg = self.messages.get("player_kicked", "Kicked [player_name].").replace("[player_name]", target.name)
+                sender.send_message(msg)
+                target.send_message(self.messages.get("you_were_kicked", "You have been kicked from the clan."))
+            
+            self.scheduler.run_task(self.plugin, notify)
+
+        self._submit_and_handle_future_result(kick_task())
+        return True
+
+    def leave(self, sender: CommandSender, command: Command, args: list[str]):
+        if not isinstance(sender, Player):
+            sender.send_error_message(self.messages.get("not_a_player", "Only players can use this command."))
+            return True
+
+        async def leave_task():
+            try:
+                xuid = int(sender.xuid)
+                clan = self.db.get_member_clan(xuid)
+                
+                if not clan:
+                    self.scheduler.run_task(self.plugin, lambda: sender.send_error_message(self.messages.get("not_in_clan", "not in clan")))
+                    return
+
+                if clan.owner_xuid == xuid:
+                    event = ClanDeleteEvent(clan)
+                    self.api.call_event(event)
+                    if event.cancelled:
+                        return
+
+                    self.db.delete_clan(xuid)
+                    msg = self.messages.get("clan_disbanded", "clan disbanded")
+                    msg = msg.replace("[clan_name]", clan.display_name)
+                    self.scheduler.run_task(self.plugin, lambda: sender.send_message(msg))
+                else:
+                    event = ClanLeaveEvent(clan, sender)
+                    self.api.call_event(event)
+                    if event.cancelled:
+                        return
+
+                    self.db.remove_member(clan.owner_xuid, xuid)
+                    msg = self.messages.get("clan_left", "clan disbanded")
+                    msg = msg.replace("[clan_name]", clan.display_name)
+                    self.scheduler.run_task(self.plugin, lambda: sender.send_message(msg))
+            except Exception as e:
+                raise e
+
+        self._submit_and_handle_future_result(leave_task())
+        return True
+
+    def __init__(self, plugin: 'ClansApiPlugin'):
+        self.plugin = plugin
+
+        self.subcommand_map = {
+            "help": self.help,
+            "create": self.create,
+            "rename": self.rename,
+            "config": self.config_command,
+            "invite": self.invite,
+            "kick": self.kick,
+            "leave": self.leave,
+        }
+
+    @property
+    def api(self) -> 'ClansApi':
+        api = self.plugin.api
+        assert api
+        return api

endstone_clans_api/database.py

@@ -0,0 +1,247 @@
+import sqlite3
+import threading
+from pathlib import Path
+from abc import ABC, abstractmethod
+from .types import Clan
+from .etc import remove_minecraft_formatting
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .main import ClansApiPlugin
+
+class Database(ABC):
+    @abstractmethod
+    def close(self) -> None:
+        ...
+
+    @abstractmethod
+    def create_clan(self, name: str, owner_xuid: int) -> None:
+        ...
+
+    @abstractmethod
+    def get_clan(self, name: str) -> Optional[Clan]:
+        ...
+
+    @abstractmethod
+    def get_clan_by_xuid(self, xuid: int) -> Optional[Clan]:
+        ...
+
+    @abstractmethod
+    def get_members_xuids(self, owner_xuid: int) -> set[int]:
+        ...
+
+    @abstractmethod
+    def get_member_clan(self, member_xuid: int) -> Optional[Clan]:
+        # Only one clan per player should be allowed. Of course, that means
+        # they can only own one clan, or be in one clan.
+        ...
+
+    @abstractmethod
+    def delete_clan(self, owner_xuid: int) -> None:
+        ...
+
+    @abstractmethod
+    def rename_clan(self, owner_xuid: int, new_name: str) -> None:
+        ...
+
+    @abstractmethod
+    def add_member(self, owner_xuid: int, member_xuid: int) -> None:
+        ...
+
+    @abstractmethod
+    def remove_member(self, owner_xuid: int, member_xuid: int) -> None:
+        ...
+
+    @abstractmethod
+    def set_player_preference(self, xuid: int, key: str, value: str) -> None:
+        ...
+
+    @abstractmethod
+    def get_player_preference(self, xuid: int, key: str) -> Optional[str]:
+        ...
+
+# The following was assisted by Claude
+class _Database(Database):
+    def __init__(self, plugin: 'ClansApiPlugin', db_path: Path) -> None:
+        self.plugin = plugin
+        self.db_path = db_path
+        self._lock = threading.Lock()
+        self._conn = sqlite3.connect(self.db_path, check_same_thread=False)
+        self._conn.execute("PRAGMA foreign_keys = ON")
+        self._init_db()
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()
+
+    def create_clan(self, name: str, owner_xuid: int) -> None:
+        with self._lock:
+            self._validate_name_availability(name)
+            self._create_clan(name, owner_xuid)
+
+    def get_clan(self, name: str) -> Optional[Clan]:
+        from .types import _Clan
+        clean_name = remove_minecraft_formatting(name).lower()
+        with self._lock:
+            row = self._get_clan(clean_name)
+        return _Clan._from_db(self.plugin, row) if row else None
+
+    def get_clan_by_xuid(self, xuid: int) -> Optional[Clan]:
+        from .types import _Clan
+        with self._lock:
+            row = self._get_clan_by_xuid(xuid)
+        return _Clan._from_db(self.plugin, row) if row else None
+
+    def get_members_xuids(self, owner_xuid: int) -> set[int]:
+        with self._lock:
+            return self._get_members_xuids(owner_xuid)
+
+    def get_member_clan(self, member_xuid: int) -> Optional[Clan]:
+        from .types import _Clan
+        with self._lock:
+            row = self._get_member_clan(member_xuid)
+        return _Clan._from_db(self.plugin, row) if row else None
+
+    def delete_clan(self, owner_xuid: int) -> None:
+        with self._lock:
+            self._delete_clan(owner_xuid)
+
+    def rename_clan(self, owner_xuid: int, new_name: str) -> None:
+        with self._lock:
+            self._validate_name_availability(new_name, exclude_owner_xuid=owner_xuid)
+            self._update_clan(owner_xuid, display_name=new_name)
+
+    def add_member(self, owner_xuid: int, member_xuid: int) -> None:
+        with self._lock:
+            self._add_member(owner_xuid, member_xuid)
+
+    def remove_member(self, owner_xuid: int, member_xuid: int) -> None:
+        with self._lock:
+            self._remove_member(owner_xuid, member_xuid)
+
+    def set_player_preference(self, xuid: int, key: str, value: str) -> None:
+        with self._lock:
+            self._conn.execute(
+                "INSERT OR REPLACE INTO player_preferences (xuid, key, value) VALUES (?, ?, ?)",
+                (xuid, key, value)
+            )
+            self._conn.commit()
+
+    def get_player_preference(self, xuid: int, key: str) -> Optional[str]:
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT value FROM player_preferences WHERE xuid = ? AND key = ?",
+                (xuid, key)
+            ).fetchone()
+            return row[0] if row else None
+
+    def _validate_name_availability(self, name: str, exclude_owner_xuid: Optional[int] = None) -> None:
+        # Note: This is called within a lock already from public methods
+        from .types import _Clan
+        clean_name = remove_minecraft_formatting(name).lower()
+        row = self._get_clan(clean_name)
+        existing_clan = _Clan._from_db(self.plugin, row) if row else None
+        
+        if existing_clan and existing_clan.owner_xuid != exclude_owner_xuid:
+            raise RuntimeError(f"Clan name '{name}' is already taken.")
+
+    def _init_db(self) -> None:
+        with self._lock:
+            # Cleanup old table if it exists
+            self._conn.execute("DROP TABLE IF EXISTS members")
+            
+            self._conn.execute("""
+                CREATE TABLE IF NOT EXISTS clans (
+                    owner_xuid INTEGER PRIMARY KEY,
+                    clean_name TEXT UNIQUE NOT NULL,
+                    display_name TEXT NOT NULL
+                )
+            """)
+            self._conn.execute("""
+                CREATE TABLE IF NOT EXISTS clan_members (
+                    owner_xuid INTEGER NOT NULL,
+                    member_xuid INTEGER NOT NULL UNIQUE,
+                    PRIMARY KEY(owner_xuid, member_xuid),
+                    FOREIGN KEY(owner_xuid) REFERENCES clans(owner_xuid) ON DELETE CASCADE
+                )
+            """)
+            self._conn.execute("""
+                CREATE TABLE IF NOT EXISTS player_preferences (
+                    xuid INTEGER NOT NULL,
+                    key TEXT NOT NULL,
+                    value TEXT NOT NULL,
+                    PRIMARY KEY(xuid, key)
+                )
+            """)
+            self._conn.commit()
+
+    def _create_clan(self, display_name: str, owner_xuid: int) -> None:
+        clean_name = remove_minecraft_formatting(display_name).lower()
+        self._conn.execute(
+            "INSERT INTO clans (owner_xuid, clean_name, display_name) VALUES (?, ?, ?)",
+            (owner_xuid, clean_name, display_name)
+        )
+        # Add owner as a member
+        self._conn.execute(
+            "INSERT INTO clan_members (owner_xuid, member_xuid) VALUES (?, ?)",
+            (owner_xuid, owner_xuid)
+        )
+        self._conn.commit()
+
+    def _get_clan(self, clean_name: str) -> Optional[tuple[int, str, str]]:
+        return self._conn.execute(
+            "SELECT owner_xuid, clean_name, display_name FROM clans WHERE clean_name = ?",
+            (clean_name,)
+        ).fetchone()
+
+    def _get_clan_by_xuid(self, owner_xuid: int) -> Optional[tuple[int, str, str]]:
+        return self._conn.execute(
+            "SELECT owner_xuid, clean_name, display_name FROM clans WHERE owner_xuid = ?",
+            (owner_xuid,)
+        ).fetchone()
+
+    def _get_members_xuids(self, owner_xuid: int) -> set[int]:
+        rows = self._conn.execute(
+            "SELECT member_xuid FROM clan_members WHERE owner_xuid = ?",
+            (owner_xuid,)
+        ).fetchall()
+        return {row[0] for row in rows}
+
+    def _get_member_clan(self, member_xuid: int) -> Optional[tuple[int, str, str]]:
+        return self._conn.execute("""
+            SELECT c.owner_xuid, c.clean_name, c.display_name
+            FROM clans c
+            JOIN clan_members m ON c.owner_xuid = m.owner_xuid
+            WHERE m.member_xuid = ?
+        """, (member_xuid,)).fetchone()
+
+    def _update_clan(
+        self,
+        owner_xuid: int,
+        display_name: str | None = None
+    ) -> None:
+        if display_name is not None:
+            clean_name = remove_minecraft_formatting(display_name).lower()
+            self._conn.execute(
+                "UPDATE clans SET clean_name = ?, display_name = ? WHERE owner_xuid = ?",
+                (clean_name, display_name, owner_xuid)
+            )
+            self._conn.commit()
+
+    def _delete_clan(self, owner_xuid: int) -> None:
+        self._conn.execute("DELETE FROM clans WHERE owner_xuid = ?", (owner_xuid,))
+        self._conn.commit()
+
+    def _add_member(self, owner_xuid: int, member_xuid: int) -> None:
+        self._conn.execute(
+            "INSERT OR IGNORE INTO clan_members (owner_xuid, member_xuid) VALUES (?, ?)",
+            (owner_xuid, member_xuid)
+        )
+        self._conn.commit()
+
+    def _remove_member(self, owner_xuid: int, member_xuid: int) -> None:
+        self._conn.execute(
+            "DELETE FROM clan_members WHERE owner_xuid = ? AND member_xuid = ?",
+            (owner_xuid, member_xuid)
+        )
+        self._conn.commit()

endstone_clans_api/etc.py

@@ -0,0 +1,22 @@
+# Parts of this was Rust code I wrote translated to Python through an LLM.
+# https://github.com/niko-at-chalupa/endstone-elytra-core/blob/main/crates/elytra-core/src/id.rs
+
+from re import I
+import re
+import xxhash
+
+# In Python, we convert the 8-byte string directly into an integer.
+HASH_SEED = int.from_bytes(b"clansapi\0", byteorder="big")
+
+def compute_id(kebab_name: str) -> int:
+    """
+    Generates a plugin ID that derives from the kebab-case name of plugins.
+    Returns an unsigned 64-bit integer.
+    """
+    # xxhash.xxh64 takes an integer seed and returns a 64-bit hash object
+    hasher = xxhash.xxh64(seed=HASH_SEED)
+    hasher.update(kebab_name.encode('utf-8'))
+    return hasher.intdigest()
+
+def remove_minecraft_formatting(formatted_stuff: str) -> str:
+    return re.sub(r'§.', '', formatted_stuff)

endstone_clans_api/events.py

@@ -0,0 +1,136 @@
+from endstone import Player
+from endstone.command import CommandSender
+from .types import Clan
+from abc import ABC
+from typing import Callable, Type, Any, get_type_hints
+import inspect
+from endstone.event import EventPriority
+
+class ClanEvent(ABC):
+    @property
+    def event_name(self) -> str:
+        return self.__class__.__name__
+
+class ClanCancellableEvent(ClanEvent):
+    def __init__(self):
+        self._cancelled = False
+
+    @property
+    def cancelled(self) -> bool:
+        return self._cancelled
+
+    @cancelled.setter
+    def cancelled(self, value: bool):
+        self._cancelled = value
+
+    def cancel(self):
+        self._cancelled = True
+
+def clan_event_handler(func=None, *, priority: EventPriority = EventPriority.NORMAL, ignore_cancelled: bool = False):
+    """
+    Decorator to register an event handler.
+
+    The first argument of the decorated method must be a subclass of ClanEvent.
+
+    # Example
+    ```python
+    @clan_event_handler
+    def on_some_event(event: SomeClanEvent):
+        ...
+    ```
+    """
+    def decorator(f):
+        setattr(f, "_is_clan_event_handler", True)
+        setattr(f, "_clan_priority", priority)
+        setattr(f, "_clan_ignore_cancelled", ignore_cancelled)
+        return f
+
+    if func:
+        return decorator(func)
+
+    return decorator
+
+class ClanEventManager:
+    def __init__(self, plugin):
+        self._plugin = plugin
+        self._handlers: dict[Type[ClanEvent], list[Callable[[Any], Any]]] = {}
+
+    def register_events(self, listener: Any) -> None:
+        for attr_name in dir(listener):
+            attr = getattr(listener, attr_name)
+            if not callable(attr) or not getattr(attr, "_is_clan_event_handler", False):
+                continue
+
+            hints = get_type_hints(attr)
+            hints.pop("return", None)
+            
+            event_type = next(iter(hints.values()), None)
+
+            if not inspect.isclass(event_type) or not issubclass(event_type, ClanEvent):
+                self._plugin.logger.error(f"Failed to register clan event handler {attr_name}: No ClanEvent type hint found.")
+                continue
+
+            if event_type not in self._handlers:
+                self._handlers[event_type] = []
+            
+            self._handlers[event_type].append(attr)
+            self._handlers[event_type].sort(key=lambda x: getattr(x, "_clan_priority").value)
+
+    def call_event(self, event: ClanEvent) -> None:
+        for registered_type, handlers in self._handlers.items():
+            if isinstance(event, registered_type):
+                handler: Callable[[Any], Any]
+                for handler in handlers:
+                    if isinstance(event, ClanCancellableEvent) and event.cancelled and not getattr(handler, "_clan_ignore_cancelled"):
+                        continue
+                    try:
+                        handler(event)
+                    except Exception as e:
+                        handler_name = getattr(handler, "__name__", str(handler))
+                        self._plugin.logger.error(f"Error while calling clan event handler {handler_name}: {e}")
+                        import traceback
+                        self._plugin.logger.error(traceback.format_exc())
+
+class ClanCreateEvent(ClanCancellableEvent):
+    def __init__(self, clan: Clan, creator: Player):
+        super().__init__()
+        self.clan = clan
+        self.creator = creator
+
+class ClanDeleteEvent(ClanCancellableEvent):
+    def __init__(self, clan: Clan):
+        super().__init__()
+        self.clan = clan
+
+class ClanJoinEvent(ClanCancellableEvent):
+    def __init__(self, clan: Clan, player: Player):
+        super().__init__()
+        self.clan = clan
+        self.player = player
+
+class ClanLeaveEvent(ClanCancellableEvent):
+    def __init__(self, clan: Clan, player: Player):
+        super().__init__()
+        self.clan = clan
+        self.player = player
+
+class ClanKickEvent(ClanCancellableEvent):
+    def __init__(self, clan: Clan, player: Player, kicker: CommandSender):
+        super().__init__()
+        self.clan = clan
+        self.player = player
+        self.kicker = kicker
+
+class ClanRenameEvent(ClanCancellableEvent):
+    def __init__(self, clan: Clan, old_name: str, new_name: str):
+        super().__init__()
+        self.clan = clan
+        self.old_name = old_name
+        self.new_name = new_name
+
+class ClanInviteEvent(ClanCancellableEvent):
+    def __init__(self, clan: Clan, inviter: Player, invitee: Player):
+        super().__init__()
+        self.clan = clan
+        self.inviter = inviter
+        self.invitee = invitee

endstone_clans_api/main.py

@@ -0,0 +1,194 @@
+import traceback
+from .commands import ClansCommands
+from pathlib import Path
+from typing import Any, cast
+from endstone.plugin import Plugin
+from pydantic import BaseModel, Field
+from ruamel.yaml import YAML
+from ruamel.yaml.comments import CommentedMap
+from .database import Database, _Database
+from endstone.command import Command, CommandSender
+from .api import ClansApi
+
+class ClansConfig(BaseModel):
+    messages: dict[str, str] = Field(default_factory=dict)
+    help: dict[str, str] = Field(default_factory=dict)
+    config_form: dict[str, str] = Field(default_factory=dict)
+    invite_cooldown: int = 600
+
+class ClansApiPlugin(Plugin):
+    api_version = "0.11"
+    _config: ClansConfig
+    _api: ClansApi | None = None
+    _invite_cooldowns: dict[tuple[str, str], float] = {}  # (inviter_xuid, target_xuid) -> timestamp
+
+    commands = {
+        "clan": {
+            "description": "Manage or create a clan",
+            "usages": [
+                "/clan <subcommand: string> [args: message]",
+                "/clan help",
+                "/clan create <name: str>",
+                "/clan rename <name: str>",
+                "/clan config",
+                "/clan invite <player: player>",
+                "/clan kick <player: player>",
+                "/clan leave",
+            ],
+            "permissions": ["clans-api.command"],
+        }
+    }
+
+    permissions = {
+        "clans-api.command": {
+            "description": "Base permission for all endstone clans API commands",
+            "default": True,
+        }
+    }
+
+    def on_load(self):
+        self._api = ClansApi(self)
+
+    def on_enable(self):
+        self.data_folder.mkdir(exist_ok=True)
+        self._config = self._load_config()
+        self._db = _Database(self, self.data_folder / "clans.db")
+        self._invite_cooldowns = {}
+        self.register_events(self)
+        self.clans_commands = ClansCommands(self)
+
+    def on_disable(self):
+        if hasattr(self, "_db"):
+            self._db.close()
+
+    @property
+    def invite_cooldowns(self) -> dict[tuple[str, str], float]:
+        return self._invite_cooldowns
+
+    def on_command(self, sender: CommandSender, command: Command, args: list[str]) -> bool:
+        if command.name != "clan":
+            return False
+
+        if len(args) == 0:
+            sender.send_error_message(self.config.messages.get("no_subcommand", "no subcommand"))
+            return False
+    
+        subcommand = self.clans_commands.subcommand_map.get(args[0])
+        if not subcommand:
+            sender.send_error_message(self.config.messages.get("invalid_subcommand", "invalid subcommand"))
+            return False
+
+        try:
+            # args[1] is actually just a string of the rest of the args
+            # since we take in a "message" type. We have to manually split.
+            return subcommand(sender, command, args[1].split() if len(args) > 1 else [])
+        except Exception as e:
+            self.logger.error(f"ERROR !!!!!!!!!!!!! 😭😭😭 While handling subcommand `{args[0]}` for `{sender.name}`!! 🥺🥺🥺")                
+            self.logger.error(str(e))
+            self.logger.error(traceback.format_exc())
+            
+            sender.send_error_message(self.config.messages.get("generic_error", "generic error"))
+
+            return False
+
+    @property
+    def config(self) -> ClansConfig:
+        return self._config
+
+    @property
+    def api(self) -> ClansApi | None:
+        return self._api
+
+    @property
+    def db(self) -> Database:
+        return self._db
+
+    def _load_config(self) -> ClansConfig:
+        folder = Path(self.data_folder)
+        folder.mkdir(parents=True, exist_ok=True)
+        cfg_path = folder / "config.yml"
+        
+        yml = YAML()
+        yml.version = (1, 2)
+        yml.preserve_quotes = False
+        
+        defaults = [
+            ("invite_cooldown", 600, "The duration of invitation cooldown in seconds"),
+            ("messages.no_permission", "You do not have permission to use this command.", "Message shown when a player lacks permission"),
+            ("messages.clan_created", "Clan [clan_name] has been successfully created!", "Message shown when a clan is created"),
+            ("messages.no_subcommand", "No subcommand was provided. Try /clans help.", "Shown when /clans is used with no arguments"),
+            ("messages.invalid_subcommand", "The subcommand provided isn't valid. Try /clan help.", "Shown when /clan is used with an invalid subcommand"),
+            ("messages.generic_error", "A technical error has occoured. Please contact a server admin or owner.", "Generic error for commands"),
+            ("messages.not_a_player", "Only players can use this command.", "Message shown when a non-player uses a player-only command"),
+            ("messages.already_in_clan", "You're already in a clan!", "Message shown when a player tries to join/create a clan while in one"),
+            ("messages.clan_name_taken", "A clan with that name already exists!", "Message shown when a clan name is already in use"),
+            ("messages.usage_create", "Usage: /clan create <name>", "Message shown when /clan create is used incorrectly"),
+            ("messages.not_in_clan", "You're not in a clan!", "Message shown when a player tries to use a clan command but isn't in one"),
+            ("messages.clan_left", "You have left the clan [clan_name].", "Message shown when a player leaves a clan"),
+            ("messages.clan_disbanded", "Your clan [clan_name] has been disbanded.", "Message shown when a clan is disbanded because the owner left"),
+            ("messages.help_header", "--- Clan Help ---", "Goes atop the help area."),
+            ("messages.not_in_a_clan", "You are NOT in a clan!!", "Message shown when player attempts to do a clan-related action when NOT in a clan."),
+            ("messages.not_the_owner", "You're NOT the owner of the clan!!", "Message shown when player attempts to do a clan-related action when NOT the owner."),
+            ("messages.clan_name_already_taken", "That name is already taken!", "Message shown to players if a clan name is already taken."),
+            ("messages.player_not_found", "Player [player_name] not found.", "Message shown when a player is not online"),
+            ("messages.invite_sent", "Invitation sent to [player_name].", "Message shown when an invitation is sent"),
+            ("messages.invite_received_title", "Clan Invitation", "Title of the invitation form"),
+            ("messages.invite_received_content", "[player_name] invited you to join [clan_name].", "Content of the invitation form"),
+            ("messages.invite_yes", "Yes", "Accept button text"),
+            ("messages.invite_no", "No", "Decline button text"),
+            ("messages.invite_cooldown", "You must wait before inviting [player_name] again.", "Message shown when an invitation is on cooldown"),
+            ("messages.invite_accepted", "You have joined [clan_name]!", "Message shown when a player accepts an invitation"),
+            ("messages.invite_declined", "[player_name] declined your invitation.", "Message shown when a player declines an invitation"),
+            ("messages.player_already_in_clan", "[player_name] is already in a clan.", "Message shown when inviting someone already in a clan"),
+            ("messages.privacy_no_invites", "[player_name] does not allow clan invitations.", "Message shown when inviting someone who disabled invites"),
+            ("messages.usage_kick", "Usage: /clan kick <player>", "Message shown when /clan kick is used incorrectly"),
+            ("messages.cannot_kick", "You cannot kick this player (are you the owner? are they in your clan?)", "Shown when a kick fails"),
+            ("messages.player_kicked", "[player_name] has been kicked from the clan.", "Success message for kicking"),
+            ("messages.you_were_kicked", "You have been kicked from the clan.", "Message shown to the player who was kicked"),
+
+            ("config_form.title", "Clan Preferences", "Title of the player preferences form"),
+            ("config_form.allow_invites", "Allow Clan Invitations", "Toggle label for invitations"),
+            ("config_form.success", "Your preferences have been updated!", "Message shown when preferences are saved"),
+
+            # Everything underneath the help.* namespace is the help description for the
+            # command specified.
+            ("help.help", "Show this help message", "/clan help"),
+            ("help.rename", "Rename a clan. Example: /clan rename \"my old clan\" \"my new one\"", "/clan rename"),
+            ("help.config", "Open the clan preferences menu", "/clan config"),
+            ("help.invite", "Invite a player to your clan", "/clan invite"),
+            ("help.kick", "Remote a player from your clan", "/clan kick"),
+            ("help.leave", "Makes you leave the clan you're in. If you're the owner of the clan you leave, then the clan will be deleted.", "/clan leave")
+        ]
+        
+        if cfg_path.exists():
+            with open(cfg_path, "r", encoding="utf-8") as f:
+                existing = yml.load(f)
+            if not isinstance(existing, CommentedMap):
+                existing = CommentedMap(existing or {})
+        else:
+            existing = CommentedMap()
+
+        for key, default, comment in defaults:
+            keys = key.split(".")
+            current = existing
+            for i, k in enumerate(keys[:-1]):
+                if k not in current:
+                    current[k] = CommentedMap()
+                current = current[k]
+            
+            if keys[-1] not in current:
+                current[keys[-1]] = default
+                current.yaml_add_eol_comment(comment, keys[-1])
+
+        with open(cfg_path, "w", encoding="utf-8") as f:
+            yml.dump(existing, f)
+
+        config_dict = self._commented_map_to_dict(existing)
+        return ClansConfig(**config_dict)
+
+    def _commented_map_to_dict(self, data: Any) -> Any:
+        if isinstance(data, CommentedMap):
+            return {k: self._commented_map_to_dict(v) for k, v in data.items()}
+        elif isinstance(data, list):
+            return [self._commented_map_to_dict(v) for v in data]
+        return data

endstone_clans_api/types.py

@@ -0,0 +1,85 @@
+from .etc import compute_id, remove_minecraft_formatting
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+from endstone import asyncio
+
+if TYPE_CHECKING:
+    from .main import ClansApiPlugin
+
+class Clan(ABC):
+    @property
+    @abstractmethod
+    def display_name(self) -> str:
+        """
+        The formatted display name of the clan.
+        
+        Use this in frontened, no where else.
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def owner_xuid(self) -> int:
+        """
+        The XUID of the clan owner.
+        
+        Primary key in the database--immutable (owner transfers? forget that!!)
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def clean_name(self) -> str:
+        """
+        The sanitized, **unique**, and lowered name without Minecraft formatting.
+        
+        Use internally and as a substitute name in commands.
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def members_xuids(self) -> set[int]:
+        """
+        XUIDs of every player in this clan, including the owner.
+        """
+
+class _Clan(Clan):
+    _members_xuids: set[int]
+    _display_name: str
+    # Primary key
+    _owner_xuid: int
+    # Internal name, set as UNIQUE, remove Minecraft formatting, use as a
+    # substitute name in commands.
+    _clean_name: str
+
+    def __init__(self, plugin: 'ClansApiPlugin', display_name: str, owner_xuid: int):
+        self._display_name = display_name
+        self._owner_xuid = owner_xuid
+        self._plugin = plugin
+
+        self._members_xuids = set()
+        self._clean_name = remove_minecraft_formatting(display_name).lower()
+
+    @property
+    def display_name(self) -> str:
+        return self._display_name
+
+    @property
+    def owner_xuid(self) -> int:
+        return self._owner_xuid
+
+    @property
+    def clean_name(self) -> str:
+        return self._clean_name
+
+    @property
+    def members_xuids(self) -> set[int]:
+        return self._members_xuids
+
+    @classmethod
+    def _from_db(cls, plugin: 'ClansApiPlugin', row: tuple) -> '_Clan':
+        owner_xuid, clean_name, display_name = row
+        clan = cls(plugin, display_name, owner_xuid)
+        clan._members_xuids = plugin.db.get_members_xuids(owner_xuid)
+        return clan

endstone_clans_api-1.0.0.dist-info/METADATA

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: endstone-clans-api
+Version: 1.0.0
+Author: niko-at-chalupa
+Requires-Dist: endstone
+Requires-Dist: pydantic
+Requires-Dist: ruamel-yaml
+Requires-Dist: xxhash

endstone_clans_api-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+endstone_clans_api/__init__.py,sha256=M3JT6mn6u1bCiy9jR290OStafI65Q3vmvsn5zdHM8O0,1475
+endstone_clans_api/api.py,sha256=gHWLChz0_EdLw_Ing4dOrP0qPZ1XmAOyGVPLKfs4MLE,986
+endstone_clans_api/commands.py,sha256=_jAloWnmofy6TngiAYlE_WPXbBgrKiyFNp0j35rnfXI,18241
+endstone_clans_api/database.py,sha256=avgwvSl41v0yLNt5hEp82STEDtgyBzkmwoZIR1Le_90,8938
+endstone_clans_api/etc.py,sha256=onnbv2V_GFfKrZQaap_PAWLasBCGg1jKjNIhFP0qwH8,816
+endstone_clans_api/events.py,sha256=nyNtysWXuP1UyHFuhglHbNbhXQsG4y2QeQiXjg60JAk,4576
+endstone_clans_api/main.py,sha256=EK-J74zEL3QAtx_c7Q3_sFwsAljoyNn6jIyb057GMXY,10216
+endstone_clans_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+endstone_clans_api/types.py,sha256=GAcs10aJF8TDAMNFmxF1PvsSDxpcNkwzWpdOnD1USXk,2257
+endstone_clans_api-1.0.0.dist-info/METADATA,sha256=Klx3zSKR34cRskL-wqIRRwo5S4-GLATyPbTdpZRCBCc,183
+endstone_clans_api-1.0.0.dist-info/WHEEL,sha256=VX-VJ7c6dw9Ge3EqJIbA6W3pOUbz24SnnGGFNr55jY4,105
+endstone_clans_api-1.0.0.dist-info/entry_points.txt,sha256=5lle5993ULf8qyfNgAiYMugMPdMxklFMhfwjktdNC_A,57
+endstone_clans_api-1.0.0.dist-info/RECORD,,

endstone_clans_api-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any

endstone_clans_api-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[endstone]
+clans-api = endstone_clans_api:ClansApiPlugin