====== Unit conversion ======

ACSUtils provides a range of functions to convert various commonly used units. All unit conversion functions operate only on fixed-point numbers, even if ZDoom only uses integers for some of these units. The only exception is byte angle conversion functions, because byte angles are always integers.

Using the same units everywhere in your mod is a good practice that reduces potential for errors. ACSUtils uses the same units in all its functions. When calling ZDoom functions that don't use your preferred units, use these unit conversion functions to convert them in place.

===== Angle units =====

The following angle units are commonly used in ZDoom:

  * ZDoom fixed-point angles [0, 1]
  * ZDoom byte angles [0 to 256, integers only]
  * Degrees [0, 360]
  * Radians [0, 6.28]

ZDoom fixed-point angles are the recommended angle unit in ZDoom, used by almost all ZDoom functions, and used by all ACSUtils functions.

Angle units can be converted using the following functions (ang = ZDoom fixed-point angles, deg = Degrees, rad = Radians):

  * ''fixed deg2ang(fixed degrees)'' -- converts degrees to ZDoom angle
  * ''fixed rad2ang(fixed radians)'' -- converts radians to ZDoom angle
  * ''fixed ang2deg(fixed angle)'' -- converts ZDoom angle to degrees
  * ''fixed ang2rad(fixed angle)'' -- converts ZDoom angle to radians
  * ''fixed deg2rad(fixed degrees)'' -- converts degrees to radians
  * ''fixed rad2deg(fixed radians)'' -- converts radians to degrees
  * ''fixed byte2ang(int byteangle)'' -- converts ZDoom byte angle to fixed-point angle
  * ''int ang2byte(fixed angle)'' -- converts fixed-point angle to ZDoom byte angle

ZDoom byte angles can also be converted to ZDoom fixed-point angles this way:
  * ''x * 256'' -- byte angle to fixed-point angle (128 gets converted to 0.5)
  * ''x / 256'' -- fixed-point angle to byte angle (0.5 gets converted to 128)

Or using bit shifts:
  * ''x<<8'' -- byte angle to fixed-point angle
  * ''x>>8'' -- fixed-point angle to byte angle

===== Gravity units =====

There are two gravity units in ZDoom:

  * acceleration -- mapunits/tic (default gravity is 1.0)
  * ''sv_gravity'' units -- acceleration*800 (default gravity is 800)

ZDoom uses ''sv_gravity'' units exclusively, but acceleration is the recommended unit, as it can be used in physics calculations without conversion.

Gravity units can be converted using the following functions:

  * ''fixed grav2accel(fixed sv_gravity)'' -- converts ''sv_gravity'' units to acceleration
  * ''fixed accel2grav(fixed acceleration)'' -- converts acceleration to ''sv_gravity'' units

ACSUtils also provides utility functions for manipulating gravity:

  * ''fixed GetGravityG()'' -- reads the value of ''sv_gravity'', converts it to acceleration and returns the result. Supports both very small and HUGE values of ''sv_gravity''.
  * ''void SetGravityG(fixed accel)'' -- a wrapper for [[zdoom>SetGravity]] that accepts acceleration instead of ''sv_gravity'' units.

===== Jump height =====

Decorate JumpZ is not the actual jump height of the actor, but a much lower non-linearly related value.

  * ''fixed jumpz2height(fixed jumpz)'' -- converts decorate JumpZ to actual resulting jump height
  * ''fixed height2jumpz(fixed height)'' -- calculates JumpZ from actual jump height