Dat File Reference for: feature_pier-system branch

[PJMack]

Elevates Way Support System.
===========

Introduction
------------

This new system of elevating ways, internally called the pier system and referred to as elevated way supports to the end users, is based on building blocks 1x1x1 tile each.  Each block, referred to as a pier, is settable for what other piers and ways can go on them as well as the directions for ways on or below them.  It is also settable as to what type of buildings can go below piers.  Multiple piers can occur on the same tile as long as they do not have the same physical space.

Notes on for pakset Design
--------------------------
The interactions between piers, other piers, ways and buildings are set with bit fields rather than lists.  This has the effect of not only making such interactions rather customize-able, but allows two or more piers on a single tile to act as if it were one pier, allowing for the user to retrofit elevated structures.  This means that the first pakset designer to use a pier would need to create a key for what the bit fields actually mean within the context of the pakset.  It also means that the pakset designer would want/need to set the fields in hexadecimal notation.

The bit-fields are not directly portrayed to the user, however it is up to the pakset designer to use the icons and images of the piers to imply what can be placed upon what.  For example, if a pier blocks a way then it should look like it would based on the images thereof.

The pier system parameters expose the raw system of ribis and slopes used internally defined in ``simutrans-extended/dataobj/ribi.h``. ribis are four bit values indicating directions: 1 is north (top right), 2 is east (bottom right), 4 is south (bottom left) and 8 is west (top left).  Multiple directions can be indecated by adding such numbers.  Slope is a 4 digit trinary number (here converted into decimal) which each trinary digit indicates the relative height of the corners relative to the lowest: all zeros is level ground, 1 is left corner up 1 level, 2 is left corner up 2 levels, 3 is bottom up 1 level, 6 is bottom up 2 levels, 9 is right corner up 1 level, 18 is right corner up 2 levels, 27 is top corner up 1 level, and 54 is top corner up 2 levels.  If more than one corner is above the lowest corner, then the aforementioned numbers can be added accordingly.


Pier dat File Parameters
------------------------

| ``obj=pier``
| Object type is pier

| ``name=<string>``
| Name of pier.  When translated, it should be a descriptive name, and should imply any details about way restrictions.  For piers that can support canals or taxiways, the name should imply it, as the player guides would mention that most piers do not support such ways.  (e.g. "Brick Ship Aquaduct", "Concrete Viaduct (Concrete Taxiway compatible)".)  Players can assume the piers support all other ways, so piers restricted to a particular type should have that type appear in the name.  (e.g. "Steel Road Viaduct", "Narrow-gage Brick Arch")

| ``cost=<unsigned>``
| Price to build pier.
| *default: 0*

| ``maintenance=<unsigned>``
| Monthly cost of maintenance.  *default: 1000*


| ``intro_year``
| ``intro_month``
| ``retire_year``
| ``retire_month``
| Dates that pier is available

| ``above_way_ribi=<ribi>``
| Directions that the pier can support a way.  Zero for no ways supported. If multiple piers are on the same tile, the *above way ribis* are OR'd.
| *default: 0x0*

| ``below_way_ribi=<ribi>``
| Directions that a way can go beneath/in the pier.  This can be used fore elevated systems such as arches where ways can to perpendicularly beneath the elevated one, but parallel to it.  If multiple piers are on the same tile, the *below way ribis* are AND'd.  The *below way ribi* also applied to ways one level beneath the pier, except for roads, canals, and tramways owned by the same player.
| *default: 0x0*

| ``auto_group=<32 bit field>``
| For piers that have auto-placement capabilities, this serves as a filter for pier types.  When a different type of pier is built than is selected, it is ensured that at least one bit of this field is the same.
| *default: 0x00000000*

| ``auto_height=<8 bits of flags>``
| Flags to adjust the preferences for auto-placement of piers.  Bit 7 (MSB) set puts the pier on low priority for auto-placement substitutions.  All other bits are reserved and are to remain at 0, so valid values are 0x00 and 0x80.
| *default: 0x00*

| ``base_mask=<32 bit field>``
| ``base_mask_2<32 bit field>``
| This pair of 32 bit fields are each rotated 8 bits per pier rotation.  In order to place a pier on another pier, the *base masks* must be a subset of the OR'd *support masks* for the lower piers.  Each bit of such masks would represent an area (and/or associated strength) of a tile.
| *defaults: 0x00000000*

| ``support_mask=<32 bit field>``
| ``support_mask_2<32 bit field>``
| This pair of 32 bit fields are each rotated 8 bits per pier rotation.  In order to place a pier on another pier, the *base masks* must be a subset of the OR'd *support masks* for the lower piers.  Each bit of such masks would represent a subarea (and/or associated strength) of a tile.
| *defaults: 0x00000000*


| ``middle_mask=<32 bit field>``
| ``middle_mask_2<32 bit field>``
| This pair of 32 bit fields are each rotated 8 bits per pier rotation.  In order for two piers to occupy the same tile, the bits for each middle mask pair must be mutually exclusive.  Each bit represents a sub-volume of a tile.
| *defaults: 0x00000000*

| ``sub_obj_mask=<16 bit field>``
| For a building to be placed below a pier (or a pier placed on a building), the *sub object mask* of the pier must be a subset of the corresponding *pier sub mask* of the building.  If more than one pier is on a tile, the *sub object masks* are OR'd.  Note, this is technically a 32 bit field, however the 16 MSBs are reserved for future use and may be 0x0000 or 0xFFFF.
| *default: 0xFFFF*

| ``deck_obj_mask=<32 bit field>``
| For a way to be placed on a pier, the *deck object mask* of the pier must be a super-set of the way's *deck mask*.  If more than one pier is on a tile, the *deck object masks* are OR'd.  It is recommended that pakset designers assign 1 bit for each class of ways (eg. 1 for canals, 2 for runways, 4 for roads, etc.) and/or 1 bit for the way widths.
| *default: 0x0000FFFF*

| ``above_slope=<slope>``
| Slope of the way on top of the pier.  Must be 0, 4, 12, 28, 36, 8, 24, 56 or 72.  Must be valid for the given *above way ribi*.
| *default: 0*

| ``drag_ribi=<ribi>``
| While dragging with manual placement, if the *above way ribi* is zero, then the *drag ribi* is used to confine the dragging.  Valid values are 0x1, 0x2, 0x3, 0x4, 0x5, 0x8, 0x9, 0xA, 0xC and 0xF.
| *default: 0x0*

| ``above_way_supplement=1``
| When set, the *above way ribi* is only applied if there exists another pier with a non-zere *above way ribi* and that other pier does not have this flag is set.

| ``keep_dry=1``
| When set, pier can not be built on water tiles.  (This does not effect building on water based ways such as rivers)

| ``bottom_only=1``
| When set, pier can not be placed on another pier.

| ``low_waydeck=1``
| When set, the pier can support a way on its bottom rather than top.  There are marked as "through truss" for the user.  When enabled the *below way ribi* is used to set direction of way.  Such piers can not be built on ground level, piers with non-zero *above slope*, nor piers with non-zero *above way ribi*.  When setting this flag, *above way ribi* and *above slope* must both be set to zero.  Piers cannot rest upon a *low waydeck* pier without another pier on the same tile.

| ``topspeed=<unsigned>``
| Speed limit for ways on the pier.  This only effects the ways supported directly from this pier, not all subsequent layers.
| *default: 65535*

| ``max_weight=<unsigned>``
| Axle load limit for ways on the pier.  For roads, this limit is halved due to roads having two lanes.  This only effects the ways supported directly from this pier, not all subsequent layers.
| *default: 65535*

| ``max_altitude=<4 bits unsigned>``
| Maximum height above ground level for the pier.  A value of 0 is no height limit.  Values above 15 reserved for future use.
| *default: 0*

| ``tooltipflagsauto=<2 bit field>``
| ``tooltipflagsmanual=<2 bit field>``
| Flags to allow extra items on the menu icon tooltips definable by the pakset designer.  Setting the bits for "tooltipflagsmanual" will add "(PierTooltipM0)" and "(PierTooltipM1)" to the pier block menu icon tooltips.  Setting the bits for "tooltipflagsauto" will add "(PierTooltipA0)" and "(PierTooltipA1)" to the pier auto build menu icon tooltips.  The strings added are parsed by the translation system, thus translations for "(PierTooltipM0)" etc should be added if the pakset uses these flags.

| ``cursor=<image>``
| Image for manual placement cursor.

| ``icon=> <image>``
| Icon for manual placement.

Pier Images
-----------

The images for the piers are defined with ``backimage[<2 decimal digit slope>][<rotation>][<winter>]`` where the *2 decimal digit slope* is the slope of land that the pier is placed on, *rotation* is the orientation (``0`` to ``3``) of the pier, and *winter* is ``0`` for no snow, ``1`` for snow.  There are a few rules and implicit definitions for the combination of such sub-parameters:

* ``backimage[00][0][0]`` must be defined.

* If no *backimage* is defined for a slope with *rotation* and *winter* both being zero, then the pier is not buildable on ground of that slope.  (e.g. if ``backimage[01][0][0]`` is given in a pier, then the pier would not support slope value decimal 1.)  Valid values of slope are: 00; 01,03,09,27; 02,06,18,54; 04,12,28,36; 05,15,45,55; 07,21,29,63; 08,24,56,72; 10,30; 11,19,33,57; 13,31,37,39; 14,42,46,58; 16,32,48,64; 17,51,59,73; 20,60; 22,34,38,66; 23,47,61,69; 25,35,65,75; 26,62,74,78.  Note the groupings with the semicolons as these indicate groups where if one *backimage* is defined, the rest should be defined as well.

* If ``backimage[00][0][1]`` is defined, then for each ``backimage[<slope>][<rotation>][0]`` defined, a *backimage* must be defined for the same *slope* and *rotation* with *winter* set.  Not defining ``backimage[00][0][1]`` disables the snow-line for that particular pier.

* If ``backimage[00][3][0]`` or ``backimage[00][2][0]`` is defined, then for each ``backimage[<slope>][3][<winter>]`` defined, a four *backimages* must be defined for the same *slope* and *winter* with *rotation* equal to 0,1,2, and 3.  If ``backimage[00][1][0]`` is defined, then for each ``backimage[<slope>][3][<winter>]`` defined, a two *backimages* must be defined for the same *slope* and *winter* with *rotation* equal to 0 and 1.  The rotational symmetry of the pier in inferred with the status of the two previous if statements, so a pier that can be rotated 180 degrees without consequence would only need two *backimages* per *slope*/*winter* combination.  Likewise a a pier than can be rotated 90, 180, or 270 degrees without consequence would only need one *backimage* per *slope*/*winter* combination.

Due to the gaps in numbers for available slopes,some values of *slope* can be used for special purpose.

* *Slope* 40, *rotation* 1-3, *winter* 0: Optional additional icons for the same pier at different rotations.  Allows user to click once rather than set rotation, at the cost of more icons per menu.  Should be used for sloped piers or any special piers than would not be placed automatically.
* *Slope* 41, *winter* 0: By default, the when selecting rotation for manual placement, ``backimage[00][<rotation>][0]`` is used.  Defining *backimage* for this *slope* and *winter* value overrides the images shown.  The rules above still apply, except the *winter* set versions do not need to be defined.
* *Slope* 43: For piers with *low waydeck* enabled, the pier is drawn after a the way is.  This slope is used for images of flat piers with a transparent window for the way to be visible.  All above rules apply.
* *Slope* 79 and *slope* 80, *rotation* 0, *winter* 0: ``backimage[79][0][0]`` is the cursor for fully automatic pier placement, and ``backimage[80][0][0]`` is the icon for fully automatic pier placement.  They need to be defined for the pier to be used as a basis for automatic placement.  No other *backimages* for such slopes are required.  All other piers in the same group should have similar costs.
* *Slopes* 44,49,50,52: Optional parapet and gaurd-rail images.  When a set of images for slope 44 is given, a parapet object is placed on top of the pier.  When a *above way supplement* is added to the same tile, the image changes to that given for slope 49, 50, or 52 depending on the which two bits of *above way ribi* are set of the two previously unset *above way ribi* bits of the original pier.
* *Slopes* 53, 67, 68, 70,71,76, and 77: reserved for future use.

For every *backimage* defined except the special purpose ones, and optional *frontimage* can be defined with the same syntax (e.g. ``frontimage[00][0][0]``).

Automated and Semi-Automated Pier building
------------------------------------------

There are three methods for the user to build a pier, fully automated, semi-automated, and manual.  The manual and semi-automated methods are invoked by the main icon, and the fully automated method is invoked by the icon provided in ``backimage[0][0][0]``.

The manual method involves the user placing a pier one at a time by clicking or for some piers.  A player can also drag while clicking in the manual mode to fill in the land with piers.  During dragging, the pier placement only occurs within the line of the pier based on the *above way ribi* (*below way ribi* when *low waydeck* is set), or if such ribi is zero, the *drag ribi* is used.  If the resultant ribi is 0xF, then the line restriction is ignored.)

The semi-automatic method uses the dragging above, however rather than filling with the same type of pier regardless of elevation, the top layer is treated separately than the lower piers.  In order for the semi-automated method to work, for each top level pier type, there must be a lower level pier that has its *support mask* be a super set of the *base mask* of both itself and the top pier.  In this method, the top pier may, if needed, be substituted for one with the same *above way ribi* (*below way ribi* when *low waydeck* is set) with overlapping *auto group*.  The lower piers also would have an overlapping *auto group*.

The fully automated method is similar to building ways.  Like the semi-automated method the top level pier may be substituted, however the *ribi* is chosen based upon what is required by two clicks of the user.  Determining the lower piers is done more exhaustively, so it is possible to have different pier types at different elevations.  It also will use piers with *above way supplement* set if available and needed.   For the pakset designer, this means that for each pier *auto group*, there should be at least one with a straight ribi, one with a diagonal ribi, and supports for such.  For intersections on piers with this method, the pakset designer would also need to incorporate piers with *above way supplement* for retrofitting the straight and/or diagonal piers for intersections.

New Menus
---------

To put manual and automatic pier icons in a toolbar, use the the metatool ``piers()``, (e.g. ``toolbar[1][13]=piers()``).

It is recommended, however, to have a new toolbar for just the auto placement of piers, with a sub-toolbar for manual placement.  Auto tools are added with the metatool ``piers(A)`` with manual tools added with ``piers(M)``.  This also enables the in-game help menu for both toolbars. ``piertools.txt`` and ``pierblocks.txt`` respectively.  Optionally, metatools``piers(a#)`` and ``piers(m#)`` can be used to place auto tools and manual tools filtering by *deck obj mask* replacing the ``#`` with the value of the mask used for filtering.  This is handy to have, for example, only piers usable for canals in the canal menu.

| For example:
| ``toolbar[0][40]=toolbar[13],47,,PIERTOOLS,piertools.txt``
| ``toolbar[13][0]=piers(A)``
| ``toolbar[13][1]=toolbar[14],49,,PIERBLOCKS,pierblocks.txt``
| ``toolbar[14][0]=piers(M)``

Additions to Ways and Buildings
-------------------------------

For ways, a new parameter ``deckmask=<32 bit field>`` is added to filter ways put on a pier as is explained in *deck obj mask* above.  A default value of 0x00000000 permits the ways to be placed upon all piers.

For buildings, two bit fields ``pier_sub_1_mask=<16 bit field>`` and ``pier_sub_2_mask=<16 bit field>`` are used to enable piers to be built on the building or buildings to be built under piers.  The difference between the two is that *pier sub 1 mask* is use when the pier is at the same level as the buildings, whereas *pier sub 2 mask* is when the pier is one level up.  A default value of 0x0000 prevents the building from being under any pier without a *sub object mask* of 0x0000.  Note, these are technically a 32 bit fields, however the 16 MSBs are reserved for future use and may be 0x0000 or 0xFFFF.


Edited 21/01/01 22/01/02
Edited 22/01/06: Added parapets and end-user name
Edited 22/02/23: Added max_altitude and tooltip flags