forked from JGRennison/OpenTTD-patches
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathnewgrf-additions-nml.html
794 lines (778 loc) · 39.1 KB
/
newgrf-additions-nml.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
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>JGR's Patchpack - Additions to NewGRF Specifications (NML)</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; }
span.code { font-family: "Courier New", Courier, mono; color: darkgreen; }
pre.code { font-family: "Courier New", Courier, mono; color: blue; background-color: #f8f9fa; border: 1px solid #eaecf0; padding: 1em; }
dt { font-weight: bold; }
</style>
</head>
<body>
<h2>Additions to NewGRF Specifications in JGR's Patchpack in NML</h2>
<p>This document describes non-standard additions to the <a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Main">Official OpenTTD NML Specifications</a> which are present in this patchpack and the associated <a href="https://github.com/JGRennison/nml">NML fork</a>.
<p>These additions MAY also be present in other patchpacks. They MAY be removed or moved in future, if necessary.</p>
<p>Not all standard NewGRF features are supported by NML, consequently not all non-standard additions to the specifications are supported by this patchpack's associated NML fork, or are listed in this document.<br />
See the associated <a href="newgrf-additions.html">non-NML document</a> for more details.</p>
<p>All of the non-standard features listed below will automatically emit suitable feature tests, conditionals, etc. such that NewGRFs which use these features will work correctly
on OpenTTD versions which do not support these features, including standard trunk OpenTTD and older/other patchpack versions.</p>
<p>All of the non-standard variables listed below will return 0 on OpenTTD versions which do not support these features/variables, including standard trunk OpenTTD and older/other patchpack versions.</p>
<h3>Features with separate pages</h3>
<ul>
<li><a href="newgrf-roadstops-nml.html">Road stops (FEAT_ROADSTOPS)</a></li>
<li><a href="newgrf-newlandscape-nml.html">New landscape (FEAT_NEWLANDSCAPE)</a></li>
<li><a href="newgrf-town-nml.html">Towns (the parent scope for stations, objects, etc.) (FEAT_TOWN)</a></li>
</ul>
<h3 id="sections">Sections</h3>
<ul>
<li><a href="#builtin-functions">Builtin functions</a></li>
<li><a href="#switch-types">Additional switch types</a></li>
<li><a href="#ship-callbacks">Ship callbacks</a></li>
<li><a href="#railtype-properties">Railtype properties</a></li>
<li><a href="#railtype-variables">Railtype variables</a></li>
<li><a href="#roadtype-properties">Roadtype properties</a></li>
<li><a href="#tramtype-properties">Tramtype properties</a></li>
<li><a href="#object-ids">Object IDs</a></li>
<li><a href="#object-properties">Object properties</a></li>
<li><a href="#object-variables">Object variables</a></li>
<li><a href="#airport-tile-variables">Airport tile variables</a></li>
<li><a href="#global-variable-properties">Global variables properties</a></li>
<li><a href="#replace-new-sprites">Replace new sprites</a></li>
<li><a href="#signal-graphics">Signal graphics using switches</a></li>
</ul>
<br />
<h3 id="builtin-functions"><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Builtin_functions">Builtin functions</a></h3>
<p>
<h4>extended_feature_test(feature_name[, min_version[, max_version]])</h4>
This returns true if the given extended feature is present and has a version within the specified minimum and maximum (inclusive).<br />
This function should only be used after the grf{} block.<br />
In most cases it is not necessary to use this function, as extended properties (listed below) which are not supported are simply skipped/ignored.
</p>
<h3 id="switch-types"><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Switch">Additional switch types</a></h3>
<p>
In addition to SELF and PARENT, switches for vehicle features may use one of the following types below.<br />
(These are mostly the same as in <a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Random_switch">random_switch</a>).<br />
The 'x' parameter (count x vehicles in given direction) is currently required to be a compile-time constant between 0 and 255.
<table>
<tr><th>Type</th><th>Meaning</th></tr>
<tr><td>BACKWARD_SELF(x)</td><td>Count x vehicles backward (away from the engine), starting at the vehicle itself</td></tr>
<tr><td>FORWARD_SELF(x)</td><td>Count x vehicles forward (towards the engine), starting at the vehicle itself</td></tr>
<tr><td>BACKWARD_ENGINE(x)</td><td>Count x vehicles backward, starting at the leading engine</td></tr>
<tr><td>BACKWARD_SAMEID(x)</td><td>Count x vehicles backward, starting at the first vehicle in the chain with the same ID</td></tr>
</table>
<p>These require the <span class="code">more_varaction2_types</span> feature. If this feature is not present, switches of these types will produce a CB_FAILED result.</p>
</p>
<h3 id="ship-callbacks"><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_callbacks">Ship callbacks</a></h3>
<p>
The <span class="code">articulated_part</span> callback is also available for ships.<br />
Additional ship parts are not used for graphics, they are only used for additional cargo capacity, the default graphics chain is unused.<br />
The default graphics chain for the primary vehicle may check the cargo states of the other ship parts if required.<br />
Additional ship parts may be refitted individually.
<p>This requires the <span class="code">multi_part_ships</span> feature.</p>
<p>From version 3 of the <span class="code">multi_part_ships</span> feature, spritegroup loading/loaded cargo thresholds refer to the entire ship, not just the first vehicle.</p>
</p>
<p>
Added callback: <span class="code">refit_part_name</span><br />
This callback is called on the primary vehicle to get the name of each part of the ship (e.g. the name of each cargo hold) in the refit window.<br />
This is not called for ships of only one part.<br />
The callback handler should return a string or CB_RESULT_NO_TEXT.<br />
If this callback is not handled or if CB_RESULT_NO_TEXT is returned, a default name is used.<br />
<span class="code">getbits(extra_callback_info1, 0, 8)</span> contains the index of the part of the ship. The first/primary part is 0, each subsequent part increases the value by 1.
</p>
<h3 id="railtype-properties"><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Railtypes#Railtype_properties">Railtype properties</a></h3>
<table>
<tr><th>Property</th><th>Value range</th><th>Comment</th></tr>
<tr><td>enable_programmable_pre_signals</td><td>0 or 1</td>
<td>
Enable programmable pre-signal graphics in <a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Railtypes#signals">railtype signals</a>.<br />
Programmable pre-signals have a signal type (<span class="code">getbits(extra_callback_info2, 16, 8)</span>) of 6.
</td>
</tr>
<tr><td>enable_no_entry_signals</td><td>0 or 1</td>
<td>
Enable no-entry signal graphics in <a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Railtypes#signals">railtype signals</a>.<br />
No-entry signals have a signal type (<span class="code">getbits(extra_callback_info2, 16, 8)</span>) of 7.<br />
No-entry signals always have a signal state of red.
</td>
</tr>
<tr><td>enable_restricted_signals</td><td>0 or 1</td>
<td>
Enable restricted signal flag in <a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Railtypes#signals">railtype signals</a>.<br />
When enabled, bit 24 of variable <span class="code">extra_callback_info2</span> is set if the signal is restricted (has a routing restriction program attached).<br />
When enabled, the "Show restricted electric signals using default graphics" client setting and signal post recolouring is not applied.<br />
This flag must only be set if a different sprite is returned when bit 24 of <span class="code">extra_callback_info2</span> is set.
</td>
</tr>
<tr><td>enable_signal_recolour</td><td>0 or 1</td>
<td>
Enable recolouring of graphics in <a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Railtypes#signals">railtype signals</a>.<br />
When enabled, in addition to returning a sprite, register 0x100 may be set to the following using STORE_TEMP:
<table>
<tr><th>Bits</th><th>Meaning</th></tr>
<tr><td>0 - 23</td><td>Recolour sprite to use. Set to 0 for no recolouring.</td></tr>
<tr><td>24 - 31</td><td>Reserved, set to zero.</td></tr>
</table>
<br />
If recolouring is not optional, the feature name: <span class="code">action0_railtype_recolour</span> should be checked using the
<span class="code">extended_feature_test</span> function
and if necessary a suitable fallback used or error message shown.<br />
If the OpenTTD version does not support this property/feature, then the property would ordinarily be ignored/skipped and no recolouring would be done.
</td>
</tr>
<tr><td>extra_aspects</td><td>0 - 6</td>
<td>
The value is the number of additional signal aspects to use (e.g. 4-aspect signalling should use a value of 2).<br />
When set, the lowest byte of <span class="code">extra_callback_info2</span> (signal state) may have the given number of additional values starting from 02:
<table>
<tr><th>Value</th><th>Meaning</th></tr>
<tr><td>00</td><td>Red signal</td></tr>
<tr><td>01</td><td>Green signal</td></tr>
<tr><td>02</td><td>1st extra aspect (e.g. yellow)</td></tr>
<tr><td>03</td><td>2nd extra aspect (e.g. double yellow)</td></tr>
<tr><td>...</td><td>Further extra aspects...</td></tr>
</table>
<br />
The provided value is currently clamped to be within the range 0 - 6 (inclusive).<br />
N.B. Realistic braking must be enabled for additional signal aspects to be used
</td>
</tr>
<tr><td>disable_realistic_braking</td><td>0 or 1</td>
<td>
When this property is set realistic braking is disabled for trains of this railtype even when realistic braking is otherwise in effect.
</td>
</tr>
</table>
<h3 id="railtype-variables"><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Railtypes#Railtype_variables">Railtype variables</a></h3>
<p>Variables in the table below which are not supported by the version of OpenTTD being used return a value of 0.</p>
<table>
<tr><th>Variable</th><th>Value range</th><th>Comment</th></tr>
<tr><td>signal_restriction_info</td><td>bitmask(SIGNAL_RESTRICTION_INFO_XXX, ...)</td>
<td>
Information about the restricted signal status of the signal being drawn:
<dl>
<dt>RESTRICTED</dt>
<dd>The signal is restricted (has a routing restriction program attached)</dd>
<dt>RESERVE_THROUGH_ALWAYS</dt>
<dd>The attached routing restriction program unconditionally sets reserve through</dd>
<dt>MAY_REVERSE</dt>
<dd>The attached routing restriction program may allow trains to reverse behind this signal</dd>
</dl>
</td>
</tr>
<tr><td>signal_context</td><td>SIGNAL_CONTEXT_XXX</td>
<td>
Information about the context of the signal being drawn:
<dl>
<dt>GUI</dt>
<dd>The signal is being drawn in the GUI (signal window)</dd>
<dt>TRACK</dt>
<dd>The signal is being drawn on ordinary rail track</dd>
<dt>TUNNEL_BRIDGE_ENTRANCE</dt>
<dd>The signal is being drawn as a tunnel/bridge entrance signal</dd>
<dt>TUNNEL_BRIDGE_EXIT</dt>
<dd>The signal is being drawn as a tunnel/bridge exit signal</dd>
<dt>BRIDGE_MIDDLE</dt>
<dd>The signal is being drawn on the middle of a bridge</dd>
</dl>
</td>
</tr>
<tr><td>signal_context_is_tunnel</td><td>0 or 1</td>
<td>
The signal is being drawn on a tunnel entrance/exit (not a bridge)
</td>
</tr>
<tr><td>signal_context_info</td><td></td>
<td>
Above signal context variables in one variable (all of the railtype_signal_context variable)
</td>
</tr>
<tr><td>signal_side</td><td>SIGNAL_SIDE_XXX</td>
<td>
<dl>
<dt>LEFT</dt>
<dd>Signals are on the left</dd>
<dt>RIGHT</dt>
<dd>Signals are on the right</dd>
</dl>
</td>
</tr>
<tr><td>signal_vertical_clearance</td><td>0 - 255</td>
<td>
Pixels of vertical clearance between the signal and any bridge above.<br />
If there is no bridge above, the value is 0xFF.
</td>
</tr>
<tr><td>adjacent_crossing</td><td>bitmask(RAILTYPE_ADJACENT_CROSSING_XXX, ...)</td>
<td>
Adjacent level crossing information:
<dl>
<dt>SOUTH</dt>
<dd>This level crossing tile is part of a continuous adjacent crossing with the tile to the south (SW or SE)</dd>
<dt>NORTH</dt>
<dd>This level crossing tile is part of a continuous adjacent crossing with the tile to the north (NW or NE)</dd>
</dl>
</td>
</tr>
</table>
<h3 id="roadtype-properties"><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Roadtypes#Roadtype_properties">Roadtype properties</a></h3>
<table>
<tr><th>Property</th><th>Value range</th><th>Comment</th></tr>
<tr><td>roadtype_extra_flags</td><td>bitmask(ROADTYPE_EXTRA_FLAG_XXX, ...)</td>
<td>
<dl>
<dt>NO_SCRIPT_BUILD</dt>
<dd>Scripts (AI/GS) may not build this roadtype</dd>
<dt>NO_TOWN_MODIFY</dt>
<dd>Towns may not modify tiles of this roadtype in any way whatsoever</dd>
<dt>NO_TUNNELS</dt>
<dd>Disallow tunnels for this roadtype</dd>
<dt>NO_TRAIN_COLLISION</dt>
<dd>Disallow collisions with trains for vehicles of this roadtype</dd>
</dl>
</td>
</tr>
<tr><td>roadtype_collision_mode</td><td>ROADTYPE_COLLISION_MODE_XXX</td>
<td>
Sets the road vehicle collision mode for road vehicles of this road type.
<dl>
<dt>NORMAL</dt>
<dd>Normal road vehicle collision rules (this is the default)</dd>
<dt>NONE</dt>
<dd>Do not collide at all with other road vehicles</dd>
<dt>ELEVATED</dt>
<dd>Collide only with other elevated road vehicles</dd>
</dl>
</td>
</tr>
</table>
<h3 id="tramtype-properties"><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Tramtypes#Tramtype_properties">Tramtype properties</a></h3>
<table>
<tr><th>Property</th><th>Value range</th><th>Comment</th></tr>
<tr><td>tramtype_extra_flags</td><td>bitmask(TRAMTYPE_EXTRA_FLAG_XXX, ...)</td>
<td>
<dl>
<dt>NO_SCRIPT_BUILD</dt>
<dd>Scripts (AI/GS) may not build this tramtype</dd>
<dt>NO_TOWN_MODIFY</dt>
<dd>Towns may not modify tiles of this tramtype in any way whatsoever</dd>
<dt>NO_TUNNELS</dt>
<dd>Disallow tunnels for this tramtype</dd>
<dt>NO_TRAIN_COLLISION</dt>
<dd>Disallow collisions with trains for vehicles of this tramtype</dd>
</dl>
</td>
</tr>
<tr><td>tramtype_collision_mode</td><td>TRAMTYPE_COLLISION_MODE_XXX</td>
<td>
Sets the road vehicle collision mode for road vehicles of this tram type.
<dl>
<dt>NORMAL</dt>
<dd>Normal road vehicle collision rules (this is the default)</dd>
<dt>NONE</dt>
<dd>Do not collide at all with other road vehicles</dd>
<dt>ELEVATED</dt>
<dd>Collide only with other elevated road vehicles</dd>
</dl>
</td>
</tr>
</table>
<h3 id="object-ids"><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Objects#Object_IDs">Object IDs</a></h3>
<p>
Object IDs are NewGRF-local and can be freely chosen in the 0..63999 range, as of the <span class="code">more_objects_per_grf</span> feature.<br />
When loaded into a version of OpenTTD without this feature, IDs are limited to the range: 0..254.
Any objects with IDs outside this range will be skipped.
</p>
<h3 id="object-properties"><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Objects#Object_properties">Object properties</a></h3>
<table>
<tr><th>Property</th><th>Value range</th><th>Comment</th></tr>
<tr><td>use_land_ground</td><td>0 or 1</td><td>
Sets whether to use the underlying ground as the object ground sprite, ignoring the ground sprite provided in the sprite layout.<br />
When enabled, the ground sprite will be bare ground, grass, snow, desert, etc. as if it were a clear ground tile.<br />
In edge foundation mode, or when foundations are disabled, the ground may be coast/shore when flooded.
</td></tr>
<tr><td>edge_foundation_mode</td><td>[mode0, mode1, mode2, mode3]</td><td>
Enables edge foundation mode for the object.<br />
This property is intended for objects which are positioned at the edge of a tile, and only require a level edge, not a completely level tile.<br />
Foundations will only be added as required to get a suitable level edge.<br />
The format is one mode value per view. If the object has fewer than 4 views then some of the values provided in the property will not be used, and may be 0.
All four values must be constants.<br />
Each mode value should be one of:
<table>
<tr><th>Value</th><th>Meaning</th></tr>
<tr><td>DIAGDIR_NE</td><td>North-east edge</td></tr>
<tr><td>DIAGDIR_SE</td><td>South-east edge</td></tr>
<tr><td>DIAGDIR_SW</td><td>South-west edge</td></tr>
<tr><td>DIAGDIR_NW</td><td>North-west edge</td></tr>
</table>
combined with 0 or more flags using the | operator:
<table>
<tr><th>Value</th><th>Meaning</th></tr>
<tr><td>OBJECT_EF_FLAG_ADJUST_Z</td><td>Change z-position for the building sprite to the height of the edge</td></tr>
<tr><td>OBJECT_EF_FLAG_FOUNDATION_LOWER</td><td>If the height of the edge is lower than the maximum height of the tile, build a foundation</td></tr>
<tr><td>OBJECT_EF_FLAG_INCLINE_FOUNDATION</td><td>Use inclined instead of a flat foundations where possible. (Slopes with one corner raised where the height of the edge is at the maximum height of the tile).</td></tr>
</table>
</td></tr>
<tr><td>flood_resistant</td><td>0 or 1</td><td>
Sets whether the object is flood resistant.<br />
Flood resistance is always enabled for objects which can be built on water.<br />
This property can be used to enable flood resistance without enabling the object to be built on water.
</td></tr>
<tr><td>map_tile_type</td><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_XXX</td><td>
Set tile type used for display in viewport map mode and the small-map window.<br />
The value should be one of:
<table>
<tr><th>Value</th><th>Meaning</th><th>Notes</th></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_DEFAULT</td><td>Default object</td><td></td></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_CLEAR</td><td>Clear/bare dirt</td><td>If use_land_ground is enabled, the underlying ground type will be used instead</td></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_GRASS</td><td>Grass</td><td></td></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_ROUGH</td><td>Rough ground</td><td></td></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_ROCKS</td><td>Rocky ground</td><td></td></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_FIELDS</td><td>Farm fields</td><td>The specific type of field can be set using map_tile_subtype</td></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_SNOW</td><td>Snow</td><td></td></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_DESERT</td><td>Desert</td><td></td></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_TREES</td><td>Trees</td><td>The specific tree count and ground type/density can be set using map_tile_subtype</td></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_HOUSE</td><td>House</td><td></td></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_WATER</td><td>Water</td><td></td></tr>
</table>
</td></tr>
<tr><td>map_tile_subtype</td><td>0 .. 65535</td><td>
<p>This can be used to further refine the type set in map_tile_type.</p>
<p>Farm fields:
<table>
<tr><th>Bit</th><th>Meaning</th></tr>
<tr><td>0 - 2</td><td>
Which field type to use
</td></tr>
</table></p>
<p>Trees:
<table>
<tr><th>Bit</th><th>Meaning</th></tr>
<tr><td>0 - 3</td><td>
Tree ground type
<table>
<tr><th>Value</th><th>Meaning</th></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_TREE_GROUND_GRASS</td><td>Grass</td></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_TREE_GROUND_ROUGH</td><td>Rough ground</td></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_TREE_GROUND_SNOW_DESERT</td><td>Snow/desert</td></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_TREE_GROUND_SHORE</td><td>Shore</td></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_TREE_GROUND_ROUGH_SNOW</td><td>Rough snow</td></tr>
</table>
</td></tr>
<tr><td>4 - 7</td><td>
Tree ground density (clamped to: 0 - 3)
</td></tr>
<tr><td>8 - 11</td><td>
Number of trees on the tile (clamped to: 1 - 4)
</td></tr>
</table></p>
</td></tr>
</table>
<h3 id="object-variables"><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Objects#Object_variables">Object variables</a></h3>
<p>Variables in the table below which are not supported by the version of OpenTTD being used return a value of 0.</p>
<table>
<tr><th>Variable</th><th>Value range</th><th>Comment</th></tr>
<tr><td>foundation_tile_slope</td><td><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:List_of_tile_slopes">SLOPE_XXX</a></td><td>
Slope of the tile after any foundation has been applied.
</td></tr>
<tr><td>foundation_change_tile_slope</td><td><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:List_of_tile_slopes">SLOPE_XXX</a></td><td>
Slope of the tile after any foundation has been applied xor the slope of the underlying tile.<br />
If this variable is non-zero a foundation is present.<br />
This is useful for xoring with the tile_slope variable, because if this variable is unavailable then the result is still the underlying tile slope.
</td></tr>
</table>
<h3 id="airport-tile-variables"><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Airports#Airport_tile_variables">Airport tile variables</a></h3>
<p>Variables in the table below which are not supported by the version of OpenTTD being used return a value of 0.</p>
<table>
<tr><th>Variable</th><th>Value range</th><th>Comment</th></tr>
<tr><td>airport_id</td><td>0..255</td><td>
Local GRF ID of the airport type.
</td></tr>
<tr><td>airport_layout</td><td>0..255</td><td>
Airport layout number (as defined in layouts).
</td></tr>
</table>
<h3 id="global-variable-properties">Global variables properties</h3>
<p>The variables listed below should set inside an item and property block of the form:<pre class="code">
item (FEAT_GLOBALVARS) {
property {
...
}
}</pre>
</p>
<table>
<tr><th>Property</th><th>Value range</th><th>Comment</th></tr>
<tr><td>lighthouse_generate_amount</td><td>0 .. 255</td><td>Sets the frequency at which lighthouse objects are generated during map generation</td></tr>
<tr><td>transmitter_generate_amount</td><td>0 .. 255</td><td>Sets the frequency at which transmitter objects are generated during map generation</td></tr>
<tr><td>extra_station_name</td><td>[string, bitmask(EXTRA_STATION_NAME_FLAG_XXX, ...)]</td>
<td>
<p>This adds an extra station name for use when all the available station names for a given town have been used.<br />
This property may be used as many times as required.<br />
Generally the referenced string should include a <span class="code">{STRING}</span> string code, this is used for the town name.
</p>
<dl>
<dt>EXTRA_STATION_NAME_FLAG_RAIL</dt>
<dd>May be used for rail stations</dd>
<dt>EXTRA_STATION_NAME_FLAG_ROAD</dt>
<dd>May be used for road stations</dd>
<dt>EXTRA_STATION_NAME_FLAG_AIRPORT</dt>
<dd>May be used for airport stations</dd>
<dt>EXTRA_STATION_NAME_FLAG_OIL_RIG</dt>
<dd>May be used for oil rig stations</dd>
<dt>EXTRA_STATION_NAME_FLAG_DOCK</dt>
<dd>May be used for dock stations</dd>
<dt>EXTRA_STATION_NAME_FLAG_HELIPORT</dt>
<dd>May be used for heliport stations</dd>
<dt>EXTRA_STATION_NAME_FLAG_TOWN_CENTRE_ONLY</dt>
<dd>May only be used for stations near the town centre</dd>
<dt>EXTRA_STATION_NAME_FLAG_NOT_TOWN_CENTRE</dt>
<dd>May not be used for stations near the town centre</dd>
<dt>EXTRA_STATION_NAME_FLAG_NEAR_WATER_ONLY</dt>
<dd>May only be used for stations near water</dd>
<dt>EXTRA_STATION_NAME_FLAG_NOT_NEAR_WATER</dt>
<dd>May not be used for stations near water</dd>
</dl>
</td>
</tr>
<tr><td>extra_station_names_probability</td><td>0 .. 255</td>
<td>
Sets the probability that an extra station name is used even when the available default names have not been exhausted.<br />
Some station names are always used first even when this is non-zero.
</td>
</tr>
<tr><td>allow_rocks_in_desert</td><td>0 or 1</td>
<td>
Sets whether rocky tiles are allowed to generate in and remain in desert zones (tropical climate).
</td>
</tr>
</table>
<p>Syntax example:
<pre class="code">
item (FEAT_GLOBALVARS) {
property {
lighthouse_generate_amount: 255;
transmitter_generate_amount: 0;
extra_station_name: [string(STR_STATION_NAME1), bitmask(EXTRA_STATION_NAME_FLAG_RAIL)];
extra_station_name: [string(STR_STATION_NAME2), bitmask(EXTRA_STATION_NAME_FLAG_ROAD, EXTRA_STATION_NAME_FLAG_TOWN_CENTRE_ONLY)];
}
}
</pre>
</p>
<h3 id="replace-new-sprites"><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Replace_new_sprites">Replace new sprites</a></h3>
<table>
<tr><th>Type</th><th>Number of sprites </th><th>Comment</th></tr>
<tr><td>PROGRAMMABLE_PRE_SIGNAL</td><td>32</td>
<td>
<b>Programmable pre-signals</b>
<p>Signal graphics come in groups of 16. These groups contain sprites in the same order as sprites 1275-1290 in trg1[r].grf and <a href="https://newgrf-specs.tt-wiki.net/wiki/Action5#04_Signal_graphics.">Action 5 type 4 (signals)</a>;
red, then green, for each of: SW-facing, NE-facing, NW-facing, SE-facing, E-facing, W-facing, S-facing, N-facing.
<table>
<tr><th>Group</th><th>Contents</th></tr>
<tr><td>0</td><td>Semaphore programmable pre-signals</td></tr>
<tr><td>1</td><td>Lighted programmable pre-signals</td></tr>
</table>
</td>
</tr>
<tr><td>NO_ENTRY_SIGNAL</td><td>16</td>
<td>
<b>No-entry signals</b>
<p>No-entry signal graphics come in groups of 8. These groups contain sprites in the same order as the red sprites of 1275-1290 in trg1[r].grf and <a href="https://newgrf-specs.tt-wiki.net/wiki/Action5#04_Signal_graphics.">Action 5 type 4 (signals)</a>;
red only, for each of: SW-facing, NE-facing, NW-facing, SE-facing, E-facing, W-facing, S-facing, N-facing.
<table>
<tr><th>Group</th><th>Contents</th></tr>
<tr><td>0</td><td>Semaphore no-entry signals</td></tr>
<tr><td>1</td><td>Lighted no-entry signals</td></tr>
</table>
</td>
</tr>
<tr><td>MISC_GUI</td><td>1</td>
<td>
<b>Miscellaneous GUI graphics</b>
<p>There is currently one misc GUI sprite.</p>
</td>
</tr>
<tr><td>ROAD_WAYPOINTS</td><td>4</td>
<td>
<b>Road waypoint graphics</b>
<p>This is the same order and format as the drive-through bus/truck road stop sprites.</p>
</td>
</tr>
</table>
<h3 id="signal-graphics">Signal graphics using switches</h3>
<p>
This feature allows signal sprites to be specified using switches in a very similar manner to <a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Railtypes#signals">railtype signals</a> in
<span class="code">item (FEAT_RAILTYPES) { graphics { signals: ... } }</span> blocks.<br />
However this applies to all signals, not only those of a particular rail type.<br />
Railtype signal graphics have a higher priority than general signal graphics as set here.<br />
<br />
Variables: <span class="code">extra_callback_info1</span>, <span class="code">extra_callback_info2</span>, and <span class="code">terrain_type</span>
are the same as for <a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Railtypes#signals">railtype signals</a>.<br />
<br />
This feature is not supported by standard OpenTTD or by standard NML.<br/>
If the use of this feature is not optional, the feature name: <span class="code">action3_signals_custom_signal_sprites</span> should be checked using the
<span class="code">extended_feature_test</span> function
and if necessary a suitable fallback used or error message shown.<br />
<br />
An <span class="code">item (FEAT_SIGNALS, custom_signals, 0) { }</span> block should be used to define properties and graphics.<br />
The graphics block should contain a single default switch.
</p>
<table>
<tr><th>Property</th><th>Value range</th><th>Comment</th></tr>
<tr><td>enable_programmable_pre_signals</td><td>0 or 1</td>
<td>
Enable programmable pre-signal graphics.<br />
Programmable pre-signals have a signal type (<span class="code">getbits(extra_callback_info2, 16, 8)</span>) of 6.
</td>
</tr>
<tr><td>enable_no_entry_signals</td><td>0 or 1</td>
<td>
Enable no-entry signal graphics.<br />
No-entry signals have a signal type (<span class="code">getbits(extra_callback_info2, 16, 8)</span>) of 7.<br />
No-entry signals always have a signal state of red.
</td>
</tr>
<tr><td>enable_restricted_signals</td><td>0 or 1</td>
<td>
Enable restricted signal flag.<br />
When enabled, bit 24 of variable <span class="code">extra_callback_info2</span> is set if the signal is restricted (has a routing restriction program attached).<br />
When enabled, the "Show restricted electric signals using default graphics" client setting and signal post recolouring is not applied.<br />
This flag must only be set if a different sprite is returned when bit 24 of <span class="code">extra_callback_info2</span> is set.
</td>
</tr>
<tr><td>enable_signal_recolour</td><td>0 or 1</td>
<td>
Enable recolouring of graphics<br />
When enabled, in addition to returning a sprite, register 0x100 may be set to the following using STORE_TEMP:
<table>
<tr><th>Bits</th><th>Meaning</th></tr>
<tr><td>0 - 23</td><td>Recolour sprite to use. Set to 0 for no recolouring.</td></tr>
<tr><td>24 - 31</td><td>Reserved, set to zero.</td></tr>
</table>
</td>
</tr>
<tr><td>extra_aspects</td><td>0 - 6</td>
<td>
The value is the number of additional signal aspects to use (e.g. 4-aspect signalling should use a value of 2).<br />
When set, the lowest byte of <span class="code">extra_callback_info2</span> (signal state) may have the given number of additional values starting from 02:
<table>
<tr><th>Value</th><th>Meaning</th></tr>
<tr><td>00</td><td>Red signal</td></tr>
<tr><td>01</td><td>Green signal</td></tr>
<tr><td>02</td><td>1st extra aspect (e.g. yellow)</td></tr>
<tr><td>03</td><td>2nd extra aspect (e.g. double yellow)</td></tr>
<tr><td>...</td><td>Further extra aspects...</td></tr>
</table>
<br />
The provided value is currently clamped to be within the range 0 - 6 (inclusive).<br />
N.B. Realistic braking must be enabled for additional signal aspects to be used
</td>
</tr>
<tr><td>define_style</td><td>1 - 255</td>
<td>
Define a custom signal style<br />
Signals using this style will only use this GRF, or the default graphics if no graphics are returned.<br />
The value supplied is returned in the signal_style variable.<br />
This property (and related signal style properties) may be used more than once.<br />
The total number of custom signal styles in a game is currently limited to 15.
</td>
</tr>
<tr><td>style_name</td><td>string</td>
<td>
Set the name of the most recently defined style (defined using the <span class="code">define_style</span> property).<br />
This property should be used if using the define_style property, as otherwise the style will have no name.
</td>
</tr>
<tr><td>style_electric_enabled</td><td>bitmask(SIGNAL_TYPE_XXX, ...)</td>
<td>
Set which electric signal types may be built using this signal style for the most recently defined style (defined using the <span class="code">define_style</span> property).<br />
At least one of this property and <span class="code">style_semaphore_enabled</span> should be set to a non-zero value, as otherwise
no signal types will be enabled for this custom signal style.<br />
If PROG or NO_ENTRY are set, it is not necessary to also set <span class="code">enable_programmable_pre_signals</span> or <span class="code">enable_no_entry_signals</span>.
<dl>
<dt>NORMAL</dt>
<dd>Normal/block signal</dd>
<dt>ENTRY</dt>
<dd>Pre-signal entry</dd>
<dt>EXIT</dt>
<dd>Pre-signal exit</dd>
<dt>COMBO</dt>
<dd>Pre-signal combo</dd>
<dt>PBS</dt>
<dd>Two-way PBS</dd>
<dt>PBS_ONEWAY</dt>
<dd>One-way PBS</dd>
<dt>PROG</dt>
<dd>Programmable pre-signal</dd>
<dt>NO_ENTRY</dt>
<dd>No-entry</dd>
</dl>
</td>
</tr>
<tr><td>style_semaphore_enabled</td><td>bitmask(SIGNAL_TYPE_XXX, ...)</td>
<td>
Set which semaphore signal types may be built using this signal style for the most recently defined style (defined using the <span class="code">define_style</span> property).<br />
See <span class="code">style_electric_enabled</span>, above.
</td>
</tr>
<tr><td>style_no_aspect_increase</td><td>0 or 1</td>
<td>
Set whether the most recently defined style (defined using the <span class="code">define_style</span> property) does not increase
the signal aspect with respect to the signals either side (i.e. function like a banner repeater).
</td>
</tr>
<tr><td>style_always_reserve_through</td><td>0 or 1</td>
<td>
Set whether reserve through is unconditionally enabled for the most recently defined style (defined using the <span class="code">define_style</span> property).
</td>
</tr>
<tr><td>style_lookahead_extra_aspects</td><td>0 - 6 or 255</td>
<td>
Set the look-ahead extra aspects for the most recently defined style (defined using the <span class="code">define_style</span> property).<br />
This property only makes a difference when the "realistic train braking is aspect limited" game setting is enabled.<br />
This limits the signal aspect which the hypothetical train driver can "read" from the signal without affecting signal aspect propagation to other signals, or variable <span class="code">extra_callback_info2</span>.<br />
Example values could include: 1 for traditional banner repeater signals.<br />
Shunt signals should use <span class="code">style_lookahead_single_signal_only</span> instead.<br />
The value is clamped to be less than or equal to the value set in the <span class="code">extra_aspects</span> property.<br />
<br />
As a special case, a value of 255 (0xFF) disables the "realistic train braking is aspect limited" setting entirely for signals using this style.<br />
This should only be used for signal types which are intended to emulate in-cab signalling, instead of the "driver" visually reading a signal.
</td>
</tr>
<tr><td>style_lookahead_single_signal_only</td><td>0 or 1</td>
<td>
Set the look-ahead to single signal only mode for the most recently defined style (defined using the <span class="code">define_style</span> property).<br />
This property only makes a difference when the "realistic train braking is aspect limited" game setting is enabled, or when using a different signal
type which uses <span class="code">style_combined_normal_shunt</span>.<br />
This is similar to <span class="code">style_lookahead_extra_aspects</span> with a value of 0, except the lookahead always ends at the
next signal, even if that signal type sets <span class="code">style_no_aspect_increase</span>.<br />
If enabled, this property overrides <span class="code">style_lookahead_extra_aspects</span>.<br />
This can be used for shunt signals.
</td>
</tr>
<tr><td>style_combined_normal_shunt</td><td>0 or 1</td>
<td>
Enable functioning as a combined normal aspect and shunt signal for the most recently defined style (defined using the <span class="code">define_style</span> property).<br />
When enabled and displaying a shunt aspect, the signal state in the lowest byte of <span class="code">extra_callback_info2</span> will have the value: 0xFF.
</td>
</tr>
<tr><td>style_opposite_side</td><td>0 or 1</td>
<td>
Set whether signals should be drawn on the opposite side of the track for the most recently defined style (defined using the <span class="code">define_style</span> property).
</td>
</tr>
<tr><td>style_both_sides</td><td>0 or 1</td>
<td>
Set whether signals should be drawn on both sides of the track for the most recently defined style (defined using the <span class="code">define_style</span> property).<br />
If set, the <span class="code">signal_context_is_second</span> variable is true when drawing the second signal.<br />
If this and <span class="code">style_opposite_side</span> are both set, the first signal is drawn on the opposite side and the second signal is drawn on the usual side.
</td>
</tr>
<tr><td>style_realistic_braking_only</td><td>0 or 1</td>
<td>
Set whether signals using this style may only be built when realistic braking is enabled, for the most recently defined style (defined using the <span class="code">define_style</span> property).
</td>
</tr>
<tr><td>no_default_style</td><td>0 or 1</td>
<td>
When enabled, custom signal graphics from this GRF are only used for custom signal styles, not the default style
</td>
</tr>
</table>
<br />
<table>
<tr><th>Variable</th><th>Value range</th><th>Comment</th></tr>
<tr><td>signal_restriction_info</td><td>bitmask(SIGNAL_RESTRICTION_INFO_XXX, ...)</td>
<td>
Information about the restricted signal status of the signal being drawn:
<dl>
<dt>RESTRICTED</dt>
<dd>The signal is restricted (has a routing restriction program attached)</dd>
<dt>RESERVE_THROUGH_ALWAYS</dt>
<dd>The attached routing restriction program unconditionally sets reserve through</dd>
<dt>MAY_REVERSE</dt>
<dd>The attached routing restriction program may allow trains to reverse behind this signal</dd>
</dl>
</td>
</tr>
<tr><td>signal_context</td><td>SIGNAL_CONTEXT_XXX</td>
<td>
Information about the context of the signal being drawn:
<dl>
<dt>GUI</dt>
<dd>The signal is being drawn in the GUI (signal window)</dd>
<dt>TRACK</dt>
<dd>The signal is being drawn on ordinary rail track</dd>
<dt>TUNNEL_BRIDGE_ENTRANCE</dt>
<dd>The signal is being drawn as a tunnel/bridge entrance signal</dd>
<dt>TUNNEL_BRIDGE_EXIT</dt>
<dd>The signal is being drawn as a tunnel/bridge exit signal</dd>
<dt>BRIDGE_MIDDLE</dt>
<dd>The signal is being drawn on the middle of a bridge</dd>
</dl>
</td>
</tr>
<tr><td>signal_context_is_tunnel</td><td>0 or 1</td>
<td>
The signal is being drawn on a tunnel entrance/exit (not a bridge)
</td>
</tr>
<tr><td>signal_context_is_second</td><td>0 or 1</td>
<td>
The second signal is being drawn (on the opposite side to the first signal), see the style_both_sides property
</td>
</tr>
<tr><td>signal_context_info</td><td></td>
<td>
Above signal context variables in one variable (all of the signals_signal_context variable)
</td>
</tr>
<tr><td>signal_side</td><td>SIGNAL_SIDE_XXX</td>
<td>
<dl>
<dt>LEFT</dt>
<dd>Signals are on the left</dd>
<dt>RIGHT</dt>
<dd>Signals are on the right</dd>
</dl>
</td>
</tr>
<tr><td>signal_style</td><td>0 - 255</td>
<td>
The style ID defined using define_style for signals using a custom style, or 0 for signals using the default style
</td>
</tr>
<tr><td>signal_vertical_clearance</td><td>0 - 255</td>
<td>
Pixels of vertical clearance between the signal and any bridge above.<br />
If there is no bridge above, the value is 0xFF.
</td>
</tr>
</table>
<p>
Custom signal sprites example:
<pre class="code">
grf {
...
}
if (!extended_feature_test("action3_signals_custom_signal_sprites")) {
error(FATAL, string(STR_UNSUPPORTED_VERSION));
}
switch (FEAT_SIGNALS, SELF, switch_signals, ...) {
...
}
item (FEAT_SIGNALS, custom_signals, 0) {
property {
enable_signal_recolour: 1;
}
graphics {
switch_signals;
}
}
</pre>
</p>
</body>
</html>