territory-autobattler/microservices/LocationsApi/README.md

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