Update readme.md
[openttd-joker.git] / src / script / api / script_station.hpp
blobb1d3b8093b08512e30dddc9d42423c4d8a80d2b7
1 /* $Id: script_station.hpp 26396 2014-03-10 22:18:53Z zuu $ */
3 /*
4 * This file is part of OpenTTD.
5 * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
6 * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
7 * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
8 */
10 /** @file script_station.hpp Everything to query and build stations. */
12 #ifndef SCRIPT_STATION_HPP
13 #define SCRIPT_STATION_HPP
15 #include "script_road.hpp"
16 #include "script_basestation.hpp"
17 #include "../../station_type.h"
19 /**
20 * Class that handles all station related functions.
21 * @api ai game
23 class ScriptStation : public ScriptBaseStation {
24 public:
25 /**
26 * All station related error messages.
28 enum ErrorMessages {
29 /** Base for station related errors */
30 ERR_STATION_BASE = ScriptError::ERR_CAT_STATION << ScriptError::ERR_CAT_BIT_SIZE,
32 /** The station is build too close to another station, airport or dock */
33 ERR_STATION_TOO_CLOSE_TO_ANOTHER_STATION, // [STR_ERROR_TOO_CLOSE_TO_ANOTHER_AIRPORT, STR_ERROR_TOO_CLOSE_TO_ANOTHER_STATION]
35 /** There are too many stations, airports and docks in the game */
36 ERR_STATION_TOO_MANY_STATIONS, // [STR_ERROR_TOO_MANY_STATIONS_LOADING, STR_ERROR_TOO_MANY_TRUCK_STOPS, STR_ERROR_TOO_MANY_BUS_STOPS, STR_ERROR_TOO_MANY_DOCKS]
38 /** There are too many stations, airports of docks in a town */
39 ERR_STATION_TOO_MANY_STATIONS_IN_TOWN, // [STR_ERROR_LOCAL_AUTHORITY_REFUSES_AIRPORT]
42 /**
43 * Type of stations known in the game.
45 enum StationType {
46 /* Note: these values represent part of the in-game StationFacility enum */
47 STATION_TRAIN = (int)::FACIL_TRAIN, ///< Train station
48 STATION_TRUCK_STOP = (int)::FACIL_TRUCK_STOP, ///< Truck station
49 STATION_BUS_STOP = (int)::FACIL_BUS_STOP, ///< Bus station
50 STATION_AIRPORT = (int)::FACIL_AIRPORT, ///< Airport
51 STATION_DOCK = (int)::FACIL_DOCK, ///< Dock
52 STATION_ANY = STATION_TRAIN | STATION_TRUCK_STOP | STATION_BUS_STOP | STATION_AIRPORT | STATION_DOCK, ///< All station types
55 /**
56 * Checks whether the given station is valid and owned by you.
57 * @param station_id The station to check.
58 * @return True if and only if the station is valid.
60 static bool IsValidStation(StationID station_id);
62 /**
63 * Get the owner of a station.
64 * @param station_id The station to get the owner of.
65 * @pre IsValidStation(station_id).
66 * @return The owner the station has.
67 * @api -ai
69 static ScriptCompany::CompanyID GetOwner(StationID station_id);
71 /**
72 * Get the StationID of a tile, if there is a station.
73 * @param tile The tile to find the stationID of
74 * @return StationID of the station.
75 * @post Use IsValidStation() to see if the station is valid.
77 static StationID GetStationID(TileIndex tile);
79 /**
80 * See how much cargo there is waiting on a station.
81 * @param station_id The station to get the cargo-waiting of.
82 * @param cargo_id The cargo to get the cargo-waiting of.
83 * @pre IsValidStation(station_id).
84 * @pre IsValidCargo(cargo_id).
85 * @return The amount of units waiting at the station.
87 static int32 GetCargoWaiting(StationID station_id, CargoID cargo_id);
89 /**
90 * See how much cargo with a specific source station there is waiting on a station.
91 * @param station_id The station to get the cargo-waiting of.
92 * @param from_station_id The source station of the cargo. Pass STATION_INVALID to get cargo of which the source has been deleted.
93 * @param cargo_id The cargo to get the cargo-waiting of.
94 * @pre IsValidStation(station_id).
95 * @pre IsValidStation(from_station_id) || from_station_id == STATION_INVALID.
96 * @pre IsValidCargo(cargo_id).
97 * @return The amount of units waiting at the station originating from from_station_id.
98 * @note source station means, the station where cargo was first loaded.
100 static int32 GetCargoWaitingFrom(StationID station_id, StationID from_station_id, CargoID cargo_id);
103 * See how much cargo with a specific via-station there is waiting on a station.
104 * @param station_id The station to get the cargo-waiting of.
105 * @param via_station_id The next station the cargo is going to. Pass STATION_INVALID to get waiting cargo for "via any station".
106 * @param cargo_id The cargo to get the cargo-waiting of.
107 * @pre IsValidStation(station_id).
108 * @pre IsValidStation(via_station_id) || via_station_id == STATION_INVALID.
109 * @pre IsValidCargo(cargo_id).
110 * @return The amount of units waiting at the station with via_station_id as next hop.
111 * @note if ScriptCargo.GetCargoDistributionType(cargo_id) == ScriptCargo.DT_MANUAL, then all waiting cargo will have STATION_INVALID as next hop.
113 static int32 GetCargoWaitingVia(StationID station_id, StationID via_station_id, CargoID cargo_id);
116 * See how much cargo with a specific via-station and source station there is waiting on a station.
117 * @param station_id The station to get the cargo-waiting of.
118 * @param from_station_id The source station of the cargo. Pass STATION_INVALID to get cargo of which the source has been deleted.
119 * @param via_station_id The next station the cargo is going to. Pass STATION_INVALID to get waiting cargo for "via any station".
120 * @param cargo_id The cargo to get the cargo-waiting of.
121 * @pre IsValidStation(station_id).
122 * @pre IsValidStation(from_station_id) || from_station_id == STATION_INVALID.
123 * @pre IsValidStation(via_station_id) || via_station_id == STATION_INVALID.
124 * @pre IsValidCargo(cargo_id).
125 * @return The amount of units waiting at the station with from_station_id as source and via_station_id as next hop.
126 * @note if ScriptCargo.GetCargoDistributionType(cargo_id) == ScriptCargo.DT_MANUAL, then all waiting cargo will have STATION_INVALID as next hop.
128 static int32 GetCargoWaitingFromVia(StationID station_id, StationID from_station_id, StationID via_station_id, CargoID cargo_id);
131 * See how much cargo was planned to pass (including production and consumption) this station per month.
132 * @param station_id The station to get the planned flow for.
133 * @param cargo_id The cargo type to get the planned flow for.
134 * @pre IsValidStation(station_id).
135 * @pre IsValidCargo(cargo_id).
136 * @return The amount of cargo units planned to pass the station per month.
138 static int32 GetCargoPlanned(StationID station_id, CargoID cargo_id);
141 * See how much cargo from the specified origin was planned to pass (including production and consumption) this station per month.
142 * @param station_id The station to get the planned flow for.
143 * @param from_station_id The station the cargo originates at.
144 * @param cargo_id The cargo type to get the planned flow for.
145 * @pre IsValidStation(station_id).
146 * @pre IsValidStation(from_station_id) || from_station_id == STATION_INVALID.
147 * @pre IsValidCargo(cargo_id).
148 * @return The amount of cargo units from the specified origin planned to pass the station per month.
150 static int32 GetCargoPlannedFrom(StationID station_id, StationID from_station_id, CargoID cargo_id);
153 * See how much cargo was planned to pass (including production and consumption) this station per month, heading for the specified next hop.
154 * @param station_id The station to get the planned flow for.
155 * @param via_station_id The next station the cargo will go on to.
156 * @param cargo_id The cargo type to get the planned flow for.
157 * @pre IsValidStation(station_id).
158 * @pre IsValidStation(via_station_id) || via_station_id == STATION_INVALID.
159 * @pre IsValidCargo(cargo_id).
160 * @return The amount of cargo units planned to pass the station per month, going via the specified next hop.
161 * @note Cargo planned to go "via" the same station that's being queried is actually planned to be consumed there.
163 static int32 GetCargoPlannedVia(StationID station_id, StationID via_station_id, CargoID cargo_id);
166 * See how much cargo from the specified origin was planned to pass this station per month,
167 * heading for the specified next hop.
168 * @param station_id The station to get the planned flow for.
169 * @param from_station_id The station the cargo originates at.
170 * @param via_station_id The next station the cargo will go on to.
171 * @param cargo_id The cargo type to get the planned flow for.
172 * @pre IsValidStation(station_id).
173 * @pre IsValidStation(from_station_id) || from_station_id == STATION_INVALID.
174 * @pre IsValidStation(via_station_id) || via_station_id == STATION_INVALID.
175 * @pre IsValidCargo(cargo_id).
176 * @return The amount of cargo units from the specified origin planned to pass the station per month, going via the specified next hop.
177 * @note Cargo planned to go "via" the same station that's being queried is actually planned to be consumed there.
178 * @note Cargo planned to pass "from" the same station that's being queried is actually produced there.
180 static int32 GetCargoPlannedFromVia(StationID station_id, StationID from_station_id, StationID via_station_id, CargoID cargo_id);
183 * Check whether the given cargo at the given station a rating.
184 * @param station_id The station to get the cargo-rating state of.
185 * @param cargo_id The cargo to get the cargo-rating state of.
186 * @pre IsValidStation(station_id).
187 * @pre IsValidCargo(cargo_id).
188 * @return True if the cargo has a rating, otherwise false.
190 static bool HasCargoRating(StationID station_id, CargoID cargo_id);
193 * See how high the rating is of a cargo on a station.
194 * @param station_id The station to get the cargo-rating of.
195 * @param cargo_id The cargo to get the cargo-rating of.
196 * @pre IsValidStation(station_id).
197 * @pre IsValidCargo(cargo_id).
198 * @pre HasCargoRating(station_id, cargo_id).
199 * @return The rating in percent of the cargo on the station.
201 static int32 GetCargoRating(StationID station_id, CargoID cargo_id);
204 * Get the coverage radius of this type of station.
205 * @param station_type The type of station.
206 * @pre station_type != STATION_AIRPORT.
207 * @return The radius in tiles.
208 * @note Coverage radius of airports needs to be requested via ScriptAirport::GetAirportCoverageRadius(), as it requires AirportType.
210 static int32 GetCoverageRadius(ScriptStation::StationType station_type);
213 * Get the coverage radius of this station.
214 * @param station_id The station to get the coverage radius of.
215 * @pre IsValidStation(station_id).
216 * @return The radius in tiles.
218 static int32 GetStationCoverageRadius(StationID station_id);
221 * Get the manhattan distance from the tile to the ScriptStation::GetLocation()
222 * of the station.
223 * @param station_id The station to get the distance to.
224 * @param tile The tile to get the distance to.
225 * @pre IsValidStation(station_id).
226 * @return The distance between station and tile.
228 static int32 GetDistanceManhattanToTile(StationID station_id, TileIndex tile);
231 * Get the square distance from the tile to the ScriptStation::GetLocation()
232 * of the station.
233 * @param station_id The station to get the distance to.
234 * @param tile The tile to get the distance to.
235 * @pre IsValidStation(station_id).
236 * @return The distance between station and tile.
238 static int32 GetDistanceSquareToTile(StationID station_id, TileIndex tile);
241 * Find out if this station is within the rating influence of a town.
242 * The service quality of stations with signs within this radius
243 * influences the rating of the town.
244 * @param station_id The station to check.
245 * @param town_id The town to check.
246 * @return True if the tile is within the rating influence of the town.
248 static bool IsWithinTownInfluence(StationID station_id, TownID town_id);
251 * Check if any part of the station contains a station of the type
252 * StationType
253 * @param station_id The station to look at.
254 * @param station_type The StationType to look for.
255 * @return True if the station has a station part of the type StationType.
257 static bool HasStationType(StationID station_id, StationType station_type);
260 * Check if any part of the station contains a station of the type
261 * RoadType.
262 * @param station_id The station to look at.
263 * @param road_type The RoadType to look for.
264 * @return True if the station has a station part of the type RoadType.
266 static bool HasRoadType(StationID station_id, ScriptRoad::RoadType road_type);
269 * Get the town that was nearest to the given station when the station was built.
270 * @param station_id The station to look at.
271 * @return The TownID of the town whose center tile was closest to the station
272 * at the time the station was built.
273 * @note There is no guarantee that the station is even near the returned town
274 * nor that the returns town is closest to the station now. A station that was
275 * 'walked' to the other end of the map will still return the same town. Also,
276 * towns grow, towns change. So don't depend on this value too much.
278 static TownID GetNearestTown(StationID station_id);
281 * Get the open/closed state of an airport.
282 * @param station_id The airport to look at.
283 * @pre IsValidStation(station_id).
284 * @pre HasStationType(station_id, STATION_AIRPORT).
285 * @return True if the airport is currently closed to incoming traffic.
287 static bool IsAirportClosed(StationID station_id);
290 * Toggle the open/closed state of an airport.
291 * @param station_id The airport to modify.
292 * @pre IsValidStation(station_id).
293 * @pre HasStationType(station_id, STATION_AIRPORT).
294 * @return True if the state was toggled successfully.
296 static bool OpenCloseAirport(StationID station_id);
298 private:
299 template<bool Tfrom, bool Tvia>
300 static bool IsCargoRequestValid(StationID station_id, StationID from_station_id,
301 StationID via_station_id, CargoID cargo_id);
303 template<bool Tfrom, bool Tvia>
304 static int32 CountCargoWaiting(StationID station_id, StationID from_station_id,
305 StationID via_station_id, CargoID cargo_id);
307 template<bool Tfrom, bool Tvia>
308 static int32 CountCargoPlanned(StationID station_id, StationID from_station_id,
309 StationID via_station_id, CargoID cargo_id);
313 DECLARE_ENUM_AS_BIT_SET(ScriptStation::StationType)
315 #endif /* SCRIPT_STATION_HPP */