DF21 Wiki - User contributions [en]

Math Script API

2024-12-15T02:29:37Z

Lucius:

Core math API used by the script system. It can be accessed using the math interface and consists of a number of constants, functions, and built-in vector and matrix types.

== Basic Types ==
Basic math types available to the script system include:

* int - 32-bit signed integer
* uint - 32-bit unsigned integer
* float - 32-bit floating point value

== Vector and Matrix Types ==

* '''float2, float3, float4''' - vector types of the indicated size. A float3, for example, consists of 3 floats in vector format. Components can be accessed as x, y, z, w or by index (see the examples below). GLSL style swizzling is supported, as well as array syntax. Swizzling can be used to copy out smaller vectors as well.
* '''float2x2, float3x3, float4x4''' - matrix types of the indicated size (2x2, 3x3, or 4x4 matrix). Rows can be accessed using the array syntax and are of the associated vector type (float2x2 = 2 x float2).

== Vector Operations ==
Vector types ('''float, float2, float3, float4''') can be referenced using array and component syntax. Swizzling is supported.

Example Swizzles:<pre>
float2 v(1, 2);
system.print("{}", v); // (1, 2)
system.print("{}", v.yx); // (2, 1)
system.print("{}", v.xx); // (1, 1)
float a = v.y;
system.print("{}", a); // 2

float3 v3(1, 2, 3);
float2 v2 = v3.xz;
</pre>
Example of Array Access:
<pre>
float2 v2(2,3);
system.print("{}", v2[0]); // 2
system.print("{}", v2[1]); // 3

float4 v4(1, 2, 3, 4);
system.print("{}", v4[1]); // 2
system.print("{}", v4[3]); // 4
</pre>
Example of mathematical operations, basic operations are supported:
<pre>
float2 a(1,2);
float2 b(2,3);
float4 a4(1,2,3,4);
float2 c = a + b; // c = (1,2) + (2,3) = (3,5)
float2 d = a * b; // d = (1,2) * (2,3) = (2,6)
float2 e = a * 2.0; // e = (1,2) * 2 = (2,4)
float3 f = a4.xyz * a.y; // f = (1,2,3) * (2) = (2,4,6)
</pre>

== Matrix Operations ==
Matrices are stored as a series of vectors, which can be accessed using array syntax. Matrix types support matrix/matrix and matrix/vector multiplication, as well as matrix/float scaling.
The following types are supported: float2x2, float3x3, float4x4.
<pre>
float2x2 m2x2(1, 0, 0, 1); // 2x2 matrix: [1 0]
[0 1]
float3x3 m0(float3(1, 0, 0), float3(0, 1, 0), float3(0, 0, 1)); // 3x3 identity.
float3x3 m1;

float3x3 m2 = m0 * m1; // concatenate matrices m0 and m1.
float3 pos;
float3 r = m2 * pos; // multiply 'pos' by matrix m2.

float3 v = m0[1]; // v = (0, 1, 0)

float2x2 rot2x2 = math.rotationMatrix2x2(angle);
float3x3 rot3x3 = math.rotationMatrix3x3(pitch, yaw, roll);
// Transform a 2D point.
float2 point;
float2 pivot; // center point of rotation.
float2 rotatedPoint = rot2x2 * (point - pivot) + pivot;
</pre>

== Math Examples ==
<pre>
float2 s(2, 3);
float2 t(4, 5);
float2 q(3, 4);
float3 r(4, 5, 6);
float3 color0(1.0, 0.5, 0.5);
float3 color1(0.25, 0.25, 1.0);
float dist = math.distance(s, q); // distance between (2,3) and (3,4).
float blend = math.smoothstep(0, 5, dist); // produce a blend factor between [0,1]
float2 value = math.mix(s, t, blend);
float2 sum = r.xy + r.yz;
float3 unit = math.normalize(r);
float3 color = math.mix(color0, color1, blend);
</pre>

== Math Constants ==
{| class="wikitable"
|+
!Constant
!Description
|-
|float pi
|value of π
|-
|float twoPi
|value of 2*π
|-
|float e
|value of the natural number e
|}

== Math Functions ==
=== countBits(x) ===
Counts the number of bits in an integer.
<pre>
int countBits(uint)
int countBits(int)
</pre>

=== findLSB(x) ===
Return the Least Significant Bit of the integer '''x'''.
<pre>
int findLSB(uint)
int findLSB(int)
</pre>

=== findMSB(x) ===
Return the Most Significant Bit of the integer '''x'''.
<pre>
int findMSB(uint)
int findMSB(int)
</pre>

=== abs(x) ===
Returns the absolute value of the input, operates per-component.
<pre>
int abs(int)
float abs(float)
float2 abs(float2)
float3 abs(float3)
float4 abs(float4)
</pre>

=== all(x) ===
Returns true if all components are non-zero.
<pre>
bool all(float)
bool all(float2)
bool all(float3)
bool all(float4)
</pre>

=== any(x) ===
Returns true if any component is non-zero.
<pre>
bool any(float)
bool any(float2)
bool any(float3)
bool any(float4)
</pre>

=== acos(x) ===
Arccosine of angles in radians, operates per-component.
<pre>
float acos(float)
float2 acos(float2)
float3 acos(float3)
float4 acos(float4)
</pre>

=== asin(x) ===
Arcsine of angles in radians, operates per-component.
<pre>
float asin(float)
float2 asin(float2)
float3 asin(float3)
float4 asin(float4)
</pre>

=== atan(x) ===
Arctangent of angles in radians, operates per-component.
<pre>
float atan(float)
float2 atan(float2)
float3 atan(float3)
float4 atan(float4)
</pre>

=== atan2(y, x) ===
Returns the angle θ between the positive x-axis and the ray from the origin to the point (x, y), confined to (−π, π].
<pre>
float atan2(float, float)
float2 atan2(float2, float2)
float3 atan2(float3, float3)
float4 atan2(float4, float4)
</pre>

=== cos(x) ===
Computes the cosine of the input angle in radians.
<pre>
float cos(float)
float2 cos(float2)
float3 cos(float3)
float4 cos(float4)
</pre>

=== sin(x) ===
Computes the sine of the input angle in radians.
<pre>
float sin(float)
float2 sin(float2)
float3 sin(float3)
float4 sin(float4)
</pre>

=== tan(x) ===
Computes the tangent of the input angle in radians.
<pre>
float tan(float)
float2 tan(float2)
float3 tan(float3)
float4 tan(float4)
</pre>

=== sincos(x) ===
Compute the sine of the input angle and store it in x, and cosine of the angle in y.
<pre>
float2 sincos(float)
</pre>

=== degrees(x) ===
Converts from radians to degrees, operates per-component.
<pre>
float degrees(float)
float2 degrees(float2)
float3 degrees(float3)
float4 degrees(float4)
</pre>

=== radians(x) ===
Converts from degrees to radians, operates per-component.
<pre>
float radians(float)
float2 radians(float2)
float3 radians(float3)
float4 radians(float4)
</pre>

=== exp(x) ===
Computes the natural number '''e''' to the power of '''x''', and operates per component.
<pre>
float exp(float)
float2 exp(float2)
float3 exp(float3)
float4 exp(float4)
</pre>

=== exp2(x) ===
Computes '''2''' to the power of '''x''', and operates per component.
<pre>
float exp2(float)
float2 exp2(float2)
float3 exp2(float3)
float4 exp2(float4)
</pre>

=== log(x) ===
Computes the natural (base '''e''') logarithm of the input.
<pre>
float log(float)
float2 log(float2)
float3 log(float3)
float4 log(float4)
</pre>

=== log2(x) ===
Computes the base '''2''' logarithm of the input.
<pre>
float log2(float)
float2 log2(float2)
float3 log2(float3)
float4 log2(float4)
</pre>

=== log10(x) ===
Computes the base '''10''' logarithm of the input.
<pre>
float log10(float)
float2 log10(float2)
float3 log10(float3)
float4 log10(float4)
</pre>

=== pow(x, y) ===
Compute the power of '''x''' to the power of '''y''' (x^y).
<pre>
float pow(float, float)
float2 pow(float2, float)
float2 pow(float2, float2)
float3 pow(float3, float)
float3 pow(float3, float3)
float4 pow(float4, float)
float4 pow(float4, float4)
</pre>

=== floor(x) ===
Rounds the input down to the nearest integer, operates per-component.
<pre>
float floor(float)
float2 floor(float2)
float3 floor(float3)
float4 floor(float4)
</pre>

=== ceil(x) ===
Rounds the input up to the nearest integer, operates per-component.
<pre>
float ceil(float)
float2 ceil(float2)
float3 ceil(float3)
float4 ceil(float4)
</pre>

=== fract(x) ===
Extract the signed fractional part of the input, operates per-component.
<pre>
float fract(float)
float2 fract(float2)
float3 fract(float3)
float4 fract(float4)
</pre>

=== max(x, y) ===
Returns the maximum of two values, operates per-component.
<pre>
float max(float, float)
float2 max(float2, float)
float2 max(float2, float2)
float3 max(float3, float)
float3 max(float3, float3)
float4 max(float4, float)
float4 max(float4, float4)
</pre>

=== min(x, y) ===
Returns the minimum of two values, operates per-component.
<pre>
float min(float, float)
float2 min(float2, float)
float2 min(float2, float2)
float3 min(float3, float)
float3 min(float3, float3)
float4 min(float4, float)
float4 min(float4, float4)
</pre>

=== clamp(x, a, b) ===
Returns '''x''' clamped to the range of '''[a,b]''', operates per-component.
<pre>
float clamp(float, float, float)
float2 clamp(float2, float, float)
float2 clamp(float2, float2, float2)
float3 clamp(float3, float, float)
float3 clamp(float3, float3, float3)
float4 clamp(float4, float, float)
float4 clamp(float4, float4, float4)
</pre>

=== saturate(x) ===
Clamps the '''x''' to the range of '''[0,1]''', operates per-component.
<pre>
float saturate(float)
float2 saturate(float2)
float3 saturate(float3)
float4 saturate(float4)
</pre>

=== mix(x, y, a) ===
Uses '''a''' to linearly interpolate between '''x''' and '''y''', if '''a == 0''' the result is '''x''', if '''a == 1''' the result is '''y''', in-between is a mix of '''x''' and '''y'''. Operates per-component.
<pre>
float mix(float, float, float)
float2 mix(float2, float2, float)
float2 mix(float2, float2, float2)
float3 mix(float3, float3, float)
float3 mix(float3, float3, float3)
float4 mix(float4, float4, float)
float4 mix(float4, float4, float4)
</pre>

=== step(edge, x) ===
A step function comparing '''x''' to '''edge''', if '''x < edge''' return '''0''' otherwise return '''1'''. Operates per component.
<pre>
int step(int, int)
float step(float, float)
float2 step(float, float2)
float2 step(float2, float2)
float3 step(float, float3)
float3 step(float3, float3)
float4 step(float, float4)
float4 step(float4, float4)
</pre>

=== smoothstep(edge0, edge1, x) ===
Performs smooth Hermite interpolation between '''0''' and '''1''' when '''edge0 < x < edge1''', operates per-component.
<pre>
float smoothstep(float, float, float)
float2 smoothstep(float, float, float2)
float2 smoothstep(float2, float2, float)
float2 smoothstep(float2, float2, float2)
float3 smoothstep(float, float, float3)
float3 smoothstep(float3, float3, float)
float3 smoothstep(float3, float3, float3)
float4 smoothstep(float, float, float4)
float4 smoothstep(float4, float4, float)
float4 smoothstep(float4, float4, float4)
</pre>

=== sign(x) ===
Returns the sign of '''x''', -1 if '''x < 0''', 1 if '''x > 0''', 0 if '''x == 0''', operates per-component.
<pre>
int sign(int)
float sign(float)
float2 sign(float2)
float3 sign(float3)
float4 sign(float4)
</pre>

=== sqrt(x) ===
Returns the square root of the input, operates per-component.
<pre>
float sqrt(float)
float2 sqrt(float2)
float3 sqrt(float3)
float4 sqrt(float4)
</pre>

=== mod(x, y) ===
The floating-point remainder of the division operation '''x / y''', operates per-component.
<pre>
float mod(float, float)
float2 mod(float2, float)
float2 mod(float2, float2)
float3 mod(float3, float)
float3 mod(float3, float3)
float4 mod(float4, float)
float4 mod(float4, float4)
</pre>

=== distance(x, y) ===
Computes the (unsigned) distance between points '''x''' and '''y'''.
<pre>
float distance(float, float)
float distance(float2, float2)
float distance(float3, float3)
float distance(float4, float4)
</pre>

=== dot(x, y) ===
Computes the dot product of '''x''' and '''y''' (also known as the inner product).
<pre>
float dot(float, float)
float dot(float2, float2)
float dot(float3, float3)
float dot(float4, float4)
</pre>

=== length(x) ===
Returns the length of the input vector.
<pre>
float length(float)
float length(float2)
float length(float3)
float length(float4)
</pre>

=== normalize(x) ===
Returns the normalized (unit) vector of '''x'''.
<pre>
float normalize(float)
float2 normalize(float2)
float3 normalize(float3)
float4 normalize(float4)
</pre>

=== perp(x, y) ===
Computes the perp product of two 2D vectors, '''x''' and '''y'''. This is similar to the cross product in 2D, where '''perp(x, y) = |x| * |y| * sin(angle)'''.
<pre>
float perp(float2, float2)
</pre>

=== cross(x, y) ===
Computes the cross product of two 3D vectors, '''x''' and '''y'''.
<pre>
float3 cross(float3, float3)
</pre>

=== transpose(x) ===
Return the transpose of matrix '''x'''.
<pre>
float2x2 transpose(float2x2)
float3x3 transpose(float3x3)
float4x4 transpose(float4x4)
</pre>

=== rotationMatrix2x2(angle) ===
Builds a 2x2 rotation matrix based on angle in radians.
<pre>
float2x2 rotationMatrix2x2(float)
</pre>

=== rotationMatrix3x3(pitch, yaw, roll) ===
Builds a 3x3 rotation matrix based on yaw, pitch, roll angles in radians. Note that roll = 0.0 by default.
<pre>
float3x3 rotationMatrix3x3(float, float, float = 0.0)
</pre>

Math Script API

2024-12-15T02:26:03Z

Lucius:

Core math API used by the script system. It can be accessed using the math interface and consists of a number of constants, functions, and built-in vector and matrix types.

== Basic Types ==
Basic math types available to the script system include:

* int - 32-bit signed integer
* uint - 32-bit unsigned integer
* float - 32-bit floating point value

== Vector and Matrix Types ==

* '''float2, float3, float4''' - vector types of the indicated size. A float3, for example, consists of 3 floats in vector format. Components can be accessed as x, y, z, w or by index (see the examples below). GLSL style swizzling is supported, as well as array syntax. Swizzling can be used to copy out smaller vectors as well.
* '''float2x2, float3x3, float4x4''' - matrix types of the indicated size (2x2, 3x3, or 4x4 matrix). Rows can be accessed using the array syntax and are of the associated vector type (float2x2 = 2 x float2).

== Vector Operations ==
Vector types ('''float, float2, float3, float4''') can be referenced using array and component syntax. Swizzling is supported.

Example Swizzles:<pre>
float2 v(1, 2);
system.print("{}", v); // (1, 2)
system.print("{}", v.yx); // (2, 1)
system.print("{}", v.xx); // (1, 1)
float a = v.y;
system.print("{}", a); // 2

float3 v3(1, 2, 3);
float2 v2 = v3.xz;
</pre>
Example of Array Access:
<pre>
float2 v2(2,3);
system.print("{}", v2[0]); // 2
system.print("{}", v2[1]); // 3

float4 v4(1, 2, 3, 4);
system.print("{}", v4[1]); // 2
system.print("{}", v4[3]); // 4
</pre>
Example of mathematical operations, basic operations are supported:
<pre>
float2 a(1,2);
float2 b(2,3);
float4 a4(1,2,3,4);
float2 c = a + b; // c = (1,2) + (2,3) = (3,5)
float2 d = a * b; // d = (1,2) * (2,3) = (2,6)
float2 e = a * 2.0; // e = (1,2) * 2 = (2,4)
float3 f = a4.xyz * a.y; // f = (1,2,3) * (2) = (2,4,6)
</pre>

== Matrix Operations ==
Matrices are stored as a series of vectors, which can be accessed using array syntax. Matrix types support matrix/matrix and matrix/vector multiplication, as well as matrix/float scaling.
The following types are supported: float2x2, float3x3, float4x4.
<pre>
float2x2 m2x2(1, 0, 0, 1); // 2x2 matrix: [1 0]
[0 1]
float3x3 m0(float3(1, 0, 0), float3(0, 1, 0), float3(0, 0, 1)); // 3x3 identity.
float3x3 m1;

float3x3 m2 = m0 * m1; // concatenate matrices m0 and m1.
float3 pos;
float3 r = m2 * pos; // multiply 'pos' by matrix m2.

float3 v = m0[1]; // v = (0, 1, 0)

float2x2 rot2x2 = math.rotationMatrix2x2(angle);
float3x3 rot3x3 = math.rotationMatrix3x3(pitch, yaw, roll);
// Transform a 2D point.
float2 point;
float2 pivot; // center point of rotation.
float2 rotatedPoint = rot2x2 * (point - pivot) + pivot;
</pre>

== Math Examples ==
<pre>
float2 s(2, 3);
float2 t(4, 5);
float2 q(3, 4);
float3 r(4, 5, 6);
float3 color0(1.0, 0.5, 0.5);
float3 color1(0.25, 0.25, 1.0);
float dist = math.distance(s, q); // distance between (2,3) and (3,4).
float blend = math.smoothstep(0, 5, dist); // produce a blend factor between [0,1]
float2 value = math.mix(s, t, blend);
float2 sum = r.xy + r.yz;
float3 unit = math.normalize(r);
float3 color = math.mix(color0, color1, blend);
</pre>

== Math Constants ==
{| class="wikitable"
|+
!Constant
!Description
|-
|float pi
|value of π
|-
|float twoPi
|value of 2*π
|-
|float e
|value of the natural number e
|}

== Math Functions ==
=== countBits(x) ===
Counts the number of bits in an integer.
<pre>
uint countBits(uint)
int countBits(int)
</pre>

=== abs(x) ===
Returns the absolute value of the input, operates per-component.
<pre>
int abs(int)
float abs(float)
float2 abs(float2)
float3 abs(float3)
float4 abs(float4)
</pre>

=== all(x) ===
Returns true if all components are non-zero.
<pre>
bool all(float)
bool all(float2)
bool all(float3)
bool all(float4)
</pre>

=== any(x) ===
Returns true if any component is non-zero.
<pre>
bool any(float)
bool any(float2)
bool any(float3)
bool any(float4)
</pre>

=== acos(x) ===
Arccosine of angles in radians, operates per-component.
<pre>
float acos(float)
float2 acos(float2)
float3 acos(float3)
float4 acos(float4)
</pre>

=== asin(x) ===
Arcsine of angles in radians, operates per-component.
<pre>
float asin(float)
float2 asin(float2)
float3 asin(float3)
float4 asin(float4)
</pre>

=== atan(x) ===
Arctangent of angles in radians, operates per-component.
<pre>
float atan(float)
float2 atan(float2)
float3 atan(float3)
float4 atan(float4)
</pre>

=== atan2(y, x) ===
Returns the angle θ between the positive x-axis and the ray from the origin to the point (x, y), confined to (−π, π].
<pre>
float atan2(float, float)
float2 atan2(float2, float2)
float3 atan2(float3, float3)
float4 atan2(float4, float4)
</pre>

=== cos(x) ===
Computes the cosine of the input angle in radians.
<pre>
float cos(float)
float2 cos(float2)
float3 cos(float3)
float4 cos(float4)
</pre>

=== sin(x) ===
Computes the sine of the input angle in radians.
<pre>
float sin(float)
float2 sin(float2)
float3 sin(float3)
float4 sin(float4)
</pre>

=== tan(x) ===
Computes the tangent of the input angle in radians.
<pre>
float tan(float)
float2 tan(float2)
float3 tan(float3)
float4 tan(float4)
</pre>

=== sincos(x) ===
Compute the sine of the input angle and store it in x, and cosine of the angle in y.
<pre>
float2 sincos(float)
</pre>

=== degrees(x) ===
Converts from radians to degrees, operates per-component.
<pre>
float degrees(float)
float2 degrees(float2)
float3 degrees(float3)
float4 degrees(float4)
</pre>

=== radians(x) ===
Converts from degrees to radians, operates per-component.
<pre>
float radians(float)
float2 radians(float2)
float3 radians(float3)
float4 radians(float4)
</pre>

=== exp(x) ===
Computes the natural number '''e''' to the power of '''x''', and operates per component.
<pre>
float exp(float)
float2 exp(float2)
float3 exp(float3)
float4 exp(float4)
</pre>

=== exp2(x) ===
Computes '''2''' to the power of '''x''', and operates per component.
<pre>
float exp2(float)
float2 exp2(float2)
float3 exp2(float3)
float4 exp2(float4)
</pre>

=== log(x) ===
Computes the natural (base '''e''') logarithm of the input.
<pre>
float log(float)
float2 log(float2)
float3 log(float3)
float4 log(float4)
</pre>

=== log2(x) ===
Computes the base '''2''' logarithm of the input.
<pre>
float log2(float)
float2 log2(float2)
float3 log2(float3)
float4 log2(float4)
</pre>

=== log10(x) ===
Computes the base '''10''' logarithm of the input.
<pre>
float log10(float)
float2 log10(float2)
float3 log10(float3)
float4 log10(float4)
</pre>

=== pow(x, y) ===
Compute the power of '''x''' to the power of '''y''' (x^y).
<pre>
float pow(float, float)
float2 pow(float2, float)
float2 pow(float2, float2)
float3 pow(float3, float)
float3 pow(float3, float3)
float4 pow(float4, float)
float4 pow(float4, float4)
</pre>

=== floor(x) ===
Rounds the input down to the nearest integer, operates per-component.
<pre>
float floor(float)
float2 floor(float2)
float3 floor(float3)
float4 floor(float4)
</pre>

=== ceil(x) ===
Rounds the input up to the nearest integer, operates per-component.
<pre>
float ceil(float)
float2 ceil(float2)
float3 ceil(float3)
float4 ceil(float4)
</pre>

=== fract(x) ===
Extract the signed fractional part of the input, operates per-component.
<pre>
float fract(float)
float2 fract(float2)
float3 fract(float3)
float4 fract(float4)
</pre>

=== max(x, y) ===
Returns the maximum of two values, operates per-component.
<pre>
float max(float, float)
float2 max(float2, float)
float2 max(float2, float2)
float3 max(float3, float)
float3 max(float3, float3)
float4 max(float4, float)
float4 max(float4, float4)
</pre>

=== min(x, y) ===
Returns the minimum of two values, operates per-component.
<pre>
float min(float, float)
float2 min(float2, float)
float2 min(float2, float2)
float3 min(float3, float)
float3 min(float3, float3)
float4 min(float4, float)
float4 min(float4, float4)
</pre>

=== clamp(x, a, b) ===
Returns '''x''' clamped to the range of '''[a,b]''', operates per-component.
<pre>
float clamp(float, float, float)
float2 clamp(float2, float, float)
float2 clamp(float2, float2, float2)
float3 clamp(float3, float, float)
float3 clamp(float3, float3, float3)
float4 clamp(float4, float, float)
float4 clamp(float4, float4, float4)
</pre>

=== saturate(x) ===
Clamps the '''x''' to the range of '''[0,1]''', operates per-component.
<pre>
float saturate(float)
float2 saturate(float2)
float3 saturate(float3)
float4 saturate(float4)
</pre>

=== mix(x, y, a) ===
Uses '''a''' to linearly interpolate between '''x''' and '''y''', if '''a == 0''' the result is '''x''', if '''a == 1''' the result is '''y''', in-between is a mix of '''x''' and '''y'''. Operates per-component.
<pre>
float mix(float, float, float)
float2 mix(float2, float2, float)
float2 mix(float2, float2, float2)
float3 mix(float3, float3, float)
float3 mix(float3, float3, float3)
float4 mix(float4, float4, float)
float4 mix(float4, float4, float4)
</pre>

=== step(edge, x) ===
A step function comparing '''x''' to '''edge''', if '''x < edge''' return '''0''' otherwise return '''1'''. Operates per component.
<pre>
int step(int, int)
float step(float, float)
float2 step(float, float2)
float2 step(float2, float2)
float3 step(float, float3)
float3 step(float3, float3)
float4 step(float, float4)
float4 step(float4, float4)
</pre>

=== smoothstep(edge0, edge1, x) ===
Performs smooth Hermite interpolation between '''0''' and '''1''' when '''edge0 < x < edge1''', operates per-component.
<pre>
float smoothstep(float, float, float)
float2 smoothstep(float, float, float2)
float2 smoothstep(float2, float2, float)
float2 smoothstep(float2, float2, float2)
float3 smoothstep(float, float, float3)
float3 smoothstep(float3, float3, float)
float3 smoothstep(float3, float3, float3)
float4 smoothstep(float, float, float4)
float4 smoothstep(float4, float4, float)
float4 smoothstep(float4, float4, float4)
</pre>

=== sign(x) ===
Returns the sign of '''x''', -1 if '''x < 0''', 1 if '''x > 0''', 0 if '''x == 0''', operates per-component.
<pre>
int sign(int)
float sign(float)
float2 sign(float2)
float3 sign(float3)
float4 sign(float4)
</pre>

=== sqrt(x) ===
Returns the square root of the input, operates per-component.
<pre>
float sqrt(float)
float2 sqrt(float2)
float3 sqrt(float3)
float4 sqrt(float4)
</pre>

=== mod(x, y) ===
The floating-point remainder of the division operation '''x / y''', operates per-component.
<pre>
float mod(float, float)
float2 mod(float2, float)
float2 mod(float2, float2)
float3 mod(float3, float)
float3 mod(float3, float3)
float4 mod(float4, float)
float4 mod(float4, float4)
</pre>

=== distance(x, y) ===
Computes the (unsigned) distance between points '''x''' and '''y'''.
<pre>
float distance(float, float)
float distance(float2, float2)
float distance(float3, float3)
float distance(float4, float4)
</pre>

=== dot(x, y) ===
Computes the dot product of '''x''' and '''y''' (also known as the inner product).
<pre>
float dot(float, float)
float dot(float2, float2)
float dot(float3, float3)
float dot(float4, float4)
</pre>

=== length(x) ===
Returns the length of the input vector.
<pre>
float length(float)
float length(float2)
float length(float3)
float length(float4)
</pre>

=== normalize(x) ===
Returns the normalized (unit) vector of '''x'''.
<pre>
float normalize(float)
float2 normalize(float2)
float3 normalize(float3)
float4 normalize(float4)
</pre>

=== perp(x, y) ===
Computes the perp product of two 2D vectors, '''x''' and '''y'''. This is similar to the cross product in 2D, where '''perp(x, y) = |x| * |y| * sin(angle)'''.
<pre>
float perp(float2, float2)
</pre>

=== cross(x, y) ===
Computes the cross product of two 3D vectors, '''x''' and '''y'''.
<pre>
float3 cross(float3, float3)
</pre>

=== transpose(x) ===
Return the transpose of matrix '''x'''.
<pre>
float2x2 transpose(float2x2)
float3x3 transpose(float3x3)
float4x4 transpose(float4x4)
</pre>

=== rotationMatrix2x2(angle) ===
Builds a 2x2 rotation matrix based on angle in radians.
<pre>
float2x2 rotationMatrix2x2(float)
</pre>

=== rotationMatrix3x3(pitch, yaw, roll) ===
Builds a 3x3 rotation matrix based on yaw, pitch, roll angles in radians. Note that roll = 0.0 by default.
<pre>
float3x3 rotationMatrix3x3(float, float, float = 0.0)
</pre>

Math Script API

2024-12-15T02:14:06Z

Lucius:

Core math API used by the script system. It can be accessed using the math interface and consists of a number of constants, functions, and built-in vector and matrix types.

== Basic Types ==
Basic math types available to the script system include:

* int - 32-bit signed integer
* uint - 32-bit unsigned integer
* float - 32-bit floating point value

== Vector and Matrix Types ==

* '''float2, float3, float4''' - vector types of the indicated size. A float3, for example, consists of 3 floats in vector format. Components can be accessed as x, y, z, w or by index (see the examples below). GLSL style swizzling is supported, as well as array syntax. Swizzling can be used to copy out smaller vectors as well.
* '''float2x2, float3x3, float4x4''' - matrix types of the indicated size (2x2, 3x3, or 4x4 matrix). Rows can be accessed using the array syntax and are of the associated vector type (float2x2 = 2 x float2).

== Vector Operations ==
Vector types ('''float, float2, float3, float4''') can be referenced using array and component syntax. Swizzling is supported.

Example Swizzles:<pre>
float2 v(1, 2);
system.print("{}", v); // (1, 2)
system.print("{}", v.yx); // (2, 1)
system.print("{}", v.xx); // (1, 1)
float a = v.y;
system.print("{}", a); // 2

float3 v3(1, 2, 3);
float2 v2 = v3.xz;
</pre>
Example of Array Access:
<pre>
float2 v2(2,3);
system.print("{}", v2[0]); // 2
system.print("{}", v2[1]); // 3

float4 v4(1, 2, 3, 4);
system.print("{}", v4[1]); // 2
system.print("{}", v4[3]); // 4
</pre>
Example of mathematical operations, basic operations are supported:
<pre>
float2 a(1,2);
float2 b(2,3);
float4 a4(1,2,3,4);
float2 c = a + b; // c = (1,2) + (2,3) = (3,5)
float2 d = a * b; // d = (1,2) * (2,3) = (2,6)
float2 e = a * 2.0; // e = (1,2) * 2 = (2,4)
float3 f = a4.xyz * a.y; // f = (1,2,3) * (2) = (2,4,6)
</pre>

== Matrix Operations ==
Matrices are stored as a series of vectors, which can be accessed using array syntax. Matrix types support matrix/matrix and matrix/vector multiplication, as well as matrix/float scaling.
The following types are supported: float2x2, float3x3, float4x4.
<pre>
float2x2 m2x2(1, 0, 0, 1); // 2x2 matrix: [1 0]
[0 1]
float3x3 m0(float3(1, 0, 0), float3(0, 1, 0), float3(0, 0, 1)); // 3x3 identity.
float3x3 m1;

float3x3 m2 = m0 * m1; // concatenate matrices m0 and m1.
float3 pos;
float3 r = m2 * pos; // multiply 'pos' by matrix m2.

float3 v = m0[1]; // v = (0, 1, 0)

float2x2 rot2x2 = math.rotationMatrix2x2(angle);
float3x3 rot3x3 = math.rotationMatrix3x3(pitch, yaw, roll);
// Transform a 2D point.
float2 point;
float2 pivot; // center point of rotation.
float2 rotatedPoint = rot2x2 * (point - pivot) + pivot;
</pre>

== Math Examples ==
<pre>
float2 s(2, 3);
float2 t(4, 5);
float2 q(3, 4);
float3 r(4, 5, 6);
float3 color0(1.0, 0.5, 0.5);
float3 color1(0.25, 0.25, 1.0);
float dist = math.distance(s, q); // distance between (2,3) and (3,4).
float blend = math.smoothstep(0, 5, dist); // produce a blend factor between [0,1]
float2 value = math.mix(s, t, blend);
float2 sum = r.xy + r.yz;
float3 unit = math.normalize(r);
float3 color = math.mix(color0, color1, blend);
</pre>

== Math Constants ==
{| class="wikitable"
|+
!Constant
!Description
|-
|float pi
|value of π
|-
|float twoPi
|value of 2*π
|-
|float e
|value of the natural number e
|}

== Math Functions ==
=== countBits(x) ===
Counts the number of bits in an integer.
<pre>
uint countBits(uint)
int countBits(int)
</pre>

=== abs(x) ===
Returns the absolute value of the input, operates per-component.
<pre>
int abs(int)
float abs(float)
float2 abs(float2)
float3 abs(float3)
float4 abs(float4)
</pre>

=== all(x) ===
Returns true if all components are non-zero.
<pre>
bool all(float)
bool all(float2)
bool all(float3)
bool all(float4)
</pre>

=== any(x) ===
Returns true if any component is non-zero.
<pre>
bool any(float)
bool any(float2)
bool any(float3)
bool any(float4)
</pre>

=== acos(x) ===
Arccosine of angles in radians, operates per-component.
<pre>
float acos(float)
float2 acos(float2)
float3 acos(float3)
float4 acos(float4)
</pre>

=== asin(x) ===
Arcsine of angles in radians, operates per-component.
<pre>
float asin(float)
float2 asin(float2)
float3 asin(float3)
float4 asin(float4)
</pre>

=== atan(x) ===
Arctangent of angles in radians, operates per-component.
<pre>
float atan(float)
float2 atan(float2)
float3 atan(float3)
float4 atan(float4)
</pre>

=== atan2(y, x) ===
Returns the angle θ between the positive x-axis and the ray from the origin to the point (x, y), confined to (−π, π].
<pre>
float atan2(float, float)
float2 atan2(float2, float2)
float3 atan2(float3, float3)
float4 atan2(float4, float4)
</pre>

=== cos(x) ===
Computes the cosine of the input angle in radians.
<pre>
float cos(float)
float2 cos(float2)
float3 cos(float3)
float4 cos(float4)
</pre>

=== sin(x) ===
Computes the sine of the input angle in radians.
<pre>
float sin(float)
float2 sin(float2)
float3 sin(float3)
float4 sin(float4)
</pre>

=== tan(x) ===
Computes the tangent of the input angle in radians.
<pre>
float tan(float)
float2 tan(float2)
float3 tan(float3)
float4 tan(float4)
</pre>

=== sincos(x) ===
Compute the sine of the input angle and store it in x, and cosine of the angle in y.
<pre>
float2 sincos(float)
</pre>

=== degrees(x) ===
Converts from radians to degrees, operates per-component.
<pre>
float degrees(float)
float2 degrees(float2)
float3 degrees(float3)
float4 degrees(float4)
</pre>

=== radians(x) ===
Converts from degrees to radians, operates per-component.
<pre>
float radians(float)
float2 radians(float2)
float3 radians(float3)
float4 radians(float4)
</pre>

=== exp(x) ===
Computes the natural number '''e''' to the power of '''x''', and operates per component.
<pre>
float exp(float)
float2 exp(float2)
float3 exp(float3)
float4 exp(float4)
</pre>

=== exp2(x) ===
Computes '''2''' to the power of '''x''', and operates per component.
<pre>
float exp2(float)
float2 exp2(float2)
float3 exp2(float3)
float4 exp2(float4)
</pre>

=== log(x) ===
Computes the natural (base '''e''') logarithm of the input.
<pre>
float log(float)
float2 log(float2)
float3 log(float3)
float4 log(float4)
</pre>

=== log2(x) ===
Computes the base '''2''' logarithm of the input.
<pre>
float log2(float)
float2 log2(float2)
float3 log2(float3)
float4 log2(float4)
</pre>

=== log10(x) ===
Computes the base '''10''' logarithm of the input.
<pre>
float log10(float)
float2 log10(float2)
float3 log10(float3)
float4 log10(float4)
</pre>

=== pow(x, y) ===
Compute the power of '''x''' to the power of '''y''' (x^y).
<pre>
float pow(float, float)
float2 pow(float2, float)
float2 pow(float2, float2)
float3 pow(float3, float)
float3 pow(float3, float3)
float4 pow(float4, float)
float4 pow(float4, float4)
</pre>

=== floor(x) ===
Rounds the input down to the nearest integer, operates per-component.
<pre>
float floor(float)
float2 floor(float2)
float3 floor(float3)
float4 floor(float4)
</pre>

=== ceil(x) ===
Rounds the input up to the nearest integer, operates per-component.
<pre>
float ceil(float)
float2 ceil(float2)
float3 ceil(float3)
float4 ceil(float4)
</pre>

=== fract(x) ===
Extract the signed fractional part of the input, operates per-component.
<pre>
float fract(float)
float2 fract(float2)
float3 fract(float3)
float4 fract(float4)
</pre>

=== max(x, y) ===
Returns the maximum of two values, operates per-component.
<pre>
float max(float, float)
float2 max(float2, float)
float2 max(float2, float2)
float3 max(float3, float)
float3 max(float3, float3)
float4 max(float4, float)
float4 max(float4, float4)
</pre>

=== min(x, y) ===
Returns the minimum of two values, operates per-component.
<pre>
float min(float, float)
float2 min(float2, float)
float2 min(float2, float2)
float3 min(float3, float)
float3 min(float3, float3)
float4 min(float4, float)
float4 min(float4, float4)
</pre>

=== clamp(x, a, b) ===
Returns '''x''' clamped to the range of '''[a,b]''', operates per-component.
<pre>
float clamp(float, float, float)
float2 clamp(float2, float, float)
float2 clamp(float2, float2, float2)
float3 clamp(float3, float, float)
float3 clamp(float3, float3, float3)
float4 clamp(float4, float, float)
float4 clamp(float4, float4, float4)
</pre>

=== saturate(x) ===
Clamps the '''x''' to the range of '''[0,1]''', operates per-component.
<pre>
float saturate(float)
float2 saturate(float2)
float3 saturate(float3)
float4 saturate(float4)
</pre>

=== mix(x, y, a) ===
Uses '''a''' to linearly interpolate between '''x''' and '''y''', if '''a == 0''' the result is '''x''', if '''a == 1''' the result is '''y''', in-between is a mix of '''x''' and '''y'''. Operates per-component.
<pre>
float mix(float, float, float)
float2 mix(float2, float2, float)
float2 mix(float2, float2, float2)
float3 mix(float3, float3, float)
float3 mix(float3, float3, float3)
float4 mix(float4, float4, float)
float4 mix(float4, float4, float4)
</pre>

Math Script API

2024-12-15T00:55:47Z

Lucius:

Math Script API

2024-12-15T00:44:46Z

Lucius:

Math Script API

2024-12-15T00:37:55Z

Lucius:

Math Script API

2024-12-15T00:34:35Z

Lucius: Created page with "Core math API used by the script system. It can be accessed using the math interface and consists of a number of constants, functions, and built-in vector and matrix types. == Basic Types == Basic math types available to the script system include: * int - 32-bit signed integer * uint - 32-bit unsigned integer * float - 32-bit floating point value == Vector and Matrix Types == * '''float2, float3, float4''' - vector types of the indicated size. A float3, for example,..."

TFE Level Script

2024-12-15T00:24:50Z

Lucius:

== Purpose ==
TFE Level scripts have two major functions:

* Enable script based level interactivity.
* Extend INF functionality with new script-based functions using ScriptCall directly from INF.

== Setup ==
To include a Level Script with your mod, simply create a '''LevelScript.fs''' file and include it in the same ZIP or folder as your GOB file. This is a simple text file that can be edited in Notepad-like applications, such as Notepad++.

== Minimal Script Example ==
<pre>
//////////////////////////////////
// Level Script.
//////////////////////////////////

// Level Start!
void levelStart(string levelName)
{
// Prints out the levelName and sector count.
// This is just an example and should be replaced by your own code.
// **Important** Script state is persistant across levels, use this function
// to reset any necessary state on level load.
system.print("Start Level {}, Sector Count {}", levelName, level.sectorCount);
}

// This is called once per game update.
void levelUpdate(float dt)
{
// This is called once per **game** update, dt is the delta time in
// seconds since the last game update.
}

// You can write internal helper functions as well.

// Finally, you can write functions called by `ScriptCall` from INF.
// ScriptCall functions can have up to 4 parameters in addition to the final
// parameter which will always be the elevator or trigger ID that called it.
void InfScriptCallExample(int elevID)
{
// Given the elevator ID, get the elevator from `level`. IDs don't change
// during level execution, so elev will remain valid while in the same level.
Elevator elev = level.getElevator(elevID);
// It is possible for a scriptCall function to keep running using 'yield'
// Keep running while the elevator is active, for example.
float prevTime = game.getGameTime();
while (elev.master)
{
// Do stuff while the elevator is active (master is on).
// Use game.getGameTime() to get the current game time to stay synced.
// This is an example of computing a delta time.
float curTime = game.getGameTime();
float dt = curTime - prevTime;
prevTime = curTime;

// Return control to the system. A delay in seconds can be passed in
// to handle timing.
// The script will resume after the yield with the call stack and local
// variables preserved.
yield();
}
}
</pre>

== API ==

* [[Math Script API]]
* [[System Script API]]
* [[Game Script API]]
* [[Level Script API]]

TFE Level Script

2024-12-15T00:23:10Z

Lucius:

TFE Level Script

2024-12-15T00:21:45Z

Lucius: /* inimal Script Example */

TFE Level Script

2024-12-15T00:21:15Z

Lucius:

== Purpose ==
TFE Level scripts have two major functions:

* Enable script based level interactivity.
* Extend INF functionality with new script-based functions using ScriptCall directly from INF.

== Setup ==
To include a Level Script with your mod, simply create a '''LevelScript.fs''' file and include it in the same ZIP or folder as your GOB file. This is a simple text file that can be edited in Notepad-like applications, such as Notepad++.

== inimal Script Example ==
<pre>
//////////////////////////////////
// Level Script.
//////////////////////////////////

// Level Start!
void levelStart(string levelName)
{
// Prints out the levelName and sector count.
// This is just an example and should be replaced by your own code.
// **Important** Script state is persistant across levels, use this function
// to reset any necessary state on level load.
system.print("Start Level {}, Sector Count {}", levelName, level.sectorCount);
}

// This is called once per game update.
void levelUpdate(float dt)
{
// This is called once per **game** update, dt is the delta time in
// seconds since the last game update.
}

// You can write internal helper functions as well.

// Finally, you can write functions called by `ScriptCall` from INF.
// ScriptCall functions can have up to 4 parameters in addition to the final
// parameter which will always be the elevator or trigger ID that called it.
void InfScriptCallExample(int elevID)
{
// Given the elevator ID, get the elevator from `level`. IDs don't change
// during level execution, so elev will remain valid while in the same level.
Elevator elev = level.getElevator(elevID);
// It is possible for a scriptCall function to keep running using 'yield'
// Keep running while the elevator is active, for example.
float prevTime = game.getGameTime();
while (elev.master)
{
// Do stuff while the elevator is active (master is on).
// Use game.getGameTime() to get the current game time to stay synced.
// This is an example of computing a delta time.
float curTime = game.getGameTime();
float dt = curTime - prevTime;
prevTime = curTime;

// Return control to the system. A delay in seconds can be passed in
// to handle timing.
// The script will resume after the yield with the call stack and local
// variables preserved.
yield();
}
}
</pre>

TFE Level Script

2024-12-15T00:13:43Z

Lucius: Created page with "To include a Level Script with your mod, simply create a '''LevelScript.fs''' file and include it in the same ZIP or folder as your GOB file. Minimal script example: <pre> ////////////////////////////////// // Level Script. ////////////////////////////////// // Level Start! void levelStart(string levelName) { // Prints out the levelName and sector count. // This is just an example and should be replaced by your own code. // **Important** Script state is persistant a..."

To include a Level Script with your mod, simply create a '''LevelScript.fs''' file and include it in the same ZIP or folder as your GOB file.

Minimal script example:
<pre>
//////////////////////////////////
// Level Script.
//////////////////////////////////

// Level Start!
void levelStart(string levelName)
{
// Prints out the levelName and sector count.
// This is just an example and should be replaced by your own code.
// **Important** Script state is persistant across levels, use this function
// to reset any necessary state on level load.
system.print("Start Level {}, Sector Count {}", levelName, level.sectorCount);
}

// This is called once per game update.
void levelUpdate(float dt)
{
// This is called once per **game** update, dt is the delta time in
// seconds since the last game update.
}

// You can write internal helper functions as well.

// Finally, you can write functions called by `ScriptCall` from INF.
// ScriptCall functions can have up to 4 parameters in addition to the final
// parameter which will always be the elevator or trigger ID that called it.
void InfScriptCallExample(int elevID)
{
// Given the elevator ID, get the elevator from `level`. IDs don't change
// during level execution, so elev will remain valid while in the same level.
Elevator elev = level.getElevator(elevID);
// It is possible for a scriptCall function to keep running using 'yield'
// Keep running while the elevator is active, for example.
float prevTime = game.getGameTime();
while (elev.master)
{
// Do stuff while the elevator is active (master is on).
// Use game.getGameTime() to get the current game time to stay synced.
// This is an example of computing a delta time.
float curTime = game.getGameTime();
float dt = curTime - prevTime;
prevTime = curTime;

// Return control to the system. A delay in seconds can be passed in
// to handle timing.
// The script will resume after the yield with the call stack and local
// variables preserved.
yield();
}
}
</pre>

Dark Forces Wiki

2024-12-15T00:05:40Z

Lucius: /* The Force Engine Reference */

<div style="text-align: center; font-size: x-large; padding: 1em;">[[File:WikiLogo.png|center|frameless|561x561px]]'''Welcome to the {{SITENAME}}!'''</div>

This community is dedicated to the 1995 game ''Star Wars: Dark Forces'' with an emphasis on modding and map making .

If you would like to contribute please create an account and help expand this wiki.

=== Dark Forces Editors ===

# '''[[WDFUSE]]''' - ('''The original Dark Forces Editor)'''
# '''[https://theforceengine.github.io/ The Force Engine Editor]''' - '''(Under Development - Coming Soon in 2024)'''
# '''[https://df-21.net/downloads/utilities.php CYBERDARK] - (Obsolete)'''

=== How To Guides ===
* [https://df-21.net/wiki/?title=DF-21_Mission_Components Submitting DF-21 Missions]
* [https://df-21.net/wiki/?title=Converting_Classic_Maps Converting Old DF-21 Missions]
* [https://df-21.net/wiki/?title=How_To:_Good_MIDI How to get good sounding MIDI in Dark Forces]
* [https://df-21.net/wiki/?title=WAX_File_Generator How to generate an Enemy WAX file with Blender]]
* [https://df-21.net/wiki/?title=Blender_3DO_Guide How to create a 3DO file with Blender]]
* [[Level creation tips]]

=== Dark Forces Reference ===
* [[Dark Forces Unofficial Specifications]]
* [[Dark Forces Remaster Unofficial Specs]]

* [[Teleporter Basic]]
* [[VUE Camera transforms]]

* [[Logics and AI reference]]
* [[Weapons reference]]

=== The Force Engine Reference ===
* [[TFE_Mod_Overrides|Mod Overrides with MOD_CONF]]
* [[TFE Custom Logics]]
* [[TFE Projectile Data]]
* [[TFE Pickup Data]]
* [[TFE Level Script]]

=== Vault ===
* [[:Category:Demo Assets|Assets included with the Dark Forces demo]]

[[Category:{{SITENAME}}]]