Implement some clientbound packets (#480)

Author: RoboMico

Obsidian.API/_Interfaces/INetworkSerializable.cs

@@ -1,6 +1,24 @@
 namespace Obsidian.API;
+
+/// <summary>
+/// Interface for network serializable objects. Due to the nature of Obsidian being a server-side only software,
+/// both <see cref="Write"/> and <see cref="Read"/> methods are not always necessary to implement. In that case,
+/// a <see cref="NotImplementedException"/> is thrown when the method is unintendedly called.
+/// </summary>
+/// <typeparam name="TValue">Type of the value to be serialized.</typeparam>
 public interface INetworkSerializable<TValue>
 {
+    /// <summary>
+    /// Writes the value to the network stream.
+    /// </summary>
+    /// <param name="value">Value to be serialized.</param>
+    /// <param name="writer">Network stream writer.</param>
     public static abstract void Write(TValue value, INetStreamWriter writer);
+
+    /// <summary>
+    /// Reads the value from the network stream.
+    /// </summary>
+    /// <param name="reader">Network stream reader.</param>
+    /// <returns>Deserialized value.</returns>
     public static abstract TValue Read(INetStreamReader reader);
 }

Obsidian.API/_Interfaces/IPacket.cs

@@ -1,10 +1,24 @@
 namespace Obsidian.API;
+
+/// <summary>
+/// Represents a network packet that can be transferred between the client and the server.
+/// </summary>
 public interface IPacket
 {
+    /// <summary>
+    /// The ID of the packet.
+    /// </summary>
     public int Id { get; }
 }
 
+/// <summary>
+/// Represents a network packet that can be sent to the client by the server.
+/// </summary>
 public interface IClientboundPacket : IPacket
 {
+    /// <summary>
+    /// Writes the data content of the packet to the stream.
+    /// </summary>
+    /// <param name="writer">The stream writer to write the data to.</param>
     public void Serialize(INetStreamWriter writer);
 }

Obsidian.API/_Types/TradeEntry.cs

@@ -0,0 +1,78 @@
+using Obsidian.API.Inventory;
+
+namespace Obsidian.API;
+
+/// <summary>
+/// Represents a trade entry offered by a villager or wandering trader.
+/// </summary>
+public sealed record TradeEntry : INetworkSerializable<TradeEntry>
+{
+    /// <summary>
+    /// The first input item of the trade. The required count of the first input is the "base price" of the trade.
+    /// The final price = base + floor(base * <see cref="Multiplier"/> * <see cref="Demand"/>) + <see cref="Discount"/>.
+    /// </summary>
+    public TradeItem FirstInput { get; set; }
+
+    /// <summary>
+    /// The output item of the trade.
+    /// </summary>
+    public ItemStack Output { get; set; }
+
+    /// <summary>
+    /// The second input item of the trade. The required count of the second input is not affected by discount
+    /// or demand.
+    /// </summary>
+    public TradeItem SecondInput { get; set; }
+
+    /// <summary>
+    /// Whether the trade is disabled.
+    /// </summary>
+    public bool IsDisabled { get; set; }
+
+    /// <summary>
+    /// Number of times the trade has been used.
+    /// </summary>
+    public int UsedCount { get; set; }
+
+    /// <summary>
+    /// The maximum number of times the trade can be used before it becomes disabled.
+    /// </summary>
+    public int MaxCount { get; set; }
+
+    /// <summary>
+    /// Number of XPs the villager will earn after each trade.
+    /// </summary>
+    public int XP { get; set; }
+
+    /// <summary>
+    /// Used in calculating the final price. Can be zero or negative.
+    /// </summary>
+    public int Discount { get; set; }
+
+    /// <summary>
+    /// Used in calculating the final price. Can be low (0.05) or high (0.2).
+    /// </summary>
+    public float Multiplier { get; set; }
+
+    /// <summary>
+    /// Used in calculating the final price. Negative values are treated as zero.
+    /// </summary>
+    public int Demand { get; set; }
+
+    public static void Write(TradeEntry value, INetStreamWriter writer)
+    {
+        TradeItem.Write(value.FirstInput, writer);
+        writer.WriteItemStack(value.Output);
+        TradeItem.Write(value.SecondInput, writer);
+        writer.WriteBoolean(value.IsDisabled);
+        writer.WriteInt(value.UsedCount);
+        writer.WriteInt(value.MaxCount);
+        writer.WriteInt(value.XP);
+        writer.WriteInt(value.Discount);
+        writer.WriteFloat(value.Multiplier);
+        writer.WriteInt(value.Demand);
+    }
+
+    // No need to implement
+    public static TradeEntry Read(INetStreamReader reader) => throw new NotImplementedException();
+}

Obsidian.API/_Types/TradeItem.cs

@@ -0,0 +1,52 @@
+using Obsidian.API.Inventory;
+
+namespace Obsidian.API;
+
+/// <summary>
+/// Represents an item stack supplied as the "price" in a <see cref="TradeEntry"/>.
+/// </summary>
+public sealed record TradeItem : INetworkSerializable<TradeItem>
+{
+    /// <summary>
+    /// The item ID.
+    /// </summary>
+    public int ID { get; set; }
+
+    /// <summary>
+    /// The item count.
+    /// </summary>
+    public int Count { get; set; }
+
+    /// <summary>
+    /// The item's components. An item stack must match all the component requirements to be considered a
+    /// valid input.
+    /// </summary>
+    public List<IDataComponent> Components { get; set; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="TradeItem"/> record.
+    /// </summary>
+    /// <param name="id">The item ID.</param>
+    /// <param name="count">The item count.</param>
+    /// <param name="components">The item's components.</param>
+    public TradeItem(int id, int count, List<IDataComponent> components)
+    {
+        ID = id;
+        Count = count;
+        Components = components;
+    }
+
+    public static void Write(TradeItem value, INetStreamWriter writer)
+    {
+        writer.WriteVarInt(value.ID);
+        writer.WriteVarInt(value.Count);
+        writer.WriteLengthPrefixedArray((c) =>
+        {
+            writer.WriteVarInt(c.Type);
+            c.Write(writer);
+        }, value.Components);
+    }
+
+    // No need to implement
+    public static TradeItem Read(INetStreamReader reader) => throw new NotImplementedException();
+}

Obsidian/Entities/Entity.cs

@@ -400,26 +400,26 @@ public virtual ValueTask TeleportAsync(VectorF pos)
     public virtual void SpawnEntity(Velocity? velocity = null, int additionalData = 0)
     {
         this.PacketBroadcaster.QueuePacketToWorldInRange(this.World, this.Position, new BundledPacket
-        {
-            Packets = [
-                        new AddEntityPacket
-                        {
-                            EntityId = this.EntityId,
-                            Uuid = this.Uuid,
-                            Type = this.Type,
-                            Position = this.Position,
-                            Pitch = this.Pitch,
-                            Yaw = this.Yaw,
-                            Data = additionalData,
-                            Velocity = velocity ?? new Velocity(0, 0, 0)
-                        },
-                        new SetEntityDataPacket
-                        {
-                            EntityId = this.EntityId,
-                            Entity = this
-                        }
-                    ]
-        }, this.EntityId);
+        (
+             [
+                new AddEntityPacket
+                {
+                    EntityId = this.EntityId,
+                    Uuid = this.Uuid,
+                    Type = this.Type,
+                    Position = this.Position,
+                    Pitch = this.Pitch,
+                    Yaw = this.Yaw,
+                    Data = additionalData,
+                    Velocity = velocity ?? new Velocity(0, 0, 0)
+                },
+                new SetEntityDataPacket
+                {
+                    EntityId = this.EntityId,
+                    Entity = this
+                }
+            ]
+        ), this.EntityId);
     }
 
     public bool TryAddAttribute(string attributeResourceName, float value) =>

Obsidian/Net/Packets/Play/Clientbound/BundleDelimiterPacket.cs

@@ -0,0 +1,7 @@
+namespace Obsidian.Net.Packets.Play.Clientbound;
+
+/// <summary>
+/// Used to wrap a <see cref="BundledPacket"/>.
+/// </summary>
+public partial class BundleDelimiterPacket
+{ }

Obsidian/Net/Packets/Play/Clientbound/BundledPacket.cs

@@ -1,7 +1,16 @@
 namespace Obsidian.Net.Packets.Play.Clientbound;
-public partial class BundledPacket : ClientboundPacket
+
+/// <summary>
+/// Represents a bundle of packets that the client should handle in the same tick.
+/// A <see cref="BundleDelimiterPacket"/> is sent before and after the content packets are sent to the client.
+/// Vanilla Minecraft client doesn't allow more than 4096 packets in one bundle.
+/// </summary>
+public partial class BundledPacket(List<ClientboundPacket> packets) : ClientboundPacket
 {
-    public required List<ClientboundPacket> Packets { get; set; }
+    /// <summary>
+    /// The packets in this bundle.
+    /// </summary>
+    public List<ClientboundPacket> Packets { get; set; } = packets;
 
     public override int Id => 0;
 

Obsidian/Net/Packets/Play/Clientbound/HorseScreenOpenPacket.cs

@@ -0,0 +1,40 @@
+using Obsidian.Serialization.Attributes;
+
+namespace Obsidian.Net.Packets.Play.Clientbound;
+
+/// <summary>
+/// Sent to tell the client to open the horse GUI. Opening other GUIs are done via <see cref="OpenScreenPacket"/>.
+/// </summary>
+/// <remarks>
+/// Initializes a new instance of the <see cref="HorseScreenOpenPacket"/> class.
+/// </remarks>
+/// <param name="windowId">The identifier of the window to open.</param>
+/// <param name="columnCount">How many columns the horse inventory should have.</param>
+/// <param name="entityId">The owner entity of the window.</param>
+public partial class HorseScreenOpenPacket(int windowId, int columnCount, int entityId)
+{
+    /// <summary>
+    /// The identifier of the window to open.
+    /// </summary>
+    [Field(0), VarLength]
+    public int WindowID { get; set; } = windowId;
+
+    /// <summary>
+    /// How many columns the horse inventory should have.
+    /// </summary>
+    [Field(1), VarLength]
+    public int ColumnCount { get; set; } = columnCount;
+
+    /// <summary>
+    /// The owner entity of the window.
+    /// </summary>
+    [Field(2)]
+    public int EntityID { get; set; } = entityId;
+
+    public override void Serialize(INetStreamWriter writer) 
+    {
+        writer.WriteVarInt(WindowID);
+        writer.WriteVarInt(ColumnCount);
+        writer.WriteInt(EntityID);
+    }
+}

Obsidian/Net/Packets/Play/Clientbound/MerchantOffersPacket.cs

@@ -0,0 +1,56 @@
+using Obsidian.API;
+using Obsidian.Serialization.Attributes;
+
+namespace Obsidian.Net.Packets.Play.Clientbound;
+
+/// <summary>
+/// The list of trades a villager is offering.
+/// </summary>
+public partial class MerchantOffersPacket
+{
+    /// <summary>
+    /// The window ID of the villager's trade list.
+    /// </summary>
+    [Field(0), VarLength]
+    public int WindowId { get; set; }
+
+    /// <summary>
+    /// The offered trades list.
+    /// </summary>
+    [Field(1)]
+    public List<TradeEntry> Offers { get; set; }
+
+    /// <summary>
+    /// The level of the villager. 1: Novice, 2: Apprentice, 3: Journeyman, 4: Expert, 5: Master.
+    /// </summary>
+    [Field(2), VarLength]
+    public int VillagerLevel { get; set; }
+
+    /// <summary>
+    /// The total experience of the villager. Always 0 for wandering traders.
+    /// </summary>
+    [Field(3), VarLength]
+    public int VillagerExperience { get; set; }
+
+    /// <summary>
+    /// True if the villager is a regular villager, false if it is a wandering trader.
+    /// </summary>
+    [Field(4)]
+    public bool IsRegularVillager { get; set; }
+
+    /// <summary>
+    /// True if the villager can restock their inventory, false otherwise.
+    /// </summary>
+    [Field(5)]
+    public bool CanRestock { get; set; }
+
+    public override void Serialize(INetStreamWriter writer)
+    {
+        writer.WriteVarInt(WindowId);
+        writer.WriteLengthPrefixedArray((o) => TradeEntry.Write(o, writer), Offers);
+        writer.WriteVarInt(VillagerLevel);
+        writer.WriteVarInt(VillagerExperience);
+        writer.WriteBoolean(IsRegularVillager);
+        writer.WriteBoolean(CanRestock);
+    }
+}

Obsidian/Net/Packets/Play/Clientbound/OpenBookPacket.cs

@@ -2,8 +2,14 @@
 
 namespace Obsidian.Net.Packets.Play.Clientbound;
 
+/// <summary>
+/// Sent to the client to open a book GUI.
+/// </summary>
 public partial class OpenBookPacket
 {
+    /// <summary>
+    /// The hand that is holding the book.
+    /// </summary>
     [Field(0), ActualType(typeof(int)), VarLength]
     public Hand Hand { get; set; }