HUD¶

HUD element types¶

The position field is used for all element types.

To account for differing resolutions, the position coordinates are the percentage of the screen, ranging in value from 0 to 1.

The name field is not yet used, but should contain a description of what the HUD element represents.

The direction field is the direction in which something is drawn. 0 draws from left to right, 1 draws from right to left, 2 draws from top to bottom, and 3 draws from bottom to top.

The alignment field specifies how the item will be aligned. It is a table where x and y range from -1 to 1, with 0 being central. -1 is moved to the left/up, and 1 is to the right/down. Fractional values can be used.

The offset field specifies a pixel offset from the position. Contrary to position, the offset is not scaled to screen size. This allows for some precisely positioned items in the HUD.

Note: offset will adapt to screen DPI as well as user defined scaling factor!

The z_index field specifies the order of HUD elements from back to front. Lower z-index elements are displayed behind higher z-index elements. Elements with same z-index are displayed in an arbitrary order. Default 0. Supports negative values. By convention, the following values are recommended:

-400: Graphical effects, such as vignette
-300: Name tags, waypoints
-200: Wieldhand
-100: Things that block the player's view, e.g. masks
0: Default. For standard in-game HUD elements like crosshair, hotbar, minimap, builtin statbars, etc.
100: Temporary text messages or notification icons
1000: Full-screen effects such as full-black screen or credits. This includes effects that cover the entire screen
Other: If your HUD element doesn't fit into any category, pick a number between the suggested values

Below are the specific uses for fields in each type; fields not listed for that type are ignored.

`image`¶

Displays an image on the HUD.

scale: The scale of the image, with 1 being the original texture size. Only the X coordinate scale is used (positive values). Negative values represent that percentage of the screen it should take; e.g. x=-100 means 100% (width).
text: The name of the texture that is displayed.
alignment: The alignment of the image.
offset: offset in pixels from position.

`text`¶

Displays text on the HUD.

scale: Defines the bounding rectangle of the text. A value such as {x=100, y=100} should work.
text: The text to be displayed in the HUD element.
number: An integer containing the RGB value of the color used to draw the text. Specify 0xFFFFFF for white text, 0xFF0000 for red, and so on.
alignment: The alignment of the text.
offset: offset in pixels from position.
size: size of the text. The player-set font size is multiplied by size.x (y value isn't used).

`statbar`¶

Displays a horizontal bar made up of half-images with an optional background.

text: The name of the texture to use.
text2: Optional texture name to enable a background / "off state" texture (useful to visualize the maximal value). Both textures must have the same size.
number: The number of half-textures that are displayed. If odd, will end with a vertically center-split texture.
item: Same as number but for the "off state" texture
direction: To which direction the images will extend to
offset: offset in pixels from position.
size: If used, will force full-image size to this value (override texture pack image size)

`inventory`¶

text: The name of the inventory list to be displayed.
number: Number of items in the inventory to be displayed.
item: Position of item that is selected.
direction
offset: offset in pixels from position.

`waypoint`¶

Displays distance to selected world position.

name: The name of the waypoint.
text: Distance suffix. Can be blank.
precision: Waypoint precision, integer >= 0. Defaults to 10. If set to 0, distance is not shown. Shown value is floor(distance*precision)/precision. When the precision is an integer multiple of 10, there will be log_10(precision) digits after the decimal point. precision = 1000, for example, will show 3 decimal places (eg: 0.999). precision = 2 will show multiples of 0.5; precision = 5 will show multiples of 0.2 and so on: precision = n will show multiples of 1/n
number: An integer containing the RGB value of the color used to draw the text.
world_pos: World position of the waypoint.
offset: offset in pixels from position.
alignment: The alignment of the waypoint.

`image_waypoint`¶

Same as image, but does not accept a position; the position is instead determined by world_pos, the world position of the waypoint.

scale: The scale of the image, with 1 being the original texture size. Only the X coordinate scale is used (positive values). Negative values represent that percentage of the screen it should take; e.g. x=-100 means 100% (width).
text: The name of the texture that is displayed.
alignment: The alignment of the image.
world_pos: World position of the waypoint.
offset: offset in pixels from position.

`compass`¶

Displays an image oriented or translated according to current heading direction.

size: The size of this element. Negative values represent percentage of the screen; e.g. x=-100 means 100% (width).
scale: Scale of the translated image (used only for dir = 2 or dir = 3).
text: The name of the texture to use.
alignment: The alignment of the image.
offset: Offset in pixels from position.
dir: How the image is rotated/translated:
0 - Rotate as heading direction
1 - Rotate in reverse direction
2 - Translate as landscape direction
3 - Translate in reverse direction

If translation is chosen, texture is repeated horizontally to fill the whole element.

`minimap`¶

Displays a minimap on the HUD.

size: Size of the minimap to display. Minimap should be a square to avoid distortion.
alignment: The alignment of the minimap.
offset: offset in pixels from position.

`csm_button`¶

Displays a pressable image on the HUD. Takes the same parameters as image, plus passes the name field to core.register_on_hud_button_press CSM callbacks. The text2 field may be used for a pressed texture.

Only works on touchscreens, this acts exactly like a regular image on other devices.

CSM: HUD element types¶

The position field is used for all element types.

To account for differing resolutions, the position coordinates are the percentage of the screen, ranging in value from 0 to 1.

The name field is not yet used, but should contain a description of what the HUD element represents. The direction field is the direction in which something is drawn.

0 draws from left to right, 1 draws from right to left, 2 draws from top to bottom, and 3 draws from bottom to top.

The alignment field specifies how the item will be aligned. It ranges from -1 to 1, with 0 being the center, -1 is moved to the left/up, and 1 is to the right/down. Fractional values can be used.

The offset field specifies a pixel offset from the position. Contrary to position, the offset is not scaled to screen size. This allows for some precisely-positioned items in the HUD.

Note: offset will adapt to screen DPI as well as user defined scaling factor!

Below are the specific uses for fields in each type; fields not listed for that type are ignored.

Note: Future revisions to the HUD API may be incompatible; the HUD API is still in the experimental stages.

`image`¶

Displays an image on the HUD.

scale: The scale of the image, with 1 being the original texture size. Only the X coordinate scale is used (positive values). Negative values represent that percentage of the screen it should take; e.g. x=-100 means 100% (width).
text: The name of the texture that is displayed.
alignment: The alignment of the image.
offset: offset in pixels from position.

`text`¶

Displays text on the HUD.

scale: Defines the bounding rectangle of the text. A value such as {x=100, y=100} should work.
text: The text to be displayed in the HUD element.
number: An integer containing the RGB value of the color used to draw the text. Specify 0xFFFFFF for white text, 0xFF0000 for red, and so on.
alignment: The alignment of the text.
offset: offset in pixels from position.

`statbar`¶

Displays a horizontal bar made up of half-images.

text: The name of the texture that is used.
number: The number of half-textures that are displayed. If odd, will end with a vertically center-split texture.
direction
offset: offset in pixels from position.
size: If used, will force full-image size to this value (override texture pack image size)

`inventory`¶

text: The name of the inventory list to be displayed.
number: Number of items in the inventory to be displayed.
item: Position of item that is selected.
direction
offset: offset in pixels from position.

`waypoint`¶

Displays distance to selected world position.

name: The name of the waypoint.
text: Distance suffix. Can be blank.
precision: Waypoint precision, integer >= 0. Defaults to 10. If set to 0, distance is not shown. Shown value is floor(distance*precision)/precision. When the precision is an integer multiple of 10, there will be log_10(precision) digits after the decimal point. precision = 1000, for example, will show 3 decimal places (eg: 0.999). precision = 2 will show multiples of 0.5; precision = 5 will show multiples of 0.2 and so on: precision = n will show multiples of 1/n
number: An integer containing the RGB value of the color used to draw the text.
world_pos: World position of the waypoint.
offset: offset in pixels from position.
alignment: The alignment of the waypoint.

`image_waypoint`¶

Same as image, but does not accept a position; the position is instead determined by world_pos, the world position of the waypoint.

scale: The scale of the image, with 1 being the original texture size. Only the X coordinate scale is used (positive values). Negative values represent that percentage of the screen it should take; e.g. x=-100 means 100% (width).
text: The name of the texture that is displayed.
alignment: The alignment of the image.
world_pos: World position of the waypoint.
offset: offset in pixels from position.

`csm_button`¶

Displays a pressable image on the HUD. Takes the same parameters as image, plus passes the name field to core.register_on_hud_button_press CSM callbacks. The text2 field may be used for a pressed texture.

Only works on touchscreens, this acts exactly like a regular image on other devices.

Particle definition (`add_particle`)¶

    {
        -- Spawn particle at pos with velocity and acceleration
        pos = {x=0, y=0, z=0},
        velocity = {x=0, y=0, z=0},
        acceleration = {x=0, y=0, z=0},

        -- Disappears after expirationtime seconds
        expirationtime = 1,

        size = 1,

        -- If true collides with physical objects
        collisiondetection = false,
        -- If true then particle is removed when it collides (requires collisiondetection = true to have any effect)
        collision_removal = false,
        -- If true faces player using y axis only
        vertical = false,
        -- Texture particle uses
        texture = "image.png",
        -- Specifies how to animate the particle texture (Optional)
        animation = {Tile Animation definition},
        -- Specify particle self-luminescence in darkness (Optional)
        glow = 0
    }

`ParticleSpawner` definition (`add_particlespawner`)¶

    {
        amount = 1,

        -- If time is 0 has infinite lifespan and spawns the amount on a per-second base
        time = 1,

        -- The particle's properties are random values in between the bounds:
        -- minpos/maxpos, minvel/maxvel (velocity), minacc/maxacc (acceleration),
        -- minsize/maxsize, minexptime/maxexptime (expirationtime)
        minpos = {x=0, y=0, z=0},
        maxpos = {x=0, y=0, z=0},
        minvel = {x=0, y=0, z=0},
        maxvel = {x=0, y=0, z=0},
        minacc = {x=0, y=0, z=0},
        maxacc = {x=0, y=0, z=0},
        minexptime = 1,
        maxexptime = 1,
        minsize = 1,
        maxsize = 1,

        -- If true uses collision detection
        collisiondetection = false,
        -- If true then particle is removed when it collides (requires collisiondetection = true to have any effect)
        collision_removal = false,
        -- If true faces player using y axis only
        vertical = false,
        -- Texture particle uses
        texture = "image.png",
    }

HUD¶

HUD element types¶

image¶

text¶

statbar¶

inventory¶

waypoint¶

image_waypoint¶

compass¶

minimap¶

csm_button¶

CSM: HUD element types¶

image¶

text¶

statbar¶

inventory¶

waypoint¶

image_waypoint¶

csm_button¶

Particle definition (add_particle)¶

ParticleSpawner definition (add_particlespawner)¶

`image`¶

`text`¶

`statbar`¶

`inventory`¶

`waypoint`¶

`image_waypoint`¶

`compass`¶

`minimap`¶

`csm_button`¶

`image`¶

`text`¶

`statbar`¶

`inventory`¶

`waypoint`¶

`image_waypoint`¶

`csm_button`¶

Particle definition (`add_particle`)¶

`ParticleSpawner` definition (`add_particlespawner`)¶