Crossfire Archetype Guide
=========================
Crossfire Development Team <crossfire@metalforge.org>
:numbered:
:toc:

Introduction
------------
This file contains general design notes about archetypes and faces. For more
technical details about how archetypes are handled inside the engine, see
'server/doc/Developers/objects' and 'server/doc/Developers/objects.dox'.

Some bits of info like types and subtypes are defined in
'server/include/object.h'.

Item Attributes
---------------
Correctly choosing item attributes is key to maintaining balance and fun.

Value
~~~~~
Values are given in integer silver coins.

Weight
~~~~~~
Weights are given in integer grams, and should resemble those of real-life
counterparts to objects. You may find some objects do not follow this closely,
so examine similar objects to better judge what weight to set. For extremely
bulky objects, you can increase the weight a bit to simulate the difficulty of
carrying large objects.

At one time, it was theorized that players would have a weight limit of about
100kg, but currently the balance is pretty far from this.
--DraugTheWhopper 4/20/2021

Images
-------
Images must be stored in PNG, optionally with indexed color, and be compressed
by tools such as optipng or pngcrush.

Licensing
~~~~~~~~~
When adding new artwork, add a sidecar file containing the licensing
information. Use freeform text comments marked by "#" to describe the origins,
author, and link to the source if applicable. After the comments, use a
"license" line to state the license name, and and "licenseurl" line to link to
the full license text. Also, use a "sourcename" line to specify the
author's or licensor's name or handle, and a "sourceurl" line to link to the
most original source possible, if it's publicly available on the internet.

If some piece of information has several values, like multiple contributing
authors, feel free to add another line for each item, like one "sourcename"
line for each author.

The license sidecar file name can vary based on the item type.

As an example of how to format the sidecar file, reference
"/misc/Container/depositbox.base.LICENSE"

If creating or adapting new artwork for the project, a Creative Commons license
is preferred, but other FOSS-type licenses are acceptable.

Perspective
~~~~~~~~~~~
Some coloring/perspective hints/clarifications from David Sundqvist:

Perspective in Crossfire is based on the XY coordinate system of possible
player movements, with a slight tilting of the graphics to allow for
greater detail and more interesting graphics, since walls have to be in
that perspective to allow joining. X and Y in graphics should correspond
to X and Y in the object. Z in the object is represented with 2 Y/X.
Keeping perspective consistency is mainly important in fixed objects
like buildings, walls and other background.

Light should generally come from the right side, so the left side of
buildings should be darker or shaded, as needed. 

Wind is generally coming from the left side, so smoke or other things
affected by wind should be travelling towards the right side.

Naming Conventions
------------------

Archetype File Name
~~~~~~~~~~~~~~~~~~~
Archetype file names should end with an extension of '.arc'. Image files
have a 3-digit extension in the form of '.PDA', where:

    P:: part number
    D:: coding, or any other instance coding in
    A:: animation phase

.License sidecar names

When an artwork file would be 'name.imageset.PDA.png', the license sidecar
should be 'name.imageset.LICENSE'. For example,
'/misc/Container/depositbox.base.111.png' has a sidecar file
'/misc/Container/depositbox.base.LICENSE'. Note that the the "P/D/A" suffix
is omitted. We also do not specify that the license is for the .png file only,
in case we have both a vector image and raster image, in which case it is
assumed to apply to both.

Numbering (PDA)
^^^^^^^^^^^^^^^

    - 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F, ..., Z
    - Alphanumeric
    - Can be thought as hexadecimals

Part Numbers
^^^^^^^^^^^^

    3x3::
-----
1 2 3
4 5 6
7 8 9
-----

    2x2::
----
1 2
3 4
----

    3x2::
-----
1 2 3
4 5 6
-----

    2x3::
----
1 2
3 4
5 6
----

Codings
^^^^^^^

.Direction

        8  1  2
         \ | /
        7- 0 -3
         / | \
        6  5  4

(Same as in Crossfire)

.Turnable (reflecting objects)

 - 0 to left, vertical
 - 1 to right, horizontal
 - also in gates, signs, ...

Walls
~~~~~

Name format: 'name_X.arc', 'name_X.PDA.png'

           1
           |
        8 -+- 2
           |
           4

X is a bit-wise combination expressed in hexadecimal form.  For example,
8 + 4 + 2 + 1 = F describes a vertical cross, and 4 + 1 = 5 identifies a
vertical wall.

P, D, and A are always 1.

.License sidecar names for walls

When a wall artwork file would be 'name_X.imageset.PDA.png', the license sidecar
should be 'name.imageset.LICENSE'. For example,
'/wall/bwall/bwall_0.base.111.png' has a sidecar file
'/wall/bwall/bwall.base.LICENSE'. Note that the wall connection suffix is
omitted, as well as the "P/D/A" suffix. We also do not specify that the license
is for the .png file only, in case we have both a vector image and raster
image, in which case it is assumed to apply to both.

.Object Names

When creating '.arc' files, the object name is determined by a similar,
but distinctly different, scheme. See the server code in
'server/build_map.c' and 'random_maps/wall.c' for the source of the
information that follows. The arch name (ie. awall) must not have any
underscores. A suffix in the form _U[_V[_W]] is appended to the arch
name.

U is the number of connection points (ie. for a pillar U == 0, and for
a cross U == 4).

At the time of this writing, the formulae for calculating V and W is
not known, but, U, V, and W can be determined as follows. Calculate a
value called "connect" by adding the values of the connecting points:

               4
               |
            1 -0- 2
               |
               8

Then use "connect" to pick a suffix:

            0:  _0
            1:  _1_3
            2:  _1_4
            3:  if (has_window)
                    _win2
                else
                    _2_1_2
            4:  _1_2
            5:  _2_2_4
            6:  _2_2_1
            7:  _3_1
            8:  _1_1
            9:  _2_2_3
            10: _2_2_2
            11: _3_3
            12: if (has_window)
                    _win1
                else
                    _2_1_1
            13: _3_4
            14: _3_2
            15: _4

For a complete example, a vertical cross wall graphic in an awall arch set
is named awall_F.base.111.png. Face information is kept in awall_F.face,
and the archetype data is in awall.arc. Inside awall.arc, the Object name
is awall_4.

Diagonal Walls and Roads
~~~~~~~~~~~~~~~~~~~~~~~~
The legacy wall-naming convention is used in conjunction with the extension
to the name format described here to provide a uniform naming scheme that
supports corner connections. Legacy names do not need to change to simply
add diagonal versions of the legacy graphics.

The name format is 'name_XY.arc', 'name_XY.PDA.png'

X follows the same rules as used for the legacy wall format, except that
when there are no NSEW connecting points, X == 0.

Y may be omitted, or may be 0 if diagonal connecting points are not offered
by the arch. If diagonal connecting points are implemented, Y is a bit-wise
combination computed in the same manner as X, and is also expressed as a
hexadecimal digit. The difference is that it refers to corner connections:

        1   2
         \ /
          X
         / \
        8   4

For example, name_0F refers to a diagonal cross, or connecting points in
all four corners. name_05 and name_0A refer to pure diagonals.

Since diagonal pieces require corner fills, P is used to differentiate the
component parts of the diagonal.

P (part number) ranges from 1 to 3:

    1:: used for "normal" pieces that connect direction points.

    2:: used for a top corner fill needed to complete diagonal
        connections.

    3:: used for a bottom corner fill needed to complete diagonal
        connections.

Examples of diagonal files are 'dirtroad_05.211', 'dirtroad_05.311',
'dirtroad_0A.211', and 'dirtroad_0A.311'. The archetypes for these are stored
in 'dirtroad_05.arc' and 'dirtroad_0A.arc'. The corner fill is a "part" of a
diagonal, and is not really useful on its own.

The '.211' and '.311' file names are based on the full diagonal, but are used
for all diagonal connecting points. Usually it is not necessary to
customize the corner piece to fit each and every possible XY combinationi
that incorporates a diagonal connecting point.

.Object Names

When creating object names, use a different format (_U_XYP) unless
the legacy naming format can be figured out and adapted to the
diagonal set - in which case, it should be documented here. This
format allows consistent object naming in the event that renaming is
desirable in the future, and it does not collide with the legacy
object naming.

    U:: Number of connecting points
    X:: X and Y are re-used as described above
    P:: Part number

Rivers
~~~~~~
WARNING: Consider deprecation of this format in favor of the extended wall
naming. It is more flexible than this format.

Simple diagonals, like non-branched rivers, are saved as 'name_XY.arc' and
'name_XY.PDA.png'.

X and Y use the direction scheme shown above (and copied here for ease of
reference). For example, river_15 runs north/south; river_26 runs from the
northeast to the southwest.

            8  1  2
             \ | /
            7- 0 -3
             / | \
            6  5  4

X and Y do not define direction of water flow. They are simply connecting
points to neighboring arches of the same set. X and Y are ordered low to
high, so it is not expected that a river_62 exist; instead the piece is
named river_26.

A cul-de-sac, or dead-end could have X == 0 and Y set to the connect point.
Conceptually, a pool could follow this same naming convention and set
X == Y == 0.

D and A are presently always set to 1.

P ranges from 1 to 3.

    1:: used for "normal" pieces that connect direction points.

    2:: used for a top corner wedge used to fill in diagonals (i.e. A
        wedge in the top right or top left corner).

    3:: used for a bottom corner wedge used to fill in diagonals (i.e.
        A wedge in the bottom right or bottom left corner).

Examples of wedges are river_48.211, river_48.311, river_26.211, and
river_26.311. The archetypes for these are stored in river_48.arc and
river_26.arc. The wedge is a "part" of a diagonal, and is not really useful
on its own.

River junctions, add another digit to the format used by simple diagonals,
and are stored as name_XYZ.arc and name_XYZ.PDA.

X, Y, and Z represent the three directions the river exits. 367 would be
east,southwest, and west. Junctions, or branchesi, may also have multiple
parts - this happens when the junction has a diagonal direction.

By convention, directions for the river parts are in ascending order. That
is, if the exit locations are 2, 6, 3, the name could be branch_236 (not
branch_326, or branch_623, etc).

Complex branching paths could be set by adding digits to allow four or more
connecting points, but use of the extended walls format is recommended
instead.