feat(api): expand block/item hooks and debug tools

WeaveLoader.API/Block/CustomBlock.cs

@@ -2,35 +2,139 @@ using System.Runtime.InteropServices;
 
 namespace WeaveLoader.API.Block;
 
+/// <summary>
+/// Base class for managed custom blocks.
+/// Mods can inherit and override callbacks for block behavior.
+/// </summary>
 public abstract class Block
 {
+    /// <summary>The namespaced ID used during registration.</summary>
     public Identifier? Id { get; internal set; }
+
+    /// <summary>The numeric runtime ID allocated by the game.</summary>
     public int NumericId { get; internal set; } = -1;
 
+    /// <summary>Optional override for the block to drop when broken.</summary>
     public Identifier? DropAsBlockId { get; init; }
+
+    /// <summary>Optional override for the block to clone via pick-block.</summary>
     public Identifier? CloneAsBlockId { get; init; }
 
+    /// <summary>
+    /// Called when the block is placed in the world.
+    /// </summary>
     public virtual void OnPlace(BlockUpdateContext context)
     {
     }
 
+    /// <summary>
+    /// Called when a neighboring block changes.
+    /// </summary>
     public virtual void OnNeighborChanged(BlockNeighborChangedContext context)
     {
     }
 
+    /// <summary>
+    /// Called when a scheduled tick for this block fires.
+    /// </summary>
     public virtual void OnScheduledTick(BlockTickContext context)
     {
     }
+
+    /// <summary>
+    /// Called when the block is used (right-click).
+    /// Return <see cref="BlockActionResult.ContinueVanilla"/> to run vanilla logic,
+    /// or <see cref="BlockActionResult.CancelVanilla"/> to skip vanilla handling.
+    /// </summary>
+    public virtual BlockActionResult OnUse(BlockUseContext context) => BlockActionResult.ContinueVanilla;
+
+    /// <summary>
+    /// Called when an entity steps on the block.
+    /// </summary>
+    public virtual void OnStepOn(BlockEntityContext context)
+    {
+    }
+
+    /// <summary>
+    /// Called when an entity is inside the block's volume.
+    /// </summary>
+    public virtual void OnEntityInsideTile(BlockEntityContext context)
+    {
+    }
+
+    /// <summary>
+    /// Called when an entity falls onto the block.
+    /// </summary>
+    public virtual void OnFallOn(BlockFallContext context)
+    {
+    }
+
+    /// <summary>
+    /// Called before the block is removed from the world.
+    /// </summary>
+    public virtual void OnRemoving(BlockRemovingContext context)
+    {
+    }
+
+    /// <summary>
+    /// Called after the block is removed from the world.
+    /// </summary>
+    public virtual void OnRemoved(BlockRemoveContext context)
+    {
+    }
+
+    /// <summary>
+    /// Called when the block is destroyed by the world (non-player).
+    /// </summary>
+    public virtual void OnDestroyed(BlockDestroyContext context)
+    {
+    }
+
+    /// <summary>
+    /// Called when the block is destroyed by a player.
+    /// </summary>
+    public virtual void OnPlayerDestroy(BlockPlayerDestroyContext context)
+    {
+    }
+
+    /// <summary>
+    /// Called just before a player destroys the block.
+    /// </summary>
+    public virtual void OnPlayerWillDestroy(BlockPlayerWillDestroyContext context)
+    {
+    }
+
+    /// <summary>
+    /// Called when the block is placed by a player with an item.
+    /// </summary>
+    public virtual void OnPlacedBy(BlockPlacedByContext context)
+    {
+    }
+
 }
 
+/// <summary>Managed falling block base class.</summary>
 public class FallingBlock : Block
 {
 }
 
+/// <summary>Managed slab block base class.</summary>
 public class SlabBlock : Block
 {
 }
 
+/// <summary>
+/// Result of managed block action callbacks.
+/// </summary>
+public enum BlockActionResult
+{
+    ContinueVanilla = 0,
+    CancelVanilla = 1
+}
+
+/// <summary>
+/// Runtime context for block update callbacks.
+/// </summary>
 public readonly struct BlockUpdateContext
 {
     public int BlockId { get; }
@@ -58,6 +162,9 @@ public readonly struct BlockUpdateContext
         return NativeInterop.native_level_has_neighbor_signal(NativeLevelPtr, X, Y, Z) != 0;
     }
 
+    /// <summary>
+    /// Set the block at this context's position.
+    /// </summary>
     public bool SetBlock(Identifier id, int data = 0, int flags = 2)
     {
         int numericId = IdHelper.GetBlockNumericId(id);
@@ -67,6 +174,9 @@ public readonly struct BlockUpdateContext
         return SetBlock(numericId, data, flags);
     }
 
+    /// <summary>
+    /// Set the block at this context's position using a numeric ID.
+    /// </summary>
     public bool SetBlock(int numericBlockId, int data = 0, int flags = 2)
     {
         if (NativeLevelPtr == 0 || numericBlockId < 0)
@@ -75,6 +185,9 @@ public readonly struct BlockUpdateContext
         return NativeInterop.native_level_set_tile(NativeLevelPtr, X, Y, Z, numericBlockId, data, flags) != 0;
     }
 
+    /// <summary>
+    /// Schedule a tick for this block after a delay (in ticks).
+    /// </summary>
     public bool ScheduleTick(int delay)
     {
         if (NativeLevelPtr == 0 || delay < 0)
@@ -83,6 +196,9 @@ public readonly struct BlockUpdateContext
         return NativeInterop.native_level_schedule_tick(NativeLevelPtr, X, Y, Z, BlockId, delay) != 0;
     }
 
+    /// <summary>
+    /// Read a block ID relative to this context's position.
+    /// </summary>
     public int GetBlockId(int offsetX = 0, int offsetY = 0, int offsetZ = 0)
     {
         if (NativeLevelPtr == 0)
@@ -92,6 +208,9 @@ public readonly struct BlockUpdateContext
     }
 }
 
+/// <summary>
+/// Runtime context for block neighbor-change callback.
+/// </summary>
 public readonly struct BlockNeighborChangedContext
 {
     public BlockUpdateContext Block { get; }
@@ -104,6 +223,9 @@ public readonly struct BlockNeighborChangedContext
     }
 }
 
+/// <summary>
+/// Runtime context for scheduled tick callback.
+/// </summary>
 public readonly struct BlockTickContext
 {
     public BlockUpdateContext Block { get; }
@@ -114,6 +236,161 @@ public readonly struct BlockTickContext
     }
 }
 
+/// <summary>
+/// Runtime context for block use callback.
+/// </summary>
+public readonly struct BlockUseContext
+{
+    public BlockUpdateContext Block { get; }
+    public nint NativePlayerPtr { get; }
+    public int Face { get; }
+    public float ClickX { get; }
+    public float ClickY { get; }
+    public float ClickZ { get; }
+    public bool SoundOnly { get; }
+
+    internal BlockUseContext(BlockUpdateContext block, nint nativePlayerPtr, int face, float clickX, float clickY, float clickZ, bool soundOnly)
+    {
+        Block = block;
+        NativePlayerPtr = nativePlayerPtr;
+        Face = face;
+        ClickX = clickX;
+        ClickY = clickY;
+        ClickZ = clickZ;
+        SoundOnly = soundOnly;
+    }
+}
+
+/// <summary>
+/// Runtime context for entity-on-block callbacks.
+/// </summary>
+public readonly struct BlockEntityContext
+{
+    public BlockUpdateContext Block { get; }
+    public nint NativeEntityPtr { get; }
+
+    internal BlockEntityContext(BlockUpdateContext block, nint nativeEntityPtr)
+    {
+        Block = block;
+        NativeEntityPtr = nativeEntityPtr;
+    }
+}
+
+/// <summary>
+/// Runtime context for block fall-on callback.
+/// </summary>
+public readonly struct BlockFallContext
+{
+    public BlockUpdateContext Block { get; }
+    public nint NativeEntityPtr { get; }
+    public float FallDistance { get; }
+
+    internal BlockFallContext(BlockUpdateContext block, nint nativeEntityPtr, float fallDistance)
+    {
+        Block = block;
+        NativeEntityPtr = nativeEntityPtr;
+        FallDistance = fallDistance;
+    }
+}
+
+/// <summary>
+/// Runtime context for block removing callback.
+/// </summary>
+public readonly struct BlockRemovingContext
+{
+    public BlockUpdateContext Block { get; }
+    public int BlockData { get; }
+
+    internal BlockRemovingContext(BlockUpdateContext block, int blockData)
+    {
+        Block = block;
+        BlockData = blockData;
+    }
+}
+
+/// <summary>
+/// Runtime context for block removed callback.
+/// </summary>
+public readonly struct BlockRemoveContext
+{
+    public BlockUpdateContext Block { get; }
+    public int RemovedBlockId { get; }
+    public int RemovedBlockData { get; }
+
+    internal BlockRemoveContext(BlockUpdateContext block, int removedBlockId, int removedBlockData)
+    {
+        Block = block;
+        RemovedBlockId = removedBlockId;
+        RemovedBlockData = removedBlockData;
+    }
+}
+
+/// <summary>
+/// Runtime context for block destroyed callback.
+/// </summary>
+public readonly struct BlockDestroyContext
+{
+    public BlockUpdateContext Block { get; }
+    public int BlockData { get; }
+
+    internal BlockDestroyContext(BlockUpdateContext block, int blockData)
+    {
+        Block = block;
+        BlockData = blockData;
+    }
+}
+
+/// <summary>
+/// Runtime context for player-destroyed callback.
+/// </summary>
+public readonly struct BlockPlayerDestroyContext
+{
+    public BlockUpdateContext Block { get; }
+    public nint NativePlayerPtr { get; }
+    public int BlockData { get; }
+
+    internal BlockPlayerDestroyContext(BlockUpdateContext block, nint nativePlayerPtr, int blockData)
+    {
+        Block = block;
+        NativePlayerPtr = nativePlayerPtr;
+        BlockData = blockData;
+    }
+}
+
+/// <summary>
+/// Runtime context for player-will-destroy callback.
+/// </summary>
+public readonly struct BlockPlayerWillDestroyContext
+{
+    public BlockUpdateContext Block { get; }
+    public nint NativePlayerPtr { get; }
+    public int BlockData { get; }
+
+    internal BlockPlayerWillDestroyContext(BlockUpdateContext block, nint nativePlayerPtr, int blockData)
+    {
+        Block = block;
+        NativePlayerPtr = nativePlayerPtr;
+        BlockData = blockData;
+    }
+}
+
+/// <summary>
+/// Runtime context for block placed-by callback.
+/// </summary>
+public readonly struct BlockPlacedByContext
+{
+    public BlockUpdateContext Block { get; }
+    public nint NativePlacerPtr { get; }
+    public nint NativeItemInstancePtr { get; }
+
+    internal BlockPlacedByContext(BlockUpdateContext block, nint nativePlacerPtr, nint nativeItemInstancePtr)
+    {
+        Block = block;
+        NativePlacerPtr = nativePlacerPtr;
+        NativeItemInstancePtr = nativeItemInstancePtr;
+    }
+}
+
 [StructLayout(LayoutKind.Sequential)]
 internal struct BlockUpdateNativeArgs
 {
@@ -132,6 +409,79 @@ internal struct BlockNeighborChangedNativeArgs
     public int NeighborBlockId;
 }
 
+[StructLayout(LayoutKind.Sequential)]
+internal struct BlockUseNativeArgs
+{
+    public BlockUpdateNativeArgs Block;
+    public nint PlayerPtr;
+    public int Face;
+    public float ClickX;
+    public float ClickY;
+    public float ClickZ;
+    public int SoundOnly;
+}
+
+[StructLayout(LayoutKind.Sequential)]
+internal struct BlockEntityNativeArgs
+{
+    public BlockUpdateNativeArgs Block;
+    public nint EntityPtr;
+}
+
+[StructLayout(LayoutKind.Sequential)]
+internal struct BlockFallNativeArgs
+{
+    public BlockUpdateNativeArgs Block;
+    public nint EntityPtr;
+    public float FallDistance;
+}
+
+[StructLayout(LayoutKind.Sequential)]
+internal struct BlockRemovingNativeArgs
+{
+    public BlockUpdateNativeArgs Block;
+    public int BlockData;
+}
+
+[StructLayout(LayoutKind.Sequential)]
+internal struct BlockRemoveNativeArgs
+{
+    public BlockUpdateNativeArgs Block;
+    public int RemovedBlockId;
+    public int RemovedBlockData;
+}
+
+[StructLayout(LayoutKind.Sequential)]
+internal struct BlockDestroyNativeArgs
+{
+    public BlockUpdateNativeArgs Block;
+    public int BlockData;
+}
+
+[StructLayout(LayoutKind.Sequential)]
+internal struct BlockPlayerDestroyNativeArgs
+{
+    public BlockUpdateNativeArgs Block;
+    public nint PlayerPtr;
+    public int BlockData;
+}
+
+[StructLayout(LayoutKind.Sequential)]
+internal struct BlockPlayerWillDestroyNativeArgs
+{
+    public BlockUpdateNativeArgs Block;
+    public nint PlayerPtr;
+    public int BlockData;
+}
+
+[StructLayout(LayoutKind.Sequential)]
+internal struct BlockPlacedByNativeArgs
+{
+    public BlockUpdateNativeArgs Block;
+    public nint PlacerPtr;
+    public nint ItemInstancePtr;
+}
+
 internal static class ManagedBlockDispatcher
 {
     private static readonly object s_lock = new();
@@ -223,4 +573,275 @@ internal static class ManagedBlockDispatcher
             nativeArgs.Z)));
         return 1;
     }
+
+    internal static int HandleUse(IntPtr args, int sizeBytes)
+    {
+        if (args == IntPtr.Zero || sizeBytes < Marshal.SizeOf<BlockUseNativeArgs>())
+            return 0;
+
+        BlockUseNativeArgs nativeArgs = Marshal.PtrToStructure<BlockUseNativeArgs>(args);
+        Block? block;
+        lock (s_lock)
+        {
+            s_blocks.TryGetValue(nativeArgs.Block.BlockId, out block);
+        }
+
+        if (block == null)
+            return 0;
+
+        var update = new BlockUpdateContext(
+            nativeArgs.Block.BlockId,
+            nativeArgs.Block.IsClientSide != 0,
+            nativeArgs.Block.LevelPtr,
+            nativeArgs.Block.X,
+            nativeArgs.Block.Y,
+            nativeArgs.Block.Z);
+
+        var result = block.OnUse(new BlockUseContext(
+            update,
+            nativeArgs.PlayerPtr,
+            nativeArgs.Face,
+            nativeArgs.ClickX,
+            nativeArgs.ClickY,
+            nativeArgs.ClickZ,
+            nativeArgs.SoundOnly != 0));
+
+        return result == BlockActionResult.CancelVanilla ? 2 : 1;
+    }
+
+    internal static int HandleStepOn(IntPtr args, int sizeBytes)
+    {
+        if (args == IntPtr.Zero || sizeBytes < Marshal.SizeOf<BlockEntityNativeArgs>())
+            return 0;
+
+        BlockEntityNativeArgs nativeArgs = Marshal.PtrToStructure<BlockEntityNativeArgs>(args);
+        Block? block;
+        lock (s_lock)
+        {
+            s_blocks.TryGetValue(nativeArgs.Block.BlockId, out block);
+        }
+
+        if (block == null)
+            return 0;
+
+        var update = new BlockUpdateContext(
+            nativeArgs.Block.BlockId,
+            nativeArgs.Block.IsClientSide != 0,
+            nativeArgs.Block.LevelPtr,
+            nativeArgs.Block.X,
+            nativeArgs.Block.Y,
+            nativeArgs.Block.Z);
+        block.OnStepOn(new BlockEntityContext(update, nativeArgs.EntityPtr));
+        return 1;
+    }
+
+    internal static int HandleEntityInsideTile(IntPtr args, int sizeBytes)
+    {
+        if (args == IntPtr.Zero || sizeBytes < Marshal.SizeOf<BlockEntityNativeArgs>())
+            return 0;
+
+        BlockEntityNativeArgs nativeArgs = Marshal.PtrToStructure<BlockEntityNativeArgs>(args);
+        Block? block;
+        lock (s_lock)
+        {
+            s_blocks.TryGetValue(nativeArgs.Block.BlockId, out block);
+        }
+
+        if (block == null)
+            return 0;
+
+        var update = new BlockUpdateContext(
+            nativeArgs.Block.BlockId,
+            nativeArgs.Block.IsClientSide != 0,
+            nativeArgs.Block.LevelPtr,
+            nativeArgs.Block.X,
+            nativeArgs.Block.Y,
+            nativeArgs.Block.Z);
+        block.OnEntityInsideTile(new BlockEntityContext(update, nativeArgs.EntityPtr));
+        return 1;
+    }
+
+    internal static int HandleFallOn(IntPtr args, int sizeBytes)
+    {
+        if (args == IntPtr.Zero || sizeBytes < Marshal.SizeOf<BlockFallNativeArgs>())
+            return 0;
+
+        BlockFallNativeArgs nativeArgs = Marshal.PtrToStructure<BlockFallNativeArgs>(args);
+        Block? block;
+        lock (s_lock)
+        {
+            s_blocks.TryGetValue(nativeArgs.Block.BlockId, out block);
+        }
+
+        if (block == null)
+            return 0;
+
+        var update = new BlockUpdateContext(
+            nativeArgs.Block.BlockId,
+            nativeArgs.Block.IsClientSide != 0,
+            nativeArgs.Block.LevelPtr,
+            nativeArgs.Block.X,
+            nativeArgs.Block.Y,
+            nativeArgs.Block.Z);
+        block.OnFallOn(new BlockFallContext(update, nativeArgs.EntityPtr, nativeArgs.FallDistance));
+        return 1;
+    }
+
+    internal static int HandleRemoving(IntPtr args, int sizeBytes)
+    {
+        if (args == IntPtr.Zero || sizeBytes < Marshal.SizeOf<BlockRemovingNativeArgs>())
+            return 0;
+
+        BlockRemovingNativeArgs nativeArgs = Marshal.PtrToStructure<BlockRemovingNativeArgs>(args);
+        Block? block;
+        lock (s_lock)
+        {
+            s_blocks.TryGetValue(nativeArgs.Block.BlockId, out block);
+        }
+
+        if (block == null)
+            return 0;
+
+        var update = new BlockUpdateContext(
+            nativeArgs.Block.BlockId,
+            nativeArgs.Block.IsClientSide != 0,
+            nativeArgs.Block.LevelPtr,
+            nativeArgs.Block.X,
+            nativeArgs.Block.Y,
+            nativeArgs.Block.Z);
+        block.OnRemoving(new BlockRemovingContext(update, nativeArgs.BlockData));
+        return 1;
+    }
+
+    internal static int HandleRemoved(IntPtr args, int sizeBytes)
+    {
+        if (args == IntPtr.Zero || sizeBytes < Marshal.SizeOf<BlockRemoveNativeArgs>())
+            return 0;
+
+        BlockRemoveNativeArgs nativeArgs = Marshal.PtrToStructure<BlockRemoveNativeArgs>(args);
+        Block? block;
+        lock (s_lock)
+        {
+            s_blocks.TryGetValue(nativeArgs.Block.BlockId, out block);
+        }
+
+        if (block == null)
+            return 0;
+
+        var update = new BlockUpdateContext(
+            nativeArgs.Block.BlockId,
+            nativeArgs.Block.IsClientSide != 0,
+            nativeArgs.Block.LevelPtr,
+            nativeArgs.Block.X,
+            nativeArgs.Block.Y,
+            nativeArgs.Block.Z);
+        block.OnRemoved(new BlockRemoveContext(update, nativeArgs.RemovedBlockId, nativeArgs.RemovedBlockData));
+        return 1;
+    }
+
+    internal static int HandleDestroyed(IntPtr args, int sizeBytes)
+    {
+        if (args == IntPtr.Zero || sizeBytes < Marshal.SizeOf<BlockDestroyNativeArgs>())
+            return 0;
+
+        BlockDestroyNativeArgs nativeArgs = Marshal.PtrToStructure<BlockDestroyNativeArgs>(args);
+        Block? block;
+        lock (s_lock)
+        {
+            s_blocks.TryGetValue(nativeArgs.Block.BlockId, out block);
+        }
+
+        if (block == null)
+            return 0;
+
+        var update = new BlockUpdateContext(
+            nativeArgs.Block.BlockId,
+            nativeArgs.Block.IsClientSide != 0,
+            nativeArgs.Block.LevelPtr,
+            nativeArgs.Block.X,
+            nativeArgs.Block.Y,
+            nativeArgs.Block.Z);
+        block.OnDestroyed(new BlockDestroyContext(update, nativeArgs.BlockData));
+        return 1;
+    }
+
+    internal static int HandlePlayerDestroy(IntPtr args, int sizeBytes)
+    {
+        if (args == IntPtr.Zero || sizeBytes < Marshal.SizeOf<BlockPlayerDestroyNativeArgs>())
+            return 0;
+
+        BlockPlayerDestroyNativeArgs nativeArgs = Marshal.PtrToStructure<BlockPlayerDestroyNativeArgs>(args);
+        Block? block;
+        lock (s_lock)
+        {
+            s_blocks.TryGetValue(nativeArgs.Block.BlockId, out block);
+        }
+
+        if (block == null)
+            return 0;
+
+        var update = new BlockUpdateContext(
+            nativeArgs.Block.BlockId,
+            nativeArgs.Block.IsClientSide != 0,
+            nativeArgs.Block.LevelPtr,
+            nativeArgs.Block.X,
+            nativeArgs.Block.Y,
+            nativeArgs.Block.Z);
+        block.OnPlayerDestroy(new BlockPlayerDestroyContext(update, nativeArgs.PlayerPtr, nativeArgs.BlockData));
+        return 1;
+    }
+
+    internal static int HandlePlayerWillDestroy(IntPtr args, int sizeBytes)
+    {
+        if (args == IntPtr.Zero || sizeBytes < Marshal.SizeOf<BlockPlayerWillDestroyNativeArgs>())
+            return 0;
+
+        BlockPlayerWillDestroyNativeArgs nativeArgs = Marshal.PtrToStructure<BlockPlayerWillDestroyNativeArgs>(args);
+        Block? block;
+        lock (s_lock)
+        {
+            s_blocks.TryGetValue(nativeArgs.Block.BlockId, out block);
+        }
+
+        if (block == null)
+            return 0;
+
+        var update = new BlockUpdateContext(
+            nativeArgs.Block.BlockId,
+            nativeArgs.Block.IsClientSide != 0,
+            nativeArgs.Block.LevelPtr,
+            nativeArgs.Block.X,
+            nativeArgs.Block.Y,
+            nativeArgs.Block.Z);
+        block.OnPlayerWillDestroy(new BlockPlayerWillDestroyContext(update, nativeArgs.PlayerPtr, nativeArgs.BlockData));
+        return 1;
+    }
+
+    internal static int HandlePlacedBy(IntPtr args, int sizeBytes)
+    {
+        if (args == IntPtr.Zero || sizeBytes < Marshal.SizeOf<BlockPlacedByNativeArgs>())
+            return 0;
+
+        BlockPlacedByNativeArgs nativeArgs = Marshal.PtrToStructure<BlockPlacedByNativeArgs>(args);
+        Block? block;
+        lock (s_lock)
+        {
+            s_blocks.TryGetValue(nativeArgs.Block.BlockId, out block);
+        }
+
+        if (block == null)
+            return 0;
+
+        var update = new BlockUpdateContext(
+            nativeArgs.Block.BlockId,
+            nativeArgs.Block.IsClientSide != 0,
+            nativeArgs.Block.LevelPtr,
+            nativeArgs.Block.X,
+            nativeArgs.Block.Y,
+            nativeArgs.Block.Z);
+        block.OnPlacedBy(new BlockPlacedByContext(update, nativeArgs.PlacerPtr, nativeArgs.ItemInstancePtr));
+        return 1;
+    }
+
+
 }

WeaveLoader.API/Item/CustomItem.cs

@@ -27,6 +27,41 @@ public abstract class Item
     /// or <see cref="UseItemResult.CancelVanilla"/> to skip vanilla handling.
     /// </summary>
     public virtual UseItemResult OnUseItem(UseItemContext context) => UseItemResult.ContinueVanilla;
+
+    /// <summary>
+    /// Called when this item is used on a block.
+    /// Return <see cref="ItemActionResult.ContinueVanilla"/> to run vanilla logic,
+    /// or <see cref="ItemActionResult.CancelVanilla"/> to skip vanilla handling.
+    /// </summary>
+    public virtual ItemActionResult OnUseOn(UseOnItemContext context) => ItemActionResult.ContinueVanilla;
+
+    /// <summary>
+    /// Called when this item interacts with an entity (right-click interaction).
+    /// Return <see cref="ItemActionResult.ContinueVanilla"/> to run vanilla logic,
+    /// or <see cref="ItemActionResult.CancelVanilla"/> to skip vanilla handling.
+    /// </summary>
+    public virtual ItemActionResult OnInteractEntity(ItemEntityInteractionContext context) => ItemActionResult.ContinueVanilla;
+
+    /// <summary>
+    /// Called when this item hurts an entity.
+    /// Return <see cref="ItemActionResult.ContinueVanilla"/> to run vanilla logic,
+    /// or <see cref="ItemActionResult.CancelVanilla"/> to skip vanilla handling.
+    /// </summary>
+    public virtual ItemActionResult OnHurtEntity(ItemEntityInteractionContext context) => ItemActionResult.ContinueVanilla;
+
+    /// <summary>
+    /// Called each tick while this item is in an inventory.
+    /// </summary>
+    public virtual void OnInventoryTick(ItemInventoryTickContext context)
+    {
+    }
+
+    /// <summary>
+    /// Called when this item is crafted by a player.
+    /// </summary>
+    public virtual void OnCraftedBy(ItemCraftedByContext context)
+    {
+    }
 }
 
 /// <summary>
@@ -47,6 +82,15 @@ public enum UseItemResult
     CancelVanilla = 1
 }
 
+/// <summary>
+/// Result of managed item action callbacks.
+/// </summary>
+public enum ItemActionResult
+{
+    ContinueVanilla = 0,
+    CancelVanilla = 1
+}
+
 /// <summary>
 /// Tool tier used by native tool constructors.
 /// </summary>
@@ -117,16 +161,14 @@ public readonly struct MineBlockContext
 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)
+    internal UseItemContext(int itemId, bool isClientSide, nint nativeItemInstancePtr, nint nativePlayerPtr, nint nativePlayerSharedPtr)
     {
         ItemId = itemId;
-        IsTestUseOnly = isTestUseOnly;
         IsClientSide = isClientSide;
         NativeItemInstancePtr = nativeItemInstancePtr;
         NativePlayerPtr = nativePlayerPtr;
@@ -177,6 +219,197 @@ public readonly struct UseItemContext
     }
 }
 
+/// <summary>
+/// Runtime context for item use-on-block callback.
+/// </summary>
+public readonly struct UseOnItemContext
+{
+    public int ItemId { get; }
+    public bool IsClientSide { get; }
+    public nint NativeItemInstancePtr { get; }
+    public nint NativePlayerPtr { get; }
+    public nint NativePlayerSharedPtr { get; }
+    public nint NativeLevelPtr { get; }
+    public int X { get; }
+    public int Y { get; }
+    public int Z { get; }
+    public int Face { get; }
+    public float ClickX { get; }
+    public float ClickY { get; }
+    public float ClickZ { get; }
+
+    internal UseOnItemContext(
+        int itemId,
+        bool isClientSide,
+        nint nativeItemInstancePtr,
+        nint nativePlayerPtr,
+        nint nativePlayerSharedPtr,
+        nint nativeLevelPtr,
+        int x,
+        int y,
+        int z,
+        int face,
+        float clickX,
+        float clickY,
+        float clickZ)
+    {
+        ItemId = itemId;
+        IsClientSide = isClientSide;
+        NativeItemInstancePtr = nativeItemInstancePtr;
+        NativePlayerPtr = nativePlayerPtr;
+        NativePlayerSharedPtr = nativePlayerSharedPtr;
+        NativeLevelPtr = nativeLevelPtr;
+        X = x;
+        Y = y;
+        Z = z;
+        Face = face;
+        ClickX = clickX;
+        ClickY = clickY;
+        ClickZ = clickZ;
+    }
+
+    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;
+    }
+}
+
+/// <summary>
+/// Runtime context for item/entity interactions.
+/// </summary>
+public readonly struct ItemEntityInteractionContext
+{
+    public int ItemId { get; }
+    public nint NativeItemInstancePtr { get; }
+    public nint NativePlayerPtr { get; }
+    public nint NativePlayerSharedPtr { get; }
+    public nint NativeTargetEntityPtr { get; }
+
+    internal ItemEntityInteractionContext(
+        int itemId,
+        nint nativeItemInstancePtr,
+        nint nativePlayerPtr,
+        nint nativePlayerSharedPtr,
+        nint nativeTargetEntityPtr)
+    {
+        ItemId = itemId;
+        NativeItemInstancePtr = nativeItemInstancePtr;
+        NativePlayerPtr = nativePlayerPtr;
+        NativePlayerSharedPtr = nativePlayerSharedPtr;
+        NativeTargetEntityPtr = nativeTargetEntityPtr;
+    }
+
+    public bool DamageItem(int amount)
+    {
+        if (NativeItemInstancePtr == 0 || NativePlayerSharedPtr == 0 || amount <= 0)
+            return false;
+
+        return NativeInterop.native_damage_item_instance(NativeItemInstancePtr, amount, NativePlayerSharedPtr) != 0;
+    }
+}
+
+/// <summary>
+/// Runtime context for inventory tick callbacks.
+/// </summary>
+public readonly struct ItemInventoryTickContext
+{
+    public int ItemId { get; }
+    public nint NativeItemInstancePtr { get; }
+    public nint NativeLevelPtr { get; }
+    public nint NativeOwnerEntityPtr { get; }
+    public int Slot { get; }
+    public bool IsSelected { get; }
+    public bool IsClientSide { get; }
+
+    internal ItemInventoryTickContext(
+        int itemId,
+        nint nativeItemInstancePtr,
+        nint nativeLevelPtr,
+        nint nativeOwnerEntityPtr,
+        int slot,
+        bool isSelected,
+        bool isClientSide)
+    {
+        ItemId = itemId;
+        NativeItemInstancePtr = nativeItemInstancePtr;
+        NativeLevelPtr = nativeLevelPtr;
+        NativeOwnerEntityPtr = nativeOwnerEntityPtr;
+        Slot = slot;
+        IsSelected = isSelected;
+        IsClientSide = isClientSide;
+    }
+}
+
+/// <summary>
+/// Runtime context for crafted-by callbacks.
+/// </summary>
+public readonly struct ItemCraftedByContext
+{
+    public int ItemId { get; }
+    public nint NativeItemInstancePtr { get; }
+    public nint NativeLevelPtr { get; }
+    public nint NativePlayerPtr { get; }
+    public nint NativePlayerSharedPtr { get; }
+    public int Amount { get; }
+    public bool IsClientSide { get; }
+
+    internal ItemCraftedByContext(
+        int itemId,
+        nint nativeItemInstancePtr,
+        nint nativeLevelPtr,
+        nint nativePlayerPtr,
+        nint nativePlayerSharedPtr,
+        int amount,
+        bool isClientSide)
+    {
+        ItemId = itemId;
+        NativeItemInstancePtr = nativeItemInstancePtr;
+        NativeLevelPtr = nativeLevelPtr;
+        NativePlayerPtr = nativePlayerPtr;
+        NativePlayerSharedPtr = nativePlayerSharedPtr;
+        Amount = amount;
+        IsClientSide = isClientSide;
+    }
+}
+
 [StructLayout(LayoutKind.Sequential)]
 internal struct MineBlockNativeArgs
 {
@@ -191,13 +424,64 @@ internal struct MineBlockNativeArgs
 internal struct UseItemNativeArgs
 {
     public int ItemId;
-    public int IsTestUseOnly;
     public int IsClientSide;
     public nint ItemInstancePtr;
     public nint PlayerPtr;
     public nint PlayerSharedPtr;
 }
 
+[StructLayout(LayoutKind.Sequential)]
+internal struct UseOnItemNativeArgs
+{
+    public int ItemId;
+    public int IsClientSide;
+    public nint ItemInstancePtr;
+    public nint PlayerPtr;
+    public nint PlayerSharedPtr;
+    public nint LevelPtr;
+    public int X;
+    public int Y;
+    public int Z;
+    public int Face;
+    public float ClickX;
+    public float ClickY;
+    public float ClickZ;
+}
+
+[StructLayout(LayoutKind.Sequential)]
+internal struct ItemEntityInteractionNativeArgs
+{
+    public int ItemId;
+    public nint ItemInstancePtr;
+    public nint PlayerPtr;
+    public nint PlayerSharedPtr;
+    public nint TargetEntityPtr;
+}
+
+[StructLayout(LayoutKind.Sequential)]
+internal struct ItemInventoryTickNativeArgs
+{
+    public int ItemId;
+    public nint ItemInstancePtr;
+    public nint LevelPtr;
+    public nint OwnerEntityPtr;
+    public int Slot;
+    public int IsSelected;
+    public int IsClientSide;
+}
+
+[StructLayout(LayoutKind.Sequential)]
+internal struct ItemCraftedByNativeArgs
+{
+    public int ItemId;
+    public nint ItemInstancePtr;
+    public nint LevelPtr;
+    public nint PlayerPtr;
+    public nint PlayerSharedPtr;
+    public int Amount;
+    public int IsClientSide;
+}
+
 internal static class ManagedItemDispatcher
 {
     private static readonly object s_lock = new();
@@ -259,7 +543,6 @@ internal static class ManagedItemDispatcher
 
         var result = item.OnUseItem(new UseItemContext(
             nativeArgs.ItemId,
-            nativeArgs.IsTestUseOnly != 0,
             nativeArgs.IsClientSide != 0,
             nativeArgs.ItemInstancePtr,
             nativeArgs.PlayerPtr,
@@ -268,4 +551,144 @@ internal static class ManagedItemDispatcher
         // 0 = no managed item, 1 = continue vanilla, 2 = cancel vanilla.
         return result == UseItemResult.CancelVanilla ? 2 : 1;
     }
+
+    internal static int HandleUseOn(IntPtr args, int sizeBytes)
+    {
+        if (args == IntPtr.Zero || sizeBytes < Marshal.SizeOf<UseOnItemNativeArgs>())
+            return 0;
+
+        UseOnItemNativeArgs nativeArgs = Marshal.PtrToStructure<UseOnItemNativeArgs>(args);
+
+        Item? item;
+        lock (s_lock)
+        {
+            s_items.TryGetValue(nativeArgs.ItemId, out item);
+        }
+
+        if (item == null)
+            return 0;
+
+        var result = item.OnUseOn(new UseOnItemContext(
+            nativeArgs.ItemId,
+            nativeArgs.IsClientSide != 0,
+            nativeArgs.ItemInstancePtr,
+            nativeArgs.PlayerPtr,
+            nativeArgs.PlayerSharedPtr,
+            nativeArgs.LevelPtr,
+            nativeArgs.X,
+            nativeArgs.Y,
+            nativeArgs.Z,
+            nativeArgs.Face,
+            nativeArgs.ClickX,
+            nativeArgs.ClickY,
+            nativeArgs.ClickZ));
+
+        return result == ItemActionResult.CancelVanilla ? 2 : 1;
+    }
+
+    internal static int HandleInteractEntity(IntPtr args, int sizeBytes)
+    {
+        if (args == IntPtr.Zero || sizeBytes < Marshal.SizeOf<ItemEntityInteractionNativeArgs>())
+            return 0;
+
+        ItemEntityInteractionNativeArgs nativeArgs = Marshal.PtrToStructure<ItemEntityInteractionNativeArgs>(args);
+
+        Item? item;
+        lock (s_lock)
+        {
+            s_items.TryGetValue(nativeArgs.ItemId, out item);
+        }
+
+        if (item == null)
+            return 0;
+
+        var result = item.OnInteractEntity(new ItemEntityInteractionContext(
+            nativeArgs.ItemId,
+            nativeArgs.ItemInstancePtr,
+            nativeArgs.PlayerPtr,
+            nativeArgs.PlayerSharedPtr,
+            nativeArgs.TargetEntityPtr));
+
+        return result == ItemActionResult.CancelVanilla ? 2 : 1;
+    }
+
+    internal static int HandleHurtEntity(IntPtr args, int sizeBytes)
+    {
+        if (args == IntPtr.Zero || sizeBytes < Marshal.SizeOf<ItemEntityInteractionNativeArgs>())
+            return 0;
+
+        ItemEntityInteractionNativeArgs nativeArgs = Marshal.PtrToStructure<ItemEntityInteractionNativeArgs>(args);
+
+        Item? item;
+        lock (s_lock)
+        {
+            s_items.TryGetValue(nativeArgs.ItemId, out item);
+        }
+
+        if (item == null)
+            return 0;
+
+        var result = item.OnHurtEntity(new ItemEntityInteractionContext(
+            nativeArgs.ItemId,
+            nativeArgs.ItemInstancePtr,
+            nativeArgs.PlayerPtr,
+            nativeArgs.PlayerSharedPtr,
+            nativeArgs.TargetEntityPtr));
+
+        return result == ItemActionResult.CancelVanilla ? 2 : 1;
+    }
+
+    internal static int HandleInventoryTick(IntPtr args, int sizeBytes)
+    {
+        if (args == IntPtr.Zero || sizeBytes < Marshal.SizeOf<ItemInventoryTickNativeArgs>())
+            return 0;
+
+        ItemInventoryTickNativeArgs nativeArgs = Marshal.PtrToStructure<ItemInventoryTickNativeArgs>(args);
+
+        Item? item;
+        lock (s_lock)
+        {
+            s_items.TryGetValue(nativeArgs.ItemId, out item);
+        }
+
+        if (item == null)
+            return 0;
+
+        item.OnInventoryTick(new ItemInventoryTickContext(
+            nativeArgs.ItemId,
+            nativeArgs.ItemInstancePtr,
+            nativeArgs.LevelPtr,
+            nativeArgs.OwnerEntityPtr,
+            nativeArgs.Slot,
+            nativeArgs.IsSelected != 0,
+            nativeArgs.IsClientSide != 0));
+        return 1;
+    }
+
+    internal static int HandleCraftedBy(IntPtr args, int sizeBytes)
+    {
+        if (args == IntPtr.Zero || sizeBytes < Marshal.SizeOf<ItemCraftedByNativeArgs>())
+            return 0;
+
+        ItemCraftedByNativeArgs nativeArgs = Marshal.PtrToStructure<ItemCraftedByNativeArgs>(args);
+
+        Item? item;
+        lock (s_lock)
+        {
+            s_items.TryGetValue(nativeArgs.ItemId, out item);
+        }
+
+        if (item == null)
+            return 0;
+
+        item.OnCraftedBy(new ItemCraftedByContext(
+            nativeArgs.ItemId,
+            nativeArgs.ItemInstancePtr,
+            nativeArgs.LevelPtr,
+            nativeArgs.PlayerPtr,
+            nativeArgs.PlayerSharedPtr,
+            nativeArgs.Amount,
+            nativeArgs.IsClientSide != 0));
+        return 1;
+    }
 }