Adv. HUD Indicator 2

From GMod Wiki

Jump to: navigation, search
Deletion.pngThis page has been nominated for deletion. Deletion is due within approximately 30 days from nomination, unless the deletion has been disputed on the talk page. See more pages nominated for deletion here.
Reason for deletion: Not what Garry wants the wiki to be used for
Last Edit was made on 11/16/2011


Contents

THIS PAGE IS STILL BEING WRITTEN!

Come back soon for actual content! -Moggie100

Installation

To install HUD2, create a folder in your addons directory (called whatever you like, but 'HUD2' seems appropriate) and SVN Checkout (using whatever client you prefer) this address into it: http://svn.dagamers.net/wiremodextras/dev/Adv%20HUD%20v2/

For help on using Subversion (SVN) see this page: Svn or this thread: http://www.wiremod.com/forum/wiremod-general-chat/4-wiremod-svn-guide.html or even this thread: http://www.facepunch.com/showthread.php?t=688324 !

HML

HUD Markup Language is based on XML and XML-like languages already out and popular in the wild. These include, but are not limited to XML itself, and the more commonly used DHTML/HTML.

This means that should you know any of the *ML languages, working with HML should be second nature, and you can skip over the 'Document Structure' part of this page.

Document Structure

A HML document formed of a tree-like structure of 'tags', each tag dividing the HUD into finer-grained detail than it's parent.

Tags come in THREE forms; OPENING, CLOSING and EMPTY form.

OPENING and CLOSING, are the most commonly seen forms, as for each OPENING form a corresponding CLOSING form must exist.

Between INNER-MATCHING pairs of OPENING/CLOSING tags, one or more child tags may reside, and will have their environment defined by the tag-pair surrounding them.

To those with a more practical mind; given that a tags named 'rect' define a rectangular area, the second pair of tags will be displayed relative to the outer pair. 

 
<rect>
   <rect></rect>
</rect>
 

This example also conveniently shows both the OPENING and CLOSING forms of tags; 

 
OPENING = <tagname>
CLOSING = </tagname>
 

This leaves only one other form of tag - the EMPTY tag. These take the form <tagname/> and act exactly the same as <tagname></tagname>, except without having to enter a closing tag.

As one might appreciate, EMPTY tags are empty - they have no child or inner elements - however, any tag can be in EMPTY form, including those which may normally have child tags, so if your script does not require child tags inside, simply use the EMPTY form.

Attributes

Tags alone only really describe relationships between elements, allowing for positions and sizes to cascade down from parent to child.

Attributes allow much finer-grained control over how elements are displayed.

Format

Attributes, in general terms consist of a NAME followed by a VALUE or EXPRESSION finished with a SEMICOLON (;)

Thus; 

 
<text value="Hello, World!";/>
 

Would set the value of 'value' in the tag 'text' to "Hello, World!".

Collections

Because its convenient to combine several variables into one handy portable entity, HML collections exist. At the moment, they're mainly used for vector and color definitions, following the schema below; 

 
2d = {x, y}
3d = {x, y, z}        (mapped to {r,g,b,255} for colors)
4d = {x, y, z, w}    (mapped to {r,g,b,a} for colors)
 

Although as -technicly- they can hold any type (reserved for later awesomeness), thus you -can- do this: 

 
<sometag variable={"This is a string",{10%,10%}, 44}; />
 

...and such... it'll break at the moment (nothing uses that functionality yet) but it is there :P

Inputs

As for inputs, anything after an @ starting with a CAPITAL LETTER is considered an input, eg; 

 
<circle radius=@Size; pos=2@Position; />
 

Where "@Size" is a number input and "2@Position" is a 2d vector input.

The prefixes for types are as follows:

Format Description
@InputName number
2@InputName 2d vector
3@InputName 3d vector
4@InputName 4d vector
c@InputName color (mapped to 3d vector)
a@InputName color with alpha (mapped to 4d vector) 
Inputs can have math performed on them like any other variable, in reality they get in-situe replaced and evaluated at runtime, so when they're being calculated they're just a number.

For example; 

 
<hml>
   <rect start={(30-@Input)%,30%}; end={(40-@Input)%,40%}; />
</hml>
 


Inline Expressions

While HUD2 doesn't have the power of an E2 chip (and isn't intended to have it!) it does support some basic math operations inline with attributes. These are split (internally) into several libraries, which may be expanded upon in the future, but currently contain the following functions;

Core Lib

Core functions for mathematical evaluation.

Function Example Description 
a + b
 
value=10+@Input;
 Adds two numbers together. 
a + b
 
value="Hello, "+"World";
 Concatenates two strings, or a string and a number. 
a + b
 
value={10,10}+{10,10};
 Adds the two vectors (accepts any form of vector, as long as their depth match!). 
a - b
 
value=10-5;
 Subtracts one number from another. 
a - b
 
value={10,10}-{5,5};
 Subtracts the contents from one vector from the other (accepts any form of vector, as long as their depth match!). 
a * b
 
value=5*5;
 Multiplies two numbers. 
a * b
 
value="wibble"*10;
 Repeats a string n times. 
a / b
 
value=10/2;
 Divides 'a' by 'b' 
a ^ b
 
value=2^10;
 Performs a 'power' operation.


Logic Lib

Logical operations - not true mathematics, but useful in programming!

Function Example Description 
clamp(value,min,max)
 
value=clamp(@Input,0,100);
 Clamps a number between two bounds. 
%
 
value={30%,20%};
 Calculates a context-based percentage. If INSIDE a collection, it will determine the tag's parent's dimensions and use those, otherwise it will assume a 0-100 range.


Trig Lib

Trigonometric operations - The same operations as Lua itself!

Function Example Description 
sin(N)
 
value=sin(@Input);
 The sine function. 
cos(N)
 
value=cos(30);
 Cosine function. 
tan(N)
 
value=tan(@Input);
 The tangent function. 
asin(N)
 
value=asin(@Input);
 Arc-Sine function. 
acos(N)
 
value=acos(@Input);
 Arc-Cosine function. 
atan(N)
 
value=atan(@Input);
 Arc-Tangent function. 
sinh(N)
 
value=sinh(@Input);
 Hyperbolic sine function. 
cosh(N)
 
value=cosh(@Input);
 Hyperbolic cosine function. 
tanh(N)
 
value=tanh(@Input);
 The Hyperbolic tangent function. 
atan2(N)
 
value=atan2(@Input);
 FIXME! This needs a decent explanation... 
abs(N)
 
value=abs(@Input);
 Calculates the ABSOLUTE value of a number, effectively returning the magnitude. 
ceil(N)
 
value=ceil(0.7);
 Returns '1' in the example here, as it rounds UP to the nearest integer. 
floor(N)
 
value=floor(0.7);
 Returns '0' in the example here. Rounds a number DOWN to the nearest integer. 
deg(N)
 
value=deg(@Input);
 Converts a value in radians to degrees. 
rad(N)
 
value=rad(30);
 Converts a number in degrees to radians. 
exp(N)
 
value=exp(@Input);
 The exponential function. 
fmod(N)
 
value=fmod(10,3);
 The floating-point remainder. 
frexpm(N)
 
value=frexpm(30.2082);
 Returns the mantissa component of a floating point number. [Coming next commit!] 
frexpe(N)
 
value=frexpe(30.2082);
 Returns the exponent component of a floating point number. [Coming next commit!] 
ldexp(N,N)
 
value=ldexp(10,7);
 The ldexp() function takes a normalized number and returns the floating point representation. This is the fractional value multiplied by 2 to the power of the exponent. 
log(N)
 
value=log(10);
 Returns the logarithm to a number with the base e (2.71828...). Also called natural logarithm. 
log10(N)
 
value=log10(2);
 Returns the logarithm of N base 10. 
pi()
 
value=pi();
 Returns 3.141... 
rand(N)
 
value=rand(10);
 Returns a random number between 0 and 'N'. 
sqrt(N)
 
value=sqrt(20);
 Returns the square-root of 'N'.

String Lib

String operations - useful functions for dealing with strings!

Function Example Description 
toByte(S,N)
 
value=toByte("Wibble",1);
 Gets the byte value of the character at 'N' in string 'S'. 
toChar(N)
 
value=toChar(@Input);
 Returns the character defined by the number 'N'. 
length(S)
 
value=length(s@Input);
 Returns the length of the supplied string. 
toLower(S)
 
value=toLower(s@Input);
 Converts all the characters in the string 'S' into lowercase form. 
toUpper(S)
 
value=toUpper(s@Input);
 Converts all the characters in the string 'S' into uppercase form. 
reverse(S)
 
value=reverse(s@Input);
 Reverses the order of the characters in the string 'S'.

Valid Tags

In the current build, the valid tags are as follows;

<hml>

This tag contains your hml document as a whole, and is required for a HML document to parse.

Reasons for this will become clearer later as HML develops (and I update this page...)

<rect>

A graphical primitive, the color-filled rectangle. It has these attributes:

Attribute Description Accepts
start Where on the screen the rectangle starts. 2d/3d vector
end Where on the screen the rectangle ends. If used together, end and start describe two diagonally opposed corners of the rectangle. 2d/3d vector
size An alternative way of sizing the rectangle, the size attribute takes a 2d vector of the rectangle's width and height. 2d/3d vector
width Equivalent to setting width with size attribute. number
height Equivalent to setting height with size attribute. number
rounded Whether or not the rectangle edges are rounded. Takes a number for radius, complete omission causes squared corners number
color The colour of the rectangle. 3d/4d vector
border The colour of the rectangle border. 3d/4d vector

<line>

Another graphical primitive, the coloured line. Attributes include:

Attribute Description Accepts
start Where the line starts 2d/3d vector
finish Where on the screen the line ends. 2d/3d vector
color The colour of the line. 3d/4d vector

<text>

Text to be drawn on the screen.

Attribute Description Accepts
position Where to position the text. Aliased as "pos" if you prefer a shorter term. 2d/3d vector.
value The actual text to be displayed. Any
color The colour of the text. 3d/4d vector
background The colour of the background. If used, there will be a wordbox around your text in this colour. 3d/4d vector
font The font in which text is displayed. No longer bugged, as of rev.161 ! String

<circle>

A graphical primitive, the circle. Currently at beta status.

Circles have no underlaying Lua command, so the algorithm has been written by hand, and uses many tiny rectangles to draw an approximate circle. However, because this is a fairly complicated piece of code, its quite buggy, but works fine for small radiuses (0 to about 50) beyond which it breaks up.

Attribute Description Accepts
position The centre of the circle. 2d/3d vector
radius The radius of the circle. Number
color The colour of the circle. 3d/4d vector
filled Whether or not the circle is filled with solid colour. Number - True if not 0

<status>

A metatag, using this makes the performance measuring tool of the indicator indicate to the player how much rendering power it is expending frame to frame. This can be used for optimising your HUD.

Valid Fonts

If unspecified, HML will default to 'Default' font!

Font Aliases

These font names are shortened versions of the fonts above, for faster, easier to read scripting.

Example HML document

This is an example HML document describing a basic percentage bar. We will build it up gradually, to show the workflow. 

 
<hml>
</hml>
 

Now we have an empty HML document. 

 
<hml>
    <rect start={35%,80%}; end={65%,83%}; color={125,125,125,125}; >
    </rect>
</hml>
 

Here we have added the parent rectangle that will hold the rest of our HUD elements for this bar. It is gray and seethrough at 125 in all colour channels.

It is worth noting that any tags within this rectangle tag will have its 'start' parameter as their origin, and their percentage-sizes defined by the size of the rectangle - thus; if you want to place the progress bar elsewhere, just move the outer-most rectangle! 

 
<hml>
    <rect start={35%,80%}; end={65%,83%}; color={125,125,125,125}; >
        <rect start={0%,90%}; end={@Percent%,10%}; color={0,255,255};>
        </rect>
    </rect>
</hml>
 

Now we have added a child rectangle which will be our actual percentage bar. It spans from 0% of the parent's width on one end to the value of the Percent input in percent of the parent's width on the other end, thus giving a visual indicator of the input's value. It leaves 10% of the parent's height open and viewable on its upper and lower edges (spans from 10% to 90% in height), and is colored in cyan. 

 
<hml>
    <rect start={35%,80%}; end={65%,83%}; color={125,125,125,125}; >
        <rect start={0%,90%}; end={@Percent%,10%}; color={0,255,255};>
                <text pos={100%, 0-20}; value=@Percent+"%"; />
        </rect>
    </rect>
</hml>
 

Here we have added a second indicator to the player of what the Percent input's value is: a text that hovers above the end of the percentage bar (the text's parent) and whose value is the numeric value of the Percent input, concatenated with a "%" sign. This is also our first example of an empty-style tag, as we don't need the text to have children.
For even better readability, we may also want to mark up a scale on the outer rectangle. 

 
<hml>
    <rect start={35%,80%}; end={65%,83%}; color={125,125,125,125}; >
        <rect start={0%,90%}; end={@Percent%,10%}; color={0,255,255};>
                <text pos={100%, 0-20}; value=@Percent+"%"; />
        </rect>
 
        <line start={50%,0%}; end={50%,100%}; color={0,0,0}; />
        <text pos={48.5%,100%}; value="50%"; />
    </rect>
</hml>
 

Now we have a line from {50%,0%} to {50%,100%}, or across the height of the parent rectangle at the exact halfway point of its width. To make this even more unambiguous, it is acompanied by a text that says, you guessed it, "50%". It is not positioned at 50% however. If you try that yourself, you may find that it looks off - the text is not centered on the line. If you've understood the example so far, you could try adding similar line-and-text markers for the 25% and 75% points yourself.

Retrieved from "http://wiki.garrysmod.com/?title=Adv._HUD_Indicator_2"
Personal tools
Namespaces
Variants
Actions
Navigation
Lua Scripting
Functions
Hooks
Toolbox