<h2>Additions to the NewGRF Road Stops Specification in JGR's Patchpack in NML</h2>
<p>This document describes the non-standard additions to the NewGRF road stops feature in the <ahref="https://newgrf-specs.tt-wiki.net/wiki/NML:Main">Official OpenTTD NML Specifications</a>, as implemented in this patchpack, and the associated <ahref="https://github.com/JGRennison/nml">NML fork</a><br/>
The additions here are compatible with the specification and OpenTTD 14.0, such that GRFs can run on OpenTTD 14.0 and also optionally use patchpack extensions where available.</p>
<p>These additions and the official specification do not match the obsolete OpenTTD PR #7955 which used a different NewGRF interface.</p>
<p>This feature will be automatically skipped when loaded into a version of OpenTTD which does not support this feature (before 14.0).<br/>
If this feature is the only significant thing in this GRF, then <spanclass="code">version_openttd(14, 0) || extended_feature_test("road_stops")</span> MAY be called and some message, error or other form of
signalling to the user used to inform the user that this version of OpenTTD does not support the feature, if the value is false.</p>
A road stop is allocated by setting the 'class'-property, which should therefore be set first.<br/>
Road stop IDs are NewGRF-local and can be freely chosen in the 0..63999 range, as of version 7 of the <spanclass="code">road_stops</span> feature.<br/>
When loaded into a version of OpenTTD with versions 1 to 6 of the <spanclass="code">road_stops</span> feature, IDs are limited to the range: 0..254.
Any road stops with IDs outside this range will be skipped.
<tr><td>classname</td><td>string</td><td>You only need to set this for one object in every class. </td></tr>
<tr><td>name</td><td>string</td><td></td></tr>
<tr><td>availability_type</td><td>RST_AVAILABILITY_TYPE_XXX</td><td>XXX = PASSENGER | FREIGHT | ALL<br/>This is ignored for stops in the WAYP waypoint class</td></tr>
<spanclass="indent">Draw spritelayout ground sprite on top of underlying road (if unset, the spritelayout ground sprite is not drawn). <b>Not in standard specification</b>.</span></p>
<tr><td>animation_speed</td><td>0..16</td><td>Speed of animation, see <ahref="https://newgrf-specs.tt-wiki.net/wiki/NML:Animation_speed">animation speed table</a> for the meaning of the values. </td></tr>
<tr><td>animation_triggers</td><td>bitmask(ANIM_TRIGGER_ROAD_STOP_XXX, ...)</td><td>Bitmask of triggers that will trigger the <spanclass="code">anim_control</span> callback, see the <ahref="#roadstop_anim_triggers">table</a> below.</td></tr>
<spanclass="indent">Do not show one way road overlay sprites, this should only be set if different graphics are provided for the different one-way states using the <spanclass="code">one_way_info</span> variable. <b>Not in standard specification</b>.</span></p>
<spanclass="indent">Only allow drive-through stops (not bay stops). (This only takes effect from <spanclass="code">road_stops</span> version 2).</span></p>
<spanclass="indent">Do not automatically build connecting road pieces. (This only takes effect from <spanclass="code">road_stops</span> version 3).</span></p>
<spanclass="indent">Only show in the road build menu (not tram). (This only takes effect from <spanclass="code">road_stops</span> version 4).</span></p>
<spanclass="indent">Only show in the tram build menu (not road). (This only takes effect from <spanclass="code">road_stops</span> version 4).</span></p>
<spanclass="indent">Use custom graphics for disabled road stop views. (This only takes effect from <spanclass="code">road_stops</span> version 8). <b>Not in standard specification</b>.</span></p>
<spanclass="indent">Read the road stop draw mode from variable 0x100 (set using STORE_TEMP), this overrides the <spanclass="code">draw_mode</span> property. (This only takes effect from <spanclass="code">road_stops</span> version 9). <b>Not in standard specification</b>.</span></p>
<tr><td>minimum_bridge_height<br/><b>Not in standard specification</b></td><td>Array of 6 items [0..255, ...]</td><td>Minimum clearances required for a bridge for each of the <ahref="#roadstop_views">6 views/rotations</a> (or 0 to not allow any bridge). Values are given in height level units (1 level == 8px).</td></tr>
<tr><td>disallowed_bridge_pillars<br/><b>Not in standard specification</b></td><td>Array of 6 items [bitmask(RST_BRIDGE_PILLAR_FLAG_, ...), ...]</td><td>
<tr><td>height<br/><b>Not in standard specification</b></td><td>0..255</td><td>Road stop height (in the build window), in height level units (1 level == 8px), see also: <ahref="https://newgrf-specs.tt-wiki.net/wiki/NML:Objects#Object_properties">object height property</a>.</td></tr>
<p>A number of variables are shared between road stops and stations. These are listed on the <ahref="https://newgrf-specs.tt-wiki.net/wiki/NML:Stations#Base_station_variables">stations</a> page.</p>
<tr><td>terrain_type</td><td>TILETYPE_XXX</td><td>XXX = NORMAL | DESERT | RAIN_FOREST | SNOW</td></tr>
<tr><td>tile_slope</td><td>SLOPE_XXX</td><td>See <ahref="https://newgrf-specs.tt-wiki.net/wiki/NML:List_of_tile_slopes">tile slopes</a> for an overview of possible values</td></tr>
<tr><td>has_road</td><td>0 | 1</td><td>1 is this road stop has road</td></tr>
<tr><td>has_tram</td><td>0 | 1</td><td>1 is this road stop has tram</td></tr>
<tr><td>road_type</td><td>road type | 0xFF</td><td>Road type. If there is no road the value will be 0xFF. If the roadtype has no entry in the roadtype translation table of the GRF, this value will be 0xFF. If no translation table is present, the raw value will be returned.</td></tr>
<tr><td>tram_type</td><td>tram type | 0xFF</td><td>Tram type. If there is no tram the value will be 0xFF. If the tramtype has no entry in the tramtype translation table of the GRF, this value will be 0xFF. If no translation table is present, the raw value will be returned.</td></tr>
<tr><td>town_manhattan_dist</td><td></td><td>Manhattan distance to the associated town</td></tr>
<tr><td>town_euclidean_dist</td><td></td><td>Squared euclidean distance to the associated town</td></tr>
<tr><td>town_zone</td><td><ahref="https://newgrf-specs.tt-wiki.net/wiki/NML:List_of_town_zones">town zone</a></td><td>The town zone of the current tile in the associated town.</td></tr>
<tr><td>company_num</td><td>0..14</td><td>Company number of the road stop owner</tr>
<tr><td>random_bits</td><td>0..16777215</td><td>All random bits</td></tr>
<tr><td>random_bits_tile</td><td>0..255</td><td>Random bits (per tile), see also <ahref="https://newgrf-specs.tt-wiki.net/wiki/NML:Stations#Base_station_variables">random_bits_station</a></td></tr>
<tr><td>one_way_info<br/><b>Not in standard specification</b></td><td>RST_OWI_XXX</td><td>One-way road information of drive-through stop tile<br/>XXX = TWO_WAY | WEST_BOUND | EAST_BOUND | NO_ENTRY</td></tr>
<tr><td>one_way_info_inferred<br/><b>Not in standard specification</b></td><td>RST_OWI_XXX</td><td>Inferred one-way road information of drive-through stop tile<br/>XXX = TWO_WAY | WEST_BOUND | EAST_BOUND | NO_ENTRY</td></tr>
<tr><td>drawn_in_gui<br/><b>Not in standard specification</b></td><td>0 | 1</td><td>1 if this road stop is being drawn in the build window</td></tr>
<tr><td>nearby_tile_slope</td><td>x, y offset (-8..7)</td><td>SLOPE_XXX</td><td>Slope of a nearby tile</td></tr>
<tr><td>nearby_tile_is_water</td><td>x, y offset (-8..7)</td><td>0 | 1</td><td>Is nearby tile a water tile?</td></tr>
<tr><td>nearby_tile_terrain_type</td><td>x, y offset (-8..7)</td><td></td><td>See terrain_type</td></tr>
<tr><td>nearby_tile_water_class</td><td>x, y offset (-8..7)</td><td>WATER_CLASS_XXX</td><td>XXX = [NONE | SEA | CANAL | RIVER]<br/>Note that tiles for which nearby_tile_is_water is 0 may still have a water class, e.g. industry tiles with water beneath them. </td></tr>
<tr><td>nearby_tile_height</td><td>x, y offset (-8..7)</td><td></td><td>The minimum height of the given tile in height level units</td></tr>
<tr><td>nearby_tile_class</td><td>x, y offset (-8..7)</td><td><ahref="https://newgrf-specs.tt-wiki.net/wiki/NML:List_of_tile_classes">tile class</a></td><td></td></tr>
<tr><td>nearby_tile_info</td><td>x, y offset (-8..7)</td><td></td><td>Above nearby tile variables in one variable (all of variable 0x67)</td></tr>
<tr><td>nearby_tile_animation_frame</td><td>x, y offset (-8..7)</td><td>0..255</td><td>Animation frame of a nearby road stop tile</td></tr>
<tr><td>nearby_tile_is_road_stop</td><td>x, y offset (-8..7)</td><td>0 | 1</td><td>Is nearby tile a road stop?</td></tr>
<tr><td>nearby_tile_road_stop_id</td><td>x, y offset (-8..7)</td><td></td><td>Is nearby_tile_same_grf is true, ID of a road stop on a nearby tile</td></tr>
<tr><td>nearby_tile_same_grf</td><td>x, y offset (-8..7)</td><td>0 | 1</td><td>Is a road stop on a nearby tile defined by the same GRF?</td></tr>
<tr><td>nearby_tile_other_grf</td><td>x, y offset (-8..7)</td><td>0 | 1</td><td>Is a road stop on a nearby tile defined by another GRF?</td></tr>
<tr><td>nearby_tile_original_gfx</td><td>x, y offset (-8..7)</td><td>0 | 1</td><td>Is a road stop on a nearby tile using original graphics?</td></tr>
<tr><td>nearby_tile_same_station</td><td>x, y offset (-8..7)</td><td>0 | 1</td><td>Is a road stop on a nearby tile the same station as this?</td></tr>
<tr><td>nearby_tile_view</td><td>x, y offset (-8..7)</td><td>0..5</td><td>The <ahref="#roadstop_views">view/rotation</a> of a nearby road stop tile</td></tr>
<tr><td>nearby_tile_different_view</td><td>x, y offset (-8..7)</td><td>0 | 1</td><td>Is the <ahref="#roadstop_views">view/rotation</a> of a road stop on a nearby tile different to that of this tile?</td></tr>
<tr><td>nearby_tile_is_drive_through</td><td>x, y offset (-8..7)</td><td>0 | 1</td><td>Is nearby road stop tile a drive-through road stop?</td></tr>
<tr><td>nearby_tile_stop_type</td><td>x, y offset (-8..7)</td><td>RST_TYPE_XXX</td><td>See stop_type</td></tr>
<tr><td>nearby_tile_same_stop_type</td><td>x, y offset (-8..7)</td><td>0 | 1</td><td>Is the stop type of a nearby road stop tile the same as this tile?</td></tr>
<tr><td>nearby_tile_one_way_info</td><td>x, y offset (-8..7)</td><td>RST_OWI_XXX</td><td>One-way state of nearby drive-through road stop tile</td></tr>
<tr><td>nearby_tile_road_stop_info</td><td>x, y offset (-8..7)</td><td></td><td>Above nearby road stop tile variables in one variable (all of variable 0x68)</td></tr>
<tr><td>nearby_tile_grfid</td><td>x, y offset (-8..7)</td><td>-1, 0 or a GRFID</td><td>Return value is -1 if the tile is not a road stop, 0 if the tile is a non-custom road stop, or else the GRFID of the NewGRF defining the road stop</td></tr>
<tr><td>nearby_tile_is_plain_road<br/><b>Not in standard specification</b></td><td>x, y offset (-8..7)</td><td>0 | 1</td><td>Is nearby tile a plain road tile</td></tr>
<tr><td>nearby_tile_road_bits<br/><b>Not in standard specification</b></td><td>x, y offset (-8..7)</td><td>bitmask(ROADBIT_XXX, ...)</td><td>XXX = [NW | SW | SE | NE]<br/>Present road bits on nearby tile</td></tr>
<tr><td>nearby_tile_tram_bits<br/><b>Not in standard specification</b></td><td>x, y offset (-8..7)</td><td>bitmask(ROADBIT_XXX, ...)</td><td>XXX = [NW | SW | SE | NE]<br/>Present tram bits on nearby tile</td></tr>
<tr><td>nearby_tile_road_piece<br/><b>Not in standard specification</b></td><td>x, y offset (-8..7)</td><td>0..18 | 0xFF</td><td>Present road piece and slope in <ahref="https://newgrf-specs.tt-wiki.net/wiki/Action3/Roadtypes#Road_underlay_.2802.29">sprite order</a>, or 0xFF if none</td></tr>
<tr><td>nearby_tile_tram_piece<br/><b>Not in standard specification</b></td><td>x, y offset (-8..7)</td><td>0..18 | 0xFF</td><td>Present tram piece and slope in <ahref="https://newgrf-specs.tt-wiki.net/wiki/Action3/Roadtypes#Road_underlay_.2802.29">sprite order</a>, or 0xFF if none</td></tr>
<tr><td>nearby_tile_road_stop_info<br/><b>Not in standard specification</b></td><td>x, y offset (-8..7)</td><td></td><td>Above nearby road tile variables in one variable (all of variable 0x6B)</td></tr>
<tr><td>nearby_tile_road_stop_info_v2<br/><b>Not in standard specification</b></td><td>x, y offset (-8..7)</td><td></td><td>Above nearby road tile variables in one variable (all of variable roadstop_road_stop_info_nearby_tiles_v2)</td></tr>
<tr><td>default</td><td>Sprite layout</td><td>Normal graphics for a road stop placed on the map</td></tr>
<tr><td>purchase</td><td>Sprite layout</td><td>Graphics shown in the build menu</td></tr>
<tr><td>availability</td><td>0 | 1</td><td>Whether this road stop type is available in the build menu, 1 is available, 0 is unavailable</td></tr>
<tr><td>anim_control</td><td>Next animation frame or CB_RESULT_XXX</td><td>
Called whenever an animation trigger happens. Return the animation frame to show, or CB_RESULT_XXX with XXX = [CB_RESULT_START_ANIMATION | STOP_ANIMATION | DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. Returning a sound effect in the high byte will cause that sound effect to be played.<br/>
<spanclass="code">extra_callback_info1</span>: 32 random bits, if the general flag RST_GENERAL_FLAG_RANDOM_ANIMATION is set.<br/>
<spanclass="code">getbits(extra_callback_info2, 0, 8)</span>: Reason for the callback trigger, see the <ahref="#roadstop_anim_triggers">table</a> below.
</td></tr>
<tr><td>anim_next_frame</td><td>Next animation frame or CB_RESULT_XXX</td><td>
Called for every animation frame, returns the next frame to display. Alternatively, return CB_RESULT_NEXT_FRAME or CB_RESULT_STOP_ANIMATION to show the next frame or stop animation, respectively.<br/>
Returning a sound effect in the high byte will cause that sound effect to be played (e.g. <spanclass="code">return (sound("mysound.wav") << 8) | CB_RESULT_NEXT_FRAME;)</span>.<br/>
<spanclass="code">extra_callback_info1</span>: 32 random bits, if the general flag RST_GENERAL_FLAG_RANDOM_ANIMATION is set.
</td></tr>
<tr><td>anim_speed</td><td>0 .. 16</td><td>Decide the time an animation frame should last. Return value is interpreted as (num_ticks = 2^anim_speed), which each tick lasting 30 ms. Avoid using this callback if possible, since it has to be called each tick for every animated tile. This can be used to create animation frames that last between 30 ms and 33 minutes.</td></tr>
<tr><td>ANIM_TRIGGER_ROAD_STOP_BUILT</td><td>Road stop is built</td><td>newly built tile</td><td></td></tr>
<tr><td>ANIM_TRIGGER_ROAD_STOP_NEW_CARGO</td><td>New cargo arrives at station</td><td>all tiles</td><td>Bits 8..15 contain the triggering cargo type</td></tr>
<tr><td>ANIM_TRIGGER_ROAD_STOP_CARGO_TAKEN</td><td>Cargo removed from station</td><td>all tiles</td><td>Bits 8..15 contain the triggering cargo type</td></tr>
<tr><td>ANIM_TRIGGER_ROAD_STOP_VEH_ENTER</td><td>Road vehicle enters stop (starts loading/unloading)</td><td>tile where the vehicle is</td><td></td></tr>
<tr><td>ANIM_TRIGGER_ROAD_STOP_VEH_LEAVE</td><td>Road vehicle leaves stop (done loading/unloading)</td><td>tile where the vehicle is</td><td></td></tr>
<tr><td>ANIM_TRIGGER_ROAD_STOP_VEH_LOAD</td><td>Road vehicle loads/unloads cargo</td><td>tile where the vehicle is</td><td></td></tr>
