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 a location for the authenticated user.
• 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.

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. Generation is applied lazily when the resource record is read.