Framework/Core/LoadingProgress.cs

Static loading-screen state for a roleplay framework: tracks title, subtitle, current stage, detail text, an overall 0-1 fraction split into weighted phases, and a list of completed steps. Steps call Begin/Phase/Step/End, Tick creeps the bar toward 92% of the current phase when nothing reports, and Show yields two frames so the screen draws before blocking work.

using System;
using System.Collections.Generic;

namespace RoleplayFramework.Core;

/// <summary>
/// What the loading screen shows while a server starts (host) or while joining one (client): the current step, an
/// optional detail ("USP (3/25)"), overall progress 0-1 and the finished steps. Steps report through
/// <see cref="Step"/>; long synchronous work (compiling Lua) should <c>await LoadingProgress.Show()</c> first so the
/// screen is drawn before the frame blocks.
/// </summary>
public static class LoadingProgress
{
	public static bool Active { get; private set; }
	public static string Title { get; private set; } = "";
	public static string Subtitle { get; private set; } = "";
	public static string Stage { get; private set; } = "";
	public static string Detail { get; private set; } = "";
	/// <summary>Overall progress 0-1.</summary>
	public static float Fraction { get; private set; }
	public static RealTimeSince Since { get; private set; }
	/// <summary>Increments on every change (UI rebuild hash).</summary>
	public static int Version { get; private set; }

	static readonly List<string> _done = new();
	public static IReadOnlyList<string> Done => _done;

	// The run is split into weighted phases so one bar can cover all of them: [start, end) of the bar per phase.
	static float _phaseStart, _phaseEnd = 1f;

	public static void Begin( string title, string subtitle )
	{
		Active = true;
		Title = title ?? "";
		Subtitle = subtitle ?? "";
		Stage = "Starting";
		Detail = "";
		Fraction = 0;
		_phaseStart = 0;
		_phaseEnd = 1;
		_done.Clear();
		_endAt = null;
		Since = 0;
		Version++;
	}

	public static void SetInfo( string title, string subtitle )
	{
		if ( title is not null ) Title = title;
		if ( subtitle is not null ) Subtitle = subtitle;
		Version++;
	}

	/// <summary>Starts a phase covering [start, end) of the bar; the previous phase is listed as done.</summary>
	public static void Phase( string stage, float start, float end, string detail = "" )
	{
		if ( !Active ) return;
		if ( !string.IsNullOrEmpty( Stage ) && Stage != "Starting" && Stage != stage && !_done.Contains( Stage ) ) _done.Add( Stage );
		Stage = stage;
		Detail = detail ?? "";
		_phaseStart = Math.Clamp( start, 0, 1 );
		_phaseEnd = Math.Clamp( Math.Max( end, start ), 0, 1 );
		Fraction = Math.Max( Fraction, _phaseStart );
		_sinceStep = 0;
		Version++;
		Diagnostics.RpLog.Info( "loading", $"{stage} ({Fraction * 100:F0}%, {(float)Since:F1}s){(string.IsNullOrEmpty( Detail ) ? "" : " - " + Detail)}" );
	}

	/// <summary>Progress inside the current phase (0-1) and what is being worked on.</summary>
	public static void Step( float phaseFraction, string detail = null )
	{
		if ( !Active ) return;
		Fraction = Math.Max( Fraction, _phaseStart + (_phaseEnd - _phaseStart) * Math.Clamp( phaseFraction, 0, 1 ) );
		if ( detail is not null ) Detail = detail;
		_sinceStep = 0;
		Version++;
	}

	public static void End()
	{
		if ( !Active ) return;
		Active = false;
		Diagnostics.RpLog.Info( "loading", $"Loading screen closed after {(float)Since:F1}s" );
		_endAt = null;
		Version++;
	}

	static RealTimeUntil? _endAt;

	/// <summary>Ends by itself after <paramref name="seconds"/> unless something ends it earlier (e.g. the player spawned).</summary>
	public static void EndAfter( float seconds ) { if ( Active ) _endAt = seconds; }

	/// <summary>Our player body is in the world: the screen can go.</summary>
	public static void OnLocalPlayerSpawned() { if ( Active && _endAt is not null ) End(); }

	static RealTimeSince _sinceStep;
	static float _shownFraction;

	/// <summary>
	/// Called every frame by the loading screen. Steps that report nothing for a while (a map loading) still move the
	/// bar: it creeps towards 92% of the phase, so the screen never looks frozen.
	/// </summary>
	public static void Tick()
	{
		if ( !Active ) return;
		if ( _endAt is { } t && t <= 0 ) { End(); return; }
		if ( _sinceStep > 0.75f )
		{
			var target = _phaseStart + (_phaseEnd - _phaseStart) * 0.92f;
			if ( Fraction < target ) Fraction += (target - Fraction) * Math.Min( 1f, Time.Delta * 0.12f );
		}
		if ( Math.Abs( Fraction - _shownFraction ) >= 0.004f ) { _shownFraction = Fraction; Version++; }
	}

	/// <summary>Waits two frames so the loading screen is drawn before blocking work.</summary>
	public static async System.Threading.Tasks.Task Show()
	{
		if ( !Active ) return;
		await GameTask.Yield();
		await GameTask.Yield();
	}
}