DAMAGE event

common/src/main/java/org/figuramc/figura/avatar/Avatar.java

@@ -430,6 +430,10 @@ public void resourceReloadEvent() {
         if (loaded) run("RESOURCE_RELOAD", tick);
     }
 
+    public void damageEvent(String sourceType, EntityAPI<?> sourceCause, EntityAPI<?> sourceDirect, FiguraVec3 sourcePosition) {
+        if (loaded) run("DAMAGE", tick, sourceType, sourceCause, sourceDirect, sourcePosition);
+    }
+
     // -- host only events -- // 
 
     public String chatSendMessageEvent(String message) { // piped event

common/src/main/java/org/figuramc/figura/lua/api/event/EventsAPI.java

@@ -87,6 +87,9 @@ public class EventsAPI {
     @LuaWhitelist
     @LuaFieldDoc("events.resource_reload")
     public final LuaEvent RESOURCE_RELOAD = new LuaEvent();
+    @LuaWhitelist
+    @LuaFieldDoc("events.damage")
+    public final LuaEvent DAMAGE = new LuaEvent();
 
     private final Map<String, LuaEvent> events = new HashMap<>();
 
@@ -112,6 +115,7 @@ public EventsAPI() {
         events.put("ITEM_RENDER", ITEM_RENDER);
         events.put("ON_PLAY_SOUND", ON_PLAY_SOUND);
         events.put("RESOURCE_RELOAD", RESOURCE_RELOAD);
+        events.put("DAMAGE", DAMAGE);
 
         for (FiguraEvent entrypoint : ENTRYPOINTS) {
             String ID = entrypoint.getID().toUpperCase(Locale.US);

common/src/main/java/org/figuramc/figura/mixin/LivingEntityMixin.java

@@ -1,13 +1,16 @@
 package org.figuramc.figura.mixin;
 
+import net.minecraft.world.damagesource.DamageSource;
 import net.minecraft.world.entity.Entity;
 import net.minecraft.world.entity.EntityType;
 import net.minecraft.world.entity.LivingEntity;
 import net.minecraft.world.item.ItemStack;
 import net.minecraft.world.level.Level;
 import org.figuramc.figura.avatar.Avatar;
 import org.figuramc.figura.avatar.AvatarManager;
+import org.figuramc.figura.lua.api.entity.EntityAPI;
 import org.figuramc.figura.lua.api.world.ItemStackAPI;
+import org.figuramc.figura.math.vector.FiguraVec3;
 import org.spongepowered.asm.mixin.Mixin;
 import org.spongepowered.asm.mixin.injection.At;
 import org.spongepowered.asm.mixin.injection.Inject;
@@ -26,4 +29,16 @@ private void triggerItemUseEffects(ItemStack stack, int particleCount, CallbackI
         if (avatar != null && avatar.useItemEvent(ItemStackAPI.verify(stack), stack.getUseAnimation().name(), particleCount))
             ci.cancel();
     }
+
+    @Inject(at = @At("TAIL"), method = "handleDamageEvent")
+    private void handleDamageEvent(DamageSource source, CallbackInfo ci) {
+        Avatar avatar = AvatarManager.getAvatar(this);
+        if (avatar == null) return;
+        avatar.damageEvent(
+                source.typeHolder().unwrapKey().get().location().toString(),
+                EntityAPI.wrap(source.getEntity()),
+                EntityAPI.wrap(source.getDirectEntity()),
+                source.getSourcePosition() != null ? FiguraVec3.fromVec3(source.getSourcePosition()) : null
+        );
+    }
 }

common/src/main/resources/assets/figura/lang/en_us.json

@@ -1060,6 +1060,7 @@
     "figura.docs.events.item_render": "Called on every one of your items that is being rendered\nIt takes six arguments: the item being rendered, the rendering mode, the position, rotation, and scale that would be applied to the item, and if it's being rendered in the left hand\nReturning a ModelPart parented to Item stops the rendering of this item and will render the returned part instead",
     "figura.docs.events.on_play_sound": "Called every time a new sound is played\nTakes the following as arguments: the sound's ID, its world position, volume, pitch, if the sound should loop, the sound's category, and the sound's file path\nReturn true to prevent this sound from playing",
     "figura.docs.events.resource_reload": "Called every time that the client resources are reloaded, allowing you to re-create or update resource texture references",
+    "figura.docs.events.damage": "Called every time you take damage\nTakes four arguments: the damage type as a string, the entity that dealt the damage, the attacking entity, and the damage position\\nThe last three arguments may return nil if there is no direct damage source",
     "figura.docs.events.get_events": "Returns a table with all events types",
     "figura.docs.event": "A hook for a certain event in Minecraft\nYou may register functions to one, and those functions will be called when the event occurs",
     "figura.docs.event.register": "Register a function on this event\nFunctions are run in registration order\nAn optional string argument can be given, grouping functions under that name, for an easier management later on",