feat: Runtime font loading (#2981)

Author: VaclavElias

sources/engine/Stride.Graphics/Font/FontManager.cs

@@ -2,6 +2,7 @@
 // Distributed under the MIT license. See the LICENSE.md file in the project root for more information.
 using System;
 using System.Collections.Generic;
+using System.IO;
 using System.Threading;
 using SharpFont;
 using Stride.Core;
@@ -114,6 +115,45 @@ public void GenerateBitmap(CharacterSpecification characterSpecification, bool s
             }
         }
 
+        /// <summary>
+        /// Loads a font from the specified file on the file system and adds it to the internal font cache for use with
+        /// the given font name and style.
+        /// </summary>
+        /// <remarks>
+        /// <para>If a font with the same name and style is already cached, the method does nothing.</para>
+        /// <para>This method is thread-safe when adding new fonts to the cache.</para>
+        /// <para><strong>Memory considerations:</strong> The complete font file data is loaded into memory and kept
+        /// resident for the lifetime of the <see cref="FontManager"/>. Fonts cannot be individually unloaded;
+        /// they are only released when the <see cref="FontManager"/> is disposed. Consider this when loading
+        /// large fonts or many font variants, especially on memory-constrained platforms.</para>
+        /// </remarks>
+        /// <param name="fontName">The name to associate with the loaded font. This name is used to reference the font in subsequent
+        /// operations.</param>
+        /// <param name="filePath">The path to the font file on the file system. The file must exist and be accessible.</param>
+        /// <param name="style">The style to apply to the loaded font, such as regular, bold, or italic.</param>
+        /// <exception cref="FileNotFoundException">Thrown if the file specified by <paramref name="filePath"/> does not exist.</exception>
+        public void LoadFontFromFileSystem(string fontName, string filePath, FontStyle style)
+        {
+            var cacheKey = FontHelper.GetFontPath(fontName, style);
+
+            // Fast path: Return if the font is already cached (avoids lock contention)
+            if (cachedFontFaces.ContainsKey(cacheKey))
+                return;
+
+            lock (freetypeLibrary)
+            {
+                // Check again inside lock to prevent race condition
+                if (cachedFontFaces.ContainsKey(cacheKey))
+                    return;
+
+                // Load font data into memory
+                var fontData = File.ReadAllBytes(filePath);
+
+                // Create FreeType face and add to cache
+                cachedFontFaces[cacheKey] = freetypeLibrary.NewMemoryFace(fontData, 0);
+            }
+        }
+
         private void GenerateCharacterGlyph(CharacterSpecification character, bool renderBitmap)
         {
             // first the possible current glyph info

sources/engine/Stride.Graphics/Font/FontSystem.cs

@@ -21,6 +21,16 @@ public class FontSystem : IFontFactory
         internal FontCacheManager FontCacheManager { get; private set; }
         internal readonly HashSet<SpriteFont> AllocatedSpriteFonts = new HashSet<SpriteFont>();
 
+        /// <summary>
+        /// Gets the runtime font provider for registering and managing fonts loaded from the file system.
+        /// </summary>
+        /// <remarks>
+        /// <para>Use this to register custom fonts at runtime that are not part of the content pipeline
+        /// via <see cref="RuntimeFontProvider.RegisterFont"/>.</para>
+        /// <para>Once registered, fonts can be loaded using the <see cref="LoadRuntimeFont"/> method.</para>
+        /// </remarks>
+        public RuntimeFontProvider RuntimeFonts { get; private set; }
+
         /// <summary>
         /// Create a new instance of <see cref="FontSystem" /> base on the provided <see cref="Stride.Graphics.GraphicsDevice" />.
         /// </summary>
@@ -40,6 +50,23 @@ public void Load(GraphicsDevice graphicsDevice, IDatabaseFileProviderService fil
             GraphicsDevice = graphicsDevice;
             FontManager = new FontManager(fileProviderService);
             FontCacheManager = new FontCacheManager(this);
+            RuntimeFonts = new RuntimeFontProvider(this);
+        }
+
+        /// <summary>
+        /// Loads a runtime-registered font by name.
+        /// This bypasses the content pipeline entirely.
+        /// </summary>
+        /// <param name="fontName">The registered font name. If the font is not registered, the method returns <c>null</c>.</param>
+        /// <param name="defaultSize">The default font size in pixels.</param>
+        /// <param name="style">The font style.</param>
+        /// <returns>A <see cref="SpriteFont"/> instance if the font is registered; otherwise, <c>null</c>.</returns>
+        public SpriteFont? LoadRuntimeFont(string fontName, float defaultSize = 16f, FontStyle style = FontStyle.Regular)
+        {
+            if (!RuntimeFonts.IsRegistered(fontName, style))
+                return null;
+
+            return NewDynamic(defaultSize, fontName, style);
         }
 
         public void Draw()

sources/engine/Stride.Graphics/Font/RuntimeFontProvider.cs

@@ -0,0 +1,82 @@
+// Copyright (c) .NET Foundation and Contributors (https://dotnetfoundation.org/ & https://stride3d.net)
+// Distributed under the MIT license. See the LICENSE.md file in the project root for more information.
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+
+namespace Stride.Graphics.Font;
+
+/// <summary>
+/// Provides runtime registration and loading of fonts from the file system.
+/// </summary>
+/// <remarks>
+/// <para>This provider allows loading custom TrueType fonts (.ttf) at runtime without going through
+/// the content pipeline. Fonts registered through this provider are immediately available for use
+/// with <see cref="FontSystem.LoadRuntimeFont"/>.</para>
+/// <para><strong>Memory Management:</strong> All registered fonts remain in memory for the lifetime
+/// of the application. There is no mechanism to unload individual fonts once registered. For applications
+/// with dynamic font requirements or memory constraints, consider the total memory footprint of all
+/// registered fonts.</para>
+/// </remarks>
+public class RuntimeFontProvider
+{
+    private readonly FontSystem fontSystem;
+    private readonly Dictionary<string, RuntimeFontInfo> registeredFonts = [];
+
+    internal RuntimeFontProvider(FontSystem fontSystem)
+    {
+        this.fontSystem = fontSystem;
+    }
+
+    /// <summary>
+    /// Registers a font file for runtime loading.
+    /// </summary>
+    /// <remarks>
+    /// <para>Once registered, fonts are loaded into memory and cached for the lifetime of the font system.
+    /// Individual fonts cannot be unregistered or unloaded - they remain in memory until the application exits
+    /// or the font system is disposed.</para>
+    /// <para>Attempting to register the same font name and style with a different file path will throw an exception.</para>
+    /// </remarks>
+    /// <param name="fontName">The name to use when loading the font (e.g., "MyFont").</param>
+    /// <param name="filePath">The absolute or relative path to the .ttf file.</param>
+    /// <param name="style">The font style.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="fontName"/> is null or empty.</exception>
+    /// <exception cref="FileNotFoundException">Thrown when the font file does not exist.</exception>
+    /// <exception cref="InvalidOperationException">Thrown when attempting to register the same font name and style with a different file path.</exception>
+    public void RegisterFont(string fontName, string filePath, FontStyle style = FontStyle.Regular)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(fontName);
+
+        if (!File.Exists(filePath))
+            throw new FileNotFoundException($"Font file not found: {filePath}", filePath);
+
+        var key = FontHelper.GetFontPath(fontName, style);
+
+        if (registeredFonts.TryGetValue(key, out var existing))
+        {
+            if (existing.FilePath == filePath) return;
+
+            throw new InvalidOperationException(
+                $"Font '{fontName}' with style '{style}' is already registered with path '{existing.FilePath}'. " +
+                $"Cannot register a different path '{filePath}' for the same font name and style.");
+        }
+
+        fontSystem.FontManager.LoadFontFromFileSystem(fontName, filePath, style);
+
+        registeredFonts[key] = new RuntimeFontInfo(fontName, filePath, style);
+    }
+
+    /// <summary>
+    /// Checks if a font is registered for runtime loading.
+    /// </summary>
+    /// <param name="fontName">The font name.</param>
+    /// <param name="style">The font style.</param>
+    /// <returns>True if registered, false otherwise.</returns>
+    public bool IsRegistered(string fontName, FontStyle style = FontStyle.Regular)
+    {
+        return registeredFonts.ContainsKey(FontHelper.GetFontPath(fontName, style));
+    }
+
+    private record RuntimeFontInfo(string FontName, string FilePath, FontStyle Style);
+}