Refactor project structure and update documentation. Replace PixiJS with plain DOM for UI rendering, enhance README with game features, and revise protocol documentation for HTTP API. Remove unused files and streamline client code for better maintainability.

src/HSchool.Server/Game/GameCommand.cs

@@ -1,20 +1,30 @@
-using HSchool.Protocol;
-
-namespace HSchool.Server.Game;
-
-/// <summary>
-/// Work item handed from a connection thread to the loop thread. The simulation is
-/// single-threaded, so every mutation arrives as one of these.
-/// </summary>
-internal abstract record GameCommand
-{
-    /// <summary>
-    /// Spawns an avatar for the connection. The loop completes <see cref="EntityId"/>
-    /// with the replication id so the handler can send a Welcome frame.
-    /// </summary>
-    internal sealed record Join(uint PlayerId, TaskCompletionSource<uint> EntityId) : GameCommand;
-
-    internal sealed record Leave(uint PlayerId) : GameCommand;
-
-    internal sealed record Input(uint PlayerId, InputButtons Buttons, uint Sequence) : GameCommand;
-}
+namespace HSchool.Server.Game;
+
+/// <summary>
+/// Work item handed from a request or connection thread to the loop thread. Schools are
+/// single-threaded, so every mutation and every read of live state arrives as one of these.
+/// </summary>
+internal abstract record GameCommand
+{
+    internal sealed record CreateSchool(
+        string Name,
+        DateTime StartDate,
+        TaskCompletionSource<SchoolCreationOutcome> Result) : GameCommand;
+
+    internal sealed record DeleteSchool(int SchoolId, TaskCompletionSource<bool> Result) : GameCommand;
+
+    internal sealed record SuggestName(TaskCompletionSource<string> Result) : GameCommand;
+
+    /// <summary>A connection starts watching a school; its calendar starts running.</summary>
+    internal sealed record OpenSchool(uint PlayerId, int SchoolId) : GameCommand;
+
+    /// <summary>
+    /// Stops watching. The school id travels with the command because the connection may already
+    /// be gone from the registry by the time the loop thread gets here.
+    /// </summary>
+    internal sealed record CloseSchool(uint PlayerId, int SchoolId) : GameCommand;
+
+    internal sealed record SetRunning(uint PlayerId, bool Running) : GameCommand;
+
+    internal sealed record SetSpeed(uint PlayerId, byte SpeedIndex) : GameCommand;
+}

src/HSchool.Server/Game/GameLoopService.cs

@@ -1,153 +1,287 @@
-using System.Diagnostics;
-using HSchool.Protocol;
-using HSchool.Server.Net;
-using HSchool.Simulation;
-using Microsoft.Extensions.Options;
-
-namespace HSchool.Server.Game;
-
-/// <summary>
-/// Owns the authoritative <see cref="GameWorld"/> and drives it at a fixed rate:
-/// drain commands, step the simulation, broadcast a full snapshot.
-/// The world is touched from this thread only.
-/// </summary>
-internal sealed class GameLoopService(
-    IOptions<SimulationOptions> options,
-    GameCommandQueue commands,
-    ClientRegistry clients,
-    GameMetrics metrics,
-    ILogger<GameLoopService> logger) : BackgroundService
-{
-    /// <summary>Upper bound on steps simulated in one wake-up; the rest of the backlog is dropped.</summary>
-    private const int MaxCatchUpSteps = 5;
-
-    private readonly SimulationOptions _options = options.Value;
-    private readonly List<EntitySnapshot> _snapshotBuffer = [];
-    private readonly GameWorld _world = new(options.Value);
-
-    private uint _currentTick;
-    private int _playerCount;
-
-    public uint CurrentTick => Volatile.Read(ref _currentTick);
-
-    public int PlayerCount => Volatile.Read(ref _playerCount);
-
-    public SimulationOptions Options => _options;
-
-    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
-    {
-        logger.LogInformation(
-            "Game loop starting at {TickRate} Hz on a {Width}x{Height} field.",
-            _options.TickRate,
-            _options.WorldWidth,
-            _options.WorldHeight);
-
-        using var timer = new PeriodicTimer(_options.TickInterval);
-        var fixedDelta = _options.FixedDeltaTime;
-        var lastTimestamp = Stopwatch.GetTimestamp();
-        var accumulator = 0d;
-
-        try
-        {
-            while (await timer.WaitForNextTickAsync(stoppingToken).ConfigureAwait(false))
-            {
-                var now = Stopwatch.GetTimestamp();
-                accumulator += Stopwatch.GetElapsedTime(lastTimestamp, now).TotalSeconds;
-                lastTimestamp = now;
-
-                DrainCommands();
-
-                var steps = 0;
-                while (accumulator >= fixedDelta && steps < MaxCatchUpSteps)
-                {
-                    var stepStarted = Stopwatch.GetTimestamp();
-                    _world.Tick();
-                    metrics.RecordTick(Stopwatch.GetElapsedTime(stepStarted, Stopwatch.GetTimestamp()).TotalMilliseconds);
-
-                    accumulator -= fixedDelta;
-                    steps++;
-                }
-
-                if (steps == MaxCatchUpSteps && accumulator >= fixedDelta)
-                {
-                    logger.LogWarning("Game loop is behind by {Backlog:F0} ms; dropping the backlog.", accumulator * 1000);
-                    accumulator = 0d;
-                }
-
-                if (steps > 0)
-                {
-                    Volatile.Write(ref _currentTick, _world.CurrentTick);
-                    BroadcastSnapshot();
-                }
-            }
-        }
-        catch (OperationCanceledException)
-        {
-            // Normal shutdown.
-        }
-        finally
-        {
-            _world.Dispose();
-            logger.LogInformation("Game loop stopped at tick {Tick}.", _world.CurrentTick);
-        }
-    }
-
-    private void DrainCommands()
-    {
-        while (commands.TryDequeue(out var command))
-        {
-            switch (command)
-            {
-                case GameCommand.Join join:
-                    HandleJoin(join);
-                    break;
-
-                case GameCommand.Leave leave:
-                    _world.DespawnPlayer(leave.PlayerId);
-                    Volatile.Write(ref _playerCount, _world.PlayerCount);
-                    metrics.PlayerLeft();
-                    logger.LogInformation("Player {PlayerId} left; {PlayerCount} remaining.", leave.PlayerId, _world.PlayerCount);
-                    break;
-
-                case GameCommand.Input input:
-                    _world.ApplyInput(input.PlayerId, input.Buttons, input.Sequence);
-                    break;
-            }
-        }
-    }
-
-    private void HandleJoin(GameCommand.Join join)
-    {
-        try
-        {
-            var entityId = _world.SpawnPlayer(join.PlayerId);
-            Volatile.Write(ref _playerCount, _world.PlayerCount);
-            metrics.PlayerJoined();
-            join.EntityId.TrySetResult(entityId);
-            logger.LogInformation(
-                "Player {PlayerId} joined as entity {EntityId}; {PlayerCount} connected.",
-                join.PlayerId,
-                entityId,
-                _world.PlayerCount);
-        }
-        catch (Exception ex)
-        {
-            join.EntityId.TrySetException(ex);
-        }
-    }
-
-    private void BroadcastSnapshot()
-    {
-        _world.CaptureSnapshot(_snapshotBuffer);
-
-        // One immutable buffer is shared by every recipient, so nothing has to be copied per client.
-        var frame = new byte[ProtocolCodec.SnapshotSize(_snapshotBuffer.Count)];
-        var written = ProtocolCodec.WriteSnapshot(frame, _world.CurrentTick, System.Runtime.InteropServices.CollectionsMarshal.AsSpan(_snapshotBuffer));
-
-        var recipients = clients.Broadcast(frame.AsMemory(0, written));
-        if (recipients > 0)
-        {
-            metrics.SnapshotSent(written, recipients);
-        }
-    }
-}
+using System.Diagnostics;
+using HSchool.Protocol;
+using HSchool.Server.Net;
+using HSchool.Simulation;
+using Microsoft.Extensions.Options;
+
+namespace HSchool.Server.Game;
+
+/// <summary>
+/// Owns every <see cref="School"/> and drives them at a fixed rate: drain commands, advance the
+/// running calendars, push a clock frame to each connection that has a school open.
+/// Schools are touched from this thread only.
+/// </summary>
+internal sealed class GameLoopService(
+    IOptions<SimulationOptions> options,
+    GameCommandQueue commands,
+    ClientRegistry clients,
+    GameMetrics metrics,
+    ILogger<GameLoopService> logger) : BackgroundService
+{
+    /// <summary>Upper bound on steps simulated in one wake-up; the rest of the backlog is dropped.</summary>
+    private const int MaxCatchUpSteps = 5;
+
+    private readonly SimulationOptions _options = options.Value;
+    private readonly SchoolRegistry _schools = new(options.Value);
+
+    private uint _currentTick;
+    private SchoolsState _publishedState = new(options.Value.MaxSchools, []);
+
+    public uint CurrentTick => Volatile.Read(ref _currentTick);
+
+    public SimulationOptions Options => _options;
+
+    /// <summary>
+    /// Last state published by the loop thread. Menu requests read this instead of blocking on a
+    /// command; it is at most one tick (50 ms) behind.
+    /// </summary>
+    public SchoolsState SchoolsState => Volatile.Read(ref _publishedState);
+
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        logger.LogInformation(
+            "Game loop starting at {TickRate} Hz, up to {MaxSchools} schools, {GameMinutes} game minutes per second.",
+            _options.TickRate,
+            _options.MaxSchools,
+            _options.GameMinutesPerRealSecond);
+
+        using var timer = new PeriodicTimer(_options.TickInterval);
+        var fixedDelta = _options.FixedDeltaTime;
+        var lastTimestamp = Stopwatch.GetTimestamp();
+        var accumulator = 0d;
+
+        try
+        {
+            while (await timer.WaitForNextTickAsync(stoppingToken).ConfigureAwait(false))
+            {
+                var now = Stopwatch.GetTimestamp();
+                accumulator += Stopwatch.GetElapsedTime(lastTimestamp, now).TotalSeconds;
+                lastTimestamp = now;
+
+                DrainCommands();
+
+                var steps = 0;
+                while (accumulator >= fixedDelta && steps < MaxCatchUpSteps)
+                {
+                    var stepStarted = Stopwatch.GetTimestamp();
+                    _schools.Tick();
+                    Volatile.Write(ref _currentTick, _currentTick + 1);
+                    metrics.RecordTick(Stopwatch.GetElapsedTime(stepStarted, Stopwatch.GetTimestamp()).TotalMilliseconds);
+
+                    accumulator -= fixedDelta;
+                    steps++;
+                }
+
+                if (steps == MaxCatchUpSteps && accumulator >= fixedDelta)
+                {
+                    logger.LogWarning("Game loop is behind by {Backlog:F0} ms; dropping the backlog.", accumulator * 1000);
+                    accumulator = 0d;
+                }
+
+                if (steps > 0)
+                {
+                    PublishState();
+                    BroadcastClocks();
+                }
+            }
+        }
+        catch (OperationCanceledException)
+        {
+            // Normal shutdown.
+        }
+        finally
+        {
+            _schools.Dispose();
+            logger.LogInformation("Game loop stopped at tick {Tick}.", _currentTick);
+        }
+    }
+
+    private void DrainCommands()
+    {
+        while (commands.TryDequeue(out var command))
+        {
+            switch (command)
+            {
+                case GameCommand.CreateSchool create:
+                    HandleCreate(create);
+                    break;
+
+                case GameCommand.DeleteSchool delete:
+                    HandleDelete(delete);
+                    break;
+
+                case GameCommand.SuggestName suggest:
+                    Complete(suggest.Result, _schools.SuggestName);
+                    break;
+
+                case GameCommand.OpenSchool open:
+                    HandleOpen(open);
+                    break;
+
+                case GameCommand.CloseSchool close:
+                    StopWatching(close.PlayerId, close.SchoolId);
+                    break;
+
+                case GameCommand.SetRunning setRunning:
+                    WithOpenSchool(setRunning.PlayerId, school => school.Clock.IsRunning = setRunning.Running);
+                    break;
+
+                case GameCommand.SetSpeed setSpeed:
+                    WithOpenSchool(setSpeed.PlayerId, school => school.Clock.SpeedIndex = setSpeed.SpeedIndex);
+                    break;
+            }
+        }
+    }
+
+    private void HandleCreate(GameCommand.CreateSchool command)
+    {
+        Complete(command.Result, () =>
+        {
+            var result = _schools.Create(command.Name, command.StartDate);
+            if (!result.Succeeded)
+            {
+                return new SchoolCreationOutcome(null, result.Error);
+            }
+
+            logger.LogInformation("School {SchoolId} \"{Name}\" created.", result.School!.Id, result.School.Name);
+            PublishState();
+
+            return new SchoolCreationOutcome(Capture(result.School), SchoolCreationError.None);
+        });
+    }
+
+    private void HandleDelete(GameCommand.DeleteSchool command)
+    {
+        Complete(command.Result, () =>
+        {
+            var deleted = _schools.Delete(command.SchoolId);
+            if (!deleted)
+            {
+                return false;
+            }
+
+            // Anyone watching it now stares at a school that no longer exists.
+            foreach (var client in clients.All)
+            {
+                if (client.OpenSchoolId == command.SchoolId)
+                {
+                    client.OpenSchoolId = null;
+                    SendSchoolGone(client, command.SchoolId);
+                }
+            }
+
+            logger.LogInformation("School {SchoolId} deleted.", command.SchoolId);
+            PublishState();
+
+            return true;
+        });
+    }
+
+    private void HandleOpen(GameCommand.OpenSchool command)
+    {
+        var client = clients.Find(command.PlayerId);
+        if (client is null)
+        {
+            return;
+        }
+
+        var school = _schools.Find(command.SchoolId);
+        if (school is null)
+        {
+            SendSchoolGone(client, command.SchoolId);
+            return;
+        }
+
+        client.OpenSchoolId = school.Id;
+
+        logger.LogInformation("Client {PlayerId} opened school {SchoolId}.", command.PlayerId, school.Id);
+    }
+
+    /// <summary>
+    /// The connection stops receiving clock frames for that school. The calendar keeps running —
+    /// schools live whether or not somebody is looking at them.
+    /// </summary>
+    private void StopWatching(uint playerId, int schoolId)
+    {
+        var client = clients.Find(playerId);
+        if (client?.OpenSchoolId == schoolId)
+        {
+            client.OpenSchoolId = null;
+        }
+    }
+
+    /// <summary>Applies a change to the school a connection has open, if it still has one.</summary>
+    private void WithOpenSchool(uint playerId, Action<School> change)
+    {
+        var client = clients.Find(playerId);
+        if (client?.OpenSchoolId is not { } schoolId)
+        {
+            return;
+        }
+
+        var school = _schools.Find(schoolId);
+        if (school is not null)
+        {
+            change(school);
+        }
+    }
+
+    private void BroadcastClocks()
+    {
+        foreach (var client in clients.All)
+        {
+            if (!client.IsReady || client.OpenSchoolId is not { } schoolId)
+            {
+                continue;
+            }
+
+            var school = _schools.Find(schoolId);
+            if (school is null)
+            {
+                continue;
+            }
+
+            var frame = new byte[ProtocolCodec.MaxFrameSize];
+            var length = ProtocolCodec.WriteClock(frame, new ServerClockMessage(
+                school.Id,
+                new DateTimeOffset(school.Clock.Time).ToUnixTimeMilliseconds(),
+                school.Clock.IsRunning,
+                (byte)school.Clock.SpeedIndex));
+
+            client.TrySend(frame.AsMemory(0, length));
+        }
+    }
+
+    private void SendSchoolGone(GameClient client, int schoolId)
+    {
+        var frame = new byte[ProtocolCodec.MaxFrameSize];
+        var length = ProtocolCodec.WriteSchoolGone(frame, new ServerSchoolGoneMessage(schoolId));
+        client.TrySend(frame.AsMemory(0, length));
+    }
+
+    private void PublishState()
+    {
+        var snapshot = new SchoolsState(
+            _schools.MaxSchools,
+            _schools.Schools.Select(Capture).ToArray());
+
+        Volatile.Write(ref _publishedState, snapshot);
+        metrics.SchoolsChanged(snapshot.Schools.Count);
+    }
+
+    private static SchoolState Capture(School school) =>
+        new(school.Id, school.Name, school.Clock.Time, school.Clock.IsRunning, (byte)school.Clock.SpeedIndex);
+
+    /// <summary>Runs work for a waiting request thread without letting an exception kill the loop.</summary>
+    private static void Complete<T>(TaskCompletionSource<T> completion, Func<T> work)
+    {
+        try
+        {
+            completion.TrySetResult(work());
+        }
+        catch (Exception ex)
+        {
+            completion.TrySetException(ex);
+        }
+    }
+}

src/HSchool.Server/Game/GameMetrics.cs

@@ -10,16 +10,17 @@ internal sealed class GameMetrics : IDisposable
     private readonly Meter _meter;
     private readonly Counter<long> _ticks;
     private readonly Histogram<double> _tickDuration;
-    private readonly UpDownCounter<long> _connectedPlayers;
-    private readonly Counter<long> _snapshotBytes;
+    private readonly UpDownCounter<long> _connections;
+
+    private int _schools;
 
     public GameMetrics(IMeterFactory meterFactory)
     {
         _meter = meterFactory.Create(MeterName);
         _ticks = _meter.CreateCounter<long>("hschool.game.ticks", "{tick}", "Simulation steps executed.");
         _tickDuration = _meter.CreateHistogram<double>("hschool.game.tick.duration", "ms", "Wall time of one simulation step.");
-        _connectedPlayers = _meter.CreateUpDownCounter<long>("hschool.game.players", "{player}", "Currently connected players.");
-        _snapshotBytes = _meter.CreateCounter<long>("hschool.game.snapshot.bytes", "By", "Snapshot bytes pushed to clients.");
+        _connections = _meter.CreateUpDownCounter<long>("hschool.game.connections", "{connection}", "Open WebSocket connections.");
+        _meter.CreateObservableGauge("hschool.game.schools", () => Volatile.Read(ref _schools), "{school}", "Schools that currently exist.");
     }
 
     public void RecordTick(double durationMs)
@@ -28,11 +29,11 @@ internal sealed class GameMetrics : IDisposable
         _tickDuration.Record(durationMs);
     }
 
-    public void PlayerJoined() => _connectedPlayers.Add(1);
+    public void ClientConnected() => _connections.Add(1);
 
-    public void PlayerLeft() => _connectedPlayers.Add(-1);
+    public void ClientDisconnected() => _connections.Add(-1);
 
-    public void SnapshotSent(int bytes, int recipients) => _snapshotBytes.Add((long)bytes * recipients);
+    public void SchoolsChanged(int count) => Volatile.Write(ref _schools, count);
 
     public void Dispose() => _meter.Dispose();
 }

src/HSchool.Server/Game/SchoolCreationOutcome.cs

@@ -0,0 +1,9 @@
+using HSchool.Simulation;
+
+namespace HSchool.Server.Game;
+
+/// <summary>What the loop thread reports back after trying to create a school.</summary>
+internal readonly record struct SchoolCreationOutcome(SchoolState? School, SchoolCreationError Error)
+{
+    public bool Succeeded => Error == SchoolCreationError.None && School is not null;
+}

src/HSchool.Server/Game/SchoolState.cs

@@ -0,0 +1,10 @@
+namespace HSchool.Server.Game;
+
+/// <summary>
+/// Immutable copy of a school, safe to hand to request threads. The live <c>School</c> object
+/// never leaves the loop thread.
+/// </summary>
+internal sealed record SchoolState(int Id, string Name, DateTime GameTime, bool Running, byte SpeedIndex);
+
+/// <summary>Everything the main menu needs in one read.</summary>
+internal sealed record SchoolsState(int MaxSchools, IReadOnlyList<SchoolState> Schools);