Script API and Wallclock time

[frosch123]

There are some rumours and myths about the Script API, and how it interacts with the new wallclock time.

Current status:

• ScriptDate returns EconomyTime by default. ScriptTimeMode can temporarily change it to CalendarTime.
• Other API methods return either EconomyTime or CalendarTime, since only one makes sense in each case.
• Most scripts use EconomyTime, CalendarTime is actually rarely needed. (citation needed)

General problems are:

• API methods do not document, which time they use. The documentation should be enhanced.
• GS often show dates and time-spans to the user. While the GS are likely to technically work with EconomyTime, the display is confusing. Nothing we can really fix, the GS must be updated.
• Some scripts assume the absolute year to be in a certain range, e.g. 4 digits, or 1900+.

[frosch123]

API methods using calendar dates:

• ScriptBaseStation.GetConstructionDate
• ScriptEngine.GetDesignDate
• ScriptIndustry.GetConstructionDate
• ScriptStoryPage.GetDate
• ScriptStoryPage.SetDate

[TrueBrain]

Usage numbers, based on "grep" over all sources.

GetConstructionDate
      4 ai
      3 game-script
GetDesignDate
     11 ai
      3 game-script
GetDate
     21 ai-library
     73 ai
     13 game-script-library
     58 game-script
SetDate
     10 game-script
---
Station.GetConstructionDate(
      4 ai
      1 game-script
Engine.GetDesignDate(
      5 ai
      1 game-script
Industry.GetConstructionDate(
StoryPage.GetDate(
StoryPage.SetDate(
      9 game-script

GetDate is an invalid result, as my simple grep returned more hits than required.

[frosch123]

The purpose of these two methods is unclear, and so is their time base:

• ScriptBaseStation.GetConstructionDate
  • This property is reset to current date, whenever the station is modified.
  • Awards GS actually uses it to detect "long service", which assumes a different meaning.
  • Some AIs use it to avoid touching a new station, and wait until service is stable.
  • Both use-cases assume economy-time, but one assumes "first construction", the other "last modification".
• ScriptIndustry.GetConstructionDate
  • Currently unused by any script.
  • There is also ScriptIndustry::GetLastProductionYear which uses economy-time, and has a meaning for default processing industries.

So, maybe both methods should just be deprecated.

[frosch123]

API methods using time-spans from calendar:

• ScriptEngine.GetMaxAge
• ScriptVehicle.GetMaxAge
• ScriptVehicle.GetWagonAge
• ScriptVehicle.GetAge
• ScriptVehicle.GetAgeLeft
• ScriptOrder.OrderCondition.OC_AGE
• ScriptOrder.OrderCondition.OC_REMAINING_LIFETIME

[TrueBrain]

Usage numbers, based on "grep" over all sources.

GetMaxAge
      1 ai-library
     19 ai
      1 game-script-library
      3 game-script
GetAge
     49 ai
      3 game-script
GetAgeLeft
     25 ai
      2 game-script
OC_AGE
      5 ai
      2 game-script
OC_REMAINING_LIFETIME
      2 ai
      2 game-script
---
Engine.GetMaxAge(
      1 ai-library
      9 ai
      1 game-script-library
Vehicle.GetMaxAge(
     11 ai
      1 game-script
Vehicle.GetAge(
     27 ai
Vehicle.GetAgeLeft(
     12 ai
OC_AGE
      5 ai
      2 game-script
OC_REMAINING_LIFETIME
      2 ai
      2 game-script

[frosch123]

API methods depending on ScriptTimeMode:

• ScriptDate.GetCurrentDate
• ScriptSubsidy::GetExpireDate: actually broken, should always use economy dates.

[frosch123]

@2TallTyler Just checking my understanding: Can you confirm?

• Currently ScriptSubsidy::GetExpireDate adds economy-months to ScriptDate::GetDate.
• If ScriptTimeMode is set to CalendarTime, this will add economy-months to a calendar-date, which makes no sense.
• Instead the method should always return an economy-date.

[TrueBrain]

Usage numbers, based on "grep" over all sources.

GetCurrentDate
      3 ai-library
     49 ai
      2 game-script-library
     45 game-script
GetExpireDate
      7 ai
      2 game-script
---
Date.GetCurrentDate(
      3 ai-library
     48 ai
      2 game-script-library
     43 game-script
Subsidy.GetExpireDate(
      5 ai

[2TallTyler]

Yes, your diagnosis is correct. Everything related to ScriptSubsidy should be in economy time.

[frosch123]

API methods using economy dates:

• ScriptIndustry.GetLastProductionYear
• ScriptIndustry.GetCargoLastAcceptedDate
• ScriptClient.GetJoinDate

[TrueBrain]

Usage numbers, based on "grep" over all sources.

GetLastProductionYear
      1 game-script
GetCargoLastAcceptedDate
      1 game-script
GetJoinDate
      1 game-script
---
Industry.GetLastProductionYear(
Industry.GetCargoLastAcceptedDate(
Client.GetJoinDate(

All three the same game-script, named RemoteGS.

[frosch123]

API suggestion: (revival of #11588)

• Deprecate ScriptTimeMode, remove it in OpenTTD 15.
• Deprecate ScriptDate, remove it in OpenTTD 15.
• Add ScriptCalendarDate and ScriptEconomyDate instead.
  • Script*Date::GetDaysInYear or similar to assist converting economy-days into economy-years, as returned by various API methods.
• Compatiblity scripts continue to provide ScriptDate.

Reasoning:

• Switching TimeMode only affects ScriptDate, so it is not really a global operation.
• Switching TimeMode only for ScriptDate is error-prone.
• Other API methods use fixed timemodes, using separate ScriptCalendarDate and ScriptEconomyDate makes it easier to compare dates with values returnes from other API methods.

[PeterN]

To be honest, if ScriptTimeMode is to be removed, I think it should just go instead of leaving it around as deprecated. It's only been in the API for a short amount of time, and not in any proper release.

[andythenorth]

Tend to agree. I've implemented ScriptTimeMode in FIRS GS (to work around Industry construction date), but that's unreleased. Have any other scripts appeared on Bananas with it?

[frosch123]

API methods in context of economy-years:

• ScriptEventEnginePreview.GetRunningCost
• ScriptEngine.GetRunningCost
• ScriptVehicle.GetRunningCost
• ScriptVehicle.GetProfitThisYear
• ScriptVehicle.GetProfitLastYear
• ScriptGroup.GetProfitThisYear
• ScriptGroup.GetProfitLastYear

API methods in context of economy-quarters:

• ScriptCompany.GetQuarterlyIncome
• ScriptCompany.GetQuarterlyExpenses
• ScriptCompany.GetQuarterlyCargoDelivered
• ScriptCompany.GetQuarterlyPerformanceRating
• ScriptCompany.GetQuarterlyCompanyValue

API methods in context of economy-months:

• ScriptInfrastructure.GetMonthlyRailCosts
• ScriptInfrastructure.GetMonthlyRoadCosts
• ScriptInfrastructure.GetMonthlyInfrastructureCosts
• ScriptAirport.GetMonthlyMaintenanceCost
• ScriptIndustry.GetLastMonthProduction
• ScriptIndustry.GetLastMonthTransported
• ScriptIndustry.GetLastMonthTransportedPercentage
• ScriptTown.GetLastMonthProduction
• ScriptTown.GetLastMonthSupplied
• ScriptTown.GetLastMonthTransportedPercentage
• ScriptTown.GetLastMonthReceived
• ScriptTown.GetRoadReworkDuration
• ScriptTown.GetFundBuildingsDuration
• ScriptTown.GetExclusiveRightsDuration
• ScriptTown.SetCargoGoal
• ScriptTown.GetCargoGoal

API methods in context of economy-days:

• ScriptTown.SetGrowthRate
• ScriptTown.GetGrowthRate

[frosch123]

API methods in context of calendar-months:

• ScriptCompany.SetAutoRenewMonths
• ScriptCompany.GetAutoRenewMonths