Druid-Extension/api/druid_helper_api.md

druid.helper API

at /druid/helper.lua

The helper module contains various functions that are used in the Druid library. You can use these functions in your projects as well.

Functions

• centrate_text_with_icon
• centrate_icon_with_text
• centrate_nodes
• get_node
• get_screen_aspect_koef
• get_gui_scale
• step
• clamp
• distance
• sign
• round
• lerp
• contains
• deepcopy
• add_array
• pick_node
• get_scaled_size
• get_scene_scale
• get_closest_stencil_node
• get_pivot_offset
• is_desktop
• is_mobile
• is_web
• is_web_mobile
• is_multitouch_supported
• table_to_string
• get_border
• get_text_metrics_from_node
• insert_with_shift
• remove_with_shift
• get_full_position
• get_animation_data_from_node

centrate_text_with_icon

---

helper.centrate_text_with_icon([text_node], [icon_node], margin)

Center two nodes. Nodes will be center around 0 x position text_node will be first (at left side)

• Parameters:

  • [text_node] (node|nil): Gui text node
  • [icon_node] (node|nil): Gui box node
  • margin (number): Offset between nodes

• Returns:

  • `` (unknown):

centrate_icon_with_text

---

helper.centrate_icon_with_text([icon_node], [text_node], [margin])

Center two nodes. Nodes will be center around 0 x position icon_node will be first (at left side)

• Parameters:

  • [icon_node] (node|nil): Gui box node
  • [text_node] (node|nil): Gui text node
  • [margin] (number|nil): Offset between nodes

• Returns:

  • `` (unknown):

centrate_nodes

---

helper.centrate_nodes([margin], ...)

Centerate nodes by x position with margin. This functions calculate total width of nodes and set position for each node. The centrate will be around 0 x position.

• Parameters:

  • [margin] (number|nil): Offset between nodes
  • ... (...): vararg

• Returns:

  • `` (unknown):

get_node

---

helper.get_node(node_id, [template], [nodes])

• Parameters:

  • node_id (string|node):
  • [template] (string|nil): Full Path to the template
  • [nodes] (table<hash, node>|nil): Nodes what created with gui.clone_tree

• Returns:

  • `` (node):

get_screen_aspect_koef

---

helper.get_screen_aspect_koef()

Get current screen stretch multiplier for each side

• Returns:
  • stretch_x (number):
  • stretch_y (number):

get_gui_scale

---

helper.get_gui_scale()

Get current GUI scale for each side

• Returns:
  • scale_x (number):

step

---

helper.step(current, target, step)

Move value from current to target value with step amount

• Parameters:

  • current (number): Current value
  • target (number): Target value
  • step (number): Step amount

• Returns:

  • New (number): value

clamp

---

helper.clamp(value, [v1], [v2])

Clamp value between min and max. Works with nil values and swap min and max if needed.

• Parameters:

  • value (number): Value
  • [v1] (number|nil): Min value. If nil, value will be clamped to positive infinity
  • [v2] (number|nil): Max value If nil, value will be clamped to negative infinity

• Returns:

  • value (number): Clamped value

distance

---

helper.distance(x1, y1, x2, y2)

Calculate distance between two points

• Parameters:

  • x1 (number): First point x
  • y1 (number): First point y
  • x2 (number): Second point x
  • y2 (number): Second point y

• Returns:

  • distance (number):

sign

---

helper.sign(val)

Return sign of value

• Parameters:

  • val (number): Value

• Returns:

  • sign (number): Sign of value, -1, 0 or 1

round

---

helper.round(num, [num_decimal_places])

Round number to specified decimal places

• Parameters:

  • num (number): Number
  • [num_decimal_places] (number|nil): Decimal places

• Returns:

  • value (number): Rounded number

lerp

---

helper.lerp(a, b, t)

Lerp between two values

• Parameters:

  • a (number): First value
  • b (number): Second value
  • t (number): Lerp amount

• Returns:

  • value (number): Lerped value

contains

---

helper.contains([array], [value])

Check if value contains in array

• Parameters:

  • [array] (any[]): Array to check
  • [value] (any): Value

• Returns:

  • index (number|nil): Index of value in array or nil if value not found

deepcopy

---

helper.deepcopy(orig_table)

Make a copy table with all nested tables

• Parameters:

  • orig_table (table): Original table

• Returns:

  • Copy (table): of original table

add_array

---

helper.add_array([target], [source])

Add all elements from source array to the target array

• Parameters:

  • [target] (any[]): Array to put elements from source
  • [source] (any[]|nil): The source array to get elements from

• Returns:

  • The (any[]): target array

pick_node

---

helper.pick_node(node, x, y, [node_click_area])

Make a check with gui.pick_node, but with additional node_click_area check.

• Parameters:

  • node (node):
  • x (number):
  • y (number):
  • [node_click_area] (node|nil): Additional node to check for click area. If nil, only node will be checked

• Returns:

  • `` (unknown):

get_scaled_size

---

helper.get_scaled_size(node)

Get size of node with scale multiplier

• Parameters:

  • node (node): GUI node

• Returns:

  • scaled_size (vector3):

get_scene_scale

---

helper.get_scene_scale(node, [include_passed_node_scale])

Get cumulative parent's node scale

• Parameters:

  • node (node): Gui node
  • [include_passed_node_scale] (boolean|nil): True if add current node scale to result

• Returns:

  • The (vector3): scene node scale

get_closest_stencil_node

---

helper.get_closest_stencil_node(node)

Return closest non inverted clipping parent node for given node

• Parameters:

  • node (node): GUI node

• Returns:

  • stencil_node (node|nil): The closest stencil node or nil

get_pivot_offset

---

helper.get_pivot_offset(pivot_or_node)

Get pivot offset for given pivot or node Offset shown in [-0.5 .. 0.5] range, where -0.5 is left or bottom, 0.5 is right or top.

• Parameters:

  • pivot_or_node (number|node): GUI pivot or node

• Returns:

  • offset (vector3): The pivot offset

is_desktop

---

helper.is_desktop()

Check if device is desktop

• Returns:
  • `` (boolean):

is_mobile

---

helper.is_mobile()

Check if device is native mobile (Android or iOS)

• Returns:
  • Is (boolean): mobile

is_web

---

helper.is_web()

Check if device is HTML5

• Returns:
  • `` (boolean):

is_web_mobile

---

helper.is_web_mobile()

Check if device is HTML5 mobile

• Returns:
  • `` (boolean):

is_multitouch_supported

---

helper.is_multitouch_supported()

Check if device is mobile and can support multitouch

• Returns:
  • is_multitouch (boolean): Is multitouch supported

table_to_string

---

helper.table_to_string(t)

Simple table to one-line string converter

• Parameters:

  • t (table):

• Returns:

  • `` (string):

get_border

---

helper.get_border(node, [offset])

Distance from node position to his borders

• Parameters:

  • node (node): GUI node
  • [offset] (vector3|nil): Offset from node position. Pass current node position to get non relative border values

• Returns:

  • border (vector4): Vector4 with border values (left, top, right, down)

get_text_metrics_from_node

---

helper.get_text_metrics_from_node(text_node)

Get text metric from GUI node.

• Parameters:

  • text_node (node):

• Returns:

  • `` (GUITextMetrics):

insert_with_shift

---

helper.insert_with_shift(array, [item], [index], [shift_policy])

Add value to array with shift policy Shift policy can be: left, right, no_shift

• Parameters:

  • array (table): Array
  • [item] (any): Item to insert
  • [index] (number|nil): Index to insert. If nil, item will be inserted at the end of array
  • [shift_policy] (number|nil): The druid_const.SHIFT.* constant

• Returns:

  • Inserted (any): item

remove_with_shift

---

helper.remove_with_shift([array], [index], [shift_policy])

Remove value from array with shift policy Shift policy can be: left, right, no_shift

• Parameters:

  • [array] (any[]): Array
  • [index] (number|nil): Index to remove. If nil, item will be removed from the end of array
  • [shift_policy] (number|nil): The druid_const.SHIFT.* constant

• Returns:

  • Removed (any): item

get_full_position

---

helper.get_full_position(node, [root])

Get full position of node in the GUI tree

• Parameters:

  • node (node): GUI node
  • [root] (node|nil): GUI root node to stop search

• Returns:

  • `` (unknown):

get_animation_data_from_node

---

helper.get_animation_data_from_node(node, atlas_path)

• Parameters:

  • node (node):
  • atlas_path (string): Path to the atlas

• Returns:

  • `` (druid.system.animation_data):