1// Copyright 2020 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.maps.playablelocations.v3.sample; 18 19import "google/api/field_behavior.proto"; 20import "google/protobuf/field_mask.proto"; 21import "google/type/latlng.proto"; 22 23option csharp_namespace = "Google.Maps.PlayableLocations.V3.Sample"; 24option go_package = "cloud.google.com/go/maps/playablelocations/apiv3/sample/samplepb;samplepb"; 25option java_multiple_files = true; 26option java_outer_classname = "ResourcesProto"; 27option java_package = "com.google.maps.playablelocations.v3.sample"; 28option objc_class_prefix = "GMPL"; 29 30// A geographical point suitable for placing game objects in location-based 31// games. 32message PlayableLocation { 33 // Required. The name of this playable location. 34 string name = 1; 35 36 // Required. 37 // Each location has one of the following identifiers: 38 oneof location_id { 39 // A [place ID] (https://developers.google.com/places/place-id) 40 string place_id = 2; 41 42 // A [plus code] (http://openlocationcode.com) 43 string plus_code = 3; 44 } 45 46 // A collection of [Playable Location Types](/maps/tt/games/types) for this 47 // playable location. The first type in the collection is the primary type. 48 // 49 // Type information might not be available for all playable locations. 50 repeated string types = 4; 51 52 // Required. The latitude and longitude associated with the center of the 53 // playable location. 54 // 55 // By default, the set of playable locations returned from 56 // [SamplePlayableLocations][google.maps.playablelocations.v3.PlayableLocations.SamplePlayableLocations] 57 // use center-point coordinates. 58 google.type.LatLng center_point = 5; 59 60 // The playable location's coordinates, snapped to the sidewalk of the 61 // nearest road, if a nearby road exists. 62 google.type.LatLng snapped_point = 6; 63} 64 65// A set of options that specifies the separation between playable locations. 66message SpacingOptions { 67 // Specifies whether the playable location's geographic coordinates (latitude 68 // and longitude) correspond to its center-point, or to its location snapped 69 // to the sidewalk of the nearest road. 70 enum PointType { 71 // Unspecified point type. Do not use this value. 72 POINT_TYPE_UNSPECIFIED = 0; 73 74 // The geographic coordinates correspond to the center of the location. 75 CENTER_POINT = 1; 76 77 // The geographic coordinates correspond to the location snapped to the 78 // sidewalk of the nearest road (when a nearby road exists). 79 SNAPPED_POINT = 2; 80 } 81 82 // Required. The minimum spacing between any two playable locations, measured 83 // in meters. The minimum value is 30. The maximum value is 1000. 84 // 85 // Inputs will be rounded up to the next 10 meter interval. 86 // 87 // The default value is 200m. 88 // 89 // Set this field to remove tight clusters of playable locations. 90 // 91 // Note: 92 // 93 // The spacing is a greedy algorithm. It optimizes for selecting the highest 94 // ranking locations first, not to maximize the number of locations selected. 95 // Consider the following scenario: 96 // 97 // * Rank: A: 2, B: 1, C: 3. 98 // * Distance: A--200m--B--200m--C 99 // 100 // If spacing=250, it will pick the highest ranked location [B], not [A, C]. 101 // 102 // 103 // Note: 104 // 105 // Spacing works within the game object type itself, as well as the previous 106 // ones. 107 // Suppose three game object types, each with the following spacing: 108 // 109 // * X: 400m, Y: undefined, Z: 200m. 110 // 111 // 1. Add locations for X, within 400m of each other. 112 // 2. Add locations for Y, without any spacing. 113 // 3. Finally, add locations for Z within 200m of each other as well X and Y. 114 // 115 // The distance diagram between those locations end up as: 116 // 117 // * From->To. 118 // * X->X: 400m 119 // * Y->X, Y->Y: unspecified. 120 // * Z->X, Z->Y, Z->Z: 200m. 121 double min_spacing_meters = 1 [(google.api.field_behavior) = REQUIRED]; 122 123 // Specifies whether the minimum spacing constraint applies to the 124 // center-point or to the snapped point of playable locations. The default 125 // value is `CENTER_POINT`. 126 // 127 // If a snapped point is not available for a playable location, its 128 // center-point is used instead. 129 // 130 // Set this to the point type used in your game. 131 PointType point_type = 2; 132} 133 134// Specifies the filters to use when searching for playable locations. 135message Filter { 136 // Specifies the maximum number of playable locations to return. This value 137 // must not be greater than 1000. The default value is 100. 138 // 139 // Only the top-ranking playable locations are returned. 140 int32 max_location_count = 1; 141 142 // A set of options that control the spacing between playable locations. By 143 // default the minimum distance between locations is 200m. 144 SpacingOptions spacing = 2; 145 146 // Restricts the set of playable locations to just the 147 // [types](/maps/tt/games/types) that you want. 148 repeated string included_types = 3; 149} 150 151// Encapsulates a filter criterion for searching for a set of playable 152// locations. 153message Criterion { 154 // Required. An arbitrary, developer-defined identifier of the type of game 155 // object that the playable location is used for. This field allows you to 156 // specify criteria per game object type when searching for playable 157 // locations. 158 // 159 // You should assign a unique `game_object_type` ID across all 160 // `request_criteria` to represent a distinct type of game object. For 161 // example, 1=monster location, 2=powerup location. 162 // 163 // The response contains a map<game_object_type, Response>. 164 int32 game_object_type = 1 [(google.api.field_behavior) = REQUIRED]; 165 166 // Specifies filtering options, and specifies what will be included in the 167 // result set. 168 Filter filter = 2; 169 170 // Specifies which `PlayableLocation` fields are returned. 171 // 172 // `name` (which is used for logging impressions), `center_point` and 173 // `place_id` (or `plus_code`) are always returned. 174 // 175 // The following fields are omitted unless you specify them here: 176 // 177 // * snapped_point 178 // * types 179 // 180 // Note: The more fields you include, the more expensive in terms of data and 181 // associated latency your query will be. 182 google.protobuf.FieldMask fields_to_return = 3; 183} 184 185// Specifies the area to search for playable locations. 186message AreaFilter { 187 // Required. The S2 cell ID of the area you want. This must be between cell 188 // level 11 and 14 (inclusive). 189 // 190 // S2 cells are 64-bit integers that identify areas on the Earth. They are 191 // hierarchical, and can therefore be used for spatial indexing. 192 // 193 // The S2 geometry library is available in a number of languages: 194 // 195 // * [C++](https://github.com/google/s2geometry) 196 // * [Java](https://github.com/google/s2-geometry-library-java) 197 // * [Go](https://github.com/golang/geo) 198 // * [Python](https://github.com/google/s2geometry/tree/master/src/python) 199 fixed64 s2_cell_id = 1 [(google.api.field_behavior) = REQUIRED]; 200} 201 202// A list of PlayableLocation objects that satisfies a single Criterion. 203message PlayableLocationList { 204 // A list of playable locations for this game object type. 205 repeated PlayableLocation locations = 1; 206} 207