Layouts.md

+Layouts are a collection of positioned assets to be displayed together.  These elements are arranged based on the viewer's screen height and width, to scale to any game window or GUI scale size.
+
+Layouts are displayed to the player on an invisible Boss Bar, and can be toggled with the `/hud layout` [Commands](Commands).
+
+[Pop-ups](Pop-Ups) are configured the same as Layouts, however they are only shown to the player for a duration of time, rather than toggled on/off.
+## Arrangement
+### Alignment
+Asset layers move in the direction of their alignment, from their start position:
+
+| **align:** | `left` | `center` | `right` |
+| ---------- | ------ | -------- | ------- |
+### Position
+The position of the element relative to the screen size of the player.   This uses values from 0 to 100 to represent the location percentage horizontally and vertically the asset's origin should be placed.
+```yaml
+  position:
+    x: 50
+    y: 50
+```
+#### Example Positions
+
+| **X** | **Y** | **Description**         |
+| ----- | ----- | ----------------------- |
+| 0     | 0     | Absolute Lower Left     |
+| 0     | 100   | Absolute Upper Left     |
+| 100   | 0     | Absolute Lower Right    |
+| 100   | 100   | Absolute Upper Right    |
+| 50    | 50    | Center a.k.a. Crosshair |
+| 50    | 0     | Center Bottom           |
+| 50    | 100   | Center Top              |
+
+Positions are the starting origin for the offset pixel arrangement of an asset - these work together to provide consistent placement of assets in HUDs.
+For example, a position of `x: 50` and `y: 0` originates at the bottom center of the screen, usually the player's hotbar - so using an offset of `y: 55` can ensure that a HUD is always bottom center, but pushed above the hotbar, regardless of screen or GUI scale size.
+### Offset
+Pixel positioning to further move the asset's placement by a fixed amount from its position.
+```yaml
+  offset:
+    x: -5  # pixels left/right
+    y: 2   # pixels up/down
+```
+#### Example
+```yaml
+default-layout:
+  elements:
+    health:
+      asset: 'vanilla-health'
+      align: left
+      position:
+        x: 50.0
+        y: 0
+      offset:
+        x: -10
+        y: 55
+    food:
+      type: 'asset'
+      asset: 'vanilla-hunger'
+      align: right
+      position:
+        x: 50.0
+        y: 0.0
+      offset:
+        x: 10
+        y: 55
+    armor:
+      asset: 'vanilla-armor'
+      align: left
+      position:
+        x: 50.0
+        y: 0.0
+      offset:
+        x: -10
+        y: 65
+    air:
+      asset: 'vanilla-air'
+      align: right
+      position:
+        x: 50.0
+        y: 0.0
+      offset:
+        x: 10
+        y: 65
+```
\ No newline at end of file