Difference between revisions of "Scripting/SMath"

Revision as of 03:01, 22 April 2017

The SMath class contains common math functions, see also SVector and SQuaternion for Vector and Quaternion related math functions.

Fields

Pi

float Pi ;

Returns the constant value of Π (readonly).

Space.Log(Space.Math.Pi);
-- prints 3.14159274101257

Members

Random

float Random ();

Returns a random float between 0 and 1 (inclusive)

local randomNumber = Space.Math.Random();
Space.Log(randomNumber);
-- prints 0.689094245433807

RandomRange

float RandomRange (float min, float max);

Returns a random float between min and max (inclusive)

local min = 100.0;
local max = 500.0;
local randomNumber = Space.Math.RandomRange(min, max );

Space.Log(randomNumber);
-- prints 0206.659149169922

RandomInteger

int RandomInteger (int min, int max);

Returns a random float between min (inclusive) and max (exclusive)

local min = 50;
local max = 75;
local randomInteger = Space.Math.RandomInteger(min, max);
Space.Log(randomInteger);
-- prints  52

Abs

float Abs (float val);

Returns the absolute value of 'val'

local value = -4.2
local absoluteNum = Space.Math.Abs(value);
Space.Log(absoluteNum);
-- prints  4 [BUG] should be 4.2

Abs

int Abs (int val);

Returns the absolute value of 'val'

local value = -4
local absoluteNum = Space.Math.Abs(value);
Space.Log(absoluteNum);
-- prints  4

Acos

float Acos (float val);

Returns the arc cosine value of 'val'

local value = 0.5;
local arcCosine = Space.Math.Acos(value);
Space.Log(arcCosine);
-- prints 1.04719758033752 (radians) which is 60 degrees

Approximately

bool Approximately (float a, float b);

True if the difference between a and b is less than epsilon

local a = 5.0;
local b = 5;
local approx1 = Space.Math.Approximately(a, b);
Space.Log(approx1);
-- prints true

local a = 5.01;
local b = 5.0;
local approx2 = Space.Math.Approximately(a, b);
Space.Log(approx2);
-- prints false

local a = 5.01;
local b = 5.0;
local approx3 = Space.Math.Approximately(a, b);
Space.Log(approx3);
-- prints false

Asin

bool Asin (float val);

Returns the arc sine value of 'val'

local value = 0.5;
local arcSine = Space.Math.Asin(value);
Space.Log(arcSine);
-- prints 0.523598790168762 (radians) which is 30 degrees

Atan

bool Atan (float val);

Returns the arc tangent value of 'val'

local value = 1.732050808;
local arcTangent = Space.Math.Atan(value);
Space.Log(arcTangent);
-- prints 1.04719758033752 (radians) which is  60 degrees

Atan2

bool Atan2 (float y, float x);

Returns the arc tangent of y/x

local x = 0.5;
local y = 0.5;
local arcTangent = Space.Math.Atan2(y, x);
Space.Log(arcTangent);
-- prints 0.785398185253143

Ceil

int Ceil (float val);

Returns the ceil value of 'val' as an integer

Space.Log(Space.Math.Ceil(4.0));

-- prints 4

Space.Log(Space.Math.Ceil(4.2));
-- prints 5

Space.Log(Space.Math.Ceil(-4.2));
-- prints -4

Clamp

float Clamp (float val, float min, float max);

Clamps val between min and max, and returns the result

local value = 100.0;
local min = 20.0;
local max = 82.0;

local clampedValue = Space.Math.Clamp(value, min, max);
Space.Log(clampedValue);

-- prints 82

Clamp01

float Clamp01 (float val);

Clamps val between 0 and 1, and returns the result

local value = -1.0;

local clampedValue = Space.Math.Clamp01(value);
Space.Log(clampedValue);
-- prints 0

ClosestPowerOfTwo

int ClosestPowerOfTwo (int val);

Returns the closest power of two to val

local value = 33;

local powerOfTwo = Space.Math.ClosestPowerOfTwo(value);
Space.Log(powerOfTwo);
-- prints 32

Cos

float Cos (float val);

Returns the cosine of val

local angle = 1.04719758033752; -- converts to 60 degrees
local cosine = Space.Math.Cos(angle);
Space.Log(cosine);
-- prints 0.499999970197678

local angle2 = Space.Math.Pi/3; -- converts to 60 degrees
local cosine2 = Space.Math.Cos(angle2);
Space.Log(cosine2);
-- prints 0.499999970197678

DeltaAngle

float DeltaAngle (float current, float target);

Returns the difference in degrees between two values (e.g. 350' and 17' returns 27')

Space.Log(Space.Math.DeltaAngle(350.0, 17.0));
-- prints 27

Exp

float Exp (float val);

Returns e raised to val power.

Space.Log(Space.Math.Exp(3.0));
-- prints 20.0855369567871

Floor

int Floor (float val);

Returns floor of val, converted to an int

Space.Log(Space.Math.Floor(4.0));
-- prints 4

Space.Log(Space.Math.Floor(4.2));
-- prints 4

Space.Log(Space.Math.Floor(-4.2));
-- prints -5

GammaToLinearSpace

float GammaToLinearSpace (float val);

Converts a colour value from Gamma to Linear Space (Pow 2.2)

Space.Log(Space.Math.GammaToLinearSpace(0.5));
-- prints 0.214041143655777

InverseLerp

float InverseLerp (float a, float b, float val);

Returns the percentage between a and b that 'val' is on a line (opposite of Lerp)

local sliderStart = 0.0;
local sliderStop = 100.0;
local currentSliderPos = 75.0;

local percentage = Space.Math.InverseLerp(sliderStart, sliderStop, currentSliderPos);
Space.Log(percentage);

-- prints 0.75

IsPowerOfTwo

bool IsPowerOfTwo (int val);

Returns true if val is a power of two

Space.Log(Space.Math.IsPowerOfTwo(55));
-- prints False

Space.Log(Space.Math.IsPowerOfTwo(32));

-- prints True

Lerp

float Lerp (float a, float b, float val);

Interpolates between 'a' and 'b' based on 'val', assuming 'val' is between 0 and 1

local sliderStart = 0.0;
local sliderStop = 100.0;
local percentage = 0.75;

local currentSliderPos = Space.Math.Lerp(sliderStart, sliderStop, percentage);
Space.Log(currentSliderPos);
 -- prints 75

LerpAngle

float LerpAngle (float a, float b, float val);

Interpolates between angles 'a' and 'b' based on 'val', assuming 'val' is between 0 and 1

local sliderStartAngle = 0.0;
local sliderStopAngle = Space.Math.Pi;-- 180 degrees
local percentage = 0.50;

local currentSliderPos = Space.Math.LerpAngle(sliderStartAngle, sliderStopAngle, percentage);
Space.Log(currentSliderPos);

-- prints 1.57079637050629 (90 degrees)

LerpUnclamped

float LerpUnclamped (float a, float b, float val);

Interpolates between 'a' and 'b' based on 'val', assuming 'val' is between 0 and 1, but unbounded (allowing higher/lower values)

local sliderStart = 0.0;
local sliderStop = 100.0;
local percentage = 2.0;

local currentSliderPos = Space.Math.LerpUnclamped(sliderStart, sliderStop, percentage);
Space.Log(currentSliderPos);
 -- prints 200

LinearToGammaSpace

float LinearToGammaSpace (float val);

Converts a colour value from Linear to Gamma Space (Pow 1/2.2)

Space.Log(Space.Math.LinearToGammaSpace(0.214041143655777));
-- prints 0.5

Log

float Log (float val);

Returns the natural logarithm for 'val'

Space.Log(Space.Math.Log(30.0));
-- prints 3.40119743347168

Log

float Log (float val, float p);

Returns the logarithm of 'p' for 'val'

Space.Log(Space.Math.Log(4.0, 2.0));
-- prints 2

Log10

float Log10 (float val);

Returns the Log10 value for 'val'

Space.Log(Space.Math.Log10(100.0));
-- prints 2

Max

float Max (float a, float b);

Returns higher of 'a' or 'b'

Space.Log(Space.Math.Max(20.0, 100.0));

-- prints 100

Min

float Min (float a, float b);

Returns lower of 'a' or 'b'

Space.Log(Space.Math.Min(20.0, 100.0));

-- prints 20

MoveTowards

float MoveTowards (float value, float target, float delta);

Move value to target, but by no more than delta

local sliderStart = 5.0;
local sliderStop = 10.0;

local deltaChange = 1.0;

local currentSliderPos = Space.Math.MoveTowards(sliderStart, sliderStop, deltaChange);

Space.Log(currentSliderPos);

-- prints 6 (moves forward 1)

local sliderStart = 5.0;

local sliderStop = 10.0;

local deltaChange = 7.0;

local currentSliderPos = Space.Math.MoveTowards(sliderStart, sliderStop, deltaChange);

Space.Log(currentSliderPos);
-- prints 10 (caps out at at the target value)

-- NOTE: Use negative delta to move away from target.

MoveTowardsAngle

float MoveTowardsAngle (float value, float target, float delta);

Move angle value to target, but by no more than delta

local sliderStartAngle = Space.Math.Pi/2; -- 90 degrees
local sliderStopAngle = Space.Math.Pi; -- 180 degrees

local deltaChange = Space.Math.Pi/6; -- 30 degrees

local currentSliderPos = Space.Math.MoveTowardsAngle(sliderStartAngle, sliderStopAngle, deltaChange);

Space.Log(currentSliderPos);

-- prints 2.09439516067505 (moves forward 30 degrees to 120 degrees)

-- NOTE: Add 180 degrees (Space.Math.Pi) to move away from target.

NextPowerOfTwo

int NextPowerOfTwo (int val);

Return the next power of two larger or equal to val

Space.Log(Space.Math.NextPowerOfTwo(16));
-- prints 16

Space.Log(Space.Math.NextPowerOfTwo(17));
-- prints 32

PerlinNoise

float PerlinNoise (float x, float y);

Return 2D Perlin noise for coordinates x and y

-- Lua Translation of Unity C# Documentation

local ball = Space.Host.ExecutingObject;

ball.SubscribeToEvents();

-- animates this object to move upwards on the y axis with slight random movement

local animateBall = function()

  local heightScale = 0.1; -- controls speed of movement

  local xScale = 1.0; -- shifts x position on perlin noise plane

  local height = heightScale * Space.Math.PerlinNoise(Space.Time * xScale, 0.0);

  local pos = ball.LocalPosition;

  pos.y = pos.y + height;

  ball.LocalPosition = pos;

  Space.Log(pos.y);

end

ball.OnUpdate(animateBall);

-- NOTE: If you need a guaranteed range of [0,1], make sure to clamp the value with Space.Math.Clamp01.

PingPong

float PingPong (float val, float length);

Return a value between 0 and length that oscillates upwards and back based on the position of 'val'

--[[ In this example, if you traced the output of Space.Math.PingPong(value, length),the return values would cycle forward through the range [0,5] then cycle backwards through the range [5,0] in order. --]]

local ball = Space.Host.ExecutingObject;

local originalPos = ball.LocalPosition;

ball.SubscribeToEvents();

-- The ball object oscillates back and forth on the x-axis.

local animateBall = function()

  local value = Space.Time;

  local length = 5.0;

  local newPos = Vector.New(Space.Math.PingPong(value, length) + originalPos.x, originalPos.y, originalPos.z);

  ball.LocalPosition = newPos;

end

ball.OnUpdate(animateBall);

Pow

float Pow (float x, float y);

Return x raised to y power

Space.Log(Space.Math.Pow(2, 4));
-- prints 16

Repeat

float Repeat (float val, float length);

Return a value between 0 and length that returns to 0 after exceeding length based on 'val'

--[[ In this example, if you traced the output of Space.Math.Repeat(value, length),the return values would cycle forward through the range [0,5]. The cycle is repeated again from 0.--]]

local ball = Space.Host.ExecutingObject;

local originalPos = ball.LocalPosition;

ball.SubscribeToEvents();

-- The ball object moves forward on the x-axis.

-- Then, it repeats the same motion again from the beginning.

local animateBall = function()

  local value = Space.Time;

  local length = 5.0;

  local newPos = Vector.New(Space.Math.Repeat(value, length) + originalPos.x, originalPos.y, originalPos.z);

  ball.LocalPosition = newPos;

end

ball.OnUpdate(animateBall);

Round

int Round (float val);

Returns the nearest integer value to val

Space.Log(Space.Math.Round(4.0));
-- print 4

Space.Log(Space.Math.Round(4.2));

-- print 4

Space.Log(Space.Math.Round(4.5));

-- print 4

Space.Log(Space.Math.Round(4.55));

-- print 5

Space.Log(Space.Math.Round(4.8));

-- print 5

Space.Log(Space.Math.Round(-4.2));

-- print -4

Space.Log(Space.Math.Round(-4.8));

-- print -5

Sign

float Sign (float val);

Returns either 1 or -1 based on the sign of 'val'

Space.Log(Space.Math.Sign(4.2));
-- print 1

Space.Log(Space.Math.Sign(-4.2));
-- print -1

Sin

float Sin (float val);

Returns the sine of val

local angle = 1.04719758033752; -- converts to 60 degrees
local sine = Space.Math.Sin(angle);
Space.Log(sine);
-- prints 0.866025447845459

local angle2 = Space.Math.Pi/3; -- converts to 60 degrees
local sine2 = Space.Math.Sin(angle2);
Space.Log(sine2);
-- prints 0.866025447845459

SmoothStep

float SmoothStep (float from, float to, float val);

Similar to Lerp but moves slowly closer to the edges ('Spherical Lerp')

-- Lua Translation of Unity C# Documentation

--[[ In this example, Space.Math.SmoothStep(min, max, time) returns values in the range [1,10] in order.
 
As values approach 10, the interpolation slows down. --]]

local ball = Space.Host.ExecutingObject;

local originalPos = ball.LocalPosition;

local min = 1.0;

local max = 10.0;

local duration = 5.0;

local startTime;

ball.SubscribeToEvents();

local initStartTime = function()

  startTime =Space.Time;

end

-- The ball jumps to min + originalPos, then it moves towards

-- max + originalPos while slowing down at the end.

local animateBall = function()

  local time = (Space.Time - startTime) / duration;

  local newPos = Vector.New(Space.Math.SmoothStep(min, max, time) + originalPos.x, originalPos.y, originalPos.z);

  ball.LocalPosition = newPos;

end

ball.OnStart(initStartTime);

ball.OnUpdate(animateBall);

Sqrt

float Sqrt (float val);

Returns the square root of val

No example provided yet

Tan

float Tan (float val);

Returns the tangent value of 'val'

No example provided yet

@@ Line 169: / Line 169: @@
 {{ScriptFunction|float|Sin|(float val);|Returns the sine of val|5=local angle = 1.04719758033752; ''-- converts to 60 degrees''<br>local sine = '''Space.Math.Sin'''(angle);<br>Space.Log(sine);<br>''-- prints 0.866025447845459''<br><br>local angle2 = Space.Math.Pi/3; ''-- converts to 60 degrees''<br>local sine2 = '''Space.Math.Sin'''(angle2);<br>Space.Log(sine2);<br>''-- prints 0.866025447845459''}}
-{{ScriptFunction|float|SmoothStep|(float from, float to, float val);|Similar to Lerp but moves slowly closer to the edges ('Spherical Lerp')}}
+{{ScriptFunction|float|SmoothStep|(float from, float to, float val);|Similar to Lerp but moves slowly closer to the edges ('Spherical Lerp')|5=
+''-- Lua Translation of Unity C# Documentation''<br><br>
+<br>''--[[ In this example, Space.Math.SmoothStep(min, max, time) returns values in the range [1,10] in order.<br>
+<br>As values approach 10, the interpolation slows down. --]]''<br>
+local ball = Space.Host.ExecutingObject;<br>
+local originalPos = ball.LocalPosition;<br>
+local min = 1.0;<br>
+local max = 10.0;<br>
+local duration = 5.0;<br>
+local startTime;<br>
+ball.SubscribeToEvents();<br><br>
+local initStartTime = function()<br>
+&nbsp;&nbsp;startTime =Space.Time;<br>
+end<br><br>
+''-- The ball jumps to min + originalPos, then it moves towards''<br>
+''-- max + originalPos while slowing down at the end.''<br>
+local animateBall = function()<br>
+&nbsp;&nbsp;local time = (Space.Time - startTime) / duration;<br>
+&nbsp;&nbsp;local newPos = Vector.New('''Space.Math.SmoothStep'''(min, max, time) + originalPos.x, originalPos.y, originalPos.z);<br>
+&nbsp;&nbsp;ball.LocalPosition = newPos;<br>
+end<br><br>
+ball.OnStart(initStartTime);<br>
+ball.OnUpdate(animateBall);
+}}
 {{ScriptFunction|float|Sqrt|(float val);|Returns the square root of val}}
 {{ScriptFunction|float|Tan|(float val);|Returns the tangent value of 'val'}}
 {{Scripting Navbox}}