1D - Damage events and entity ownership

Omena0 · Omena0 · commit 252e5361f927 · 2026-02-01T19:21:05.000+02:00
diff --git a/changelog.md b/changelog.md
@@ -1,6 +1,18 @@
 
 # Changelog
 
+## 1D
+
+Damage event
+
+Changes:
+
+- Added damage override to damage events
+- Added damage source and damager attributes to damage events
+- Added shooter attribute to projectile entities
+- Added owner attribute to tamed entities
+- Added is_tamed attribute to entities
+
 ## 1C
 
 API cleanup
diff --git a/docs/index.md b/docs/index.md
@@ -49,6 +49,10 @@ Base event proxy. Event payloads may expose additional fields depending on event
 
 - `block`: [`Block`](#block) — The block involved in the event, if any.
 - `chunk`: [`Chunk`](#chunk) — The chunk involved in the event, if any.
+- `damager`: [`Entity`](#entity) or [`Block`](#block) — The damage source for damage-related events, if any.
+- `damage`: float — Raw damage for damage-related events.
+- `final_damage`: float — Final damage after modifiers for damage-related events.
+- `damage_cause`: [`EntityDamageEvent.DamageCause`](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/entity/EntityDamageEvent.DamageCause.html) — Damage cause, if available.
 - `entity`: [`Entity`](#entity) — The entity involved in the event, if any.
 - `inventory`: [`Inventory`](#inventory) — The inventory involved in the event, if any.
 - `item`: [`Item`](#item) — The item involved in the event, if any.
@@ -61,6 +65,8 @@ Base event proxy. Event payloads may expose additional fields depending on event
 
 - `cancel()` — Cancel the event if it is cancellable. Returns an awaitable that resolves to `None`.
 
+For damage-related events, returning a number from the handler overrides the event damage.
+
 ### Chat formatting
 
 For `player_chat` handlers, returning a string will cancel the original chat event and broadcast the returned string instead. Returning `None` (or no return value) leaves chat unchanged.
@@ -138,6 +144,13 @@ Base entity proxy.
 
 - `location`: [`Location`](#location) — Current location.
 - `type`: [`EntityType`](#entitytype) — Entity type.
+- `is_projectile`: bool — Whether this entity is a projectile.
+- `shooter`: [`Entity`](#entity) or [`Block`](#block) — Projectile shooter/source, if any.
+- `is_tamed`: bool — Whether this entity is tamed (if tameable).
+- `owner`: [`Player`](#player) — Owner (if tameable and owner is online).
+- `owner_uuid`: str — Owner UUID (if tameable).
+- `owner_name`: str — Owner name (if tameable and known).
+- `source`: [`Entity`](#entity) or [`Player`](#player) — Source for spawned entities (e.g., TNT, clouds), if available.
 - `uuid`: str — Unique id.
 - `world`: [`World`](#world) — Current world.
 
diff --git a/releases/pyjavabridge-1C.jar b/releases/pyjavabridge-1C.jar
diff --git a/src/main/java/com/pyjavabridge/PyJavaBridgePlugin.java b/src/main/java/com/pyjavabridge/PyJavaBridgePlugin.java
@@ -14,6 +14,9 @@
 import org.bukkit.entity.EntityType;
 import org.bukkit.entity.LivingEntity;
 import org.bukkit.entity.Player;
+import org.bukkit.entity.Projectile;
+import org.bukkit.entity.Tameable;
+import org.bukkit.entity.AnimalTamer;
 import org.bukkit.event.Event;
 import org.bukkit.event.EventPriority;
 import org.bukkit.event.HandlerList;
@@ -24,13 +27,16 @@
 import org.bukkit.block.BlockState;
 import org.bukkit.event.inventory.InventoryClickEvent;
 import org.bukkit.event.entity.CreatureSpawnEvent;
+import org.bukkit.event.entity.EntityDamageEvent;
 import org.bukkit.plugin.EventExecutor;
 import org.bukkit.plugin.java.JavaPlugin;
 import org.bukkit.scheduler.BukkitTask;
 import org.bukkit.command.CommandMap;
 import org.bukkit.util.RayTraceResult;
 import org.bukkit.util.Vector;
 import org.bukkit.permissions.PermissionAttachment;
+import org.bukkit.projectiles.BlockProjectileSource;
+import org.bukkit.projectiles.ProjectileSource;
 import org.bukkit.attribute.Attribute;
 import org.bukkit.attribute.AttributeModifier;
 import org.bukkit.inventory.InventoryHolder;
@@ -825,7 +831,20 @@ private void handleEventResult(JsonObject message) {
                 return;
             }
 
-            if (message.has("result") && !message.get("result").isJsonNull()) {
+            if (!message.has("result") || message.get("result").isJsonNull()) {
+                return;
+            }
+
+            String resultType = message.has("result_type") ? message.get("result_type").getAsString() : null;
+            if ("damage".equalsIgnoreCase(resultType)) {
+                JsonElement result = message.get("result");
+                if (result.isJsonPrimitive() && result.getAsJsonPrimitive().isNumber()) {
+                    pending.damageOverride = result.getAsDouble();
+                }
+                return;
+            }
+
+            if (resultType == null || "chat".equalsIgnoreCase(resultType)) {
                 pending.chatOverride = message.get("result").getAsString();
             }
         }
@@ -2142,6 +2161,8 @@ private JsonElement serialize(Object value, Set<Object> seen) {
                 fields.add("type", serialize(entity.getType(), seen));
                 fields.add("location", serialize(entity.getLocation(), seen));
                 fields.add("world", serialize(entity.getWorld(), seen));
+                fields.addProperty("is_projectile", entity instanceof Projectile);
+                addAttributionFields(entity, fields, seen);
             }
 
             if (value instanceof org.bukkit.World world) {
@@ -2545,6 +2566,12 @@ private JsonObject baseEventPayload(Event event, String eventName) {
             tryAddPayload(payload, event, "player", "getPlayer", "getWhoClicked");
             tryAddPayload(payload, event, "block", "getBlock", "getClickedBlock");
             tryAddPayload(payload, event, "entity", "getEntity");
+            tryAddPayload(payload, event, "damager", "getDamager");
+            if (event instanceof EntityDamageEvent damageEvent) {
+                payload.addProperty("damage", damageEvent.getDamage());
+                payload.addProperty("final_damage", damageEvent.getFinalDamage());
+                payload.add("damage_cause", serialize(damageEvent.getCause()));
+            }
             tryAddPayload(payload, event, "location", "getLocation");
             tryAddPayload(payload, event, "world", "getWorld");
             tryAddPayload(payload, event, "item", "getItem");
@@ -2601,6 +2628,9 @@ private boolean dispatchCancellableEvent(Event event, String eventName, JsonObje
                     Bukkit.getScheduler().runTask(plugin,
                             () -> Bukkit.getServer().broadcast(net.kyori.adventure.text.Component.text(message)));
                 }
+                if (pending.damageOverride != null && pending.event instanceof EntityDamageEvent damageEvent) {
+                    damageEvent.setDamage(pending.damageOverride);
+                }
                 if (cancelRequested && cancelMode == CancelMode.EVENT) {
                     pending.cancellable.setCancelled(true);
                 }
@@ -2695,6 +2725,115 @@ private void tryAddPayload(JsonObject payload, Event event, String key, String..
             }
         }
 
+        private void addAttributionFields(org.bukkit.entity.Entity entity, JsonObject fields, Set<Object> seen) {
+            Object shooter = null;
+            if (entity instanceof Projectile projectile) {
+                shooter = projectile.getShooter();
+            } else {
+                shooter = tryInvokeNoArg(entity, "getShooter");
+            }
+            addAttribution("shooter", shooter, fields, seen);
+
+            Object source = tryInvokeNoArg(entity, "getSource");
+            addAttribution("source", source, fields, seen);
+
+            Object owner = null;
+            if (entity instanceof Tameable tameable) {
+                fields.addProperty("is_tamed", tameable.isTamed());
+                owner = tameable.getOwner();
+            }
+            if (owner == null) {
+                owner = tryInvokeNoArg(entity, "getOwner");
+            }
+            if (owner == null) {
+                owner = tryInvokeNoArg(entity, "getOwningPlayer");
+            }
+            if (owner == null) {
+                owner = tryInvokeNoArg(entity, "getOwningEntity");
+            }
+            if (owner == null) {
+                owner = tryInvokeNoArg(entity, "getSummoner");
+            }
+            addAttribution("owner", owner, fields, seen);
+
+        }
+
+        private Object tryInvokeNoArg(Object target, String methodName) {
+            try {
+                Method method = target.getClass().getMethod(methodName);
+                if (method.getParameterCount() != 0) {
+                    return null;
+                }
+                return method.invoke(target);
+            } catch (Exception ignored) {
+                return null;
+            }
+        }
+
+        private void addAttribution(String key, Object source, JsonObject fields, Set<Object> seen) {
+            if (source == null) {
+                return;
+            }
+            if (fields.has(key)) {
+                return;
+            }
+
+            Object resolved = source;
+            if (source instanceof ProjectileSource projectileSource && !(source instanceof Entity)) {
+                if (projectileSource instanceof BlockProjectileSource blockSource) {
+                    resolved = blockSource.getBlock();
+                }
+            }
+
+            if ("source".equals(key) || "shooter".equals(key)) {
+                if (resolved instanceof Entity sourceEntity) {
+                    fields.add(key, serialize(sourceEntity, seen));
+                } else if (resolved instanceof org.bukkit.block.Block block) {
+                    fields.add(key, serialize(block, seen));
+                }
+                return;
+            }
+
+            if (resolved instanceof Entity sourceEntity) {
+                fields.add(key, serialize(sourceEntity, seen));
+                fields.addProperty(key + "_uuid", sourceEntity.getUniqueId().toString());
+                if (sourceEntity instanceof Player player) {
+                    fields.addProperty(key + "_name", player.getName());
+                } else {
+                    Object name = tryInvokeNoArg(sourceEntity, "getName");
+                    if (name instanceof String nameText && !nameText.isBlank()) {
+                        fields.addProperty(key + "_name", nameText);
+                    }
+                }
+                return;
+            }
+
+            if (resolved instanceof org.bukkit.block.Block block) {
+                fields.add(key, serialize(block, seen));
+                return;
+            }
+
+            if (resolved instanceof AnimalTamer tamer) {
+                fields.addProperty(key + "_uuid", tamer.getUniqueId().toString());
+                if (tamer.getName() != null) {
+                    fields.addProperty(key + "_name", tamer.getName());
+                }
+                if (tamer instanceof Player player) {
+                    fields.add(key, serialize(player, seen));
+                }
+                return;
+            }
+
+            if (resolved instanceof UUID uuid) {
+                fields.addProperty(key + "_uuid", uuid.toString());
+                return;
+            }
+
+            if (resolved instanceof String nameText) {
+                fields.addProperty(key + "_name", nameText);
+            }
+        }
+
         private void send(JsonObject response) {
             if (writer == null) {
                 return;
@@ -3332,6 +3471,7 @@ static class PendingEvent {
             Event event;
             int id;
             String chatOverride;
+            Double damageOverride;
         }
 
         private Class<? extends Event> resolveEventClass(String eventName) throws ClassNotFoundException {
diff --git a/src/main/resources/python/bridge.py b/src/main/resources/python/bridge.py
@@ -1960,11 +1960,17 @@ async def _dispatch_event(self, event_name: str, payload: Any):
             if event_id is not None:
                 if handlers:
                     override_text = None
+                    override_damage = None
+                    is_damage_event = isinstance(payload, ProxyBase) and "damage" in payload._fields
                     for result in results:
                         if isinstance(result, str):
                             override_text = result
+                        elif is_damage_event and isinstance(result, (int, float)) and not isinstance(result, bool):
+                            override_damage = float(result)
                     if override_text is not None:
-                        self.send({"type": "event_result", "id": event_id, "result": override_text})
+                        self.send({"type": "event_result", "id": event_id, "result": override_text, "result_type": "chat"})
+                    if override_damage is not None:
+                        self.send({"type": "event_result", "id": event_id, "result": override_damage, "result_type": "damage"})
                 self.send({"type": "event_done", "id": event_id})
 
     def _handle_reader_error(self, exc: Exception):
diff --git a/src/main/resources/python/bridge.pyi b/src/main/resources/python/bridge.pyi
@@ -18,6 +18,10 @@ class Event:
     def cancel(self) -> Awaitable[None]: ...
     player: "Player"
     entity: "Entity"
+    damager: "Entity" | "Block" | None
+    damage: float
+    final_damage: float
+    damage_cause: Any
     block: "Block"
     world: "World"
     location: "Location"
@@ -83,6 +87,13 @@ class Entity:
     type: "EntityType"
     location: "Location"
     world: "World"
+    is_projectile: bool
+    shooter: "Entity" | "Player" | "Block" | None
+    is_tamed: bool
+    owner: "Player" | None
+    owner_uuid: str | None
+    owner_name: str | None
+    source: "Entity" | "Player" | None
     def teleport(self, location: "Location") -> Awaitable[None]: ...
     def remove(self) -> Awaitable[None]: ...
     def set_velocity(self, vector: "Vector") -> Awaitable[None]: ...
