src/newgrf_callbacks.h

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