View source for Callback: Custom station rating calculation

== Custom station rating calculation (145) ==

This callback allows you to modify part of the station cargo rating calculation for your cargo. To understand how to use it, you must first understand how the default rating calculation works:

Internally, the station rating is stored in a byte, 0 meaning 0% and 255 meaning 100%. The rating is calculated as the sum of the following components:

==== Time since the cargo was last picked up =====

{| |-
!Time units (days)!!Score (%, rounded)
|-
|&gt;21 (&gt;52.5 days)||0 (0%)
|-
|13..21 (32.5 days..52.5 days)||25 (10%)
|-
|7..12 (17.5 days..32.5 days)||50 (20%)
|-
|4..6 (10 days..17.5 days)||95 (37%)
|-
|0..3 (0 days..10 days)||130 (51%)
|}

The time unit used equals 185 engine ticks, or 2.5 TTD days. For ships, the time units are divided by 4 before calculating this component, so ships have four times more time before the ratings start dropping.

==== Amount of cargo waiting =====

{| |-
!Amount of cargo!!Score (%, rounded)
|-
|&gt;1500||-90 (-35%)
|-
|1001..1500||-35 (-14%)
|-
|601..1000||0 (0%)
|-
|301..600||10 (4%)
|-
|101..300||30 (12%)
|-
|0..100||40 (16%)
|}

==== Max. speed of the last vehicle picking up the cargo =====

This calculation is somewhat complicated. The maximum speed of the vehicle is expressed in "speed units". For trains and road vehicles, the speed unit is 1 km/h; for ships, it's 0.5 km/h; for aircraft, it's 8 mph. If the max. speed is above 255 speed units, 255 is used instead. If the vehicle is slower than 85 units, no points are awarded; otherwise, you get (speed_units-85)/4 points. Therefore, the maximum you can get is 42 points, or 16%.

==== Age of the last carrier picking up the cargo =====

The original calculation goes like this:

{| |-
!Age of vehicle (years)!!Score (%, rounded)
|-
|2||10 (4%)
|-
|1||20 (8%)
|-
|0||33 (13%)
|}

If the newagerating switch is turned on, the calculation changes. You get 33 points for vehicles younger than 5 years, and get 0 points for vehicles older than 21 years. Between these two ages, score drops slowly, by 2 points per year.

==== Bonus for AI companies =====

{| |-
!AI intelligence setting!!Score (%, rounded)
|-
|Low||0 (0%)
|-
|Medium||31 (12%)
|-
|High||63 (25%)
|}

That is, AI players cheat to get good ratings for their brain-dead routes.
==== Bonus for statue in nearest town =====

If your company has erected a statue in the nearest town, you get 26 points (10%) bonus to all cargo ratings.

==== Clamping =====
If a human player does everything perfectly, the maximum rating she can get is 271 points, while the worst possible transport service gets -90 points; for "highly intelligent" AI players, the corresponding values are 334 and -27, respectively. The resulting value gets clamped to the 0..255 range. TTD makes sure the ratings change slowly, but steadily: every 2.5 days, the actual rating moves towards the value calculated above, by no more than 2 points. For example, you 'd need at least 320 days to go from 0% to 100%, even if your service is perfect. When a cargo type first appears at a station, its rating is set to 175 points (69%), so it takes some time until it gets adjusted to the actual parameters of the service.

==== Callback effect =====
The callback allows you to replace the first three components (days since last pickup, amount waiting and max. speed of last vehicle) in the calculation above. If your callback succeeds, the first three components are skipped and the returned value is used instead their results. Bit 14 is considered the sign bit, so you can return negative numbers (and need not to worry about calculated callback results yielding a negative result, as long as you stay in the range -16384..16383). During the callback, variable 18 has the value ssaaaatt, where
* tt is the time since the cargo was last picked up, in the time units described above (1 unit = 2.5 days independent of vehicle type)
* aaaa is the amount of cargo waiting
* ss is the speed of the last vehicle picking the cargo up, in the speed units described above (if no vehicle entered the station yet, the value is FFh)

The lowest byte of variable 10 contains one of the following values:

{| |-
!value!!meaning
|-
|10h||the last vehicle entering the station was a train
|-
|11h||the last vehicle entering the station was a road vehicle
|-
|12h||the last vehicle entering the station was a ship
|-
|13h||the last vehicle entering the station was an aircraft
|-
|00h||no vehicle entered the station yet, or the last one entering was sold
|}

Please note that there's only one "last vehicle" field per station, so the vehicle this refers to may not have picked up any of your cargo. The original TTD calculation doesn't care about this and just uses the field to get the vehicle type used in the first component.

Currently, you can only use variables 10 and 18 for your decision, since neither vehicle nor station variables are available for a cargo callback. As soon as the architecture of TTDPatch allows this, the callback will be given access to the station and the last vehicle that entered.
[[Category:Callbacks]]