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();
}
}