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.

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