-
-
Notifications
You must be signed in to change notification settings - Fork 130
/
script-additions.html
181 lines (172 loc) · 9.58 KB
/
script-additions.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
<!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>