211 lines
14 KiB
Markdown
211 lines
14 KiB
Markdown
# Working agreements
|
||
|
||
Read this before changing anything. It is written for coding agents, and it is just as valid for
|
||
humans. [`docs/architecture.md`](docs/architecture.md) explains *why* the pieces are shaped this
|
||
way; this file is *how to work in them*.
|
||
|
||
## Orientation
|
||
|
||
| I want to change… | Go to |
|
||
| --- | --- |
|
||
| schools, the game clock, game rules | `src/HSchool.Simulation` |
|
||
| defs, JSONC catalog, map validation | `src/HSchool.Content` |
|
||
| skills, traits, body, needs, countries | `src/HSchool.Content` |
|
||
| people generation, families, roster records, yearly intake | `src/HSchool.People` |
|
||
| timetable planning | `src/HSchool.Schedule` |
|
||
| routes, day plans, who comes today | `src/HSchool.Ai` |
|
||
| people in a school's World, need decay, walking | `src/HSchool.Simulation` |
|
||
| the menu API (list, create, delete, mods, catalog) and the people list/card | `src/HSchool.Server/Api` **and** `docs/protocol.md` |
|
||
| what the socket carries | `src/HSchool.Protocol` **and** `src/HSchool.Client/src/net/protocol.ts` **and** `docs/protocol.md` |
|
||
| connection handling, workers, saves | `src/HSchool.Server` |
|
||
| what runs locally | `src/HSchool.AppHost/AppHost.cs` |
|
||
| screens, dialogs, formatting, UI language | `src/HSchool.Client/src` |
|
||
| clothing, inventory, climate, dress codes | [`docs/design/inventory.md`](docs/design/inventory.md) — slice 7, phases 29–37; country, wardrobes and weather are live |
|
||
| login, who owns a school, watching others | [`docs/design/session.md`](docs/design/session.md) — slice 8, phases 38–39 |
|
||
| clock speed buttons and high-speed stride | `src/HSchool.Simulation/ClockSpeed.cs` **and** [`docs/design/session.md`](docs/design/session.md) — phase 40 |
|
||
| talks, opinions, fights, romance pack | [`docs/design/social.md`](docs/design/social.md) — slice 9, phases 41–47 |
|
||
| lesson consequences (teacher present, skill, warmth, textbook, weather commute) | [`docs/design/off-queue.md`](docs/design/off-queue.md) — phases 48, 50–53 |
|
||
| layer tests, client tsc-in-test, worker/card splits, dump nodes | [`docs/design/craft.md`](docs/design/craft.md) — slice 10, phases 56–59 |
|
||
| a bug in already-shipped behaviour | `.claude/skills/bug-work` — document in `docs/bugs/`, discuss only if the fix has a fork, then patch |
|
||
| a task that is not in any slice | `.claude/skills/side-work` — discuss, document in «Вне очереди», then implement |
|
||
| a new named slice of the game | `.claude/skills/slice-work` — discuss, write design and phases, then `/phase-orch` |
|
||
|
||
## Commands
|
||
|
||
```bash
|
||
dotnet build h-school.sln
|
||
```
|
||
|
||
```bash
|
||
dotnet test tests/HSchool.People.Tests --filter FullyQualifiedName~YearlyIntake
|
||
```
|
||
|
||
```bash
|
||
npm --prefix src/HSchool.Client test -- src/ui/peoplePanel.test.ts
|
||
```
|
||
|
||
Solution-wide `dotnet test` and a full client `npm test` are CI, or when the user asked. Agents
|
||
scope the run — Testing policy.
|
||
|
||
```bash
|
||
npm --prefix src/HSchool.Client run build
|
||
```
|
||
|
||
```bash
|
||
dotnet run --project src/HSchool.AppHost
|
||
```
|
||
|
||
`run-aspire.ps1` is the Windows entry point (`run-aspire.cmd` just forwards to it);
|
||
`run-aspire.sh` is the same on Ubuntu. They skip MSBuild when AppHost and Server dlls are
|
||
newer than C# / csproj / props. Pass `--rebuild` to force a build. When `tailscale` is on
|
||
PATH and connected they run `tailscale serve --bg 5173` and print the HTTPS client URL;
|
||
otherwise they warn and continue locally only. Pass `--no-tailscale` to skip Serve. Keep
|
||
`tools/apphost-uptodate.ps1`, `LaunchBuildStamp`, and `needs_build` in `run-aspire.sh` in
|
||
sync if the AppHost path ever moves.
|
||
|
||
`dotnet run --project src/HSchool.AppHost` still compiles every time — that is for a dirty tree,
|
||
not a fast relaunch. It starts the server *and* the Vite dev server and opens the Aspire
|
||
dashboard. The Vite client listens on port **5173** (pinned in AppHost for Tailscale Serve).
|
||
|
||
Do not start a dev server with a bare `npm run dev` when you meant to run the whole app — the
|
||
client only finds the backend through the Aspire-injected `SERVER_HTTP` environment variable, or
|
||
the `localhost:5180` fallback that matches the server's own launch profile.
|
||
|
||
## Invariants
|
||
|
||
These are the rules that keep the base coherent. Breaking one is a design decision, not a detail —
|
||
say so explicitly in the change description.
|
||
|
||
1. **The server is authoritative.** The client sends intents and draws what it is told. No game
|
||
logic in `src/HSchool.Client` — not even a local clock that ticks between frames.
|
||
2. **The protocol lives in three places at once.** `ProtocolCodec.cs`, `protocol.ts` and
|
||
`docs/protocol.md` change in the same commit. A layout change bumps
|
||
`ProtocolConstants.Version` / `PROTOCOL_VERSION`. Tests on both sides assert byte offsets —
|
||
if one of them has to change, so do the other two.
|
||
3. **Only a school's worker thread touches that `School` or its `World`.** The supervisor
|
||
owns the mailbox table and never calls into a world. Create/delete/name suggestions go
|
||
through `GameCommandQueue`; open/close/running/speed go to that school's mailbox; menu
|
||
reads use the snapshots workers publish; everything outbound goes through the per-client
|
||
outbox. No locks around a school, no `Task.Run` into it.
|
||
4. **The simulation knows nothing about the network.** `HSchool.Simulation` must not reference
|
||
ASP.NET Core, sockets or logging infrastructure. It stays testable without a host.
|
||
5. **Fixed timestep.** The clock advances by `SimulationOptions.FixedDeltaTime`, never by
|
||
wall-clock deltas and never from `DateTime.Now`. Same tick count, same date.
|
||
6. **Everything from the wire is untrusted.** Validate lengths and ranges before anything reaches
|
||
the simulation — names, dates and speed indexes all arrive from a browser.
|
||
7. **One intent per message.** A frame that also resends a neighbouring field overwrites it with a
|
||
stale client copy; that is why running and speed are separate messages.
|
||
|
||
## Conventions
|
||
|
||
**C#**
|
||
|
||
- File-scoped namespaces, `var` where the type is obvious, primary constructors for services.
|
||
- Private fields are `_camelCase`; `.editorconfig` enforces it.
|
||
- Nullable is on everywhere. Don't add `!` to silence it; fix the flow.
|
||
- Internal by default in `HSchool.Server`; public only where another project consumes it.
|
||
- New tunables go on `SimulationOptions` with a default, not as a constant buried in a class.
|
||
|
||
**TypeScript**
|
||
|
||
- `strict` is on, no `any`, no non-null `!` assertions.
|
||
- Relative imports carry the `.ts` extension (bundler resolution is configured for it).
|
||
- Modules stay thin: `net/` speaks to the server, `ui/` renders, `format/` formats, `i18n/`
|
||
holds the RU/EN dictionaries, `main.ts` wires them together.
|
||
- No framework, plain DOM. `ui/dom.ts` is the whole helper budget.
|
||
- UI strings go through `t(...)` in `i18n/strings.ts`, never inline. Game dates go through
|
||
`format/gameTime.ts`, which follows the active locale.
|
||
|
||
**Both**
|
||
|
||
- Comments explain *why*, not *what*. Assume the reader can read code.
|
||
- Match the surrounding style rather than introducing a new one.
|
||
|
||
## Testing policy
|
||
|
||
**What to run.** One project from the list below, filtered to the new or changed class while
|
||
iterating. Client Vitest only if `src/HSchool.Client` changed. `HSchool.AppHost.Tests` only if
|
||
the change is HTTP, WebSocket, or host wiring — it boots a server. Do not `dotnet test` the
|
||
solution, do not run client and .NET together "to be sure", do not re-run after a merge that
|
||
only resolved a status line. Solution-wide is CI.
|
||
|
||
- Simulation changes need a `GameClock` or `SchoolRegistry` test. They are fast and need no host.
|
||
Putting a roster into `World` and ticking needs belongs there too.
|
||
- People generation belongs in `tests/HSchool.People.Tests`. Same seed, map, country and
|
||
native language must produce the same roster; the suite does not boot a host.
|
||
- Timetable planning belongs in `tests/HSchool.Schedule.Tests`. Same staff, map and locks must
|
||
produce the same table; the suite does not boot a host.
|
||
- Walking and day plans belong in `tests/HSchool.Ai.Tests`. Same seed and map must produce the
|
||
same route and commute; the suite does not boot a host, and it does not reference Arch.
|
||
- Catalog, inheritance, patches and map validation belong in `tests/HSchool.Content.Tests`.
|
||
Feed the loader documents, not disk paths.
|
||
- Protocol changes need a round-trip test **and** a byte-layout assertion on both sides.
|
||
- Server wiring, endpoints and the WebSocket belong in `tests/HSchool.AppHost.Tests`. That suite
|
||
shares one AppHost across all tests (`AppHostFixture`) — keep it that way, booting per test costs
|
||
about ten seconds each.
|
||
- Those tests also share one server, so schools survive between them (and now on disk too):
|
||
start each test by clearing the list (`SchoolApiTests.ResetAsync`) instead of assuming it
|
||
is empty. Reset deletes through the API, which deletes the save files. Headless AppHost
|
||
sets `HSchool:AllowSaveReload` so tests can `POST /api/dev/reload-schools` without killing
|
||
the shared fixture.
|
||
- Launch-script up-to-date checks belong in `tests/HSchool.AppHost.Tests` and must not use
|
||
`AppHostFixture`. Keep `LaunchBuildStamp` and `tools/apphost-uptodate.ps1` in sync.
|
||
- Screen logic is covered in Vitest under happy-dom (`ui/*.test.ts`): people filters and the
|
||
pager, the create dialog (core stays on, map reset, submit busy), planner rejection text, and
|
||
the payroll-cap message. Layout and styles are still verified by running the app. Dictionaries
|
||
and date formatting stay in `i18n/strings.test.ts` and `format/gameTime.test.ts`.
|
||
|
||
## Dependencies
|
||
|
||
- NuGet versions are centrally managed in `Directory.Packages.props`. Add the version there and a
|
||
bare `<PackageReference Include="..." />` in the project.
|
||
- Transitive pinning is on, so a downgrade warning means you bump the central version rather than
|
||
adding a per-project override.
|
||
- Keep the dependency count low. Arch, Aspire and the test runners are the whole budget.
|
||
|
||
## Things that will bite you
|
||
|
||
- **`<dialog>`'s `close` event is not delivered by every engine** (Chromium 148 fires only
|
||
`toggle`). `ui/modal.ts` resolves its promise explicitly on every exit for that reason — never go
|
||
back to awaiting the event, or a dialog will silently freeze the screen that awaited it.
|
||
- **A modal `<dialog>` is absolutely positioned with `inset: 0`,** so `height: auto` stretches it
|
||
to its `max-height` instead of shrink-wrapping. `.dialog--screen` uses `height: fit-content` for
|
||
that reason — the map editor sized itself to 800px around a two-room school before it did.
|
||
- **Game dates are UTC on the wire and UTC when formatted.** A `DateTime` bound from configuration
|
||
arrives as `Kind=Unspecified`, serializes without a `Z`, and the browser then reads it in its own
|
||
time zone — `SimulationOptions.DefaultStartDate` forces the kind for exactly that reason.
|
||
- `PeriodicTimer` does not catch up on its own. The accumulator in each `SchoolWorker` does,
|
||
capped at 5 steps — do not "simplify" it away.
|
||
- Every school runs whether or not a connection is watching it, so anything you hang off the tick
|
||
runs six times over once six schools exist. `OpenSchool` only subscribes to clock frames.
|
||
- The menu polls `GET /api/schools` once a second and patches its cards in place. Rebuilding the
|
||
list on every refresh would drop focus and swallow clicks.
|
||
- **An abandoned `WaitToReadAsync` stays queued on its channel.** `GameClient.RunSendLoopAsync`
|
||
keeps its two wait tasks across iterations for that reason; recreating both on every idle pass
|
||
leaked the loser of `Task.WhenAny` once per clock frame.
|
||
- **A map snapshot is not bounded by `MaxMessageSize`.** That constant limits what the server
|
||
reads. Outbound snapshots are sized with `ProtocolCodec.MapSnapshotSize`, because a school the
|
||
player enlarged in the create editor passes 8 KiB at roughly sixty furnished rooms.
|
||
- **A worker that dies must tell the supervisor** (`GameCommand.WorkerFailed`). It owns the table,
|
||
so a school that removed itself would break invariant 3 — and a school that removes nothing
|
||
leaves a card in the menu whose clock never moves again.
|
||
- The client outbox drops the oldest frame under pressure. That is correct for clock frames and
|
||
wrong for anything that must arrive exactly once — such a message would need its own path.
|
||
- `erasableSyntaxOnly` is off in `tsconfig.app.json` on purpose: constructor parameter properties
|
||
are used throughout.
|
||
- **A large one-shot `Tick(week)` jumps the clock, then applies all those minutes at the new
|
||
time.** Presence equality tests must loop `FixedDeltaTime` or one game minute. `string.GetHashCode`
|
||
is randomized — commute slack goes through `Seed.Mix`, never that.
|
||
- **The school seed used to be its id.** A test that needs a specific family shape is green on
|
||
one machine and red on a clean clone. Assert a property, not the first pupil of school 1.
|
||
- **Host tests share one server and one save folder.** Start each test by clearing the list
|
||
through the API (`SchoolApiTests.ResetAsync`).
|
||
- **A paused school still emits presence frames.** The worker loop ticks the mailbox even when
|
||
the clock does not advance, so occupancy (often empty) and lesson labels from the timetable
|
||
keep going out. Opening sends one extra snapshot. A test that waits for *people* on pause
|
||
will hang; a test that waits for a lesson label will not.
|
||
- **`dotnet run` on the AppHost always evaluates MSBuild**, even when nothing changed.
|
||
`run-aspire.ps1` / `run-aspire.sh` skip that with `--no-build` when AppHost and Server dlls
|
||
are newer than C# / csproj / props. `--rebuild` forces a build. Bare
|
||
`dotnet run --project src/HSchool.AppHost` still compiles.
|