docs(design): add user story knowledge bundle

2026-08-08 12:31:15 -04:00
parent baed3b4901
commit c76ea5b434
9 changed files with 198 additions and 0 deletions
@@ -0,0 +1,27 @@
+---
+type: User Story
+title: "US-004: Capture periodic player snapshots"
+description: Periodically capture player location and comprehensive Bukkit statistics without monopolizing a server tick.
+status: done
+---
+
+# US-004: Capture periodic player snapshots
+
+As a **server analyst**, I want periodic player location and statistic snapshots so that I can analyze movement and gameplay progression over time.
+
+## Acceptance criteria
+
+- [x] Each configured interval captures every online player's world identity, coordinates, orientation, game mode, and biome.
+- [x] Every Bukkit untyped, block, item, and entity statistic combination accepted by Bukkit is captured, including zero values.
+- [x] Invalid statistic subtype combinations are skipped without stopping the snapshot.
+- [x] Statistic reads are spread across ticks according to a configurable operation budget and run through Bukkit scheduling.
+- [x] A player is not queued for a second statistic capture while an earlier capture remains queued or active.
+- [x] Statistics are partitioned by category and configured JSON size, with shared snapshot metadata and one-based part information.
+- [x] Empty statistic categories still emit an explicit part.
+- [x] Offline players are removed safely from queued or active capture work.
+
+## Related
+
+- [US-001: Configure the event producer](us-001-configure-event-producer.md)
+- [US-002: Produce standard CloudEvents](us-002-produce-standard-cloud-events.md)
+- [Snapshot behavior](../../README.md#location-snapshots)