astra

README.md

@@ -9,6 +9,35 @@ A 2-dimensional multiplayer game utilising ray tracing.
 
 For optimised 2D ray tracing, [SDF-2D](https://github.com/schmelczerandras/sdf-2d) is used.
 
+## Development
+
+Run `npm install && npm run init` once, then `npm run dev`. Run `npm test` for
+regressions, `npm run lint:check` for formatting and lint, and `npm run build` for
+all production bundles. Tests rebuild the shared library before running.
+
+## Movement and networking
+
+The server owns physics and combat. It simulates at 200 Hz, keeps each player's
+latest held movement direction, and sends snapshots at 25 Hz. Clients send input
+changes immediately on their next frame and send idle heartbeats at 30 Hz.
+
+The local player replays input from the latest authoritative pose using the same
+physics as the server. The acknowledgement includes movement state, remaining leap
+cooldown, and the age of the acknowledged input, so the client can align replay
+without synchronizing wall clocks. Nearby planets are included even when offscreen
+because their gravity affects prediction. Replay stops after 400 ms without a fresh
+anchor; only reconciliation corrections are eased over 80 ms. The camera follows
+the displayed player directly.
+
+Other objects interpolate snapshots on a server timeline delayed by 100 ms, with
+at most 60 ms of extrapolation. Creation and deletion use that same timeline.
+Remote effects use that timeline too; feedback for the local player is immediate.
+End-of-round slow motion comes from server snapshots and disables local prediction;
+outgoing velocity and projectile fade rates are expressed per wall-clock second.
+When a connection backs up, regenerable state can be skipped; lifecycle messages
+keep their timestamps. The frontend bundles one `gl-matrix` instance so prediction
+and server physics both use JavaScript's full numeric precision.
+
 ## Deployment
 
 CI/CD runs on Forgejo Actions (`.forgejo/workflows/deploy.yml`). On a push to