h-school

Base for a school-management game: an authoritative .NET server that owns the saves and their in-game calendars, a TypeScript client that renders the menus, and .NET Aspire tying them together for local runs and integration tests.

What exists today is the shell around a game: a main menu of schools, a creation form, and a school screen with a running game clock. The school itself is still empty.

Stack

Layer	Choice
Server	.NET 10, ASP.NET Core
Simulation	Arch ECS, fixed 20 Hz tick
Transport	REST for the menu, raw WebSocket + binary protocol for the clock
Client	TypeScript, Vite, plain DOM
Orchestration	.NET Aspire 13
Tests	xUnit v3, Vitest, Aspire.Hosting.Testing

Prerequisites

• .NET SDK 10 (global.json pins the 10.0.1xx band)
• Node.js 22.12 or newer
• Optional: the Aspire CLI (dotnet tool install -g aspire.cli) if you prefer aspire run

Run everything

dotnet run --project src/HSchool.AppHost

On Windows run-aspire.cmd does the same and can be double-clicked; it checks that the .NET SDK and Node are on PATH first and passes any arguments through (run-aspire.cmd --launch-profile http).

The Aspire dashboard opens with two resources: server (ASP.NET Core) and client (Vite dev server). Aspire assigns the client a random port on every run, so take its URL from the dashboard rather than guessing.

What you can do

• Main menu — every school as a card with its name and its current in-game date and time, ticking live. Deleting one asks for confirmation first. The footer switches the UI between Russian and English; the choice is remembered in the browser.
• Create a school — type a name or roll a random one, pick a start date (3 April 2012, 06:00 by default). At six schools the create button is disabled and says why.
• Inside a school — the date, time and weekday of the game calendar, play/pause and the ×½ ×1 ×2 ×3 ×4 speed buttons, plus a way back to the menu.

Time runs at 5 game minutes per real second at ×1. Every school runs on its own, whether or not you are inside it — the menu cards keep counting. Only the pause button stops a school, and it stays paused (the card says so) until you press play again.

Schools are written under saves/ on the server. Restarting the process brings them back.

Run the pieces separately

dotnet run --project src/HSchool.Server

npm --prefix src/HSchool.Client run dev

Without Aspire the client falls back to http://localhost:5180 for its /api and /ws proxy, which matches the server's launch profile.

Tests

dotnet test

• tests/HSchool.Protocol.Tests — wire-format round-trips and byte layouts.
• tests/HSchool.Content.Tests — JSONC catalog, inheritance, patches, map connectivity. No host.
• tests/HSchool.Simulation.Tests — the game clock, school load/create, and the school registry, no host involved.
• tests/HSchool.AppHost.Tests — boots the real Aspire graph, drives the menu API and the WebSocket clock. Runs headless (--HSchool:Headless=true), so no Node install is needed.

npm --prefix src/HSchool.Client test

Vitest covers the client codec, the calendar formatting and the RU/EN dictionaries.

Layout

src/
  HSchool.Protocol/        binary wire format (shared contract with the client)
  HSchool.Content/         JSONC defs, patches, map validation
  HSchool.Simulation/      schools, the game clock, the Arch ECS world
  HSchool.Server/          ASP.NET Core host, menu API, WebSocket, workers
  HSchool.Server/mods/     pack folders; `core` is always on
  HSchool.ServiceDefaults/ Aspire telemetry, health checks, resilience
  HSchool.AppHost/         Aspire orchestration
  HSchool.Client/          Vite + TypeScript UI
tests/
docs/
  architecture.md          how the pieces fit together
  protocol.md              the HTTP API and the wire format, byte by byte
AGENTS.md                  working agreements for humans and coding agents

Configuration

Simulation tunables live under the Simulation section of src/HSchool.Server/appsettings.json:

Key	Default	Meaning
TickRate	20	fixed simulation steps per second
MaxSchools	6	how many schools may exist at once
GameMinutesPerRealSecond	5	game minutes per real second at ×1
DefaultStartDate	2012-03-31T06:00:00	prefilled start of a new school
SavesDirectory	saves	per-school JSON files
ModsDirectory	mods	pack folders; core is required
SaveIntervalSeconds	30	rare clock snapshot; not every tick
MinSaveIntervalMilliseconds	1000	shortest gap between saves caused by pause or speed
MonthlyPayrollCap	100000	monthly payroll the player may commit; hires and assignments that would exceed it are rejected
SchoolWeekDays	5	working days from Monday (5 is Mon–Fri; 6 adds Saturday)
MaxDecisionsPerTick	64	presence decisions processed per tick; overflow waits

What is deliberately missing

No authentication, no action execution, and the create dialog does not yet pick mods or edit the map — every new school gets the vanilla core layout. Each of these has a seam described in docs/architecture.md.