Update .gitignore to exclude TypeScript build info and add dist directory. Expand README with project overview, technology stack, prerequisites, and instructions for running and testing the application.

README.md

@@ -1,2 +1,107 @@
-# h-school
-
+# h-school
+
+Base for a multiplayer browser game: an authoritative .NET server simulating the world with an
+ECS, a PixiJS client that renders snapshots, and .NET Aspire tying them together for local runs
+and integration tests.
+
+There is no game here yet — there is a world with a few obstacles, players that can walk around
+it, and every piece of plumbing needed to build a game on top.
+
+## Stack
+
+| Layer | Choice |
+| --- | --- |
+| Server | .NET 10, ASP.NET Core |
+| Simulation | [Arch](https://github.com/genaray/Arch) ECS, fixed 20 Hz tick |
+| Transport | raw WebSocket, custom binary protocol |
+| Client | TypeScript, [PixiJS 8](https://pixijs.com/), Vite |
+| Orchestration | .NET Aspire 13 |
+| Tests | xUnit v3, Vitest, `Aspire.Hosting.Testing` |
+
+## Prerequisites
+
+- [.NET SDK 10](https://dotnet.microsoft.com/download) (`global.json` pins the 10.0.1xx band)
+- [Node.js](https://nodejs.org/) 22.12 or newer
+- Optional: the Aspire CLI (`dotnet tool install -g aspire.cli`) if you prefer `aspire run`
+
+## Run everything
+
+```bash
+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. Open it and use **WASD** or the arrow keys to move — the HUD shows
+connection state, server tick, round-trip time and entity count.
+
+Open the same URL in a second tab to see another player: both are simulated by the one server.
+
+## Run the pieces separately
+
+```bash
+dotnet run --project src/HSchool.Server
+```
+
+```bash
+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
+
+```bash
+dotnet test
+```
+
+- `tests/HSchool.Protocol.Tests` — wire-format round-trips and byte layouts.
+- `tests/HSchool.Simulation.Tests` — ECS behaviour against `GameWorld`, no host involved.
+- `tests/HSchool.AppHost.Tests` — boots the real Aspire graph, connects a WebSocket, plays a few
+  ticks. Runs headless (`--HSchool:Headless=true`), so no Node install is needed.
+
+```bash
+npm --prefix src/HSchool.Client test
+```
+
+Vitest covers the client codec and snapshot interpolation.
+
+## Layout
+
+```
+src/
+  HSchool.Protocol/        binary wire format (shared contract with the client)
+  HSchool.Simulation/      Arch ECS world, components, systems
+  HSchool.Server/          ASP.NET Core host, WebSocket endpoint, game loop
+  HSchool.ServiceDefaults/ Aspire telemetry, health checks, resilience
+  HSchool.AppHost/         Aspire orchestration
+  HSchool.Client/          Vite + TypeScript + PixiJS renderer
+tests/
+docs/
+  architecture.md          how the pieces fit together
+  protocol.md              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 |
+| `WorldWidth` / `WorldHeight` | 1600 × 900 | field size in simulation units |
+| `PlayerSpeed` | 260 | units per second |
+| `PlayerRadius` | 18 | player body radius |
+
+## What is deliberately missing
+
+No authentication, no persistence, no client-side prediction, no delta compression, no rooms or
+matchmaking. Each of these has a natural seam described in
+[`docs/architecture.md`](docs/architecture.md).