mirror
/
OpenTTD
mirror of https://github.com/OpenTTD/OpenTTD
1
0
Fork 0
Code Issues

Doc: [Script] Extend API documentation on calendar- vs economy-time

pull/12653/head
frosch 2024-03-23 21:34:31 +01:00 committed by Peter Nelson
parent 04cc0c8125
commit dc22edc556
15 changed files with 154 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/script/api/script_airport.hpp
View File

@ -204,7 +204,8 @@ public:
* Get the monthly maintenance cost of an airport type.
* @param type The airport type to get the monthly maintenance cost of.
* @pre IsAirportInformationAvailable(type)
* @return Monthly maintenance cost of the airport type.
* @return Maintenance cost of the airport type per economy-month.
* @see \ref ScriptEconomyTime
*/
static Money GetMonthlyMaintenanceCost(AirportType type);

5
src/script/api/script_basestation.hpp
View File

@ -68,9 +68,10 @@ public:
static TileIndex GetLocation(StationID station_id);
/**
* Get the last date a station part was added to this station.
* Get the last calendar-date a station part was added to this station.
* @param station_id The station to look at.
* @return The last date some part of this station was build.
* @return The last calendar-date some part of this station was build.
* @see \ref ScriptCalendarTime
*/
static ScriptDate::Date GetConstructionDate(StationID station_id);
};

5
src/script/api/script_client.hpp
View File

@ -56,10 +56,11 @@ public:
static ScriptCompany::CompanyID GetCompany(ClientID client);
/**
* Get the game date when the given client has joined.
* Get the economy-date when the given client has joined.
* @param client The client to get joining date for.
* @pre ResolveClientID(client) != CLIENT_INVALID.
* @return The date when client has joined.
* @return The economy-date when client has joined.
* @see \ref ScriptEconomyTime
*/
static ScriptDate::Date GetJoinDate(ClientID client);
};

43
src/script/api/script_company.hpp
View File

@ -281,59 +281,64 @@ public:
static bool ChangeBankBalance(CompanyID company, Money delta, ExpensesType expenses_type, TileIndex tile);
/**
* Get the income of the company in the given quarter.
* Get the income of the company in the given economy-quarter.
* Note that this function only considers recurring income from vehicles;
* it does not include one-time income from selling stuff.
* @param company The company to get the quarterly income of.
* @param quarter The quarter to get the income of.
* @param quarter The economy-quarter to get the income of.
* @pre ResolveCompanyID(company) != COMPANY_INVALID.
* @pre quarter <= EARLIEST_QUARTER.
* @return The gross income of the company in the given quarter.
* @return The gross income of the company in the given economy-quarter.
* @see \ref ScriptEconomyTime
*/
static Money GetQuarterlyIncome(CompanyID company, SQInteger quarter);
/**
* Get the expenses of the company in the given quarter.
* Get the expenses of the company in the given economy-quarter.
* Note that this function only considers recurring expenses from vehicle
* running cost, maintenance and interests; it does not include one-time
* expenses from construction and buying stuff.
* @param company The company to get the quarterly expenses of.
* @param quarter The quarter to get the expenses of.
* @param quarter The economy-quarter to get the expenses of.
* @pre ResolveCompanyID(company) != COMPANY_INVALID.
* @pre quarter <= EARLIEST_QUARTER.
* @return The expenses of the company in the given quarter.
* @return The expenses of the company in the given economy-quarter.
* @see \ref ScriptEconomyTime
*/
static Money GetQuarterlyExpenses(CompanyID company, SQInteger quarter);
/**
* Get the amount of cargo delivered by the given company in the given quarter.
* Get the amount of cargo delivered by the given company in the given economy-quarter.
* @param company The company to get the amount of delivered cargo of.
* @param quarter The quarter to get the amount of delivered cargo of.
* @param quarter The economy-quarter to get the amount of delivered cargo of.
* @pre ResolveCompanyID(company) != COMPANY_INVALID.
* @pre quarter <= EARLIEST_QUARTER.
* @return The amount of cargo delivered by the given company in the given quarter.
* @return The amount of cargo delivered by the given company in the given economy-quarter.
* @see \ref ScriptEconomyTime
*/
static SQInteger GetQuarterlyCargoDelivered(CompanyID company, SQInteger quarter);
/**
* Get the performance rating of the given company in the given quarter.
* Get the performance rating of the given company in the given economy-quarter.
* @param company The company to get the performance rating of.
* @param quarter The quarter to get the performance rating of.
* @param quarter The economy-quarter to get the performance rating of.
* @pre ResolveCompanyID(company) != COMPANY_INVALID.
* @pre quarter <= EARLIEST_QUARTER.
* @pre quarter != CURRENT_QUARTER.
* @note The performance rating is calculated after every quarter, so the value for CURRENT_QUARTER is undefined.
* @return The performance rating of the given company in the given quarter.
* @note The performance rating is calculated after every economy-quarter, so the value for CURRENT_QUARTER is undefined.
* @return The performance rating of the given company in the given economy-quarter.
* @see \ref ScriptEconomyTime
*/
static SQInteger GetQuarterlyPerformanceRating(CompanyID company, SQInteger quarter);
/**
* Get the value of the company in the given quarter.
* Get the value of the company in the given economy-quarter.
* @param company The company to get the value of.
* @param quarter The quarter to get the value of.
* @param quarter The economy-quarter to get the value of.
* @pre ResolveCompanyID(company) != COMPANY_INVALID.
* @pre quarter <= EARLIEST_QUARTER.
* @return The value of the company in the given quarter.
* @return The value of the company in the given economy-quarter.
* @see \ref ScriptEconomyTime
*/
static Money GetQuarterlyCompanyValue(CompanyID company, SQInteger quarter);
@ -377,10 +382,11 @@ public:
/**
* Set the number of months before/after max age to autorenew an engine for your company.
* @param months The new months between autorenew.
* @param months The number of calendar-months before/after max age of engine.
* The value will be clamped to MIN(int16_t) .. MAX(int16_t).
* @game @pre ScriptCompanyMode::IsValid().
* @return True if autorenew months has been modified.
* @see \ref ScriptCalendarTime
*/
static bool SetAutoRenewMonths(SQInteger months);
@ -388,7 +394,8 @@ public:
* Return the number of months before/after max age to autorenew an engine for a company.
* @param company The company to get the autorenew months of.
* @pre ResolveCompanyID(company) != COMPANY_INVALID.
* @return The months before/after max age of engine.
* @return The number of calendar-months before/after max age of engine.
* @see \ref ScriptCalendarTime
*/
static SQInteger GetAutoRenewMonths(CompanyID company);

24
src/script/api/script_date.hpp
View File

@ -23,6 +23,30 @@
* @note Dates can be used to determine the number of days between
* two different moments in time because they count the number
* of days since the year 0.
*
* \anchor ScriptCalendarTime
* \b Calendar-Time
*
* Calendar time measures the technological progression in the game.
* \li The calendar date is shown in the status bar.
* \li The calendar date affects engine model introduction and expiration.
* \li Progression of calendar time can be slowed or even halted via game settings.
*
* Calendar time uses the Gregorian calendar with 365 or 366 days per year.
*
* \anchor ScriptEconomyTime
* \b Economy-Time
*
* Economy time measures the in-game time progression, while the game is not paused.
* \li Cargo production and consumption follows economy time.
* \li Recurring income and expenses follow economy time.
* \li Production and income statistics and balances are created per economy month/quarter/year.
*
* Depending on game settings economy time is represented differently:
* \li Calendar-based timekeeping: Economy- and calendar-time use the identical Gregorian calendar.
* \li Wallclock-based timekeeping: Economy- and calendar-time are separate.
* Economy-time will use a 360 day calendar (12 months with 30 days each), which runs at a constant speed of one economy-month per realtime-minute.
* Calendar-time will use a Gregorian calendar, which can be slowed to stopped via game settings.
*/
class ScriptDate : public ScriptObject {
public:

13
src/script/api/script_engine.hpp
View File

@ -125,8 +125,8 @@ public:
* Get the maximum age of a brand new engine.
* @param engine_id The engine to get the maximum age of.
* @pre IsValidEngine(engine_id).
* @returns The maximum age of a new engine in days.
* @note Age is in days; divide by 366 to get per year.
* @returns The maximum age of a new engine in calendar-days.
* @see \ref ScriptCalendarTime
*/
static SQInteger GetMaxAge(EngineID engine_id);
@ -134,8 +134,8 @@ public:
* Get the running cost of an engine.
* @param engine_id The engine to get the running cost of.
* @pre IsValidEngine(engine_id).
* @return The running cost of a vehicle per year.
* @note Cost is per year; divide by 365 to get per day.
* @return The running cost of a vehicle per economy-year.
* @see \ref ScriptEconomyTime
*/
static Money GetRunningCost(EngineID engine_id);
@ -167,10 +167,11 @@ public:
static SQInteger GetMaxTractiveEffort(EngineID engine_id);
/**
* Get the date this engine was designed.
* Get the calendar-date this engine was designed.
* @param engine_id The engine to get the design date of.
* @pre IsValidEngine(engine_id).
* @return The date this engine was designed.
* @return The calendar-date this engine was designed.
* @see \ref ScriptCalendarTime
*/
static ScriptDate::Date GetDesignDate(EngineID engine_id);

4
src/script/api/script_event_types.hpp
View File

@ -272,8 +272,8 @@ public:
/**
* Get the running cost of the offered engine.
* @return The running cost of the vehicle per year.
* @note Cost is per year; divide by 365 to get per day.
* @return The running cost of the vehicle per economy-year.
* @see \ref ScriptEconomyTime
*/
Money GetRunningCost();

6
src/script/api/script_group.hpp
View File

@ -222,7 +222,8 @@ public:
* Get the current profit of a group.
* @param group_id The group to get the profit of.
* @pre IsValidGroup(group_id).
* @return The current profit the group has.
* @return The profit the vehicles in this group have made this economy-year so far.
* @see \ref ScriptEconomyTime
*/
static Money GetProfitThisYear(GroupID group_id);
@ -230,7 +231,8 @@ public:
* Get the profit of last year of a group.
* @param group_id The group to get the profit of.
* @pre IsValidGroup(group_id).
* @return The current profit the group had last year.
* @return The profit the vehicles in this group made in the previous economy-year.
* @see \ref ScriptEconomyTime
*/
static Money GetProfitLastYear(GroupID group_id);

30
src/script/api/script_industry.hpp
View File

@ -86,10 +86,11 @@ public:
static std::optional<std::string> GetName(IndustryID industry_id);
/**
* Get the construction date of an industry.
* Get the construction calendar-date of an industry.
* @param industry_id The index of the industry.
* @pre IsValidIndustry(industry_id).
* @return Date the industry was constructed.
* @return Calendar-date the industry was constructed.
* @see \ref ScriptCalendarTime
* @api -ai
*/
static ScriptDate::Date GetConstructionDate(IndustryID industry_id);
@ -126,32 +127,35 @@ public:
static SQInteger GetStockpiledCargo(IndustryID industry_id, CargoID cargo_id);
/**
* Get the total last month's production of the given cargo at an industry.
* Get the total last economy-month's production of the given cargo at an industry.
* @param industry_id The index of the industry.
* @param cargo_id The index of the cargo.
* @pre IsValidIndustry(industry_id).
* @pre ScriptCargo::IsValidCargo(cargo_id).
* @return The last month's production of the given cargo for this industry.
* @return The last economy-month's production of the given cargo for this industry.
* @see \ref ScriptEconomyTime
*/
static SQInteger GetLastMonthProduction(IndustryID industry_id, CargoID cargo_id);
/**
* Get the total amount of cargo transported from an industry last month.
* Get the total amount of cargo transported from an industry last economy-month.
* @param industry_id The index of the industry.
* @param cargo_id The index of the cargo.
* @pre IsValidIndustry(industry_id).
* @pre ScriptCargo::IsValidCargo(cargo_id).
* @return The amount of given cargo transported from this industry last month.
* @return The amount of given cargo transported from this industry last economy-month.
* @see \ref ScriptEconomyTime
*/
static SQInteger GetLastMonthTransported(IndustryID industry_id, CargoID cargo_id);
/**
* Get the percentage of cargo transported from an industry last month.
* Get the percentage of cargo transported from an industry last economy-month.
* @param industry_id The index of the industry.
* @param cargo_id The index of the cargo.
* @pre IsValidIndustry(industry_id).
* @pre ScriptCargo::IsValidCargo(cargo_id).
* @return The percentage of given cargo transported from this industry last month.
* @return The percentage of given cargo transported from this industry last economy-month.
* @see \ref ScriptEconomyTime
*/
static SQInteger GetLastMonthTransportedPercentage(IndustryID industry_id, CargoID cargo_id);
@ -246,21 +250,23 @@ public:
static IndustryType GetIndustryType(IndustryID industry_id);
/**
* Get the last year this industry had any production output.
* Get the last economy-year this industry had any production output.
* @param industry_id The index of the industry.
* @pre IsValidIndustry(industry_id).
* @return Year the industry last had production, 0 if error.
* @return Economy-year the industry last had production, 0 if error.
* @see \ref ScriptEconomyTime
* @api -ai
*/
static SQInteger GetLastProductionYear(IndustryID industry_id);
/**
* Get the last date this industry accepted any cargo delivery.
* Get the last economy-date this industry accepted any cargo delivery.
* @param industry_id The index of the industry.
* @param cargo_type The cargo to query, or INVALID_CARGO to query latest of all accepted cargoes.
* @pre IsValidIndustry(industry_id).
* @pre IsValidCargo(cargo_type) || cargo_type == INVALID_CARGO.
* @return Date the industry last received cargo from a delivery, or ScriptDate::DATE_INVALID on error.
* @return Economy-date the industry last received cargo from a delivery, or ScriptDate::DATE_INVALID on error.
* @see \ref ScriptEconomyTime
* @api -ai
*/
static ScriptDate::Date GetCargoLastAcceptedDate(IndustryID industry_id, CargoID cargo_type);

9
src/script/api/script_infrastructure.hpp
View File

@ -58,7 +58,8 @@ public:
* Return the monthly maintenance costs of a specific rail type for a company.
* @param company The company to get the monthly cost for.
* @param railtype Rail type to get the cost of.
* @return Monthly maintenance cost for the rail type.
* @return Maintenance cost for the rail type per economy-month.
* @see \ref ScriptEconomyTime
*/
static Money GetMonthlyRailCosts(ScriptCompany::CompanyID company, ScriptRail::RailType railtype);
@ -66,7 +67,8 @@ public:
* Return the monthly maintenance costs of a specific road type for a company.
* @param company The company to get the monthly cost for.
* @param roadtype Road type to get the cost of.
* @return Monthly maintenance cost for the road type.
* @return Maintenance cost for the road type per economy-month.
* @see \ref ScriptEconomyTime
*/
static Money GetMonthlyRoadCosts(ScriptCompany::CompanyID company, ScriptRoad::RoadType roadtype);
@ -74,8 +76,9 @@ public:
* Return the monthly maintenance costs of an infrastructure category for a company.
* @param company The company to get the monthly cost for.
* @param infra_type Infrastructure category to get the cost of.
* @return Monthly maintenance cost for the wanted category.
* @return Maintenance cost for the wanted category per economy-month.
* @note #INFRASTRUCTURE_RAIL and #INFRASTRUCTURE_ROAD return the total cost for all rail/road types.
* @see \ref ScriptEconomyTime
*/
static Money GetMonthlyInfrastructureCosts(ScriptCompany::CompanyID company, Infrastructure infra_type);
};

4
src/script/api/script_order.hpp
View File

@ -93,10 +93,10 @@ public:
OC_RELIABILITY = ::OCV_RELIABILITY, ///< Skip based on the reliability, value is percent (0..100).
OC_MAX_RELIABILITY = ::OCV_MAX_RELIABILITY, ///< Skip based on the maximum reliability. Value in percent
OC_MAX_SPEED = ::OCV_MAX_SPEED, ///< Skip based on the maximum speed, value is in OpenTTD's internal speed unit, see ScriptEngine::GetMaxSpeed.
OC_AGE = ::OCV_AGE, ///< Skip based on the age, value is in years.
OC_AGE = ::OCV_AGE, ///< Skip based on the age, value is in calender-years. @see \ref ScriptCalendarTime
OC_REQUIRES_SERVICE = ::OCV_REQUIRES_SERVICE, ///< Skip when the vehicle requires service, no value.
OC_UNCONDITIONALLY = ::OCV_UNCONDITIONALLY, ///< Always skip, no compare function, no value.
OC_REMAINING_LIFETIME = ::OCV_REMAINING_LIFETIME, ///< Skip based on the remaining lifetime
OC_REMAINING_LIFETIME = ::OCV_REMAINING_LIFETIME, ///< Skip based on the remaining lifetime in calendar-years. @see \ref ScriptCalendarTime
/* Custom added value, only valid for this API */
OC_INVALID = -1, ///< An invalid condition, do not use.

6
src/script/api/script_story_page.hpp
View File

@ -265,18 +265,20 @@ public:
/**
* Get the page date which is displayed at the top of each page.
* @param story_page_id The story page to get the date of.
* @return The date
* @return The calendar-date
* @pre IsValidStoryPage(story_page_id).
* @see \ref ScriptCalendarTime
*/
static ScriptDate::Date GetDate(StoryPageID story_page_id);
/**
* Update date of a story page. The date is shown in the top left of the page
* @param story_page_id The story page to set the date for.
* @param date Date to display at the top of story page or ScriptDate::DATE_INVALID to disable showing date on this page. (also, @see ScriptDate)
* @param date Calendar-date to display at the top of story page or ScriptDate::DATE_INVALID to disable showing date on this page. (also, @see ScriptDate)
* @return True if the action succeeded.
* @pre ScriptCompanyMode::IsDeity().
* @pre IsValidStoryPage(story_page_id).
* @see \ref ScriptCalendarTime
*/
static bool SetDate(StoryPageID story_page_id, ScriptDate::Date date);

7
src/script/api/script_subsidy.hpp
View File

@ -74,14 +74,15 @@ public:
static ScriptCompany::CompanyID GetAwardedTo(SubsidyID subsidy_id);
/**
* Get the date this subsidy expires. In case the subsidy is already
* awarded, return the date the subsidy expires, else, return the date the
* Get the economy-date this subsidy expires. In case the subsidy is already
* awarded, return the economy-date the subsidy expires, else, return the economy-date the
* offer expires.
* @param subsidy_id The SubsidyID to check.
* @pre IsValidSubsidy(subsidy_id).
* @return The last valid date of this subsidy.
* @return The last valid economy-date of this subsidy.
* @note The return value of this function will change if the subsidy is
* awarded.
* @see \ref ScriptEconomyTime
*/
static ScriptDate::Date GetExpireDate(SubsidyID subsidy_id);

58
src/script/api/script_town.hpp
View File

@ -48,7 +48,8 @@ public:
TOWN_ACTION_ADVERTISE_LARGE = 2,
/**
* Rebuild the roads of this town for 6 months.
* Rebuild the roads of this town for 6 economy-months.
* @see \ref ScriptEconomyTime
*/
TOWN_ACTION_ROAD_REBUILD = 3,
@ -58,12 +59,14 @@ public:
TOWN_ACTION_BUILD_STATUE = 4,
/**
* Fund the creation of extra buildings for 3 months.
* Fund the creation of extra buildings for 3 economy-months.
* @see \ref ScriptEconomyTime
*/
TOWN_ACTION_FUND_BUILDINGS = 5,
/**
* Buy exclusive rights for this town for 12 months.
* Buy exclusive rights for this town for 12 economy-months.
* @see \ref ScriptEconomyTime
*/
TOWN_ACTION_BUY_RIGHTS = 6,
@ -191,92 +194,100 @@ public:
static TileIndex GetLocation(TownID town_id);
/**
* Get the total last month's production of the given cargo at a town.
* Get the total last economy-month's production of the given cargo at a town.
* @param town_id The index of the town.
* @param cargo_id The index of the cargo.
* @pre IsValidTown(town_id).
* @pre ScriptCargo::IsValidCargo(cargo_id).
* @return The last month's production of the given cargo for this town.
* @return The last economy-month's production of the given cargo for this town.
* @see \ref ScriptEconomyTime
*/
static SQInteger GetLastMonthProduction(TownID town_id, CargoID cargo_id);
/**
* Get the total amount of cargo supplied from a town last month.
* Get the total amount of cargo supplied from a town last economy-month.
* @param town_id The index of the town.
* @param cargo_id The index of the cargo.
* @pre IsValidTown(town_id).
* @pre ScriptCargo::IsValidCargo(cargo_id).
* @return The amount of cargo supplied for transport from this town last month.
* @return The amount of cargo supplied for transport from this town last economy-month.
* @see \ref ScriptEconomyTime
*/
static SQInteger GetLastMonthSupplied(TownID town_id, CargoID cargo_id);
/**
* Get the percentage of transported production of the given cargo at a town.
* Get the percentage of transported production of the given cargo at a town last economy-month.
* @param town_id The index of the town.
* @param cargo_id The index of the cargo.
* @pre IsValidTown(town_id).
* @pre ScriptCargo::IsValidCargo(cargo_id).
* @return The percentage of given cargo transported from this town last month.
* @return The percentage of given cargo transported from this town last economy-month.
* @see \ref ScriptEconomyTime
*/
static SQInteger GetLastMonthTransportedPercentage(TownID town_id, CargoID cargo_id);
/**
* Get the total amount of cargo effects received by a town last month.
* Get the total amount of cargo effects received by a town last economy-month.
* @param town_id The index of the town.
* @param towneffect_id The index of the cargo.
* @pre IsValidTown(town_id).
* @pre ScriptCargo::IsValidTownEffect(cargo_id).
* @return The amount of cargo received by this town last month for this cargo effect.
* @return The amount of cargo received by this town last economy-month for this cargo effect.
* @see \ref ScriptEconomyTime
*/
static SQInteger GetLastMonthReceived(TownID town_id, ScriptCargo::TownEffect towneffect_id);
/**
* Set the goal of a cargo for this town.
* Set the goal of a cargo per economy-month for this town.
* @param town_id The index of the town.
* @param towneffect_id The index of the towneffect.
* @param goal The new goal.
* @param goal The new goal amount for cargo delivered per economy-month.
* The value will be clamped to 0 .. MAX(uint32_t).
* @pre IsValidTown(town_id).
* @pre ScriptCargo::IsValidTownEffect(towneffect_id).
* @pre ScriptCompanyMode::IsDeity().
* @return True if the action succeeded.
* @see \ref ScriptEconomyTime
* @api -ai
*/
static bool SetCargoGoal(TownID town_id, ScriptCargo::TownEffect towneffect_id, SQInteger goal);
/**
* Get the amount of cargo that needs to be delivered (per TownEffect) for a
* Get the amount of cargo per economy-month that needs to be delivered (per TownEffect) for a
* town to grow. All goals need to be reached before a town will grow.
* @param town_id The index of the town.
* @param towneffect_id The index of the towneffect.
* @pre IsValidTown(town_id).
* @pre ScriptCargo::IsValidTownEffect(towneffect_id).
* @return The goal of the cargo.
* @return The goal of the cargo (amount per economy-month).
* @note Goals can change over time. For example with a changing snowline, or
* with a growing town.
* @see \ref ScriptEconomyTime
*/
static SQInteger GetCargoGoal(TownID town_id, ScriptCargo::TownEffect towneffect_id);
/**
* Set the amount of days between town growth.
* Set the amount of economy-days between town growth.
* @param town_id The index of the town.
* @param days_between_town_growth The amount of days between town growth, TOWN_GROWTH_NONE or TOWN_GROWTH_NORMAL.
* @param days_between_town_growth The amount of economy-days between town growth, TOWN_GROWTH_NONE or TOWN_GROWTH_NORMAL.
* @pre IsValidTown(town_id).
* @pre days_between_town_growth <= 880 || days_between_town_growth == TOWN_GROWTH_NONE || days_between_town_growth == TOWN_GROWTH_NORMAL.
* @return True if the action succeeded.
* @note Even when setting a growth rate, towns only grow when the conditions for growth (SetCargoCoal) are met,
* and the game settings (economy.town_growth_rate) allow town growth at all.
* @note When changing the growth rate, the relative progress is preserved and scaled to the new rate.
* @see \ref ScriptEconomyTime
* @api -ai
*/
static bool SetGrowthRate(TownID town_id, SQInteger days_between_town_growth);
/**
* Get the amount of days between town growth.
* Get the amount of economy-days between town growth.
* @param town_id The index of the town.
* @pre IsValidTown(town_id).
* @return Amount of days between town growth, or TOWN_GROWTH_NONE.
* @return Amount of economy-days between town growth, or TOWN_GROWTH_NONE.
* @note This function does not indicate when it will grow next. It only tells you the time between growths.
* @see \ref ScriptEconomyTime
*/
static SQInteger GetGrowthRate(TownID town_id);
@ -332,8 +343,9 @@ public:
* Find out how long the town is undergoing road reconstructions.
* @param town_id The town to check.
* @pre IsValidTown(town_id).
* @return The number of months the road reworks are still going to take.
* @return The number of economy-months the road reworks are still going to take.
* The value 0 means that there are currently no road reworks.
* @see \ref ScriptEconomyTime
*/
static SQInteger GetRoadReworkDuration(TownID town_id);
@ -341,8 +353,9 @@ public:
* Find out how long new buildings are still being funded in a town.
* @param town_id The town to check.
* @pre IsValidTown(town_id).
* @return The number of months building construction is still funded.
* @return The number of economy-months building construction is still funded.
* The value 0 means that there is currently no funding.
* @see \ref ScriptEconomyTime
*/
static SQInteger GetFundBuildingsDuration(TownID town_id);
@ -361,9 +374,10 @@ public:
* Find out how long the town is under influence of the exclusive rights.
* @param town_id The town to check.
* @pre IsValidTown(town_id).
* @return The number of months the exclusive rights hold.
* @return The number of economy-months the exclusive rights hold.
* The value 0 means that there are currently no exclusive rights
* given out to anyone.
* @see \ref ScriptEconomyTime
*/
static SQInteger GetExclusiveRightsDuration(TownID town_id);

26
src/script/api/script_vehicle.hpp
View File

@ -188,8 +188,8 @@ public:
* Get the current age of a vehicle.
* @param vehicle_id The vehicle to get the age of.
* @pre IsValidVehicle(vehicle_id).
* @return The current age the vehicle has.
* @note The age is in days.
* @return The current age of the vehicle in calendar-days.
* @see \ref ScriptCalendarTime
*/
static SQInteger GetAge(VehicleID vehicle_id);
@ -199,8 +199,8 @@ public:
* @param wagon The wagon in the vehicle to get the age of.
* @pre IsValidVehicle(vehicle_id).
* @pre wagon < GetNumWagons(vehicle_id).
* @return The current age the vehicle has.
* @note The age is in days.
* @return The current age of the vehicle in calendar-days.
* @see \ref ScriptCalendarTime
*/
static SQInteger GetWagonAge(VehicleID vehicle_id, SQInteger wagon);
@ -208,8 +208,8 @@ public:
* Get the maximum age of a vehicle.
* @param vehicle_id The vehicle to get the age of.
* @pre IsPrimaryVehicle(vehicle_id).
* @return The maximum age the vehicle has.
* @note The age is in days.
* @return The maximum age for the vehicle in calendar-days.
* @see \ref ScriptCalendarTime
*/
static SQInteger GetMaxAge(VehicleID vehicle_id);
@ -217,8 +217,8 @@ public:
* Get the age a vehicle has left (maximum - current).
* @param vehicle_id The vehicle to get the age of.
* @pre IsPrimaryVehicle(vehicle_id).
* @return The age the vehicle has left.
* @note The age is in days.
* @return The remaining age of the vehicle in calendar-days.
* @see \ref ScriptCalendarTime
*/
static SQInteger GetAgeLeft(VehicleID vehicle_id);
@ -245,10 +245,10 @@ public:
* Get the running cost of this vehicle.
* @param vehicle_id The vehicle to get the running cost of.
* @pre IsPrimaryVehicle(vehicle_id).
* @return The running cost of the vehicle per year.
* @note Cost is per year; divide by 365 to get per day.
* @return The running cost of the vehicle per economy-year.
* @note This is not equal to ScriptEngine::GetRunningCost for Trains, because
* wagons and second engines can add up in the calculation too.
* @see \ref ScriptEconomyTime
*/
static Money GetRunningCost(VehicleID vehicle_id);
@ -256,7 +256,8 @@ public:
* Get the current profit of a vehicle.
* @param vehicle_id The vehicle to get the profit of.
* @pre IsPrimaryVehicle(vehicle_id).
* @return The current profit the vehicle has.
* @return The profit the vehicle has made this economy-year so far.
* @see \ref ScriptEconomyTime
*/
static Money GetProfitThisYear(VehicleID vehicle_id);
@ -264,7 +265,8 @@ public:
* Get the profit of last year of a vehicle.
* @param vehicle_id The vehicle to get the profit of.
* @pre IsPrimaryVehicle(vehicle_id).
* @return The profit the vehicle had last year.
* @return The profit the vehicle made in the previous economy-year.
* @see \ref ScriptEconomyTime
*/
static Money GetProfitLastYear(VehicleID vehicle_id);