# Module `util`

Generic utility functions.

## Functions

subtitles.util.get_node_sound (name, keys) | Returns the sound spec for a particular action on a node.
subtitles.util.get_dig_sound_for_groups (groups) | Decides which sounds to use for a node with the specified groups.
subtitles.util.describe_damage (reason) | Describes how a player was damaged.
subtitles.util.update (tbl, ...) | Updates a table, overriding existing keys.
subtitles.util.object_is_walking (objref) | Checks if a player or entity is moving at walking speed.
subtitles.util.get_feet_pos (objref) | Returns the position of an object's feet based on its collision box.
subtitles.util.update_hud (player, hud_id, old_def, new_def) | Updates a HUD, only settings attributes that have changed.
subtitles.util.clamp (value, min, max) | Clamps a number to within a specified range.
subtitles.util.get_meta_bool (meta, key, default) | Reads a boolean value from metadata.
subtitles.util.set_meta_bool (meta, key, value) | Writes a boolean value to metadata.
subtitles.util.rgb_to_number (red, green, blue) | Converts a colour from RGB to a number for HUDs.

## Tables

subtitles.util.HUDDirection | An enumerator of HUD directions.
subtitles.util.TextStyle | A bitfield of HUD text styles.

## Functions

subtitles.util.get_node_sound (name, keys)
  Returns the sound spec for a particular action on a node.

  ### Parameters:

  - name The name of the node.
  - keys A key in the sounds table, such as 'dig' or 'footstep', or a list of such keys.

  ### Returns:

  A SimpleSoundSpec or `nil`.
subtitles.util.get_dig_sound_for_groups (groups)
  Decides which sounds to use for a node with the specified groups.

  ### Parameters:

  - groups A group table.

  ### Returns:

  A SimpleSoundSpec or `nil`.
subtitles.util.describe_damage (reason)
  Describes how a player was damaged.

  ### Parameters:

  - reason A damage reason table, as passed to on_player_hp_change callbacks.

  ### Returns:

  A human-readabable description
subtitles.util.update (tbl, ...)
  Updates a table, overriding existing keys.

  ### Parameters:

  - tbl The table to update.
  - ... Any number of additional tables to update from.

  ### Returns:

  A reference to the original table.
subtitles.util.object_is_walking (objref)
  Checks if a player or entity is moving at walking speed. This function does not check if the object is on ground.

  ### Parameters:

  - objref An ObjectRef.

  ### Returns:

  true if the object is moving at walking speed.
subtitles.util.get_feet_pos (objref)
  Returns the position of an object's feet based on its collision box.

  ### Parameters:

  - objref A player or entity.

  ### Returns:

  An absolute position vector.
subtitles.util.update_hud (player, hud_id, old_def, new_def)
  Updates a HUD, only settings attributes that have changed.

  ### Parameters:

  - player A player ObjectRef.
  - hud_id The id of the HUD to update.
  - old_def The old HUD definition table.
  - new_def The new HUD definition table.
subtitles.util.clamp (value, min, max)
  Clamps a number to within a specified range.

  ### Parameters:

  - value The value to clamp.
  - min The lower bound.
  - max The upper bound.

  ### Returns:

  min, max, or value.
subtitles.util.get_meta_bool (meta, key, default)
  Reads a boolean value from metadata.

  ### Parameters:

  - meta The MetaDataRef to read from.
  - key The name of the metadata entry to read.
  - default The default value. Not necessarily a boolean.

  ### Returns:

  A boolean value or the default.
subtitles.util.set_meta_bool (meta, key, value)
  Writes a boolean value to metadata.

  ### Parameters:

  - meta The MetaDataRef to write to.
  - key The name of the metadata entry to write.
  - value The boolean value to write.
subtitles.util.rgb_to_number (red, green, blue)
  Converts a colour from RGB to a number for HUDs.

  ### Parameters:

  - red The red component, from 0 to 255.
  - green The green component, from 0 to 255.
  - blue The blue component, from 0 to 255.

  ### Returns:

  An integer in the form 0xRRGGBB.

## Tables

subtitles.util.HUDDirection
  An enumerator of HUD directions.

  ### Fields:

  - LEFT_TO_RIGHT
  - RIGHT_TO_LEFT
  - TOP_TO_BOTTOM
  - BOTTOM_TO_TOP
subtitles.util.TextStyle
  A bitfield of HUD text styles.

  ### Fields:

  - REGULAR
  - BOLD
  - ITALIC
  - MONOSPACE

generated by LDoc 1.4.6 Last updated 2023-01-14 06:51:17