62 lines
2.9 KiB
Markdown
62 lines
2.9 KiB
Markdown
# 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. 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.
|
|
|
|
## 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`
|