feat(modloader): add item use and summon APIs

Add managed item use hooks, server-authoritative summon support, and side-aware use item context.

Include IdHelper mappings, example ruby wand usage, and related runtime/crash-handler updates.

WeaveLoader.API/Item/CustomItem.cs

@@ -20,6 +20,13 @@ public abstract class Item
     /// or <see cref="MineBlockResult.CancelVanilla"/> to skip vanilla handling.
     /// </summary>
     public virtual MineBlockResult OnMineBlock(MineBlockContext context) => MineBlockResult.ContinueVanilla;
+
+    /// <summary>
+    /// Called when this item is actively used by the player (right-click use path).
+    /// Return <see cref="UseItemResult.ContinueVanilla"/> to run vanilla logic,
+    /// or <see cref="UseItemResult.CancelVanilla"/> to skip vanilla handling.
+    /// </summary>
+    public virtual UseItemResult OnUseItem(UseItemContext context) => UseItemResult.ContinueVanilla;
 }
 
 /// <summary>
@@ -31,6 +38,15 @@ public enum MineBlockResult
     CancelVanilla = 1
 }
 
+/// <summary>
+/// Result of managed use-item callback.
+/// </summary>
+public enum UseItemResult
+{
+    ContinueVanilla = 0,
+    CancelVanilla = 1
+}
+
 /// <summary>
 /// Tool tier used by native tool constructors.
 /// </summary>
@@ -73,6 +89,72 @@ public readonly struct MineBlockContext
     }
 }
 
+/// <summary>
+/// Runtime context for item use callback.
+/// </summary>
+public readonly struct UseItemContext
+{
+    public int ItemId { get; }
+    public bool IsTestUseOnly { get; }
+    public bool IsClientSide { get; }
+    public nint NativeItemInstancePtr { get; }
+    public nint NativePlayerPtr { get; }
+    public nint NativePlayerSharedPtr { get; }
+
+    internal UseItemContext(int itemId, bool isTestUseOnly, bool isClientSide, nint nativeItemInstancePtr, nint nativePlayerPtr, nint nativePlayerSharedPtr)
+    {
+        ItemId = itemId;
+        IsTestUseOnly = isTestUseOnly;
+        IsClientSide = isClientSide;
+        NativeItemInstancePtr = nativeItemInstancePtr;
+        NativePlayerPtr = nativePlayerPtr;
+        NativePlayerSharedPtr = nativePlayerSharedPtr;
+    }
+
+    public bool ConsumeInventoryItem(Identifier id, int count = 1)
+    {
+        if (NativePlayerPtr == 0 || count <= 0)
+            return false;
+
+        int numericId = IdHelper.GetItemNumericId(id);
+        if (numericId < 0)
+            return false;
+
+        return NativeInterop.native_consume_item_from_player(NativePlayerPtr, numericId, count) != 0;
+    }
+
+    public bool DamageItem(int amount)
+    {
+        if (NativeItemInstancePtr == 0 || NativePlayerSharedPtr == 0 || amount <= 0)
+            return false;
+
+        return NativeInterop.native_damage_item_instance(NativeItemInstancePtr, amount, NativePlayerSharedPtr) != 0;
+    }
+
+    public bool SpawnEntityFromLook(Identifier id, double speed = 1.4, double spawnForward = 1.0, double spawnUp = 1.2)
+    {
+        int numericEntityId = IdHelper.GetEntityNumericId(id);
+        if (numericEntityId < 0)
+            return false;
+
+        return SpawnEntityFromLook(numericEntityId, speed, spawnForward, spawnUp);
+    }
+
+    public bool SpawnEntityFromLook(int numericEntityId, double speed = 1.4, double spawnForward = 1.0, double spawnUp = 1.2)
+    {
+        if (NativePlayerPtr == 0 || numericEntityId < 0)
+            return false;
+
+        return NativeInterop.native_spawn_entity_from_player_look(
+            NativePlayerPtr,
+            NativePlayerSharedPtr,
+            numericEntityId,
+            speed,
+            spawnForward,
+            spawnUp) != 0;
+    }
+}
+
 [StructLayout(LayoutKind.Sequential)]
 internal struct MineBlockNativeArgs
 {
@@ -83,6 +165,17 @@ internal struct MineBlockNativeArgs
     public int Z;
 }
 
+[StructLayout(LayoutKind.Sequential)]
+internal struct UseItemNativeArgs
+{
+    public int ItemId;
+    public int IsTestUseOnly;
+    public int IsClientSide;
+    public nint ItemInstancePtr;
+    public nint PlayerPtr;
+    public nint PlayerSharedPtr;
+}
+
 internal static class ManagedItemDispatcher
 {
     private static readonly object s_lock = new();
@@ -125,4 +218,32 @@ internal static class ManagedItemDispatcher
         // 0 = no managed item, 1 = continue vanilla, 2 = cancel vanilla.
         return result == MineBlockResult.CancelVanilla ? 2 : 1;
     }
+
+    internal static int HandleUseItem(IntPtr args, int sizeBytes)
+    {
+        if (args == IntPtr.Zero || sizeBytes < Marshal.SizeOf<UseItemNativeArgs>())
+            return 0;
+
+        UseItemNativeArgs nativeArgs = Marshal.PtrToStructure<UseItemNativeArgs>(args);
+
+        Item? item;
+        lock (s_lock)
+        {
+            s_items.TryGetValue(nativeArgs.ItemId, out item);
+        }
+
+        if (item == null)
+            return 0;
+
+        var result = item.OnUseItem(new UseItemContext(
+            nativeArgs.ItemId,
+            nativeArgs.IsTestUseOnly != 0,
+            nativeArgs.IsClientSide != 0,
+            nativeArgs.ItemInstancePtr,
+            nativeArgs.PlayerPtr,
+            nativeArgs.PlayerSharedPtr));
+
+        // 0 = no managed item, 1 = continue vanilla, 2 = cancel vanilla.
+        return result == UseItemResult.CancelVanilla ? 2 : 1;
+    }
 }

WeaveLoader.API/Item/ItemRegistry.cs

@@ -1,3 +1,5 @@
+using System.Collections.Generic;
+
 namespace WeaveLoader.API.Item;
 
 /// <summary>
@@ -24,6 +26,9 @@ public class RegisteredItem
 /// </summary>
 public static class ItemRegistry
 {
+    private static readonly object s_lock = new();
+    private static readonly Dictionary<int, Identifier> s_idByNumeric = new();
+
     /// <summary>
     /// Register a new item with the game engine.
     /// </summary>
@@ -85,6 +90,18 @@ public static class ItemRegistry
         }
 
         Logger.Debug($"Registered item '{id}' -> numeric ID {numericId}");
+        lock (s_lock)
+        {
+            s_idByNumeric[numericId] = id;
+        }
         return new RegisteredItem(id, numericId);
     }
+
+    internal static bool TryGetIdentifier(int numericId, out Identifier id)
+    {
+        lock (s_lock)
+        {
+            return s_idByNumeric.TryGetValue(numericId, out id);
+        }
+    }
 }