# 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.

`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. Log Camps generate wood. Generation is applied lazily when the resource
record is read.

## Units

Unit training is stored server-side in the `UnitTraining` collection. The first
unit type is `Scout`, which costs 50 gold 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.

## Buildings

Buildings are stored on location records. The first building type is `LogCamp`,
which can be built on controlled Forest territory, takes 60 seconds to build,
and adds 5 wood per minute to the owning player's resource generation after it
finishes. 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`
- `LogCampBuildSeconds`