MQWCL HUD CONFIGURATION
=======================

What is a HUD element?
----------------------
Hud element is a single 2D element, that can be drawn on-screen, moved to
different positions, aligned etc.. Most of HUD elements also have ability to
display frame beneath themselves (background).

HUD element have a name, which is a string, like "netgraph", "fps" etc..
You use that name in HUD commands, like "show netgraph". Given HUD element
remembers its all settings (its properties) as variables, which are named

    hud_<hud_name>_<property_name>

examples:

    hud_netgraph_frame
    hud_ping_period

etc..

Changing property is simple. As you can easily guess, simple way to do
this is changing the variable. There is more convinient way however.
Try typing element name at console, like this:

    netgraph <enter>

You will see some infos about netgraph and list of its properties with
its current values. If you want to change some - it's easy:

    netgraph frame 0    // disable background
    netgraph show  0    // same as hide netgraph

This is a preferred way, however there is no TAB completion for properties
now - coming soon..

Some properties (like "show") are controlled by commands (like "show" and
"hide"). Some of them (those for setting element position) will not have
effect, if you change them directly by vars. If you do so, try
"hud_recalculate" command.

Showing and hiding
------------------
To show given HUD element, use show command givind element name as
a parameter. Giving no parameters will display a list of all HUD elements
with its current status. There is a special parameter - "all" - which
you can use to show all elements. Examples:

    show netgraph   // shows netgraph
    show fps        // show fps counter
    show            // list HUD elements
    show all        // shows all hud elements

For opposite - there's a "hide" commands, which should be self-explanatory.

Current status in rememberd as a "show" property, so typing

    show netgraph

will have a similar effect as typing

    netgraph show 1

Let's move them
---------------
When you want to move given HUD element, firstly you have to decide what
screen area it occupies. Use command:

    place <element-name> <where-to-place>

And possible places are:
    "screen"    - screen,
    "view"      - view area (depends on viewsize var),
    "top"       - area above status bar,
    "sbar"      - sbar area (health bar + inventory bar, no free
                  space after sbar, if you play at higher res)
    "ibar"      - inventory bar (upper part of sbar),
    "hbar"      - health bar (lower part of sbar),
    "sfree"     - free area after status bar (if res > 320 or hud_sbar_size
                  changed),
    "ifree"     - free area after inventory bar,
    "hfree"     - free area after health bar,

Some examples:

    place netgraph screen
    place fps top
    place health hfree

If you have a place for your favourite element, align it to some edges.
Command is, obviously, "align". Syntax:

    align <element-name> <X-alignment> <Y-alignment>

X-alignment can be:

    "left"      - left edge of area chosen by "place",
    "center"    - center,
    "right"     - right area,
    "before"    - explained later..
    "after"     - explained later..

Y-alignment can be:

    "top"       - top edge,
    "center"    - center,
    "bottom"    - bottom :)
    "console"   - below console (like clock by default)
    "before", "after" - explained later..

Example:

    align netgraph left top     // left upper corner
    align fps right bottom      // right lower corner

Finally, if element position still does not match your preferences, you can
fine-tune it with "move" command. Syntax is:

    move <element_name> <X-offset> <Y-offset>

Offsets can be either negative or positive. Positive X offset moves
element to the right, and positive Y-offset moves element
to the bottom. Exaples:

    move netgraph 2 2   // move 2 pixels right and 2 pixels down
    move fps -10 5      // 10 pixels left, 5 pixels bottom

Note, that your element will not be drawn, if you locate it off the screen,
even partially.

All those commands - place, align, move - can be used without parameters
(print help then) or with on parameter - HUD element name. Then current
values are printed.

Add/remove frame
----------------
Frame is a regular property, it differs a little because every HUD element
can have a frame. Values for frame property are:

    0 - no frame
    1 - black frame
    (0..1) - transparent frame, lower number means more transparency,
    2 - a box like that for netgraph.

Examples:
    net frame 2         // add nice frame for network statistics
    netgraph frame 0    // make netgraph more useful
    fps frame 0.6       // make fps more readable

Relative positioning
--------------------
You can align some elements relative to other elements. Firstly you have
decide, if you element, which you are locating now (element B) is to be inside
another element (element A) or outside it.

If outside, do:

    place A B

if inside, do:

    place A @B

examples:

    place fps @net
    place health face
    place iammo health
    place ammo iammo

Then yu have to align it. If you want to place it outside, you have
some additional alignments - before and after.

Examples:

    place health after top
    plce iammo after top
    place ammo after top

and you have a nice chain combined of healht, armor and it's icons.

You can ask what is the difference between inside and outside placing..
You can eaily see it if you add frame to your elements, that enlarge
them (like frame 2).

HUD elements
------------
Currently list of HUD elements contains few elements for occasional use
(like netgraph), many elements taken from your status bar (reorganize your
screen with them) and additional "group" objects, which display nothing
(except frame if enabled) and can be used for groupping some objects
together (like ammo counts).
Full list is:

    fps         - fps counter
    net         - net statistics
    ping        - small net statistics,
    netgraph    - everything about net,
    clock       - clock


    iarmor      - armor icon
    armor       - armor level
    face        - player face
    health      - health level
    iammo       - current ammo icon
    iammo1      - shells icon
    iammo2      - nails icon
    iammo3      - rockets icon
    iammo4      - cells icon
    ammo        - current ammo value
    ammo1       - number of shells
    ammo2       - number of nails
    ammo3       - number of rockets
    ammo4       - number of cells
    gun         - current weapon icon
    gun2        - shotgun icon
    gun3        - super shotgun icon
    ...
    sigil1      - sigil 1 icon (rune)
    sigil2      - sigil 2 icon
    ...
    key1        - silver key
    key2        - gold key
    suit        - suit icon
    quad        - quad icon
    pent        - pentagram icon
    ring        - ring icon

    
    group1      - groupping object
    ...
    group5      - ...

Every element has its own properties. You can check them, by simply typing
element name in console. Some common properties are described below, which
affect you inventory elements - guns, health etc..

    style - this always change the look of the element, styles are
        different, depending on element type; usually there is one style
        which, if enabled, enables text-mode look of element (like gun6
        is "gl", health level with small text etc.). Style values are
        cardinal numbers (0, 1, ...)

    scale - mostly for GL users (currently it doesn't work in SOFT) - lets
        you change size of element - make health 2 times bigger etc..
        With scale you can make a HUD that look like in 320x200 (big numbers),
        and still have -width 640 without conwidth, so your console holds more
        text

    wide - only used with "gun" and "gun8" and affects style of lightning gun
        icon,

    align - used for numbers (health, armor etc..) and specify, how they should
        be aligned,

    digits - used for numbers and specify how many digits they should display,
        for example to save space, you can have your ammo printed only with
        two digits, it will always show 99 if is more than 100

Groupping elements have only two properties - width and height - they should
be self-explanatory.

It's damn difficult
-------------------
But flexible I think. Check examples, if you have some problems with
understanding HUD. If you made some screen arrangements you think may be
useful for others -  feel free to send them to me (mqwcl@go2.pl), that may
be included with next version of examples files.
