endstone-clans-api 1.0.0__tar.gz

endstone_clans_api-1.0.0/.github/workflows/python-publish.yml

@@ -0,0 +1,70 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      # url: https://pypi.org/p/YOURPROJECT
+      #
+      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
+      # ALTERNATIVE: exactly, uncomment the following line instead:
+      # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

endstone_clans_api-1.0.0/.gitignore

@@ -0,0 +1,3 @@
+.venv
+bedrock_server
+**__pycache__

endstone_clans_api-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,68 @@
+<div align="center">
+
+# Endstone Clans API
+
+</div>
+
+A plugin that manages clans (or teams, if you will). This is meant to be used in conjunction with one of your own plugins, so using it on its own isn't recommended (this genuinely does not do anything without it).
+
+## Features
+
+> - Portable SQLite database
+> You can test this plugin in staging, and bring the `clans.db` file to production. While it's not recommended to modify the database while it's still running, you can do it and most of the time you'll be fine.
+
+> - User-facing commands that let them manage their own clans
+> Users may create clans, rename their own clans, whatever. They must stay in only one clan, though.
+
+> - API that _respects_ your language server
+> No more blindly throwing methods, `getattr`s, and `setattr`s at an `Any` type like in certain other APIs. As long as you import `get_clans_api` and use that, then your language server gets to have all the information to do things like full autocomplete and typehints.
+
+> - Event system
+> You can cancel events, do whatever. You can even use this to do things like replace the invite UI with your own.
+
+> - Extensive config
+> The config lets you configure a lot.
+>
+> Every single piece of front-end facing text translatable through the config.
+
+## Documentation
+
+> [!IMPORTANT]
+> Always use this by installing the plugin into your environment, not putting it into the server's `plugins/` directory as a `.whl`. Installing will give you the typehints that you're meant to have.
+
+### Quick Start
+```python
+from endstone_clans_api import (
+    get_clans_api, 
+    ClanCreateEvent, 
+    clan_event_handler, 
+    ClansApi
+)
+from endstone.plugin import Plugin
+
+class ExamplePlugin(Plugin):
+    def on_enable(self):
+        # This will get the plugin, and then the plugin's API.
+        api: ClansApi | None = get_clans_api(self.server.plugin_manager)
+
+        # Since we're doing everything right, there is little-to-no reason that
+        # this should return None.
+        assert api, "`get_clans_api` returned `None`"
+        self.api: ClansApi = api
+        
+        # Just like Endstone's register_events, you can make a sperate listener
+        # class in a different module to make everything cleaner.
+        self.api.register_events(self)
+
+    @clan_event_handler
+    def on_clan_create(self, event: ClanCreateEvent):
+        # Simple test log so you can see that the plugin's API is funcitonal.
+        self.logger.info(f"Event: ClanCreateEvent - Name: {event.clan.display_name}, Creator: {event.creator.name}")
+        
+        # Let's say that we wanted to ban spaces from clan names. Just handle it
+        # here.
+        if " " in event.clan.display_name:
+            event.cancel()
+            event.creator.send_error_message("Clan names cannot have spaces in them!")
+```
+I think you've noticed by now that this feels really native to Endstone. Feels like we're re-implementing their design, and that's a good thing--Endstone's design is *exceptional*.

endstone_clans_api-1.0.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "endstone-clans-api"
+version = "1.0.0"
+description = ""
+authors = [
+    { name = "niko-at-chalupa"},
+]
+dependencies = [
+    "endstone",
+    "pydantic",
+    "ruamel.yaml",
+    "xxhash",
+]
+
+[project.entry-points."endstone"]
+clans-api = "endstone_clans_api:ClansApiPlugin"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/endstone_clans_api"]

endstone_clans_api-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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