1 /* 2 * This file is part of OpenTTD. 3 * 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. 4 * 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. 5 * 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/>. 6 */ 7 8 /** @file newgrf_callbacks.h Callbacks that NewGRFs could implement. */ 9 10 #ifndef NEWGRF_CALLBACKS_H 11 #define NEWGRF_CALLBACKS_H 12 13 /** 14 * List of implemented NewGRF callbacks. 15 * Most of these callbacks are only triggered when the corresponding 16 * bit is set in the callback flags/trigger for a vehicle, house, 17 * industry, etc. 18 * Names are formatted as CBID_<CLASS>_<CALLBACK> 19 */ 20 enum CallbackID { 21 /** Set when using the callback resolve system, but not to resolve a callback. */ 22 CBID_NO_CALLBACK = 0x00, 23 24 /** Set when calling a randomizing trigger (almost undocumented). */ 25 CBID_RANDOM_TRIGGER = 0x01, 26 27 /* There are no callbacks 0x02 - 0x0F. */ 28 29 /** Visual effects and wagon power. */ 30 CBID_VEHICLE_VISUAL_EFFECT = 0x10, // 8 bit callback 31 32 /** Vehicle length, returns the amount of 1/8's the vehicle is shorter for trains and RVs. */ 33 CBID_VEHICLE_LENGTH = 0x11, 34 35 /** Determine the amount of cargo to load per unit of time when using gradual loading. */ 36 CBID_VEHICLE_LOAD_AMOUNT = 0x12, // 8 bit callback 37 38 /** Determine whether a newstation should be made available to build. */ 39 CBID_STATION_AVAILABILITY = 0x13, // 8 bit callback 40 41 /** Choose a sprite layout to draw, instead of the standard 0-7 range. */ 42 CBID_STATION_SPRITE_LAYOUT = 0x14, 43 44 /** 45 * Refit capacity, the passed vehicle needs to have its ->cargo_type set to 46 * the cargo we are refitting to, returns the new cargo capacity. 47 */ 48 CBID_VEHICLE_REFIT_CAPACITY = 0x15, // 15 bit callback 49 50 /** Builds articulated engines for trains and RVs. */ 51 CBID_VEHICLE_ARTIC_ENGINE = 0x16, // 8 bit callback for grf version < 8 52 53 /** Determine whether the house can be built on the specified tile. */ 54 CBID_HOUSE_ALLOW_CONSTRUCTION = 0x17, // 8 bit callback 55 56 /** AI construction/purchase selection */ 57 CBID_GENERIC_AI_PURCHASE_SELECTION = 0x18, // 8 bit callback, implemented for stations only 58 59 /** Determine the cargo "suffixes" for each refit possibility of a cargo. */ 60 CBID_VEHICLE_CARGO_SUFFIX = 0x19, 61 62 /** Determine the next animation frame for a house. */ 63 CBID_HOUSE_ANIMATION_NEXT_FRAME = 0x1A, // 15 bit callback 64 65 /** Called for periodically starting or stopping the animation. */ 66 CBID_HOUSE_ANIMATION_START_STOP = 0x1B, // 15 bit callback 67 68 /** Called whenever the construction state of a house changes. */ 69 CBID_HOUSE_CONSTRUCTION_STATE_CHANGE = 0x1C, // 15 bit callback 70 71 /** Determine whether a wagon can be attached to an already existing train. */ 72 CBID_TRAIN_ALLOW_WAGON_ATTACH = 0x1D, 73 74 /** Called to determine the colour of a town building. */ 75 CBID_HOUSE_COLOUR = 0x1E, // 15 bit callback 76 77 /** Called to decide how much cargo a town building can accept. */ 78 CBID_HOUSE_CARGO_ACCEPTANCE = 0x1F, // 15 bit callback 79 80 /** Called to indicate how long the current animation frame should last. */ 81 CBID_HOUSE_ANIMATION_SPEED = 0x20, // 8 bit callback 82 83 /** Called periodically to determine if a house should be destroyed. */ 84 CBID_HOUSE_DESTRUCTION = 0x21, // 8 bit callback 85 86 /** Called to determine if the given industry type is available. For grf version >= 8 also a probability can be returned. */ 87 CBID_INDUSTRY_PROBABILITY = 0x22, // 15 bit callback 88 89 /** 90 * This callback is called from vehicle purchase lists. It returns a value to be 91 * used as a custom string ID in the 0xD000 range. 92 */ 93 CBID_VEHICLE_ADDITIONAL_TEXT = 0x23, 94 95 /** Called when building a station to customize the tile layout */ 96 CBID_STATION_TILE_LAYOUT = 0x24, // 15 bit callback 97 98 /** Called for periodically starting or stopping the animation. */ 99 CBID_INDTILE_ANIM_START_STOP = 0x25, // 15 bit callback 100 101 /** Called to determine industry tile next animation frame. */ 102 CBID_INDTILE_ANIM_NEXT_FRAME = 0x26, // 15 bit callback 103 104 /** Called to indicate how long the current animation frame should last. */ 105 CBID_INDTILE_ANIMATION_SPEED = 0x27, // 8 bit callback 106 107 /** Called to determine if the given industry can be built on specific area. */ 108 CBID_INDUSTRY_LOCATION = 0x28, // 15 bit callback 109 110 /** Called on production changes, so it can be adjusted. */ 111 CBID_INDUSTRY_PRODUCTION_CHANGE = 0x29, // 15 bit callback 112 113 /** Called to determine which cargoes a town building should accept. */ 114 CBID_HOUSE_ACCEPT_CARGO = 0x2A, // 15 bit callback 115 116 /** Called to query the cargo acceptance of the industry tile */ 117 CBID_INDTILE_CARGO_ACCEPTANCE = 0x2B, // 15 bit callback 118 119 /** Called to determine which cargoes an industry should accept. */ 120 CBID_INDTILE_ACCEPT_CARGO = 0x2C, // 15 bit callback 121 122 /** 123 * Called to determine if a specific colour map should be used for a vehicle 124 * instead of the default livery. 125 */ 126 CBID_VEHICLE_COLOUR_MAPPING = 0x2D, // 15 bit callback 127 128 /** Called to determine how much cargo a town building produces. */ 129 CBID_HOUSE_PRODUCE_CARGO = 0x2E, // 15 bit callback 130 131 /** Called to determine if the given industry tile can be built on specific tile. */ 132 CBID_INDTILE_SHAPE_CHECK = 0x2F, // 15 bit callback 133 134 /** Called to determine the type (if any) of foundation to draw for industry tile. */ 135 CBID_INDTILE_DRAW_FOUNDATIONS = 0x30, // 15 bit callback 136 137 /** 138 * Called when the company (or AI) tries to start or stop a vehicle. Mainly 139 * used for preventing a vehicle from leaving the depot. 140 */ 141 CBID_VEHICLE_START_STOP_CHECK = 0x31, // 15 bit callback, but 0xFF test is done with 8 bit 142 143 /** Called for every vehicle every 32 days (not all on same date though). */ 144 CBID_VEHICLE_32DAY_CALLBACK = 0x32, // 2 bit callback 145 146 /** Called to play a special sound effect */ 147 CBID_VEHICLE_SOUND_EFFECT = 0x33, // 15 bit callback 148 149 /** Return the vehicles this given vehicle can be "upgraded" to. */ 150 CBID_VEHICLE_AUTOREPLACE_SELECTION = 0x34, // 15 bit callback, not implemented 151 152 /** Called monthly on production changes, so it can be adjusted more frequently */ 153 CBID_INDUSTRY_MONTHLYPROD_CHANGE = 0x35, // 15 bit callback 154 155 /** 156 * Called to modify various vehicle properties. Callback parameter 1 157 * specifies the property index, as used in Action 0, to change. 158 */ 159 CBID_VEHICLE_MODIFY_PROPERTY = 0x36, // 8/15 bit depends on queried property 160 161 /** Called to determine text to display after cargo name */ 162 CBID_INDUSTRY_CARGO_SUFFIX = 0x37, // 15 bit callback, but 0xFF test is done with 8 bit 163 164 /** Called to determine more text in the fund industry window */ 165 CBID_INDUSTRY_FUND_MORE_TEXT = 0x38, // 15 bit callback 166 167 /** Called to calculate the income of delivered cargo */ 168 CBID_CARGO_PROFIT_CALC = 0x39, // 15 bit callback 169 170 /** Called to determine more text in the industry window */ 171 CBID_INDUSTRY_WINDOW_MORE_TEXT = 0x3A, // 15 bit callback 172 173 /** Called to determine industry special effects */ 174 CBID_INDUSTRY_SPECIAL_EFFECT = 0x3B, // 15 bit callback 175 176 /** Called to determine if industry can alter the ground below industry tile */ 177 CBID_INDTILE_AUTOSLOPE = 0x3C, // 15 bit callback 178 179 /** Called to determine if the industry can still accept or refuse more cargo arrival */ 180 CBID_INDUSTRY_REFUSE_CARGO = 0x3D, // 15 bit callback 181 182 /* There are no callbacks 0x3E - 0x13F */ 183 184 /** Called for periodically starting or stopping the animation. */ 185 CBID_STATION_ANIM_START_STOP = 0x140, // 15 bit callback 186 187 /** Called to determine station tile next animation frame. */ 188 CBID_STATION_ANIM_NEXT_FRAME = 0x141, // 15 bit callback 189 190 /** Called to indicate how long the current animation frame should last. */ 191 CBID_STATION_ANIMATION_SPEED = 0x142, // 8 bit callback 192 193 /** Called to determine whether a town building can be destroyed. */ 194 CBID_HOUSE_DENY_DESTRUCTION = 0x143, // 15 bit callback 195 196 /** Select an ambient sound to play for a given type of tile. */ 197 CBID_SOUNDS_AMBIENT_EFFECT = 0x144, // 15 bit callback 198 199 /** Called to calculate part of a station rating. */ 200 CBID_CARGO_STATION_RATING_CALC = 0x145, // 15 bit callback 201 202 /** Allow signal sprites to be replaced dynamically. */ 203 CBID_NEW_SIGNALS_SPRITE_DRAW = 0x146, // 15 bit callback, not implemented 204 205 /** Add an offset to the default sprite numbers to show another sprite. */ 206 CBID_CANALS_SPRITE_OFFSET = 0x147, // 15 bit callback 207 208 /** Called when a cargo type specified in property 20 is accepted. */ 209 CBID_HOUSE_WATCHED_CARGO_ACCEPTED = 0x148, // 15 bit callback 210 211 /** Callback done for each tile of a station to check the slope. */ 212 CBID_STATION_LAND_SLOPE_CHECK = 0x149, // 15 bit callback 213 214 /** Called to determine the colour of an industry. */ 215 CBID_INDUSTRY_DECIDE_COLOUR = 0x14A, // 4 bit callback 216 217 /** Customize the input cargo types of a newly build industry. */ 218 CBID_INDUSTRY_INPUT_CARGO_TYPES = 0x14B, // 8 bit callback 219 220 /** Customize the output cargo types of a newly build industry. */ 221 CBID_INDUSTRY_OUTPUT_CARGO_TYPES = 0x14C, // 8 bit callback 222 223 /** Called on the Get Tile Description for an house tile. */ 224 CBID_HOUSE_CUSTOM_NAME = 0x14D, // 15 bit callback 225 226 /** Called to determine the type (if any) of foundation to draw for house tile. */ 227 CBID_HOUSE_DRAW_FOUNDATIONS = 0x14E, // 15 bit callback 228 229 /** Called to determine if one can alter the ground below a house tile */ 230 CBID_HOUSE_AUTOSLOPE = 0x14F, // 15 bit callback 231 232 /** Called to determine the type (if any) of foundation to draw for an airport tile. */ 233 CBID_AIRPTILE_DRAW_FOUNDATIONS = 0x150, // 15 bit callback 234 235 /** Called for periodically starting or stopping the animation. */ 236 CBID_AIRPTILE_ANIM_START_STOP = 0x152, // 15 bit callback 237 238 /** Called to determine airport tile next animation frame. */ 239 CBID_AIRPTILE_ANIM_NEXT_FRAME = 0x153, // 15 bit callback 240 241 /** Called to indicate how long the current animation frame should last. */ 242 CBID_AIRPTILE_ANIMATION_SPEED = 0x154, // 8 bit callback 243 244 /** 245 * This callback is called from airport list. It returns a value to be 246 * used as a custom string ID in the 0xD000 range. 247 */ 248 CBID_AIRPORT_ADDITIONAL_TEXT = 0x155, // 15 bit callback 249 250 /** Called to determine text to show as airport layout name. */ 251 CBID_AIRPORT_LAYOUT_NAME = 0x156, // 15 bit callback 252 253 /** Callback done for each tile of an object to check the slope. */ 254 CBID_OBJECT_LAND_SLOPE_CHECK = 0x157, // 15 bit callback 255 256 /** Determine the next animation frame for a house. */ 257 CBID_OBJECT_ANIMATION_NEXT_FRAME = 0x158, // 15 bit callback 258 259 /** Called for periodically starting or stopping the animation. */ 260 CBID_OBJECT_ANIMATION_START_STOP = 0x159, // 15 bit callback 261 262 /** Called to indicate how long the current animation frame should last. */ 263 CBID_OBJECT_ANIMATION_SPEED = 0x15A, // 8 bit callback 264 265 /** Called to determine the colour of a town building. */ 266 CBID_OBJECT_COLOUR = 0x15B, // 15 bit callback 267 268 /** Called to determine more text in the fund object window */ 269 CBID_OBJECT_FUND_MORE_TEXT = 0x15C, // 15 bit callback 270 271 /** Called to determine if one can alter the ground below an object tile */ 272 CBID_OBJECT_AUTOSLOPE = 0x15D, // 15 bit callback 273 274 /** Called to determine the cost factor for refitting a vehicle. */ 275 CBID_VEHICLE_REFIT_COST = 0x15E, // 15 bit callback 276 277 /** Called when industry is built to set initial production level. */ 278 CBID_INDUSTRY_PROD_CHANGE_BUILD = 0x15F, // 15 bit callback 279 280 /** Called to spawn visual effects for vehicles. */ 281 CBID_VEHICLE_SPAWN_VISUAL_EFFECT = 0x160, // 15 bit callback 282 }; 283 284 /** 285 * Callback masks for vehicles, indicates which callbacks are used by a vehicle. 286 * Some callbacks are always used and don't have a mask. 287 */ 288 enum VehicleCallbackMask { 289 CBM_VEHICLE_VISUAL_EFFECT = 0, ///< Visual effects and wagon power (trains, road vehicles and ships) 290 CBM_VEHICLE_LENGTH = 1, ///< Vehicle length (trains and road vehicles) 291 CBM_VEHICLE_LOAD_AMOUNT = 2, ///< Load amount 292 CBM_VEHICLE_REFIT_CAPACITY = 3, ///< Cargo capacity after refit 293 CBM_VEHICLE_ARTIC_ENGINE = 4, ///< Add articulated engines (trains and road vehicles) 294 CBM_VEHICLE_CARGO_SUFFIX = 5, ///< Show suffix after cargo name 295 CBM_VEHICLE_COLOUR_REMAP = 6, ///< Change colour mapping of vehicle 296 CBM_VEHICLE_SOUND_EFFECT = 7, ///< Vehicle uses custom sound effects 297 }; 298 299 /** 300 * Callback masks for stations. 301 */ 302 enum StationCallbackMask { 303 CBM_STATION_AVAIL = 0, ///< Availability of station in construction window 304 CBM_STATION_SPRITE_LAYOUT = 1, ///< Use callback to select a sprite layout to use 305 CBM_STATION_ANIMATION_NEXT_FRAME = 2, ///< Use a custom next frame callback 306 CBM_STATION_ANIMATION_SPEED = 3, ///< Customize the animation speed of the station 307 CBM_STATION_SLOPE_CHECK = 4, ///< Check slope of new station tiles 308 }; 309 310 /** 311 * Callback masks for houses. 312 */ 313 enum HouseCallbackMask { 314 CBM_HOUSE_ALLOW_CONSTRUCTION = 0, ///< decide whether the house can be built on a given tile 315 CBM_HOUSE_ANIMATION_NEXT_FRAME = 1, ///< decides next animation frame 316 CBM_HOUSE_ANIMATION_START_STOP = 2, ///< periodically start/stop the animation 317 CBM_HOUSE_CONSTRUCTION_STATE_CHANGE = 3, ///< change animation when construction state changes 318 CBM_HOUSE_COLOUR = 4, ///< decide the colour of the building 319 CBM_HOUSE_CARGO_ACCEPTANCE = 5, ///< decides amount of cargo acceptance 320 CBM_HOUSE_ANIMATION_SPEED = 6, ///< decides animation speed 321 CBM_HOUSE_DESTRUCTION = 7, ///< trigger destruction of building 322 CBM_HOUSE_ACCEPT_CARGO = 8, ///< decides accepted types 323 CBM_HOUSE_PRODUCE_CARGO = 9, ///< custom cargo production 324 CBM_HOUSE_DENY_DESTRUCTION = 10, ///< conditional protection 325 CBM_HOUSE_DRAW_FOUNDATIONS = 11, ///< decides if default foundations need to be drawn 326 CBM_HOUSE_AUTOSLOPE = 12, ///< decides allowance of autosloping 327 }; 328 329 /** 330 * Callback masks for canals. 331 */ 332 enum CanalCallbackMask { 333 CBM_CANAL_SPRITE_OFFSET = 0, ///< Enable add sprite offset callback 334 }; 335 336 /** 337 * Callback masks for cargoes. 338 */ 339 enum CargoCallbackMask { 340 CBM_CARGO_PROFIT_CALC = 0, ///< custom profit calculation 341 CBM_CARGO_STATION_RATING_CALC = 1, ///< custom station rating for this cargo type 342 }; 343 344 /** 345 * Callback masks for Industries 346 */ 347 enum IndustryCallbackMask { 348 CBM_IND_PROBABILITY = 0, ///< industry availability/probability callback 349 CBM_IND_PRODUCTION_CARGO_ARRIVAL = 1, ///< call production callback when cargo arrives at the industry 350 CBM_IND_PRODUCTION_256_TICKS = 2, ///< call production callback every 256 ticks 351 CBM_IND_LOCATION = 3, ///< check industry construction on given area 352 CBM_IND_PRODUCTION_CHANGE = 4, ///< controls random production change 353 CBM_IND_MONTHLYPROD_CHANGE = 5, ///< controls monthly random production change 354 CBM_IND_CARGO_SUFFIX = 6, ///< cargo sub-type display 355 CBM_IND_FUND_MORE_TEXT = 7, ///< additional text in fund window 356 CBM_IND_WINDOW_MORE_TEXT = 8, ///< additional text in industry window 357 CBM_IND_SPECIAL_EFFECT = 9, ///< control special effects 358 CBM_IND_REFUSE_CARGO = 10, ///< option out of accepting cargo 359 CBM_IND_DECIDE_COLOUR = 11, ///< give a custom colour to newly build industries 360 CBM_IND_INPUT_CARGO_TYPES = 12, ///< customize the cargoes the industry requires 361 CBM_IND_OUTPUT_CARGO_TYPES = 13, ///< customize the cargoes the industry produces 362 CBM_IND_PROD_CHANGE_BUILD = 14, ///< initialise production level on construction 363 }; 364 365 /** 366 * Callback masks for industry tiles 367 */ 368 enum IndustryTileCallbackMask { 369 CBM_INDT_ANIM_NEXT_FRAME = 0, ///< decides next animation frame 370 CBM_INDT_ANIM_SPEED = 1, ///< decides animation speed 371 CBM_INDT_CARGO_ACCEPTANCE = 2, ///< decides amount of cargo acceptance 372 CBM_INDT_ACCEPT_CARGO = 3, ///< decides accepted types 373 CBM_INDT_SHAPE_CHECK = 4, ///< decides slope suitability 374 CBM_INDT_DRAW_FOUNDATIONS = 5, ///< decides if default foundations need to be drawn 375 CBM_INDT_AUTOSLOPE = 6, ///< decides allowance of autosloping 376 }; 377 378 /** 379 * Callback masks for objects 380 */ 381 enum ObjectCallbackMask { 382 CBM_OBJ_SLOPE_CHECK = 0, ///< decides slope suitability 383 CBM_OBJ_ANIMATION_NEXT_FRAME = 1, ///< decides next animation frame 384 CBM_OBJ_ANIMATION_SPEED = 2, ///< decides animation speed 385 CBM_OBJ_COLOUR = 3, ///< decide the colour of the building 386 CBM_OBJ_FUND_MORE_TEXT = 4, ///< additional text in fund window 387 CBM_OBJ_AUTOSLOPE = 5, ///< decides allowance of autosloping 388 }; 389 390 /** 391 * Callback masks for airport tiles 392 */ 393 enum AirportTileCallbackMask { 394 CBM_AIRT_ANIM_NEXT_FRAME = 0, ///< decides next animation frame 395 CBM_AIRT_ANIM_SPEED = 1, ///< decides animation speed 396 CBM_AIRT_SHAPE_CHECK = 4, ///< decides slope suitability 397 CBM_AIRT_DRAW_FOUNDATIONS = 5, ///< decides if default foundations need to be drawn 398 CBM_AIRT_AUTOSLOPE = 6, ///< decides allowance of autosloping 399 }; 400 401 /** 402 * Different values for Callback result evaluations 403 */ 404 static const uint CALLBACK_FAILED = 0xFFFF; ///< Result of a failed callback. 405 static const uint CALLBACK_HOUSEPRODCARGO_END = 0x20FF; ///< Sentinel indicating that the loop for CBID_HOUSE_PRODUCE_CARGO has ended 406 407 #endif /* NEWGRF_CALLBACKS_H */ 408