feat(SAMPLE-062): support streamed particle XML

Author: robertvokac

docs/XmlSerializationScope.md

@@ -1,10 +1,10 @@
 # `System.Xml.Serialization` — scope, evidence, and known deviations
 
 Ticket: `SAMPLES-DEC-008`. Module: `modules/xml-serialization` (`Xml.Serialization`, header-only,
-`INTERFACE`, depends on `Core.Base` and `Xml`).
+`INTERFACE`, depends on `Collections.Core`, `IO`, and `Xml`).
 
-This module exists to unblock three `cna-samples` ports — `SAMPLE-014` (Spacewar),
-`SAMPLE-066` (ShipGame) and `SAMPLE-070` (RolePlayingGame) — which the owner marked blocked on
+This module exists to unblock four `cna-samples` ports — `SAMPLE-014` (Spacewar),
+`SAMPLE-062` (NetRumble), `SAMPLE-066` (ShipGame), and `SAMPLE-070` (RolePlayingGame) — which the owner marked blocked on
 2026-08-28 with an explicit instruction not to add another hand-written per-sample XML parser.
 It is a shared, generic engine, not a parser for any one sample.
 
@@ -53,6 +53,7 @@ inside a local class, so a type declared inside a function body will not compile
 | `INF`/`-INF`/`NaN` schema tokens, not .NET's `Infinity` spelling | XML Schema's `float` lexical space |
 | Markup escaping (`&`, `<`, `>`, quotes) and non-ASCII text | a quest named `Smith & Son` must not corrupt a save |
 | **Nested serialization into a caller's document** (`SerializeInto`/`DeserializeFrom`/`RootElementName`) | **16 of the 20** `Session.cs` call sites serialize into an already-open `XmlWriter` |
+| Deserialization from a readable `Stream` at its current position without taking ownership | NetRumble's `ParticleEffect.Load(ContentManager, String)` opens each particle XML with `File.OpenRead` and passes the stream to `XmlSerializer.Deserialize` |
 
 ## The dominant call-site shape: nesting, not standalone documents
 
@@ -99,12 +100,12 @@ Each of these is **absent by evidence, not by omission**:
   belongs to the **Content Pipeline** writers (`CharacterWriter.cs`,
   `FightingCharacterWriter.cs` in `RolePlayingGameProcessors`), which build `.xnb` at build time
   and never reach `XmlSerializer`.
-- **`[XmlArray]` / `[XmlArrayItem]` naming overrides.** No occurrences in the three samples.
+- **`[XmlArray]` / `[XmlArrayItem]` naming overrides.** No occurrences in the four samples.
 - **`[XmlAttribute]`-mapped members.** Every reachable member is element-mapped.
 - **Circular-reference detection.** The reachable save graphs are trees and lists, with content
   referenced by asset *name* rather than by object identity.
 
-If any of these turns up in a fourth sample, it is new work with its own ticket — not a silent
+If any of these turns up in a fifth sample, it is new work with its own ticket — not a silent
 gap here.
 
 ## Known deviations

modules/io/include/System/IO/DirectoryInfo.hpp

@@ -5,6 +5,7 @@
 #include <filesystem>
 #include <string>
 #include <vector>
+#include "System/IO/Directory.hpp"
 #include "System/IO/DirectoryNotFoundException.hpp"
 #include "System/IO/FileInfo.hpp"
 #include "System/IO/FileSystemInfo.hpp"
@@ -157,6 +158,24 @@ namespace System::IO {
             return result;
         }
 
+        /**
+         * @brief Returns FileInfo objects for files whose names match the search pattern.
+         *
+         * @param searchPattern Pattern containing the same wildcard syntax accepted by
+         *        Directory::GetFiles.
+         * @return Matching files in the directory.
+         * @throws System::IO::DirectoryNotFoundException if the directory does not exist.
+         * @throws System::UnauthorizedAccessException if enumeration is denied.
+         * @throws System::IO::IOException for another filesystem enumeration failure.
+         */
+        [[nodiscard]] std::vector<FileInfo> GetFiles(const std::string& searchPattern) const {
+            std::vector<FileInfo> result;
+            for (const std::string& path : Directory::GetFiles(fullPath_.string(), searchPattern)) {
+                result.emplace_back(path);
+            }
+            return result;
+        }
+
         /**
          * @brief Returns a list of file paths for the files in this directory.
          * @throws System::IO::DirectoryNotFoundException if this directory does not exist.

modules/io/tests/System/IO/IOStreamTests.cpp

@@ -758,6 +758,24 @@ TEST(DirectoryInfoTests, GetFiles_NonExistent_ThrowsDirectoryNotFoundException)
     EXPECT_THROW((void)di.GetFiles(), System::IO::DirectoryNotFoundException);
 }
 
+TEST(DirectoryInfoTests, GetFiles_SearchPattern_ReturnsMatchingFileInfoObjects) {
+    const std::string dir = tf("di_getfiles_pattern");
+    Directory::CreateDirectory(dir);
+    File::WriteAllText(dir + "/first.xnb", "xnb");
+    File::WriteAllText(dir + "/SECOND.XNB", "xnb");
+    File::WriteAllText(dir + "/ignored.wav", "wav");
+
+    const DirectoryInfo info(dir);
+    const auto files = info.GetFiles("*.xnb");
+
+    ASSERT_EQ(files.size(), 2u);
+    EXPECT_TRUE(files[0].getNameProperty() == "first.xnb" ||
+                files[1].getNameProperty() == "first.xnb");
+    EXPECT_TRUE(files[0].getNameProperty() == "SECOND.XNB" ||
+                files[1].getNameProperty() == "SECOND.XNB");
+    Directory::Delete(dir, true);
+}
+
 // ===========================================================================
 // BinaryWriter + BinaryReader
 // ===========================================================================

modules/xml-serialization/CMakeLists.txt

@@ -5,5 +5,5 @@ sharp_runtime_register_module(
     NAME Xml.Serialization
     TARGET sharp_runtime_xml_serialization
     TYPE INTERFACE
-    PUBLIC_DEPENDENCIES Collections.Core Xml
+    PUBLIC_DEPENDENCIES Collections.Core IO Xml
 )

modules/xml-serialization/include/System/Xml/Serialization/XmlSerializer.hpp

@@ -9,6 +9,7 @@
 #include <vector>
 
 #include "System/Collections/Generic/List.hpp"
+#include "System/IO/StreamReader.hpp"
 #include "System/Xml/Serialization/detail/XmlLeafConvert.hpp"
 #include "System/Xml/Serialization/detail/XmlMember.hpp"
 #include "System/Xml/XmlDocument.hpp"
@@ -101,6 +102,19 @@ namespace System::Xml::Serialization {
             return result;
         }
 
+        /**
+         * @brief Deserializes an XML document read from the stream's current position.
+         *
+         * @param stream Readable stream containing the XML document.
+         * @return Deserialized value.
+         * @throws System::ArgumentException if the stream is not readable.
+         * @throws System::Xml::XmlException if the XML is malformed.
+         */
+        [[nodiscard]] T Deserialize(System::IO::Stream& stream) const {
+            System::IO::StreamReader reader(&stream, true);
+            return Deserialize(reader.ReadToEnd());
+        }
+
         /**
          * @brief Appends @p value to @p parent as one element, inside a document the caller owns.
          *

modules/xml-serialization/tests/System/Xml/Serialization/XmlSerializerTests.cpp

@@ -15,6 +15,7 @@
 #include <gtest/gtest.h>
 
 #include "System/Xml/Serialization/XmlSerializer.hpp"
+#include "System/IO/MemoryStream.hpp"
 
 using System::Xml::Serialization::XmlSerializationOptions;
 using System::Xml::Serialization::XmlSerializer;
@@ -35,6 +36,23 @@ struct SaveGameDescriptionData {
                             SHARP_XML_M(SaveGameDescriptionData, Description))
 };
 
+TEST(XmlSerializerStreamTests, DeserializeReadsFromCurrentStreamPositionAndLeavesStreamOpen) {
+    const std::string xml = "prefix<?xml version=\"1.0\"?><SaveGameDescription>"
+                            "<FileName>slot1</FileName><ChapterName>One</ChapterName>"
+                            "<Description>Ready</Description></SaveGameDescription>";
+    System::IO::MemoryStream stream(
+        reinterpret_cast<const SharpRuntime::bytecs*>(xml.data()),
+        static_cast<SharpRuntime::intcs>(xml.size()), false);
+    stream.setPositionProperty(6);
+
+    const SaveGameDescriptionData value = XmlSerializer<SaveGameDescriptionData>{}.Deserialize(stream);
+
+    EXPECT_EQ(value.FileName, "slot1");
+    EXPECT_EQ(value.ChapterName, "One");
+    EXPECT_EQ(value.Description, "Ready");
+    EXPECT_TRUE(stream.getCanReadProperty());
+}
+
 // --- ShipGame's Entity/EntityList: ShipGame/ShipGame/EntityList.cs ----------------------------
 
 struct MatrixData {