================ Value Extensions ================ Mathematics-oriented extensions that allow for better vector logic, distance and direction calculation out of the box, castless conversion between vectors and much more. All extensions here are chainable. Overview -------- * :ref:`Add and Sub` * :ref:`AsPositive and AsNegative` (*No documentation yet*) * :ref:`AverageBrightness, Luminance, and PerceivedLuminance` * :ref:`ClosestPoint` * :ref:`Dir and Dist` * :ref:`GetBrightness` (*No documentation yet*) * :ref:`InversePoint` * :ref:`Logic` * :ref:`ToGrayscale` (*No documentation yet*) * :ref:`ToRGB(A)(32)` (*No documentation yet*) * :ref:`ToVec` * :ref:`WithR/G/B/A` * :ref:`WithX/Y/Z/W` * :ref:`Get Help <**GET HELP**>` **EXTENSIONS** -------------- Add and Sub ----------- * ``Add(int/float/double/decimal v)`` * ``Sub(int/float/double/decimal v)`` **Add** adds the value **v** to all parameters of the vector. **Sub** subtracts the value **v** from all parameters of the vector. Add and Sub are available to all vectors, including VectorInts. .. code-block:: csharp :linenos: using NutTools; using UnityEngine; public class MyClass : MonoBehaviour { void MyMethod() { Vector2 vec2 = new Vector2(1f, 1f); vec2.Add(2f); vec2.Sub(2f); } } AverageBrightness, Luminance, and PerceivedLuminance ---------------------------------------------------- * ``AverageBrightness(this Color/Color32 color, BrightnessMode brightnessMode = BrightnessMode.AverageBrightness)`` * ``Luminance(this Color/Color32 color, BrightnessMode brightnessMode = BrightnessMode.AverageBrightness)`` * ``PerceivedLuminance(this Color/Color32 color, BrightnessMode brightnessMode = BrightnessMode.AverageBrightness)`` These methods use maths to return different types of brightness levels of a color. They will always return a value within the 0-1 range. **AverageBrightness** takes an average between the RGB values of a color. Alpha is discarded. It is the same as ``(r + g + b) / 3f``. **Luminance** returns the standard calculation used to define brightness in most cases. It also discards alpha. ``0.2126f * r + 0.7152f * g + 0.0722f * b``. **PerceivedLuminance** returns a value closer to what we perceive as luminance on colors naturally. ``0.299 * r + 0.587 * g + 0.114 * b``. .. code-block:: csharp :linenos: using NutCore; using UnityEngine; public class MyClass : MonoBehaviour { public void MyMethod() { Color color = new Color(0.786f, 0.39f, 0.189f); Debug.Log($"Average Brightness: {color.AverageBrightness()}"); Debug.Log($"Luminance: {color.Luminance()}"); Debug.Log($"Perceived Luminance: {color.PerceivedLuminance()}"); /* * Results: * * Average Brightness: 0,455 * Luminance: 0,4596774 * Perceived Luminance: 0,48549 */ } } IMAGE GOES HERE ClosestPoint ------------ * ``ClosestPoint(params Vector4[] points)`` * ``ClosestPoint(params Vector3[] points)`` * ``ClosestPoint(params Vector3Int[] points)`` * ``ClosestPoint(params Vector2[] points)`` * ``ClosestPoint(params Vector2Int[] points)`` * ``ClosestPoint(params int[] points)`` * ``ClosestPoint(params float[] points)`` * ``ClosestPoint(params double[] points)`` * ``ClosestPoint(params decimal[] points)`` Returns the closest point in an array of floats, ints, and vectors. .. code-block:: csharp :linenos: using NutTools; using UnityEngine; public class MyClass : MonoBehaviour { public Transform[] objs; void MyMethod() { 3f.ClosestPoint(-3f, 5f); // Returns 5. transform.ClosestPoint(objs); // Returns the closest transform. } } Dir and Dist ------------ * ``Dir, Dir2, and Dir4(other)`` * ``Dist, Dist2, and Dist4(other, bool sqr = true)`` **Dir** methods return the direction from point a to b (non normalized). **Dist** methods return the square distance between two points. You can call them from components, vectors, and GameObjects. .. code-block:: csharp :linenos: using NutTools; using UnityEngine; public class MyClass : MonoBehaviour { public GameObject other; void MyMethod() { float sqr_dist = this.Dist(other); float dist = this.Dist(other, false); // False forces the method to return the true distance. Vector3 dir = this.Dir(other); } } InversePoint ------------ * ``InversePointUp()`` * ``InversePointDown()`` * ``InversePointLeft()`` * ``InversePointForward()`` * ``InversePointBackward()`` ``transform.InverseTransformPoint()`` with all of its own transform directions. .. code-block:: csharp :linenos: using NutTools; using UnityEngine; public class MyClass : MonoBehaviour { public Transform[] transforms = new Transform[0]; void MyMethod() { Vector3 inverse_up = transform.InversePointUp(); } } Logic ----- * ``bool IsAnyPointGreaterThan(this Vector a, Vector b)`` * ``bool IsAnyPointLessThan(this Vector a, Vector b)`` * ``bool AreAllPointsGreaterThan(this Vector a, Vector b)`` * ``bool AreAllPointsLessThan(this Vector a, Vector b)`` **IsAnyPointGreaterThan**, previously **GreaterAny**, returns true if any axis from **a** is greater than any axis from **b**. **IsAnyPointLessThan**, previously **LessAny**, returns true if any axis from **a** is lesser than any axis from **b**. **AreAllPointsGreaterThan**, previously **GreaterAll**, returns true if all axis from **a** are greater than all axis from **b**. **AreAllPointsLessThan**, previously **LessAll**, returns if all axis from **a** are lesser than all axis from **b**. .. code-block:: csharp :linenos: using NutTools; using UnityEngine; public class MyClass : MonoBehaviour { void MyMethod() { Vector3 a = new Vector3(5f, 6f, 1f); Vector3 b = new Vector3(6f, 2f, 3f); a.IsAnyPointGreaterThan(b); // Returns true. b.AreAllPointsLessThan(a); // Returns false. } } ToVec ----- Converts values to vectors, and vectors into other vectors. **TO VECTOR 4** * ``ToVec4(this Color vec)`` * ``ToVec4(this Color32 vec)`` * ``ToVec4(this Vector3 vec, float w)`` * ``ToVec4(this Vector3Int vec, float w)`` * ``ToVec4(this Vector2 vec, float z, float w)`` * ``ToVec4(this Vector2Int vec, float z, float w)`` * ``ToVec4(this decimal v)`` * ``ToVec4(this double v)`` * ``ToVec4(this float v)`` * ``ToVec4(this byte v)`` * ``ToVec4(this int v)`` **TO VECTOR 3** * ``ToVec3(this Color vec)`` * ``ToVec3(this Color32 vec)`` * ``ToVec3(this Vector4 vec)`` * ``ToVec3(this Vector3Int vec)`` * ``ToVec3(this Vector2 vec, float z)`` * ``ToVec3(this Vector2Int vec, float z)`` * ``ToVec3(this decimal v)`` * ``ToVec3(this double v)`` * ``ToVec3(this float v)`` * ``ToVec3(this byte v)`` * ``ToVec3(this int v)`` **TO VECTOR 3 INT** * ``ToVec3Int(this Vector4 vec)`` * ``ToVec3Int(this Vector3 vec)`` * ``ToVec3Int(this Vector2 vec, int z)`` * ``ToVec3Int(this Vector2Int vec, int z)`` * ``ToVec3Int(this decimal v)`` * ``ToVec3Int(this double v)`` * ``ToVec3Int(this float v)`` * ``ToVec3Int(this byte v)`` * ``ToVec3Int(this int v)`` **TO VECTOR 2** * ``ToVec2(this Vector4 vec)`` * ``ToVec2(this Vector3 vec)`` * ``ToVec2(this Vector3Int vec)`` * ``ToVec2(this Vector2Int vec)`` * ``ToVec2(this decimal v)`` * ``ToVec2(this double v)`` * ``ToVec2(this float v)`` * ``ToVec2(this byte v)`` * ``ToVec2(this int v)`` **TO VECTOR 2 INT** * ``ToVec2Int(this Vector4 vec)`` * ``ToVec2Int(this Vector3 vec)`` * ``ToVec2Int(this Vector3Int vec)`` * ``ToVec2Int(this Vector2 vec)`` * ``ToVec2Int(this decimal v)`` * ``ToVec2Int(this double v)`` * ``ToVec2Int(this float v)`` * ``ToVec2Int(this byte v)`` * ``ToVec2Int(this int v)`` .. code-block:: csharp :linenos: using NutTools; using UnityEngine; public class MyClass : MonoBehaviour { void MyMethod() { 5f.ToVec3(); 2.ToVec2Int(); transform.position.ToVec4(2f, 4f); 3m.ToVec2(); 10d.ToVec4(); } } WithR/G/B/A ----------- They return a new color which copies all values from the extended one, and sets the relevant field to the given value. Support for Color and Color32 is available. .. code-block:: csharp :linenos: using NutTools; using UnityEngine; public class MyClass : MonoBehaviour { void MyMethod() { Color color = Color.white; Debug.Log(color.WithR(.5f).WithA(.2f)); // Prints ".5, 1f, 1f, .2f". Debug.Log(color); // Prints "1f, 1f, 1f, 1f". color = color.WithG(5f).WithB(2f); Debug.Log(color); // Prints "5f, 1f, 2f, 1f". } } WithX/Y/Z/W ----------- They return a new vector with the respective field set to the provided value. They support all vector types: Vector2, Vector2Int, Vector3, Vector3Int, and Vector4. They don't set the vector extended, but rather return a new vector with that value applied. .. code-block:: csharp :linenos: using NutTools; using UnityEngine; public class MyClass : MonoBehaviour { void MyMethod() { Vector3 vector = Vector3.zero; Debug.Log(vector.WithX(5f).WithZ(2f)); // Prints "5, 0, 2". Debug.Log(vector); // Prints "0, 0, 0". vector = vector.WithX(5f).WithZ(2f); Debug.Log(vector); // Prints "5, 0, 2". } } **** **GET HELP** ------------ `Join this Discord server `_ to get help from the community, suggest new features, and vote on future updates! .. seealso:: * :ref:`Array and List Extensions ` * :ref:`GameObject and Component Extensions ` * :ref:`ParticleSystem Extensions ` * :ref:`Physics Extensions ` * :ref:`Texture Extensions `