pumpkin-api-py 0.1.0.dev0__tar.gz → 0.1.0.dev2__tar.gz

{pumpkin_api_py-0.1.0.dev0 → pumpkin_api_py-0.1.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pumpkin-api-py
-Version: 0.1.0.dev0
+Version: 0.1.0.dev2
 Summary: Pumpkin plugin API for Python
 Author: alex
 License-Expression: GPL-3.0-only
@@ -24,29 +24,22 @@ pip install pumpkin-api-py
 2. Create your plugin (`main.py`):
 
 ```python
-from pumpkin_api import (
-    Plugin, PluginMetadata, register_plugin, 
-    server, event, command, text, context
-)
+from pumpkin_api import Plugin, context, logging, metadata, register_plugin
+
+PluginMetadata = metadata.PluginMetadata
 
 class MyPlugin(Plugin):
     def metadata(self) -> PluginMetadata:
         return PluginMetadata(
-            name="my-plugin",
+            name="my-python-plugin",
             version="0.1.0",
             authors=["you"],
-            description="An example plugin."
+            description="An example python plugin.",
+            dependencies=[],
         )
 
     def on_load(self, ctx: context.Context) -> None:
-        print("Python plugin loaded!")
-        
-        # Register an event handler
-        self.register_event(ctx, event.EventType.PLAYER_JOIN_EVENT, self.on_player_join)
-
-    def on_player_join(self, srv: server.Server, evt: event.PlayerJoinEventData) -> event.PlayerJoinEventData:
-        print(f"Player {evt.player.get_name()} joined!")
-        return evt
+        logging.log(logging.Level.INFO, "Python plugin loaded!")
 
 register_plugin(MyPlugin)
 ```
@@ -54,5 +47,5 @@ register_plugin(MyPlugin)
 3. Build your plugin into a WebAssembly component:
 
 ```bash
-pumpkin-api-build main -o my_plugin.wasm
+pumpkin-plugin-build main -o my_plugin.wasm
 ```

{pumpkin_api_py-0.1.0.dev0 → pumpkin_api_py-0.1.0.dev2}/README.md

@@ -13,29 +13,22 @@ pip install pumpkin-api-py
 2. Create your plugin (`main.py`):
 
 ```python
-from pumpkin_api import (
-    Plugin, PluginMetadata, register_plugin, 
-    server, event, command, text, context
-)
+from pumpkin_api import Plugin, context, logging, metadata, register_plugin
+
+PluginMetadata = metadata.PluginMetadata
 
 class MyPlugin(Plugin):
     def metadata(self) -> PluginMetadata:
         return PluginMetadata(
-            name="my-plugin",
+            name="my-python-plugin",
             version="0.1.0",
             authors=["you"],
-            description="An example plugin."
+            description="An example python plugin.",
+            dependencies=[],
         )
 
     def on_load(self, ctx: context.Context) -> None:
-        print("Python plugin loaded!")
-        
-        # Register an event handler
-        self.register_event(ctx, event.EventType.PLAYER_JOIN_EVENT, self.on_player_join)
-
-    def on_player_join(self, srv: server.Server, evt: event.PlayerJoinEventData) -> event.PlayerJoinEventData:
-        print(f"Player {evt.player.get_name()} joined!")
-        return evt
+        logging.log(logging.Level.INFO, "Python plugin loaded!")
 
 register_plugin(MyPlugin)
 ```
@@ -43,5 +36,5 @@ register_plugin(MyPlugin)
 3. Build your plugin into a WebAssembly component:
 
 ```bash
-pumpkin-api-build main -o my_plugin.wasm
+pumpkin-plugin-build main -o my_plugin.wasm
 ```

pumpkin_api_py-0.1.0.dev2/hatch_build.py

@@ -0,0 +1,28 @@
+from os import path
+from shutil import rmtree
+
+import componentize_py
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version: str, build_data: dict[str, any]) -> None:
+        bindings_out_path = path.join(self.directory, "bindings")
+        if path.exists(bindings_out_path):
+            rmtree(bindings_out_path)
+
+        componentize_py.generate_bindings(
+            wit_path=[
+                path.join(self.root, "wit", "repo", "pumpkin-plugin-wit", "v0.1")
+            ],
+            worlds=[],
+            features=[],
+            all_features=False,
+            world_module="wit_world",
+            output_dir=bindings_out_path,
+            import_interface_names=[],
+            export_interface_names=[],
+            full_names=False,
+        )
+
+        build_data["force_include"][bindings_out_path] = ""

pumpkin_api_py-0.1.0.dev2/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "pumpkin-api-py"
+version = "0.1.0.dev2"
+description = "Pumpkin plugin API for Python"
+authors = [{name = "alex"}]
+license = "GPL-3.0-only"
+dependencies = [
+    "componentize-py>=0.22.1",
+]
+readme = "README.md"
+requires-python = ">=3.9"
+
+[project.scripts]
+pumpkin-plugin-build = "pumpkin_api.build:main"
+
+[build-system]
+requires = ["hatchling","componentize-py>=0.22.1"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/pumpkin_api",
+    "hatch_build.py",
+    "wit/repo/pumpkin-plugin-wit/v0.1"
+]
+
+[tool.hatch.build.targets.wheel]
+include = ["src/pumpkin_api", "wit/repo/pumpkin-plugin-wit/v0.1/"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""
+"bindings" = ""
+"wit/repo/pumpkin-plugin-wit/v0.1/" = "pumpkin_api/wit"
+
+[tool.hatch.build.targets.wheel.hooks.custom]

pumpkin_api_py-0.1.0.dev2/src/pumpkin_api/__init__.py

@@ -0,0 +1,41 @@
+from wit_world.exports import metadata
+from wit_world.imports import (
+    block_entity,
+    command,
+    common,
+    context,
+    event,
+    gui,
+    i18n,
+    logging,
+    permission,
+    player,
+    scheduler,
+    scoreboard,
+    server,
+    text,
+    world,
+)
+
+from .impl import Plugin, register_plugin
+
+__all__ = [
+    "Plugin",
+    "register_plugin",
+    "block_entity",
+    "command",
+    "common",
+    "context",
+    "event",
+    "gui",
+    "i18n",
+    "logging",
+    "metadata",
+    "permission",
+    "player",
+    "scheduler",
+    "server",
+    "scoreboard",
+    "text",
+    "world",
+]

pumpkin_api_py-0.1.0.dev2/src/pumpkin_api/build.py

@@ -0,0 +1,69 @@
+import argparse
+import os
+import tempfile
+
+import componentize_py
+
+
+def _build_entrypoint_wrapper(app_module: str, wrapper_dir: str) -> str:
+    wrapper_name = "_pumpkin_componentize_entry"
+    wrapper_path = os.path.join(wrapper_dir, f"{wrapper_name}.py")
+
+    with open(wrapper_path, "w", encoding="utf-8") as wrapper_file:
+        wrapper_file.write(
+            "from pathlib import Path\n"
+            "from pumpkin_api.impl import MetadataImpl, WitWorldImpl\n\n"
+            "WitWorld = WitWorldImpl\n"
+            "Metadata = MetadataImpl\n\n"
+            f"import {app_module}\n"
+        )
+    return wrapper_name
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Build a Pumpkin Python plugin")
+    parser.add_argument(
+        "app_module", help="The python module containing the plugin (e.g. 'main')"
+    )
+    parser.add_argument(
+        "-o", "--output", default="plugin.wasm", help="Output wasm file name"
+    )
+    args = parser.parse_args()
+
+    import pumpkin_api
+
+    pkg_dir = os.path.dirname(pumpkin_api.__file__)
+    # In source checkout, they are in wit_files/repo/...
+    # In installed package, they are directly in wit_files/
+    wit_dir = os.path.join(
+        pkg_dir, "..", "..", "wit", "repo", "pumpkin-plugin-wit", "v0.1.0"
+    )
+    if not os.path.exists(wit_dir):
+        wit_dir = os.path.join(pkg_dir, "wit")
+
+    # Pass the parent directory of pumpkin_api to componentize-py so it can resolve `pumpkin_api` module
+    # in case it's not installed in a standard site-packages (e.g. editable install or no venv)
+    pkg_parent_dir = os.path.dirname(pkg_dir)
+
+    with tempfile.TemporaryDirectory(prefix="pumpkin-api-build-") as wrapper_dir:
+        wrapper_module = _build_entrypoint_wrapper(args.app_module, wrapper_dir)
+
+        componentize_py.componentize(
+            wit_path=[wit_dir],
+            worlds=[],
+            features=[],
+            all_features=False,
+            world_module="wit_world",
+            python_path=[".", pkg_parent_dir, wrapper_dir],
+            module_worlds=[],
+            app_name=wrapper_module,
+            output_path=args.output,
+            stub_wasi=False,
+            import_interface_names=[],
+            export_interface_names=[],
+            full_names=False,
+        )
+
+
+if __name__ == "__main__":
+    main()

pumpkin_api_py-0.1.0.dev2/src/pumpkin_api/impl.py

@@ -0,0 +1,216 @@
+# pumpkin-api-py: Pumpkin plugin API for Python
+# Copyright (C) 2024 alex
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import traceback
+from typing import Any, Callable, Dict, Optional, Type
+
+import wit_world
+import wit_world.exports
+from componentize_py_types import Err
+from wit_world.exports import metadata
+from wit_world.imports import command, context, event, scheduler, server, text
+
+_PLUGIN_INSTANCE: Optional["Plugin"] = None
+_EVENT_HANDLERS: Dict[int, Callable[[server.Server, Any], Any]] = {}
+_COMMAND_HANDLERS: Dict[
+    int, Callable[[command.CommandSender, server.Server, command.ConsumedArgs], int]
+] = {}
+_TASK_HANDLERS: Dict[int, Callable[[server.Server], None]] = {}
+_NEXT_HANDLER_ID: int = 0
+
+
+def _exception_message(exc: Exception) -> str:
+    if hasattr(exc, "value"):
+        value = getattr(exc, "value")
+        if value is not None:
+            return str(value)
+    message = str(exc)
+    if message:
+        return message
+    return "".join(traceback.format_exception_only(type(exc), exc)).strip()
+
+
+def _format_exception(exc: Exception) -> str:
+    details = "".join(
+        traceback.format_exception(type(exc), exc, exc.__traceback__)
+    ).strip()
+    if details:
+        return details
+    return _exception_message(exc)
+
+
+def _get_next_handler_id() -> int:
+    global _NEXT_HANDLER_ID
+    handler_id = _NEXT_HANDLER_ID
+    _NEXT_HANDLER_ID += 1
+    return handler_id
+
+
+class Plugin:
+    def __init__(self):
+        self._pending_events = []
+
+    def metadata(self) -> metadata.PluginMetadata:
+        raise NotImplementedError
+
+    def on_load(self, ctx: context.Context) -> None:
+        for event_type, handler, priority, blocking in self._pending_events:
+            self.register_event(ctx, event_type, handler, priority, blocking)
+
+    def on_unload(self, ctx: context.Context) -> None:
+        pass
+
+    def register_event(
+        self,
+        ctx: context.Context,
+        event_type: event.EventType,
+        handler: Callable[[server.Server, Any], Any],
+        priority=event.EventPriority.NORMAL,
+        blocking=True,
+    ):
+        handler_id = _get_next_handler_id()
+        _EVENT_HANDLERS[handler_id] = handler
+        ctx.register_event(handler_id, event_type, priority, blocking)
+
+    def register_command(
+        self,
+        ctx: context.Context,
+        cmd: command.Command,
+        handler: Callable[
+            [command.CommandSender, server.Server, command.ConsumedArgs], int
+        ],
+        permission: str = "",
+    ):
+        handler_id = _get_next_handler_id()
+        _COMMAND_HANDLERS[handler_id] = handler
+        cmd.execute_with_handler_id(handler_id)
+        ctx.register_command(cmd, permission)
+
+    def schedule_delayed_task(
+        self, delay_ticks: int, handler: Callable[[server.Server], None]
+    ) -> int:
+        handler_id = _get_next_handler_id()
+        _TASK_HANDLERS[handler_id] = handler
+        return scheduler.schedule_delayed_task(handler_id, delay_ticks)
+
+    def schedule_repeating_task(
+        self,
+        delay_ticks: int,
+        period_ticks: int,
+        handler: Callable[[server.Server], None],
+    ) -> int:
+        handler_id = _get_next_handler_id()
+        _TASK_HANDLERS[handler_id] = handler
+        return scheduler.schedule_repeating_task(handler_id, delay_ticks, period_ticks)
+
+    def event_handler(
+        self,
+        event_type: event.EventType,
+        priority=event.EventPriority.NORMAL,
+        blocking=True,
+    ):
+        def decorator(func):
+            self._pending_events.append((event_type, func, priority, blocking))
+            return func
+
+        return decorator
+
+
+def register_plugin(plugin_class: Type[Plugin]):
+    global _PLUGIN_INSTANCE
+    _PLUGIN_INSTANCE = plugin_class()
+
+
+class WitWorldImpl(wit_world.WitWorld):
+    def init_plugin(self) -> None:
+        pass
+
+    def on_load(self, context: context.Context) -> None:
+        if _PLUGIN_INSTANCE:
+            try:
+                # In WIT, on-load returns result<_, string>
+                # componentize-py handles this by expecting None or raising Err
+                _PLUGIN_INSTANCE.on_load(context)
+            except Err as e:
+                raise Err(_exception_message(e))
+            except Exception as e:
+                raise Err(_format_exception(e))
+
+    def on_unload(self, context: context.Context) -> None:
+        if _PLUGIN_INSTANCE:
+            try:
+                _PLUGIN_INSTANCE.on_unload(context)
+            except Err as e:
+                raise Err(_exception_message(e))
+            except Exception as e:
+                raise Err(_format_exception(e))
+
+    def handle_event(
+        self, event_id: int, server: server.Server, event: event.Event
+    ) -> event.Event:
+        if event_id in _EVENT_HANDLERS:
+            # Pass the inner event data to the handler
+            result = _EVENT_HANDLERS[event_id](server, event.value)
+            # If the handler returns something, assume it's the updated event data
+            if result is not None:
+                event.value = result
+        return event
+
+    def handle_command(
+        self,
+        command_id: int,
+        sender: command.CommandSender,
+        server: server.Server,
+        args: command.ConsumedArgs,
+    ) -> int:
+        if command_id in _COMMAND_HANDLERS:
+            try:
+                return _COMMAND_HANDLERS[command_id](sender, server, args)
+            except Exception as e:
+                if hasattr(e, "value") and isinstance(
+                    e.value,
+                    (
+                        command.CommandError_InvalidConsumption,
+                        command.CommandError_InvalidRequirement,
+                        command.CommandError_PermissionDenied,
+                        command.CommandError_CommandFailed,
+                    ),
+                ):
+                    raise e
+                raise Err(
+                    command.CommandError_CommandFailed(
+                        text.TextComponent.text(_format_exception(e))
+                    )
+                )
+
+        raise Err(
+            command.CommandError_CommandFailed(
+                text.TextComponent.text(
+                    f"no handler registered for command id {command_id}"
+                )
+            )
+        )
+
+    def handle_task(self, handler_id: int, server: server.Server) -> None:
+        if handler_id in _TASK_HANDLERS:
+            _TASK_HANDLERS[handler_id](server)
+
+
+class MetadataImpl:
+    def get_metadata(self) -> metadata.PluginMetadata:
+        if _PLUGIN_INSTANCE:
+            return _PLUGIN_INSTANCE.metadata()
+        return metadata.PluginMetadata("unknown", "0.0.0", [], "No metadata", [])

pumpkin_api_py-0.1.0.dev0/src/pumpkin_api/wit_files/entity.wit → pumpkin_api_py-0.1.0.dev2/wit/repo/pumpkin-plugin-wit/v0.1/block-entity.wit

@@ -1,4 +1,4 @@
-interface entity {
+interface block-entity {
     use common.{block-position};
 
     resource block-entity {
@@ -30,7 +30,7 @@ interface entity {
         powered: func() -> bool;
     }
 
-    variant entity {
+    variant block-entity-type {
         command-block-entity(command-block-entity),
     }
 }

pumpkin_api_py-0.1.0.dev2/wit/repo/pumpkin-plugin-wit/v0.1/boss-bar.wit

@@ -0,0 +1,82 @@
+interface boss-bar {
+    use text.{text-component};
+    use player.{player};
+
+    /// Represents the color of a boss bar.
+    enum boss-bar-color {
+        pink,
+        blue,
+        red,
+        green,
+        yellow,
+        purple,
+        white,
+    }
+
+    /// Represents the notches/divisions of a boss bar.
+    enum boss-bar-division {
+        no-division,
+        notches-6,
+        notches-10,
+        notches-12,
+        notches-20,
+    }
+
+    /// Metadata flags that can be toggled on a boss bar.
+    record boss-bar-metadata {
+        /// Darkens the sky for players who see the boss bar.
+        darken-sky: bool,
+        /// If true, the bar is considered a "dragon bar" (used for Ender Dragon).
+        dragon-bar: bool,
+        /// If true, fog is created around the players who see the boss bar.
+        create-fog: bool,
+    }
+
+    /// Represents a boss bar that can be shown to players.
+    resource boss-bar {
+        /// Creates a new boss bar.
+        constructor(title: text-component, color: boss-bar-color, division: boss-bar-division);
+        
+        /// Returns the title of this boss bar.
+        get-title: func() -> text-component;
+        
+        /// Sets the title of this boss bar.
+        set-title: func(title: text-component);
+        
+        /// Returns the health (0.0 to 1.0) of this boss bar.
+        get-health: func() -> f32;
+        
+        /// Sets the health (0.0 to 1.0) of this boss bar.
+        set-health: func(health: f32);
+        
+        /// Returns the color of this boss bar.
+        get-color: func() -> boss-bar-color;
+        
+        /// Sets the color of this boss bar.
+        set-color: func(color: boss-bar-color);
+        
+        /// Returns the division of this boss bar.
+        get-division: func() -> boss-bar-division;
+        
+        /// Sets the division of this boss bar.
+        set-division: func(division: boss-bar-division);
+
+        /// Returns the currently active metadata on this boss bar.
+        get-metadata: func() -> boss-bar-metadata;
+
+        /// Updates the metadata on this boss bar.
+        set-metadata: func(metadata: boss-bar-metadata);
+        
+        /// Adds a player to this boss bar, making it visible to them.
+        add-player: func(player: player);
+        
+        /// Removes a player from this boss bar, hiding it from them.
+        remove-player: func(player: player);
+        
+        /// Returns a list of all players currently seeing this boss bar.
+        get-players: func() -> list<player>;
+        
+        /// Removes this boss bar from all players and cleans it up.
+        remove-all: func();
+    }
+}

{pumpkin_api_py-0.1.0.dev0/src/pumpkin_api/wit_files → pumpkin_api_py-0.1.0.dev2/wit/repo/pumpkin-plugin-wit/v0.1}/command.wit

@@ -1,7 +1,8 @@
 interface command {
-    use player.{player};
     use %world.{%world};
-    use entity.{command-block-entity, entity};
+    use entity.{entity};
+    use player.{player};
+    use block-entity.{command-block-entity};
     use common.{position, block-position, locale};
     use server.{server, difficulty};
     use text.{text-component};

{pumpkin_api_py-0.1.0.dev0/src/pumpkin_api/wit_files → pumpkin_api_py-0.1.0.dev2/wit/repo/pumpkin-plugin-wit/v0.1}/common.wit

@@ -67,6 +67,28 @@ interface common {
         count: u8,
     }
 
+    /// Represents the various poses an entity can be in.
+    enum entity-pose {
+        standing,
+        fall-flying,
+        sleeping,
+        swimming,
+        spin-attack,
+        crouching,
+        long-jumping,
+        dying,
+        croaking,
+        using-tongue,
+        sitting,
+        roaring,
+        sniffing,
+        emerging,
+        digging,
+        sliding,
+        shooting,
+        inhaling,
+    }
+
     /// All Minecraft-supported locales.
     enum locale {
         af-za,

pumpkin_api_py-0.1.0.dev2/wit/repo/pumpkin-plugin-wit/v0.1/entity.wit

@@ -0,0 +1,3 @@
+interface entity {
+    use %world.{entity};
+}

{pumpkin_api_py-0.1.0.dev0/src/pumpkin_api/wit_files → pumpkin_api_py-0.1.0.dev2/wit/repo/pumpkin-plugin-wit/v0.1}/event.wit

@@ -150,7 +150,6 @@ interface event {
         player: player,
         action: interact-action,
         clicked-pos: option<block-position>,
-        item: item-stack,
         block: string,
         cancelled: bool
     }
@@ -161,6 +160,12 @@ interface event {
         cancelled: bool
     }
 
+    record player-toggle-flight-event-data {
+        player: player,
+        is-flying: bool,
+        cancelled: bool
+    }
+
     record player-toggle-sprint-event-data {
         player: player,
         is-sprinting: bool,
@@ -265,6 +270,7 @@ interface event {
         player-interact-unknown-entity-event,
         player-interact-event,
         player-toggle-sneak-event,
+        player-toggle-flight-event,
         player-toggle-sprint-event,
         block-redstone-event,
         block-break-event,
@@ -297,6 +303,7 @@ interface event {
         player-interact-unknown-entity-event(player-interact-unknown-entity-event-data),
         player-interact-event(player-interact-event-data),
         player-toggle-sneak-event(player-toggle-sneak-event-data),
+        player-toggle-flight-event(player-toggle-flight-event-data),
         player-toggle-sprint-event(player-toggle-sprint-event-data),
         block-redstone-event(block-redstone-event-data),
         block-break-event(block-break-event-data),

{pumpkin_api_py-0.1.0.dev0/src/pumpkin_api/wit_files → pumpkin_api_py-0.1.0.dev2/wit/repo/pumpkin-plugin-wit/v0.1}/gui.wit

@@ -34,5 +34,17 @@ interface gui {
         constructor(%type: gui-type, title: text-component);
         set-item: func(slot: u32, item: item-stack);
         get-item: func(slot: u32) -> option<item-stack>;
+        
+        /// Returns the type of this GUI.
+        get-type: func() -> gui-type;
+        
+        /// Returns the title of this GUI.
+        get-title: func() -> text-component;
+        
+        /// Returns the number of slots in this GUI.
+        get-size: func() -> u32;
+        
+        /// Clears all items from the GUI.
+        clear-items: func();
     }
 }