# Table `Util`

Utility functions for various calculations.

## Functions

HasLineOfSight(roomID, posA, posB) | Determine if there is a clear line of sight between two positions.
CalculateDistance(posA, posB) | Calculate the distance between two positions.
CalculateHorizontalDistance(posA, posB) | Calculate the horizontal distance between two positions.
GetDisplayPosition(worldPos) | Get the projected display space position of a 3D world position.
PercentToScreen(x, y) | Translate a pair display position coordinates to pixel coordinates.
ScreenToPercent(x, y) | Translate a pair of pixel coordinates to display position coordinates.
PickMoveableByDisplayPosition(Display) | Pick a moveable by the given display position.
PickStaticByDisplayPosition(Display) | Pick a static mesh by the given display position.
PrintLog(message, logLevel[, allowSpam]) | Write messages within the Log file

## Functions

HasLineOfSight(roomID, posA, posB)
  Determine if there is a clear line of sight between two positions. NOTE: Limited to room geometry. Objects are ignored.()

  ### Parameters:

  - roomID float Room ID of the first position's room.
  - posA Vec3 First position.
  - posB Vec3 Second position.

  ### Returns:

  bool true if there is a line of sight, false if not.

  ### Usage:

      local flamePlinthPos = flamePlinth:GetPosition() + Vec3(0, flamePlinthHeight, 0);
      print(Misc.HasLineOfSight(enemyHead:GetRoomNumber(), enemyHead:GetPosition(), flamePlinthPos))

CalculateDistance(posA, posB)
  Calculate the distance between two positions.

  ### Parameters:

  - posA Vec3 First position.
  - posB Vec3 Second position.

  ### Returns:

  float Distance between two positions.
CalculateHorizontalDistance(posA, posB)
  Calculate the horizontal distance between two positions.

  ### Parameters:

  - posA Vec3 First position.
  - posB Vec3 Second position.

  ### Returns:

  float Horizontal distance between the two positions.
GetDisplayPosition(worldPos)
  Get the projected display space position of a 3D world position. Returns nil if the world position is behind the camera view.

  ### Parameters:

  - worldPos Vec3 3D world position.

  ### Returns:

  Vec2 Projected display space position in percent.

  ### Usage:

      Example: Display a string at the player's position.
      local string = DisplayString('Example', 0, 0, Color(255, 255, 255), false)
      local displayPos = GetDisplayPosition(Lara:GetPosition())
      string:SetPosition(PercentToScreen(displayPos.x, displayPos.y))

PercentToScreen(x, y)
  Translate a pair display position coordinates to pixel coordinates. To be used with Strings.DisplayString:SetPosition and Strings.DisplayString.

  ### Parameters:

  - x float X component of the display position.
  - y float Y component of the display position.

  ### Returns:

  1. int x X coordinate in pixels.
  2. int y Y coordinate in pixels.

  ### Usage:

      local halfwayX, halfwayY = PercentToScreen(50, 50)
      local baddy
      local spawnLocationNullmesh = GetMoveableByName("position_behind_left_pillar")
      local str1 = DisplayString("You spawned an enemy!", halfwayX, halfwayY, Color(255, 100, 100), false, { DisplayStringOption.SHADOW, DisplayStringOption.CENTER })

      LevelFuncs.triggerOne = function(obj)
      	ShowString(str1, 4)
      end

ScreenToPercent(x, y)
  Translate a pair of pixel coordinates to display position coordinates. To be used with Strings.DisplayString:GetPosition.

  ### Parameters:

  - x int X pixel coordinate to translate to display position.
  - y int Y pixel coordinate to translate to display position.

  ### Returns:

  1. float x X component of display position.
  2. float y Y component of display position.
PickMoveableByDisplayPosition(Display)
  Pick a moveable by the given display position.

  ### Parameters:

  - Display Vec2 space position in percent.

  ### Returns:

  Moveable Picked moveable (nil if no moveable was found under the cursor).
PickStaticByDisplayPosition(Display)
  Pick a static mesh by the given display position.

  ### Parameters:

  - Display Vec2 space position in percent.

  ### Returns:

  Static Picked static mesh (nil if no static mesh was found under the cursor).
PrintLog(message, logLevel[, allowSpam])
  Write messages within the Log file

  For native Lua handling of errors, see the official Lua website:

  Error management

  debug.traceback

  ### Parameters:

  - message string to be displayed within the Log
  - logLevel LogLevel log level to be displayed
  - allowSpam bool true allows spamming of the message (optional)

  ### Usage:

      PrintLog('test info log', LogLevel.INFO)
      PrintLog('test warning log', LogLevel.WARNING)
      PrintLog('test error log', LogLevel.ERROR)
      -- spammed message
      PrintLog('test spam log', LogLevel.INFO, true)

generated by TEN-LDoc (a fork of LDoc 1.4.6)