feat: support custom Python events with optional cancellation (#368)

wu-vincent · web-flow · commit a98d70a721e2 · 2026-04-07T18:07:23.000+01:00
* feat: support custom Python events with optional cancellation

Previously, Python plugins could not define custom events — only C++
events exposed via pybind11 were available. This adds a PyEvent
trampoline class that allows Python subclasses of Event to work
correctly, and moves Cancellable to a pure Python mixin so custom
events can opt into cancellation via multiple inheritance.

Also removes the deprecated `cancelled` property (replaced by
`is_cancelled` in a prior release).

* fix: align event name resolution for custom Python events

register_events and PyEvent::getEventName() now agree on naming:
built-in events (endstone.*) use the short class name, custom plugin
events use the fully qualified module.qualname to avoid collisions.

Also adds runtime integration tests for custom event fire/handle cycle
including cancellation semantics via plugin manager.

* fix: use virtual isCancelled() in EventHandler dispatch

EventHandler::callEvent() was reading the C++ cancelled_ field directly,
but custom Python events store cancellation state in a Python attribute.
Use virtual dispatch so PyEvent::isCancelled() is called correctly.

* fix: always return false in Event::isCancelled()
diff --git a/endstone/event/__init__.py b/endstone/event/__init__.py
@@ -16,6 +16,33 @@ def decorator(f):
     return decorator
 
 
+class Cancellable:
+    """
+    Represents an event that may be cancelled by a plugin or the server.
+    """
+
+    @property
+    def is_cancelled(self) -> bool:
+        """
+        Gets or sets the cancellation state of this event.
+
+        A cancelled event will not be executed in the server, but will still pass to other plugins.
+        """
+        return getattr(self, "_cancelled", False)
+
+    @is_cancelled.setter
+    def is_cancelled(self, arg1: bool) -> None:  # noqa
+        setattr(self, "_cancelled", arg1)
+
+    def cancel(self) -> None:
+        """
+        Cancel this event.
+
+        A cancelled event will not be executed in the server, but will still pass to other plugins.
+        """
+        self.is_cancelled = True
+
+
 __getattr__, __dir__, __all__ = lazy.attach(
     "endstone._python",
     submod_attrs={
@@ -40,7 +67,6 @@ def decorator(f):
             "BlockPistonRetractEvent",
             "BlockPlaceEvent",
             "BroadcastMessageEvent",
-            "Cancellable",
             "ChunkEvent",
             "ChunkLoadEvent",
             "ChunkUnloadEvent",
@@ -92,4 +118,4 @@ def decorator(f):
     },
 )
 
-__all__.extend(["EventPriority", "event_handler"])
+__all__.extend(["Cancellable", "EventPriority", "event_handler"])
diff --git a/endstone/event/__init__.pyi b/endstone/event/__init__.pyi
@@ -123,6 +123,7 @@ class Event:
     """
     Represents an event.
     """
+    def __init__(self, is_async: bool = False) -> None: ...
     @property
     def event_name(self) -> str:
         """
@@ -146,24 +147,20 @@ class Cancellable:
     Represents an event that may be cancelled by a plugin or the server.
     """
     @property
-    def cancelled(self) -> bool:
-        """
-        Gets or sets the cancellation state of this event. A cancelled event will not be executed in the server, but will still pass to other plugins. [Warning] Deprecated: Use is_cancelled instead.
-        """
-        ...
-    @cancelled.setter
-    def cancelled(self, arg1: bool) -> None: ...
-    @property
     def is_cancelled(self) -> bool:
         """
-        Gets or sets the cancellation state of this event. A cancelled event will not be executed in the server, but will still pass to other plugins.
+        Gets or sets the cancellation state of this event.
+
+        A cancelled event will not be executed in the server, but will still pass to other plugins.
         """
         ...
     @is_cancelled.setter
     def is_cancelled(self, arg1: bool) -> None: ...
     def cancel(self) -> None:
         """
-        Cancel this event. A cancelled event will not be executed in the server, but will still pass to other plugins.
+        Cancel this event.
+
+        A cancelled event will not be executed in the server, but will still pass to other plugins.
         """
         ...
 
diff --git a/endstone/plugin/__init__.py b/endstone/plugin/__init__.py
@@ -85,9 +85,11 @@ def register_events(self, listener: object) -> None:
             event_cls = params[0].annotation
             priority = getattr(func, "_priority")
             ignore_cancelled = getattr(func, "_ignore_cancelled")
-            self.server.plugin_manager.register_event(
-                getattr(event_cls, "NAME", event_cls.__name__), func, priority, self, ignore_cancelled
-            )
+            if event_cls.__module__.startswith("endstone."):
+                event_name = event_cls.__name__
+            else:
+                event_name = f"{event_cls.__module__}.{event_cls.__qualname__}"
+            self.server.plugin_manager.register_event(event_name, func, priority, self, ignore_cancelled)
 
     @property
     def config(self) -> dict:
diff --git a/include/endstone/event/event.h b/include/endstone/event/event.h
@@ -63,6 +63,7 @@ class Event {
 
 private:
     [[nodiscard]] virtual bool isCancellable() const { return false; }
+    [[nodiscard]] virtual bool isCancelled() const { return false; }
 
     template <class T>
     friend class Cancellable;
diff --git a/include/endstone/event/event_handler.h b/include/endstone/event/event_handler.h
@@ -68,7 +68,7 @@ class EventHandler {
         if (event.getEventName() != event_) {
             return;
         }
-        if (event.isCancellable() && event.cancelled_ && isIgnoreCancelled()) {
+        if (event.isCancellable() && event.isCancelled() && isIgnoreCancelled()) {
             return;
         }
         executor_(event);
diff --git a/src/endstone/python/endstone_python.cpp b/src/endstone/python/endstone_python.cpp
@@ -18,6 +18,7 @@
 
 #include "endstone/detail.h"
 #include "endstone/endstone.hpp"
+#include "event.h"
 #include "registry.h"
 #include "type_caster.h"
 
@@ -32,7 +33,7 @@ void init_command(py::module &, py_class<CommandSender> &command_sender);
 void init_damage(py::module_ &);
 void init_effect(py::module_ &);
 void init_enchantments(py::module_ &);
-void init_event(py::module_ &, py::class_<Event> &event);
+void init_event(py::module_ &, py::class_<Event, PyEvent> &event);
 void init_form(py::module_ &);
 void init_game_mode(py::module_ &);
 void init_inventory(py::module_ &, py::class_<ItemStack> &item_stack);
@@ -123,7 +124,7 @@ PYBIND11_MODULE(_python, m)  // NOLINT(*-use-anonymous-namespace)
 
     // Forward declaration, see:
     // https://pybind11.readthedocs.io/en/stable/advanced/misc.html#avoiding-c-types-in-docstrings
-    auto event = py::class_<Event>(m_event, "Event", "Represents an event.");
+    auto event = py::class_<Event, PyEvent>(m_event, "Event", "Represents an event.");
     auto permissible = py_class<Permissible>(
         m_permissions, "Permissible",
         "Represents an object that may become a server operator and can be assigned permissions.");
diff --git a/src/endstone/python/event.cpp b/src/endstone/python/event.cpp
@@ -12,48 +12,33 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+#include "event.h"
+
 #include "endstone_python.h"
 
 namespace py = pybind11;
 
 namespace endstone::python {
 
-void init_event(py::module_ &m, py::class_<Event> &event)
+void init_event(py::module_ &m, py::class_<Event, PyEvent> &event)
 {
     py::native_enum<EventResult>(m, "EventResult", "enum.Enum")
         .value("DENY", EventResult::Deny)
         .value("DEFAULT", EventResult::Default)
         .value("ALLOW", EventResult::Allow)
         .finalize();
 
-    event.def_property_readonly("event_name", &Event::getEventName, "Gets a user-friendly identifier for this event.")
+    event.def(py::init<bool>(), py::arg("is_async") = false)
+        .def_property_readonly("event_name", &Event::getEventName, "Gets a user-friendly identifier for this event.")
         .def_property_readonly("is_asynchronous", &Event::isAsynchronous, "Whether the event fires asynchronously.");
 
     py::class_<ICancellable>(m, "Cancellable", "Represents an event that may be cancelled by a plugin or the server.")
-        .def_property(
-            "cancelled",
-            [](const ICancellable &self) {
-                PyErr_WarnEx(PyExc_FutureWarning,
-                             "The event.cancelled property is deprecated and will be removed from endstone in a future "
-                             "version. Use event.is_cancelled instead.",
-                             1);
-                return self.isCancelled();
-            },
-            [](ICancellable &self, const bool value) {
-                PyErr_WarnEx(PyExc_FutureWarning,
-                             "The event.cancelled property is deprecated and will be removed from endstone in a future "
-                             "version. Use event.is_cancelled instead.",
-                             1);
-                self.setCancelled(value);
-            },
-            "Gets or sets the cancellation state of this event. A cancelled event will not be executed in "
-            "the server, but will still pass to other plugins. [Warning] Deprecated: Use is_cancelled instead.")
         .def_property("is_cancelled", &ICancellable::isCancelled, &ICancellable::setCancelled,
-                      "Gets or sets the cancellation state of this event. A cancelled event will not be executed in "
-                      "the server, but will still pass to other plugins.")
+                      "Gets or sets the cancellation state of this event.\n\n"
+                      "A cancelled event will not be executed in the server, but will still pass to other plugins.")
         .def("cancel", &ICancellable::cancel,
-             "Cancel this event. A cancelled event will not be executed in the server, but will still pass to other "
-             "plugins.");
+             "Cancel this event.\n\n"
+             "A cancelled event will not be executed in the server, but will still pass to other plugins.");
 
     // Actor events
     py::class_<ActorEvent<Actor>, Event>(m, "ActorEvent", "Represents an Actor-related event.")
@@ -125,8 +110,7 @@ void init_event(py::module_ &m, py::class_<Event> &event)
                                                           "Called when a block is broken by a player.")
         .def_property_readonly("player", &BlockBreakEvent::getPlayer, py::return_value_policy::reference,
                                "Gets the Player that is breaking the block involved in this event.");
-    py::class_<BlockExplodeEvent, BlockEvent, ICancellable>(m, "BlockExplodeEvent",
-                                                             "Called when a block explodes.")
+    py::class_<BlockExplodeEvent, BlockEvent, ICancellable>(m, "BlockExplodeEvent", "Called when a block explodes.")
         .def_property(
             "block_list",
             [](const BlockExplodeEvent &self) {
diff --git a/src/endstone/python/event.h b/src/endstone/python/event.h
@@ -0,0 +1,68 @@
+// Copyright (c) 2024, The Endstone Project. (https://endstone.dev) All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include <string>
+
+#include <fmt/format.h>
+#include <pybind11/pybind11.h>
+
+#include "endstone/event/cancellable.h"
+#include "endstone/event/event.h"
+
+namespace py = pybind11;
+
+namespace endstone::python {
+
+class PyEvent : public Event, public ICancellable {
+public:
+    using Event::Event;
+    [[nodiscard]] std::string getEventName() const override
+    {
+        py::gil_scoped_acquire gil;
+        const auto self = py::cast(this);
+        const auto type = py::type::of(self);
+        auto module = type.attr("__module__").cast<std::string>();
+        auto qualname = type.attr("__qualname__").cast<std::string>();
+        if (module.starts_with("endstone.")) {
+            return qualname;
+        }
+        return fmt::format("{}.{}", module, qualname);
+    }
+
+    [[nodiscard]] bool isCancelled() const override
+    {
+        py::gil_scoped_acquire gil;
+        return py::getattr(py::cast(this), "_cancelled", py::bool_(false)).cast<bool>();
+    }
+
+    void setCancelled(bool cancel) override
+    {
+        py::gil_scoped_acquire gil;
+        py::setattr(py::cast(this), "_cancelled", py::bool_(cancel));
+    }
+
+    void cancel() override { setCancelled(true); }
+
+private:
+    [[nodiscard]] bool isCancellable() const override
+    {
+        py::gil_scoped_acquire gil;
+        const py::object cls = py::module_::import("endstone.event").attr("Cancellable");
+        return py::isinstance(py::cast(this), cls);
+    }
+};
+
+}  // namespace endstone::python
diff --git a/tests/endstone_test/src/endstone_test/tests/test_custom_event.py b/tests/endstone_test/src/endstone_test/tests/test_custom_event.py
@@ -0,0 +1,115 @@
+from endstone import Server
+from endstone.event import Cancellable, Event, EventPriority, event_handler
+from endstone.plugin import Plugin
+
+
+class CustomEvent(Event):
+    """A simple non-cancellable custom event."""
+
+    pass
+
+
+class CancellableCustomEvent(Event, Cancellable):
+    """A cancellable custom event."""
+
+    pass
+
+
+class TestCustomEvent:
+    def test_fire_and_handle(self, server: Server, plugin: Plugin):
+        handled = []
+
+        class Listener:
+            @event_handler
+            def on_custom(self, event: CustomEvent):
+                handled.append(True)
+
+        plugin.register_events(Listener())
+        server.plugin_manager.call_event(CustomEvent())
+        assert len(handled) == 1
+
+    def test_event_name(self):
+        event = CustomEvent()
+        assert event.event_name.endswith("test_custom_event.CustomEvent")
+
+    def test_handler_receives_event_instance(self, server: Server, plugin: Plugin):
+        received = []
+
+        class Listener:
+            @event_handler
+            def on_custom(self, event: CustomEvent):
+                received.append(event)
+
+        plugin.register_events(Listener())
+        event = CustomEvent()
+        server.plugin_manager.call_event(event)
+        assert len(received) == 1
+        assert received[0] is event
+
+
+class TestCancellableCustomEvent:
+    def test_fire_and_handle(self, server: Server, plugin: Plugin):
+        handled = []
+
+        class Listener:
+            @event_handler
+            def on_custom(self, event: CancellableCustomEvent):
+                handled.append(True)
+
+        plugin.register_events(Listener())
+        server.plugin_manager.call_event(CancellableCustomEvent())
+        assert len(handled) == 1
+
+    def test_cancel_in_handler(self, server: Server, plugin: Plugin):
+        class Listener:
+            @event_handler
+            def on_custom(self, event: CancellableCustomEvent):
+                event.cancel()
+
+        plugin.register_events(Listener())
+        event = CancellableCustomEvent()
+        server.plugin_manager.call_event(event)
+        assert event.is_cancelled
+
+    def test_ignore_cancelled_skips_handler(self, server: Server, plugin: Plugin):
+        results = []
+
+        class CancellingListener:
+            @event_handler(priority=EventPriority.LOW)
+            def on_custom(self, event: CancellableCustomEvent):
+                event.cancel()
+                results.append("low")
+
+        class IgnoringListener:
+            @event_handler(priority=EventPriority.HIGH, ignore_cancelled=True)
+            def on_custom(self, event: CancellableCustomEvent):
+                results.append("high_ignore")
+
+        plugin.register_events(CancellingListener())
+        plugin.register_events(IgnoringListener())
+        event = CancellableCustomEvent()
+        server.plugin_manager.call_event(event)
+        assert "low" in results
+        assert "high_ignore" not in results
+
+    def test_default_handler_still_runs_when_cancelled(self, server: Server, plugin: Plugin):
+        results = []
+
+        class CancellingListener:
+            @event_handler(priority=EventPriority.LOW)
+            def on_custom(self, event: CancellableCustomEvent):
+                event.cancel()
+                results.append("low")
+
+        class DefaultListener:
+            @event_handler(priority=EventPriority.HIGH)
+            def on_custom(self, event: CancellableCustomEvent):
+                results.append("high_default")
+
+        plugin.register_events(CancellingListener())
+        plugin.register_events(DefaultListener())
+        event = CancellableCustomEvent()
+        server.plugin_manager.call_event(event)
+        assert "low" in results
+        assert "high_default" in results
+        assert event.is_cancelled
diff --git a/tests/endstone_test/src/endstone_test/tests/test_registry.py b/tests/endstone_test/src/endstone_test/tests/test_registry.py
diff --git a/tests/mocks.h b/tests/mocks.h
diff --git a/tests/test_event.py b/tests/test_event.py
diff --git a/tests/test_nbt.py b/tests/test_nbt.py

Original file line number	Diff line number	Diff line change
`@@ -68,7 +68,7 @@ class EventHandler {`
`68`	`68`	`if (event.getEventName() != event_) {`
`69`	`69`	`return;`
`70`	`70`	`}`
`71`		`- if (event.isCancellable() && event.cancelled_ && isIgnoreCancelled()) {`
	`71`	`+ if (event.isCancellable() && event.isCancelled() && isIgnoreCancelled()) {`
`72`	`72`	`return;`
`73`	`73`	`}`
`74`	`74`	`executor_(event);`