Element Positioning - rbjaxter/budhud GitHub Wiki

(this is a work in progress)

TL;DR

  • xpos/ypos/wide/tall are controlled by units, not screen pixels
  • Minimum screen size is 640x480
  • Maximum xpos is dependent on user resolution
  • Maximum ypos value is 480
  • In general, elements are moved from the top left corner of their overall bounding box
    • Depending on if the element is pinned, it may move differently than this

Values

HUD element locations are controlled on a cartesian coordinate plane system (xyz).

    "Example Element"
    {
        "ControlName"                                               "ImagePanel"
        "fieldName"                                                 "Example Element"
        "xpos"                                                      "0"
        "ypos"                                                      "50"
        "zpos"                                                      "0"
        "wide"                                                      "f0"
        "tall"                                                      "100"
        "autoResize"                                                "0"
        "pinCorner"                                                 "0"
        "labeltext"                                                 ""
        "visible"                                                   "1"
        "enabled"                                                   "1"
        "fillcolor"                                                 "bh_Theme_BG20"
        "image"                                                     ""
        "paintbackgroundtype"                                       "0"
    }
  • xpos controls left/right positioning
  • ypos controls up/down positioning
  • zpos controls front/back positioning (an element with a higher zpos will draw above an element with a lower zpos)

Bounding Box

When adjusting these values, the element is moved relative to the top left corner of the element. The wide and tall values determine the overall size of the element, which I refer to as the bounding box (there may honestly be a more proper name but w/e lmao).

Element Bounding Box

When an element is nested within another element (in other words, the element has a parent element), it is possible to move the nested element outside of the parent element's own bounding box. This is almost always the explanation for elements or text being cut off.

Example

Here's a quick visualization of a child element (SubButton) being cut off by its parent element's (MutePlayersButton) bounding box:

image

HUD Units

The units of measurement for TF2 hud editing are known as units, not screen pixels. The minimum screen size for TF2 is 640 x units and 480 y units. The maximum x unit is dependent on your aspect ratio, whereas the maximum y unit will always be 480 units.

This means that any ypos value between 0 and 480 will show in the same place on every resolution. Anything over 480 is not guaranteed to be in the same place on every aspect ratio.

Because HUD elements move from the top left corner of the element, setting the ypos value of something to 479 would only show one row of pixels of that element (I know this explanation kinda sucks, but you can also see it under "Quick Reference" below).

The maximum xpos value is a bit harder to explain, because it varies due to aspect ratio. I need to flesh out this section, but the general rule of thumb is that using c-values ("center" values, such as c50. see "Quick Reference" for more info) in your xpos values will save you a lot of headaches. c-values will position the element from the center of the screen instead of the left corner of the screen, which mitigates a lot of issues you might run into on other aspect ratios.

A c-value will stay where it is relative to the center regardless of aspect ratio, whereas a regular value will adjust based on aspect ratio. As an example, if I have a "CLOSE" button that I want to stay on the left edge of my screen, I would use a regular xpos value (e.g., "xpos" "50"). When my resolution increases, it will remain 50 units away from the left side of my screen, thus moving to the left as the horizontal resolution increases. If I instead wanted it to stay in the same place regardless of resolution (such as for health or ammo), I would use a c-value (such as xpos c-50). Center values work this way because they are based on where the center of the screen is, not the edges of the screen.

Quick Reference

Normal Value

  • xpos: Element moves from the left of the screen to the right
  • ypos: Element moves from the top of the screen to the bottom

r (reverse/right) Value

  • xpos: Element moves from the right of the screen to the left
  • ypos: Element moves from the bottom of the screen to the top

c (center) Value

  • xpos: Element moves from the center of the screen
    • If you use a positive value, it moves from center to the right
    • If you use a negative value, it moves from center to the left
  • ypos: Element moves from the center of the screen
    • If you use a positive value, it moves from center to the top
    • If you use a negative value, it moves from center to the bottom

s (scale) Value

  • xpos/ypos: Element's position is based on a percentage of the total size of the element (e.g., its wide or tall value)
  • Example: s0.5 will move the element 50% of the distance of the parent's wide or tall value

f (fill) Value

  • wide/tall: Element extends the length of the parent and then subtracts the specified offset (if any set).
  • If no offset given (e.g., f0), it will fill the entire distance
  • For getting started, all you really need to know about is f0. You do this for a lot of the main elements so your bounding boxes always takes up the whole screen, thus avoiding any cut-off issues

p (proportional) Value

o Value

  • xpos/ypos: Element's position is based on a percentage of the other value
  • wide/tall: Same as above
  • Example: wide 100, tall o1 is equal to wide 100, tall 100. tall o0.5 would be 50% of wide 100, so tall 50 would be its equivalent.

Some of these value types can be complicated to understand, but if it's any consolation: from personal experience with budhud, I've found that 90% of my hud uses regular, r-values, or c-values. For f-values, I really only ever use f0. For scale values, I only ever really use cs-0.5.

Test Element

	"Test Element"	
	{
		"ControlName"		"ImagePanel"
		"fieldName"		"Test Element"
		"xpos"			"0"
		"ypos"			"0"
		"zpos"			"0"
		"wide"			"100"
		"tall"			"100"
		"autoResize"		"0"
		"pinCorner"		"0"
		"labeltext"		""
		"visible"		"1"
		"enabled"		"1"
		"fillcolor"		"bh_Theme_BG20"
		"image"			""
		"paintbackgroundtype"	"0"
    }
  • Given the above test element, the images below show how changes solely to the xpos and ypos values affect it.
  • This element is not nested within another element (which would make that element this one's "parent"). Because of this, the "parent" of this "Test Element" is the actual screen space.

xpos: 0, ypos: 0

  • Normal value
  • xpos: Value moves from left to right
  • ypos: Value moves from top to bottom 0 0

xpos: 0, ypos: 479

  • This shows how y-based screen space is fixed to 480 units
  • ypos 479 translates to only showing one unit's worth of pixels in the bottom left 0 479

xpos: r0, ypos: r0

  • r-value: the "r" means "right" (probably)
  • xpos: Value moves from right to left
  • ypos: Value moves from bottom to top
  • Element not visible and appearing just off-screen in the bottom right r0 r0

xpos: r100, ypos: r100

  • Element is now visible because we've told it to move the size of its wide/tall value r100 r100

xpos: c0, ypos: 240

  • c-value: the "c" refers to "center"
  • Offset: whole number representing a unit
  • ypos 240 (480 total y-based screen space divided by 2) places the element in the center of the screen c0 240

xpos: c0, ypos: c0

  • No change between ypos: 240 and ypos: c0 c0 c0

xpos: c-50, ypos: c-50

  • Centers the element, and then moves the element by 50 units (half of its wide and tall value, thus centering it c-50 c-50

xpos: s1, ypos: s1

  • s-value: the "s" refers to "scale"
  • Offset: Percentage in decimal form
  • Element will be offset by a percentage of its wide/tall or parent value
  • In this example, the element is being offset by 100% of its wide and tall values (100) s1 s1

xpos: cs-0.5, ypos: cs-0.5

  • Centers the element, and then moves the element by the offset of its own size
  • In this example, the element is placed in the middle of the screen and then uses a negative offset to properly center it
  • Same result is achieved with xpos: c-50, ypos: c-50, but with this method you'd only need to make changes to your wide/tall values to keep the element properly centered cs-0.5 cs-0.5

References