---
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)