# 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 and Mines generate ore. 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 by deleting that Scout's
training record.

## 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`
- `LogCampBuildSeconds`
- `MineBuildSeconds`
- `BarracksBuildSeconds`