|
|
(11 intermediate revisions by one other user not shown) |
Line 1: |
Line 1: |
− | The SMath class contains common math functions, see also [[SVector]] and [[SQuaternion]] for Vector and Quaternion related math functions.
| + | https://docs.sine.space/v/scripting/client-scripting/static-classes/smath |
− | | + | |
− | ==Fields==
| + | |
− | {{ScriptFunction|float|Pi|;|Returns the constant value of Π (readonly).|5=Space.Log('''Space.Math.Pi''');<br>''-- prints 3.14159274101257''
| + | |
− | }}
| + | |
− | | + | |
− | ==Members==
| + | |
− | {{ScriptFunction|float|Random|();|Returns a random float between 0 and 1 (inclusive)|5 = local randomNumber = '''Space.Math.Random()''';<br>Space.Log(randomNumber);<br>-- prints 0.689094245433807}}
| + | |
− | | + | |
− | {{ScriptFunction|float|RandomRange|(float min, float max);|Returns a random float between min and max (inclusive)|5=local min = 100.0;<br>local max = 500.0;<br>local randomNumber = '''Space.Math.RandomRange'''(min, max );
| + | |
− | <br>Space.Log(randomNumber);<br>-- prints 0206.659149169922}}
| + | |
− | | + | |
− | {{ScriptFunction|int|RandomInteger|(int min, int max);|Returns a random float between min (inclusive) and max (exclusive)|5=local min = 50;<br>local max = 75;<br>local randomInteger = '''Space.Math.RandomInteger'''(min, max);<br>Space.Log(randomInteger);<br>-- prints 52}}
| + | |
− | | + | |
− | {{ScriptFunction|float|Abs|(float val);|Returns the absolute value of 'val'|5=local value = -4.2<br>local absoluteNum = '''Space.Math.Abs'''(value);<br>Space.Log(absoluteNum);<br>''-- prints 4 [BUG] should be 4.2''}}
| + | |
− | | + | |
− | {{ScriptFunction|int|Abs|(int val);|Returns the absolute value of 'val'|5=local value = -4<br>local absoluteNum = '''Space.Math.Abs'''(value);<br>Space.Log(absoluteNum);<br>''-- prints 4''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|Acos|(float val);|Returns the arc cosine value of 'val'|5=local value = 0.5;<br>local arcCosine = '''Space.Math.Acos'''(value);<br>Space.Log(arcCosine);<br>''-- prints 1.04719758033752 (radians) which is 60 degrees''}}
| + | |
− | | + | |
− | {{ScriptFunction|bool|Approximately|(float a, float b);|True if the difference between a and b is less than epsilon|5=local a = 5.0;<br>local b = 5;<br>local approx1 = '''Space.Math.Approximately'''(a, b);<br>Space.Log(approx1);<br>''-- prints true''<br><br>local a = 5.01;<br>local b = 5.0;<br>local approx2 = '''Space.Math.Approximately'''(a, b);<br>Space.Log(approx2);<br>''-- prints false''<br><br>local a = 5.01;<br>local b = 5.0;<br>local approx3 = '''Space.Math.Approximately'''(a, b);<br>Space.Log(approx3);<br>''-- prints false''}}
| + | |
− | | + | |
− | {{ScriptFunction|bool|Asin|(float val);|Returns the arc sine value of 'val'|5=local value = 0.5;<br>local arcSine = '''Space.Math.Asin'''(value);<br>Space.Log(arcSine);<br>''-- prints 0.523598790168762 (radians) which is 30 degrees''}}
| + | |
− | | + | |
− | {{ScriptFunction|bool|Atan|(float val);|Returns the arc tangent value of 'val'|5=local value = 1.732050808;<br>local arcTangent = '''Space.Math.Atan'''(value);<br>Space.Log(arcTangent);<br>''-- prints 1.04719758033752 (radians) which is 60 degrees''}}
| + | |
− | | + | |
− | {{ScriptFunction|bool|Atan2|(float y, float x);|Returns the arc tangent of y/x|5=local x = 0.5;<br>local y = 0.5;<br>local arcTangent = '''Space.Math.Atan2'''(y, x);<br>Space.Log(arcTangent);<br>''-- prints 0.785398185253143''}}
| + | |
− | | + | |
− | {{ScriptFunction|int|Ceil|(float val);|Returns the ceil value of 'val' as an integer|5=Space.Log('''Space.Math.Ceil'''(4.0));<br>
| + | |
− | ''-- prints 4''<br><br>Space.Log('''Space.Math.Ceil'''(4.2));<br>''-- prints 5''<br><br>Space.Log('''Space.Math.Ceil'''(-4.2));<br>''-- prints -4''
| + | |
− | }}
| + | |
− | | + | |
− | {{ScriptFunction|float|Clamp|(float val, float min, float max);|Clamps val between min and max, and returns the result|5=local value = 100.0;<br>local min = 20.0;<br>local max = 82.0;<br><br>local clampedValue = '''Space.Math.Clamp'''(value, min, max);<br>Space.Log(clampedValue);<br>
| + | |
− | ''-- prints 82''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|Clamp01|(float val);|Clamps val between 0 and 1, and returns the result|5=local value = -1.0;<br><br>local clampedValue = '''Space.Math.Clamp01'''(value);<br>Space.Log(clampedValue);<br>''-- prints 0''}}
| + | |
− | | + | |
− | {{ScriptFunction|int|ClosestPowerOfTwo|(int val);|Returns the closest power of two to val|5=local value = 33;<br><br>local powerOfTwo = '''Space.Math.ClosestPowerOfTwo'''(value);<br>Space.Log(powerOfTwo);<br>''-- prints 32''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|Cos|(float val);|Returns the cosine of val|5=local angle = 1.04719758033752; ''-- converts to 60 degrees''<br>local cosine = '''Space.Math.Cos'''(angle);<br>Space.Log(cosine);<br>''-- prints 0.499999970197678''<br><br>local angle2 = Space.Math.Pi/3; ''-- converts to 60 degrees''<br>local cosine2 = '''Space.Math.Cos'''(angle2);<br>Space.Log(cosine2);<br>''-- prints 0.499999970197678''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|DeltaAngle|(float current, float target);|Returns the difference in degrees between two values (e.g. 350' and 17' returns 27')|5=Space.Log('''Space.Math.DeltaAngle'''(350.0, 17.0));<br>''-- prints 27''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|Exp|(float val);|Returns e raised to val power.|5=Space.Log('''Space.Math.Exp'''(3.0));<br>''-- prints 20.0855369567871''}}
| + | |
− | | + | |
− | {{ScriptFunction|int|Floor|(float val);|Returns floor of val, converted to an int|5=Space.Log('''Space.Math.Floor'''(4.0));<br>''-- prints 4''<br><br>Space.Log('''Space.Math.Floor'''(4.2));<br>''-- prints 4''<br><br>Space.Log('''Space.Math.Floor'''(-4.2));<br>''-- prints -5''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|GammaToLinearSpace|(float val);|Converts a colour value from Gamma to Linear Space (Pow 2.2)|5=Space.Log('''Space.Math.GammaToLinearSpace'''(0.5));<br>''-- prints 0.214041143655777''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|InverseLerp|(float a, float b, float val);|Returns the percentage between a and b that 'val' is on a line (opposite of Lerp)|5=local sliderStart = 0.0;<br>local sliderStop = 100.0;<br>local currentSliderPos = 75.0;<br><br>local percentage = '''Space.Math.InverseLerp'''(sliderStart, sliderStop, currentSliderPos);<br>Space.Log(percentage);
| + | |
− | <br>''-- prints 0.75''}}
| + | |
− | | + | |
− | {{ScriptFunction|bool|IsPowerOfTwo|(int val);|Returns true if val is a power of two|5=Space.Log('''Space.Math.IsPowerOfTwo'''(55));<br>''-- prints False''<br><br>Space.Log('''Space.Math.IsPowerOfTwo'''(32));<br>
| + | |
− | ''-- prints True''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|Lerp|(float a, float b, float val);|Interpolates between 'a' and 'b' based on 'val', assuming 'val' is between 0 and 1|5=local sliderStart = 0.0;<br>local sliderStop = 100.0;<br>local percentage = 0.75;<br><br>local currentSliderPos = '''Space.Math.Lerp'''(sliderStart, sliderStop, percentage);<br>Space.Log(currentSliderPos);<br> ''-- prints 75''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|LerpAngle|(float a, float b, float val);|Interpolates between angles 'a' and 'b' based on 'val', assuming 'val' is between 0 and 1|5=local sliderStartAngle = 0.0;<br>local sliderStopAngle = Space.Math.Pi;''-- 180 degrees''<br>local percentage = 0.50;<br><br>local currentSliderPos = '''Space.Math.LerpAngle'''(sliderStartAngle, sliderStopAngle, percentage);<br>Space.Log(currentSliderPos);<br>
| + | |
− | ''-- prints 1.57079637050629 (90 degrees)''}}
| + | |
− | | + | |
− | {{ScriptFunction|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)|5=local sliderStart = 0.0;<br>local sliderStop = 100.0;<br>local percentage = 2.0;<br><br>local currentSliderPos = '''Space.Math.LerpUnclamped'''(sliderStart, sliderStop, percentage);<br>Space.Log(currentSliderPos);<br> ''-- prints 200''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|LinearToGammaSpace|(float val);|Converts a colour value from Linear to Gamma Space (Pow 1/2.2)|5=Space.Log('''Space.Math.LinearToGammaSpace'''(0.214041143655777));<br>-''- prints 0.5''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|Log|(float val);|Returns the natural logarithm for 'val'|5=Space.Log('''Space.Math.Log'''(30.0));<br>''-- prints 3.40119743347168''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|Log|(float val, float p);|Returns the logarithm of 'p' for 'val'|5=Space.Log('''Space.Math.Log'''(4.0, 2.0));<br>''-- prints 2''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|Log10|(float val);|Returns the Log10 value for 'val'|5=Space.Log('''Space.Math.Log10'''(100.0));<br>''-- prints 2''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|Max|(float a, float b);|Returns higher of 'a' or 'b'|5=Space.Log('''Space.Math.Max'''(20.0, 100.0));<br>
| + | |
− | ''-- prints 100''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|Min|(float a, float b);|Returns lower of 'a' or 'b'|5=Space.Log('''Space.Math.Min'''(20.0, 100.0));<br>
| + | |
− | ''-- prints 20''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|MoveTowards|(float value, float target, float delta);|Move value to target, but by no more than delta|5=local sliderStart = 5.0;<br>
| + | |
− | local sliderStop = 10.0;<br>
| + | |
− | local deltaChange = 1.0;<br><br>
| + | |
− | local currentSliderPos = '''Space.Math.MoveTowards'''(sliderStart, sliderStop, deltaChange);<br>
| + | |
− | Space.Log(currentSliderPos);<br>
| + | |
− | ''-- prints 6 (moves forward 1)''<br><br><br>
| + | |
− | local sliderStart = 5.0;<br>
| + | |
− | local sliderStop = 10.0;<br>
| + | |
− | local deltaChange = 7.0;<br><br>
| + | |
− | local currentSliderPos = '''Space.Math.MoveTowards'''(sliderStart, sliderStop, deltaChange);<br>
| + | |
− | Space.Log(currentSliderPos);
| + | |
− | ''-- prints 10 (caps out at at the target value)''<br><br>
| + | |
− | ''-- NOTE: Use negative delta to move away from target.''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|MoveTowardsAngle|(float value, float target, float delta);|Move angle value to target, but by no more than delta|5=local sliderStartAngle = Space.Math.Pi/2; ''-- 90 degrees''<br>
| + | |
− | local sliderStopAngle = Space.Math.Pi; ''-- 180 degrees''<br>
| + | |
− | local deltaChange = Space.Math.Pi/6; ''-- 30 degrees''<br><br>
| + | |
− | local currentSliderPos = '''Space.Math.MoveTowardsAngle'''(sliderStartAngle, sliderStopAngle, deltaChange);<br>
| + | |
− | Space.Log(currentSliderPos);<br>
| + | |
− | ''-- prints 2.09439516067505 (moves forward 30 degrees to 120 degrees)''<br><br>
| + | |
− | -- NOTE: Add 180 degrees (Space.Math.Pi) to move away from target.}}
| + | |
− | | + | |
− | {{ScriptFunction|int|NextPowerOfTwo|(int val);|Return the next power of two larger or equal to val|5=Space.Log('''Space.Math.NextPowerOfTwo'''(16));<br>''-- prints 16''<br><br>Space.Log('''Space.Math.NextPowerOfTwo'''(17));<br>''-- prints 32''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|PerlinNoise|(float x, float y);|Return 2D Perlin noise for coordinates x and y|5=-- Lua Translation of Unity C# Documentation<br><br>
| + | |
− | local ball = Space.Host.ExecutingObject;<br>
| + | |
− | ball.SubscribeToEvents();<br><br>
| + | |
− | ''-- animates this object to move upwards on the y axis with slight random movement''<br>
| + | |
− | local animateBall = function()<br>
| + | |
− | local heightScale = 0.1; ''-- controls speed of movement''<br>
| + | |
− | local xScale = 1.0; ''-- shifts x position on perlin noise plane''<br><br>
| + | |
− | local height = heightScale * '''Space.Math.PerlinNoise'''(Space.Time * xScale, 0.0);<br>
| + | |
− | local pos = ball.LocalPosition;<br>
| + | |
− | pos.y = pos.y + height;<br>
| + | |
− | ball.LocalPosition = pos;<br>
| + | |
− | Space.Log(pos.y);<br>
| + | |
− | end<br><br>
| + | |
− | ball.OnUpdate(animateBall);<br><br>
| + | |
− | ''-- NOTE: If you need a guaranteed range of [0,1], make sure to clamp the value with Space.Math.Clamp01.''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|PingPong|(float val, float length);|Return a value between 0 and length that oscillates upwards and back based on the position of 'val'|5=
| + | |
− | ''--[[ 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. --]]''<br><br>
| + | |
− | local ball = Space.Host.ExecutingObject;<br>
| + | |
− | local originalPos = ball.LocalPosition;<br>
| + | |
− | ball.SubscribeToEvents();<br><br>
| + | |
− | ''-- The ball object oscillates back and forth on the x-axis.''<br>
| + | |
− | local animateBall = function()<br>
| + | |
− | local value = Space.Time;<br>
| + | |
− | local length = 5.0;<br><br>
| + | |
− | local newPos = Vector.New('''Space.Math.PingPong'''(value, length) + originalPos.x, originalPos.y, originalPos.z);<br>
| + | |
− | ball.LocalPosition = newPos;<br>
| + | |
− | end<br><br>
| + | |
− | ball.OnUpdate(animateBall);
| + | |
− | }}
| + | |
− | | + | |
− | {{ScriptFunction|float|Pow|(float x, float y);|Return x raised to y power|5=Space.Log('''Space.Math.Pow'''(2, 4));<br>''-- prints 16''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|Repeat|(float val, float length);|Return a value between 0 and length that returns to 0 after exceeding length based on 'val'|5=
| + | |
− | ''--[[ 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.--]]''<br><br>
| + | |
− | local ball = Space.Host.ExecutingObject;<br>
| + | |
− | local originalPos = ball.LocalPosition;<br>
| + | |
− | ball.SubscribeToEvents();<br><br>
| + | |
− | ''-- The ball object moves forward on the x-axis.''<br>
| + | |
− | ''-- Then, it repeats the same motion again from the beginning.<br>
| + | |
− | local animateBall = function()<br>
| + | |
− | local value = Space.Time;<br>
| + | |
− | local length = 5.0;<br><br>
| + | |
− | local newPos = Vector.New('''Space.Math.Repeat'''(value, length) + originalPos.x, originalPos.y, originalPos.z);<br>
| + | |
− | ball.LocalPosition = newPos;<br>
| + | |
− | end<br><br>
| + | |
− | ball.OnUpdate(animateBall);}}
| + | |
− | | + | |
− | {{ScriptFunction|int|Round|(float val);|Returns the nearest integer value to val|5=
| + | |
− | Space.Log('''Space.Math.Round'''(4.0));<br>
| + | |
− | ''-- print 4''<br><br>
| + | |
− | Space.Log('''Space.Math.Round'''(4.2));<br>
| + | |
− | ''-- print 4''<br><br>
| + | |
− | Space.Log('''Space.Math.Round'''(4.5));<br>
| + | |
− | ''-- print 4''<br><br>
| + | |
− | Space.Log('''Space.Math.Round'''(4.55));<br>
| + | |
− | ''-- print 5''<br><br>
| + | |
− | Space.Log('''Space.Math.Round'''(4.8));<br>
| + | |
− | ''-- print 5''<br><br>
| + | |
− | Space.Log('''Space.Math.Round'''(-4.2));<br>
| + | |
− | ''-- print -4''<br><br>
| + | |
− | Space.Log('''Space.Math.Round'''(-4.8));<br><br>
| + | |
− | ''-- print -5''}}
| + | |
− | | + | |
− | {{ScriptFunction|float|Sign|(float val);|Returns either 1 or -1 based on the sign of 'val'|5=Space.Log('''Space.Math.Sign'''(4.2));<br>''-- print'' 1<br><br>Space.Log('''Space.Math.Sign'''(-4.2));<br>''-- print -1''}}
| + | |
− | | + | |
− | {{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')|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>
| + | |
− | 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>
| + | |
− | local time = (Space.Time - startTime) / duration;<br>
| + | |
− | local newPos = Vector.New('''Space.Math.SmoothStep'''(min, max, time) + originalPos.x, originalPos.y, originalPos.z);<br>
| + | |
− | 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}}
| + | |