Enhance school creation and map management features by updating the API to support mod packs and map layouts. Introduce a new map snapshot protocol for efficient data handling during school sessions. Revise documentation to reflect these changes, including updates to the protocol and architecture documents. Improve UI components for mod selection and map editing, ensuring a better user experience. Update tests to validate new functionalities and ensure robustness.

src/HSchool.Protocol/ProtocolCodec.cs

@@ -7,7 +7,10 @@ namespace HSchool.Protocol;
 /// </summary>
 public static class ProtocolCodec
 {
-    /// <summary>Largest frame this codec produces; handlers can size their buffers from it.</summary>
+    /// <summary>
+    /// Largest <em>fixed-size</em> frame this codec produces. Variable map snapshots use
+    /// <see cref="ProtocolConstants.MaxMessageSize"/> instead.
+    /// </summary>
     public const int MaxFrameSize = 16;
 
     public static int WriteHello(Span<byte> destination, in ClientHelloMessage message)
@@ -15,6 +18,7 @@ public static class ProtocolCodec
         var writer = new PacketWriter(destination);
         writer.WriteMessageType(MessageType.ClientHello);
         writer.WriteByte(message.ProtocolVersion);
+        writer.WriteByte(message.Locale);
         return writer.Position;
     }
 
@@ -95,6 +99,45 @@ public static class ProtocolCodec
         return writer.Position;
     }
 
+    public static int WriteMapSnapshot(Span<byte> destination, ServerMapSnapshotMessage message)
+    {
+        if (message.Nodes.Count > ushort.MaxValue)
+        {
+            throw new ProtocolException($"Map snapshot has {message.Nodes.Count} nodes; u16 count cannot hold it.");
+        }
+
+        var writer = new PacketWriter(destination);
+        writer.WriteMessageType(MessageType.ServerMapSnapshot);
+        writer.WriteInt32(message.SchoolId);
+        writer.WriteUInt16((ushort)message.Nodes.Count);
+
+        foreach (var node in message.Nodes)
+        {
+            if (node.Items.Count > byte.MaxValue || node.Positions.Count > byte.MaxValue)
+            {
+                throw new ProtocolException($"Map node '{node.Id}' has too many items or positions for a u8 count.");
+            }
+
+            writer.WriteByte(node.Kind);
+            writer.WriteString(node.Id);
+            writer.WriteString(node.ParentId);
+            writer.WriteString(node.Name);
+            writer.WriteByte((byte)node.Items.Count);
+            foreach (var item in node.Items)
+            {
+                writer.WriteString(item);
+            }
+
+            writer.WriteByte((byte)node.Positions.Count);
+            foreach (var position in node.Positions)
+            {
+                writer.WriteString(position);
+            }
+        }
+
+        return writer.Position;
+    }
+
     public static MessageType PeekMessageType(ReadOnlySpan<byte> source) =>
         source.IsEmpty ? MessageType.None : (MessageType)source[0];
 
@@ -102,7 +145,9 @@ public static class ProtocolCodec
     {
         var reader = new PacketReader(source);
         Expect(ref reader, MessageType.ClientHello);
-        return new ClientHelloMessage(reader.ReadByte());
+        var version = reader.ReadByte();
+        var locale = reader.ReadByte();
+        return new ClientHelloMessage(version, locale);
     }
 
     public static ClientPingMessage ReadPing(ReadOnlySpan<byte> source)
@@ -170,6 +215,40 @@ public static class ProtocolCodec
         return new ServerSchoolGoneMessage(reader.ReadInt32());
     }
 
+    public static ServerMapSnapshotMessage ReadMapSnapshot(ReadOnlySpan<byte> source)
+    {
+        var reader = new PacketReader(source);
+        Expect(ref reader, MessageType.ServerMapSnapshot);
+        var schoolId = reader.ReadInt32();
+        var nodeCount = reader.ReadUInt16();
+        var nodes = new MapSnapshotNode[nodeCount];
+
+        for (var i = 0; i < nodeCount; i++)
+        {
+            var kind = reader.ReadByte();
+            var id = reader.ReadString();
+            var parentId = reader.ReadString();
+            var name = reader.ReadString();
+            var itemCount = reader.ReadByte();
+            var items = new string[itemCount];
+            for (var item = 0; item < itemCount; item++)
+            {
+                items[item] = reader.ReadString();
+            }
+
+            var positionCount = reader.ReadByte();
+            var positions = new string[positionCount];
+            for (var position = 0; position < positionCount; position++)
+            {
+                positions[position] = reader.ReadString();
+            }
+
+            nodes[i] = new MapSnapshotNode(kind, id, parentId, name, items, positions);
+        }
+
+        return new ServerMapSnapshotMessage(schoolId, nodes);
+    }
+
     private static void Expect(ref PacketReader reader, MessageType expected)
     {
         var actual = reader.ReadMessageType();