src/newgrf_callbacks.h

   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 tile layout to draw, instead of the standard range. */
  42         CBID_STATION_DRAW_TILE_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_BUILD_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         /** Called to determine the engine name to show. */
 284         CBID_VEHICLE_NAME                    = 0x161, // 15 bit callback
 285
 286         /** Called to determine probability during build. */
 287         CBID_VEHICLE_BUILD_PROBABILITY       = 0x162, // 15 bit callback
 288 };
 289
 290 /**
 291  * Callback masks for vehicles, indicates which callbacks are used by a vehicle.
 292  * Some callbacks are always used and don't have a mask.
 293  */
 294 enum VehicleCallbackMask {
 295         CBM_VEHICLE_VISUAL_EFFECT  = 0, ///< Visual effects and wagon power (trains, road vehicles and ships)
 296         CBM_VEHICLE_LENGTH         = 1, ///< Vehicle length (trains and road vehicles)
 297         CBM_VEHICLE_LOAD_AMOUNT    = 2, ///< Load amount
 298         CBM_VEHICLE_REFIT_CAPACITY = 3, ///< Cargo capacity after refit
 299         CBM_VEHICLE_ARTIC_ENGINE   = 4, ///< Add articulated engines (trains and road vehicles)
 300         CBM_VEHICLE_CARGO_SUFFIX   = 5, ///< Show suffix after cargo name
 301         CBM_VEHICLE_COLOUR_REMAP   = 6, ///< Change colour mapping of vehicle
 302         CBM_VEHICLE_SOUND_EFFECT   = 7, ///< Vehicle uses custom sound effects
 303         CBM_VEHICLE_NAME           = 8, ///< Engine name
 304 };
 305
 306 /**
 307  * Callback masks for stations.
 308  */
 309 enum StationCallbackMask {
 310         CBM_STATION_AVAIL                = 0, ///< Availability of station in construction window
 311         CBM_STATION_DRAW_TILE_LAYOUT     = 1, ///< Use callback to select a tile layout to use when drawing.
 312         CBM_STATION_ANIMATION_NEXT_FRAME = 2, ///< Use a custom next frame callback
 313         CBM_STATION_ANIMATION_SPEED      = 3, ///< Customize the animation speed of the station
 314         CBM_STATION_SLOPE_CHECK          = 4, ///< Check slope of new station tiles
 315 };
 316
 317 /**
 318  * Callback masks for road stops.
 319  */
 320 enum RoadStopCallbackMask {
 321         CBM_ROAD_STOP_AVAIL                = 0, ///< Availability of road stop in construction window
 322         CBM_ROAD_STOP_ANIMATION_NEXT_FRAME = 1, ///< Use a custom next frame callback
 323         CBM_ROAD_STOP_ANIMATION_SPEED      = 2, ///< Customize the animation speed of the road stop
 324 };
 325
 326 /**
 327  * Callback masks for houses.
 328  */
 329 enum HouseCallbackMask {
 330         CBM_HOUSE_ALLOW_CONSTRUCTION        =  0, ///< decide whether the house can be built on a given tile
 331         CBM_HOUSE_ANIMATION_NEXT_FRAME      =  1, ///< decides next animation frame
 332         CBM_HOUSE_ANIMATION_START_STOP      =  2, ///< periodically start/stop the animation
 333         CBM_HOUSE_CONSTRUCTION_STATE_CHANGE =  3, ///< change animation when construction state changes
 334         CBM_HOUSE_COLOUR                    =  4, ///< decide the colour of the building
 335         CBM_HOUSE_CARGO_ACCEPTANCE          =  5, ///< decides amount of cargo acceptance
 336         CBM_HOUSE_ANIMATION_SPEED           =  6, ///< decides animation speed
 337         CBM_HOUSE_DESTRUCTION               =  7, ///< trigger destruction of building
 338         CBM_HOUSE_ACCEPT_CARGO              =  8, ///< decides accepted types
 339         CBM_HOUSE_PRODUCE_CARGO             =  9, ///< custom cargo production
 340         CBM_HOUSE_DENY_DESTRUCTION          = 10, ///< conditional protection
 341         CBM_HOUSE_DRAW_FOUNDATIONS          = 11, ///< decides if default foundations need to be drawn
 342         CBM_HOUSE_AUTOSLOPE                 = 12, ///< decides allowance of autosloping
 343 };
 344
 345 /**
 346  * Callback masks for canals.
 347  */
 348 enum CanalCallbackMask {
 349         CBM_CANAL_SPRITE_OFFSET       = 0, ///< Enable add sprite offset callback
 350 };
 351
 352 /**
 353  * Callback masks for cargoes.
 354  */
 355 enum CargoCallbackMask {
 356         CBM_CARGO_PROFIT_CALC         = 0, ///< custom profit calculation
 357         CBM_CARGO_STATION_RATING_CALC = 1, ///< custom station rating for this cargo type
 358 };
 359
 360 /**
 361  * Callback masks for Industries
 362  */
 363 enum IndustryCallbackMask {
 364         CBM_IND_PROBABILITY               =  0, ///< industry availability/probability callback
 365         CBM_IND_PRODUCTION_CARGO_ARRIVAL  =  1, ///< call production callback when cargo arrives at the industry
 366         CBM_IND_PRODUCTION_256_TICKS      =  2, ///< call production callback every 256 ticks
 367         CBM_IND_LOCATION                  =  3, ///< check industry construction on given area
 368         CBM_IND_PRODUCTION_CHANGE         =  4, ///< controls random production change
 369         CBM_IND_MONTHLYPROD_CHANGE        =  5, ///< controls monthly random production change
 370         CBM_IND_CARGO_SUFFIX              =  6, ///< cargo sub-type display
 371         CBM_IND_FUND_MORE_TEXT            =  7, ///< additional text in fund window
 372         CBM_IND_WINDOW_MORE_TEXT          =  8, ///< additional text in industry window
 373         CBM_IND_SPECIAL_EFFECT            =  9, ///< control special effects
 374         CBM_IND_REFUSE_CARGO              = 10, ///< option out of accepting cargo
 375         CBM_IND_DECIDE_COLOUR             = 11, ///< give a custom colour to newly build industries
 376         CBM_IND_INPUT_CARGO_TYPES         = 12, ///< customize the cargoes the industry requires
 377         CBM_IND_OUTPUT_CARGO_TYPES        = 13, ///< customize the cargoes the industry produces
 378         CBM_IND_PROD_CHANGE_BUILD         = 14, ///< initialise production level on construction
 379 };
 380
 381 /**
 382  * Callback masks for industry tiles
 383  */
 384 enum IndustryTileCallbackMask {
 385         CBM_INDT_ANIM_NEXT_FRAME          = 0,  ///< decides next animation frame
 386         CBM_INDT_ANIM_SPEED               = 1,  ///< decides animation speed
 387         CBM_INDT_CARGO_ACCEPTANCE         = 2,  ///< decides amount of cargo acceptance
 388         CBM_INDT_ACCEPT_CARGO             = 3,  ///< decides accepted types
 389         CBM_INDT_SHAPE_CHECK              = 4,  ///< decides slope suitability
 390         CBM_INDT_DRAW_FOUNDATIONS         = 5,  ///< decides if default foundations need to be drawn
 391         CBM_INDT_AUTOSLOPE                = 6,  ///< decides allowance of autosloping
 392 };
 393
 394 /**
 395  * Callback masks for objects
 396  */
 397 enum ObjectCallbackMask {
 398         CBM_OBJ_SLOPE_CHECK               =  0, ///< decides slope suitability
 399         CBM_OBJ_ANIMATION_NEXT_FRAME      =  1, ///< decides next animation frame
 400         CBM_OBJ_ANIMATION_SPEED           =  2, ///< decides animation speed
 401         CBM_OBJ_COLOUR                    =  3, ///< decide the colour of the building
 402         CBM_OBJ_FUND_MORE_TEXT            =  4, ///< additional text in fund window
 403         CBM_OBJ_AUTOSLOPE                 =  5, ///< decides allowance of autosloping
 404 };
 405
 406 /**
 407  * Callback masks for airport tiles
 408  */
 409 enum AirportTileCallbackMask {
 410         CBM_AIRT_ANIM_NEXT_FRAME          = 0,  ///< decides next animation frame
 411         CBM_AIRT_ANIM_SPEED               = 1,  ///< decides animation speed
 412         CBM_AIRT_SHAPE_CHECK              = 4,  ///< decides slope suitability
 413         CBM_AIRT_DRAW_FOUNDATIONS         = 5,  ///< decides if default foundations need to be drawn
 414         CBM_AIRT_AUTOSLOPE                = 6,  ///< decides allowance of autosloping
 415 };
 416
 417 /**
 418  * Different values for Callback result evaluations
 419  */
 420 static const uint CALLBACK_FAILED              = 0xFFFF; ///< Result of a failed callback.
 421 static const uint CALLBACK_HOUSEPRODCARGO_END  = 0x20FF; ///< Sentinel indicating that the loop for CBID_HOUSE_PRODUCE_CARGO has ended
 422
 423 #endif /* NEWGRF_CALLBACKS_H */