Callback: Custom cargo production

From GRFSpecs
Revision as of 18:58, 16 June 2011 by Pm-bot (talk | contribs) (Create a separate page for each callback)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Custom cargo production (2E)

This callback can be used to customize cargo production of house tiles. It is called every 256 ticks when the tile can produce cargo. Because a tile can produce many types of cargo, this callback is called in a loop until it returns 20FFh (the loop count is limited to 256 to avoid endless loops). If the returned value is not 20FFh, the high byte must be a cargo type and the low byte must be the amount to be distributed. You can return a cargo type more than once if needed, so you can distribute more than 255 units from it. During the callback, the lowest byte of variable 10 contains the number of iterations happened so far and variable 18 contains a random value to help randomizing the production. (The old code randomizes production to make it look more natural, you can do the same via a variational action 2 with nvar=0)

This is how the original passenger generation is done: In each periodic processing (i.e. every 256 ticks), a random value 0<=X<=255 is generated for each house tile. If X isn't smaller than the population of the tile, no passengers are generated. Otherwise, X/8+1 passengers are generated (rounded down). If there is a recession going on, the number of generated passengers is halved, but this division gets rounded up instead of down. Mail generation happens in a similar manner, but with a new random value, and checking against the mail generation multiplier instead of the population.

Uses 15 return bits

From GRF version 7 and above, the interpretation of the high byte in the returned value changes: instead of a climate-dependent cargo slot number, you have to return a climate-independent cargo ID. If your GRF has a cargo translation table, then this ID is the index in that table; otherwise, it's the cargo bit. Trying to produce a cargo not currently present is not an error, but will be ignored.