feat: Add MateriaEntries

Per #2225.

Dalamud/Game/Inventory/GameInventoryItem.cs

@@ -1,7 +1,9 @@
+using System.Collections.Generic;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 
 using Dalamud.Data;
+using Dalamud.Game.Inventory.Records;
 using Dalamud.Utility;
 
 using FFXIVClientStructs.FFXIV.Client.Game;
@@ -160,6 +162,25 @@ public unsafe struct GameInventoryItem : IEquatable<GameInventoryItem>
         }
     }
 
+    public IReadOnlyList<MateriaEntry> MateriaEntries
+    {
+        get
+        {
+            if (ItemUtil.IsEventItem(this.BaseItemId) || this.IsMateriaUsedForDate)
+                return [];
+
+            var result = new List<MateriaEntry>();
+            for (byte i = 0; i < this.InternalItem.GetMateriaCount(); i++)
+            {
+                var entry = new MateriaEntry(this.InternalItem.GetMateriaId(i), this.InternalItem.GetMateriaGrade(i));
+                if (entry.IsValid())
+                    result.Add(entry);
+            }
+
+            return result;
+        }
+    }
+
     /// <summary>
     /// Gets the address of native inventory item in the game.<br />
     /// Can be 0 if this instance of <see cref="GameInventoryItem"/> does not point to a valid set of container type and slot.<br />

Dalamud/Game/Inventory/Records/MateriaEntry.cs

@@ -0,0 +1,42 @@
+using Dalamud.Data;
+
+using Lumina.Excel;
+using Lumina.Excel.Sheets;
+
+namespace Dalamud.Game.Inventory.Records;
+
+/// <summary>
+/// A record to hold easy information about a given piece of Materia.
+/// </summary>
+public record MateriaEntry
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MateriaEntry"/> class.
+    /// </summary>
+    /// <param name="typeId">The ID of the materia.</param>
+    /// <param name="gradeValue">The grade of the materia.</param>
+    public MateriaEntry(ushort typeId, byte gradeValue)
+    {
+        this.Type = LuminaUtils.CreateRef<Materia>(typeId);
+        this.Grade = LuminaUtils.CreateRef<MateriaGrade>(gradeValue);
+    }
+
+    /// <summary>
+    /// Gets the Lumina row for this Materia.
+    /// </summary>
+    public RowRef<Materia> Type { get; }
+
+    /// <summary>
+    /// Gets the Lumina row for this Materia's grade.
+    /// </summary>
+    public RowRef<MateriaGrade> Grade { get; }
+
+    /// <summary>
+    /// Checks if this MateriaEntry is valid.
+    /// </summary>
+    /// <returns>True if valid, false otherwise.</returns>
+    internal bool IsValid()
+    {
+        return this.Type.IsValid && this.Grade.IsValid;
+    }
+}