You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
OpenTTD-patches/docs/script-additions.html

182 lines
9.6 KiB
HTML

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>JGR's Patchpack - Additions to Script Specifications (AI and GameScript)</title>
<style type="text/css">
td li { white-space: nowrap; text-align: left; }
th { white-space: nowrap; text-align: center; }
td, th { border: 1px solid #CCCCCC; padding: 0px 5px; }
table { border-collapse: collapse; empty-cells: show; }
.code { font-family: "Courier New", Courier, mono; color: darkgreen; }
.methodtext{ margin-left: 3em; }
.indent { margin-left: 1em; margin-bottom: 0.5em; }
dt { font-weight: bold; }
</style>
</head>
<body>
<h2>Additions to AI/GS Script Specifications in JGR's Patchpack</h2>
<p>This document describes non-standard additions to the Official OpenTTD <a href="https://docs.openttd.org/ai-api/">AI</a> and <a href="https://docs.openttd.org/gs-api/">GS</a> Specifications which are present in this patchpack.
<p>These additions MAY also be present in other patchpacks. They MAY be removed or moved in future, if necessary.</p>
<p>Scripts which use any of these features SHOULD check whether the feature is present and if not, fallback to not using it and/or emitting a clear and end-user friendly error message.<br>
Testing for the presence of methods may be done using the "in" operator.</p>
<h4 style="margin-bottom: 0px">Contents:</h4>
<ul style="margin-top: 0px">
<li><a href="#date">Date: GSDate and AIDate</a></li>
<li><a href="#marine">Marine: GSMarine and AIMarine</a></li>
<li><a href="#road">Road: GSRoad and AIRoad</a></li>
<li><a href="#company">Company: GSCompany and AICompany</a></li>
<li><a href="#inflation">Inflation: GSInflation and AIInflation</a></li>
<li><a href="#asyncmode">Command Asynchronous Mode: GSAsyncMode</a></li>
</ul>
<h3 id="date">Date: <a href="https://docs.openttd.org/gs-api/classGSDate.html">GSDate Class</a> and <a href="https://docs.openttd.org/ai-api/classAIDate.html">AIDate Class</a></h3>
<div class="indent">
<h4>Additional Static Public Member Functions:</h4>
<div class="indent">
<div class="code">static int32 GetDayLengthFactor ()</div>
<div class="methodtext">Get current day length factor.</div>
</div>
<div class="indent">
<div class="code">static bool IsTimeShownInMinutes ()</div>
<div class="methodtext">Get whether time is shown in minutes in the game settings.</div>
<div class="methodtext">This ignores the "Use client time settings instead of savegame time settings" setting.</div>
</div>
<div class="indent">
<div class="code">static int32 GetTicksPerMinute ()</div>
<div class="methodtext">Get the ticks per minutes in the game settings.</div>
<div class="methodtext">This ignores the "Use client time settings instead of savegame time settings" setting.</div>
</div>
<div class="indent">
<div class="code">static DateTicksScaled GetCurrentScaledDateTicks ()</div>
<div class="methodtext">Get the current scaled date ticks.</div>
<div class="methodtext">This increments at the same rate regardless of the day length factor.</div>
<div class="methodtext">Changing the day length factor will also change this value.</div>
</div>
<div class="indent">
<div class="code">static int32 GetHour (DateTicksScaled ticks)</div>
<div class="methodtext">Get the hour of the given scaled date ticks value.</div>
<div class="methodtext">This ignores the "Use client time settings instead of savegame time settings" setting.</div>
</div>
<div class="indent">
<div class="code">static int32 GetMinute (DateTicksScaled ticks)</div>
<div class="methodtext">Get the minute of the given scaled date ticks value.</div>
<div class="methodtext">This ignores the "Use client time settings instead of savegame time settings" setting.</div>
</div>
</div>
<h3 id="marine">Marine: <a href="https://docs.openttd.org/gs-api/classGSMarine.html">GSMarine Class</a> and <a href="https://docs.openttd.org/ai-api/classAIMarine.html">AIMarine Class</a></h3>
<div class="indent">
<h4>Additional Static Public Member Functions:</h4>
<div class="indent">
<div class="code">static bool BuildRiver (TileIndex tile)</div>
<div class="methodtext">Builds a river on tile (subject to permissions/settings).</div>
<div class="methodtext">All other details are the same as BuildCanal.</div>
</div>
</div>
<h3 id="road">Road: <a href="https://docs.openttd.org/gs-api/classGSRoad.html">GSRoad Class</a> and <a href="https://docs.openttd.org/ai-api/classAIRoad.html">AIRoad Class</a></h3>
<div class="indent">
<h4>Additional Static Public Member Functions:</h4>
<div class="indent">
<div class="code">static bool HasRoadTramType(TileIndex tile, RoadTramTypes road_tram_type)</div>
<div class="methodtext">Check if a tile has the given road tram type.</div>
</div>
<div class="indent">
<div class="code">static RoadType GetRoadType(TileIndex tile, RoadTramTypes road_tram_type)</div>
<div class="methodtext">Get the RoadType that is used on a tile.</div>
</div>
<div class="indent">
<div class="code">static bool IsCatenaryRoadType(RoadType roadtype)</div>
<div class="methodtext">Checks whether the given road type uses a catenary.</div>
</div>
<div class="indent">
<div class="code">static bool IsNonLevelCrossingRoadType(RoadType roadtype)</div>
<div class="methodtext">Checks whether the given road type disallows level crossings.</div>
</div>
<div class="indent">
<div class="code">static bool IsNoTownHousesRoadType(RoadType roadtype)</div>
<div class="methodtext">Checks whether the given road type cannot be used by towns to build houses.</div>
</div>
<div class="indent">
<div class="code">static bool IsTownBuildableRoadType(RoadType roadtype)</div>
<div class="methodtext">Checks whether the given road type is buildable by towns.</div>
</div>
<div class="indent">
<div class="code">static RoadPieces GetRoadPieces(TileIndex tile, RoadTramTypes road_tram_type)</div>
<div class="methodtext">Get the RoadPieces that are on a tile.</div>
</div>
<div class="indent">
<div class="code">static OneWayInfo GetOneWayInfo(TileIndex tile)</div>
<div class="methodtext">Get info about the one-way state of a tile.</div>
</div>
</div>
<h3 id="company">Company: <a href="https://docs.openttd.org/gs-api/classGSCompany.html">GSCompany Class</a> and <a href="https://docs.openttd.org/ai-api/classAICompany.html">AICompany Class</a></h3>
<div class="indent">
<h4>Additional Static Public Member Functions:</h4>
<div class="indent">
<div class="code">static bool GetAnnualExpenseValue (CompanyID company, uint32 year_offset, ExpensesType expenses_type)</div>
<div class="methodtext">Get the annual expense value for the given company.</div>
<div class="methodtext">year_offset is relative to the current year and must be either: 0, 1, or 2.</div>
</div>
<h4>Additional Enum Values:</h4>
<div class="indent">
<div class="code">ExpensesType</div>
<div>Additional value: <span class="code">EXPENSES_SHARING_COST</span></div>
<div class="methodtext">Infrastructure sharing costs.</div>
<div>Additional value: <span class="code">EXPENSES_SHARING_INC</span></div>
<div class="methodtext">Infrastructure sharing income.</div>
<div>ExpensesType is additionally available via AICompany.</div>
</div>
</div>
<h3 id="inflation">Inflation: GSInflation Class and AIInflation Class</h3>
<div class="indent">
<h4>Static Public Member Functions:</h4>
<div class="indent">
<div class="code">static int64 GetPriceFactor ()</div>
<div class="methodtext">Get the inflation factor for prices.</div>
<div class="methodtext">Returns the inflation factor as a fixed point value (16 bits).</div>
</div>
<div class="indent">
<div class="code">static int64 GetPaymentFactor ()</div>
<div class="methodtext">Get the inflation factor for payments.</div>
<div class="methodtext">Returns the inflation factor as a fixed point value (16 bits).</div>
</div>
<div class="indent">
<div class="code">static bool SetPriceFactor (int64 factor)</div>
<div class="methodtext">Set the inflation factor for prices (GS only).</div>
<div class="methodtext">The inflation factor is a fixed point value (16 bits).</div>
</div>
<div class="indent">
<div class="code">static bool SetPaymentFactor (int64 factor)</div>
<div class="methodtext">Set the inflation factor for payments (GS only).</div>
<div class="methodtext">The inflation factor is a fixed point value (16 bits).</div>
</div>
</div>
<h3 id="asyncmode">Command Asynchronous Mode: GSAsyncMode Class</h3>
<div class="indent">
<h4>Public Constructor:</h4>
<div class="indent">
<div class="code">GSAsyncMode (bool asynchronous)</div>
<div class="methodtext">Creating an instance of this class switches the asynchronous execution mode for commands.</div>
<div class="methodtext">
A value of true sets the mode to Asynchronous, the commands you execute are queued for later execution, and the script
is not delayed waiting for the command result. The estimated result is returned to the script.
The actual cost and whether the command succeeded when the command is eventually executed may differ from what was returned to the script.
</div>
<div class="methodtext">
A value of false sets the mode to Non-Asynchronous, this is the normal mode of executing commands.
</div>
<div class="methodtext">The original mode is stored and recovered from when ever the instance is destroyed.</div>
<div class="methodtext">Use in a similar way to the <a href="https://docs.openttd.org/gs-api/classGSTestMode.html">GSTestMode class</a>.</div>
</div>
</div>
</body>
</html>