# LocationsApi

Tracks hex locations for the territory map.

## Endpoints

- `GET /api/locations` List visible locations for USER/SUPER, all known locations for SUPER.
- `GET /api/locations?minQ=-7&maxQ=7&minR=-7&maxR=7` List a coordinate range, constrained by visibility for USER.
- `GET /api/locations/{q}/{r}` Fetch one visible location for USER, any known location for SUPER.
- `POST /api/locations/claim` Claim visible unclaimed territory for the authenticated user. Normal players spend one completed Scout.
- `POST /api/locations/build` Build on controlled territory.
- `GET /api/locations/home` Get the authenticated user's home location.
- `POST /api/locations/home` Assign or return the authenticated user's home location.
- `GET /api/locations/visible` Get locations visible to the authenticated user.
- `GET /api/locations/visible?depth=3` Override visibility depth for a request.
- `PUT /api/locations` Upsert location data (SUPER only).
- `GET /api/resources/me` Get the authenticated player's resources.
- `GET /api/units/me` Get completed units and active training for the authenticated player.
- `POST /api/units/train` Spend gold and start training a unit.
- `POST /api/units/move` Move a persisted unit squad to a visible non-rival tile.

`claim` and `put` require the same JWT issued by AuthApi.

When a player gains visibility over previously unseen coordinates, the service
generates and persists those locations before returning them. Generated visible
locations are unowned `Open` records until claimed by a player.

## Resources

Player resource state is stored server-side in the `PlayerResources` collection.
New players start with 100 gold. A player's headquarters generates 10 gold per
minute. The starting town hall stores up to 500 gold, 100 wood, and 100 ore.
Log Camps generate wood and Mines generate ore. Generation is applied lazily
when the resource record is read and clamps at the current storage capacity.

## Units

Unit training is stored server-side in the `UnitTraining` collection. `Scout`
costs 50 gold and takes 60 seconds to train. `Archer` requires a completed
Barracks, costs 100 gold and 100 wood, and takes 60 seconds to train. Finished
training is completed lazily when unit state is read. Claiming an unclaimed
visible location consumes one completed Scout by deleting that Scout's training
record.

Completed Archers are stored as persisted unit instances in the `Units`
collection with their current `q`/`r` location. Archer squads can move to
visible tiles that are unclaimed or controlled by the owning player.

## Buildings

Buildings are stored on location records. `LogCamp` can be built on controlled
Forest territory, takes 60 seconds to build, and adds 5 wood per minute after it
finishes. `Mine` can be built on controlled Ore territory, takes 60 seconds to
build, and adds 5 ore per minute after it finishes. `Barracks` can be built on
any controlled territory, costs 500 gold, 100 wood, and 100 ore, and takes 60
seconds to build. Each location has one building slot; a building under
construction occupies that slot.

Timer settings are stored in the MongoDB `GameSettings` collection and are
seeded on first read:

- `ScoutTrainingSeconds`
- `ArcherTrainingSeconds`
- `LogCampBuildSeconds`
- `MineBuildSeconds`
- `BarracksBuildSeconds`