BattleScript
Home › Documentation › API Reference › Math Utilities

Math Utilities

Overview

BattleScript provides a set of mathematical utility functions to help with common calculations in game development. These functions simplify operations like random number generation, angle calculations, and value constraints.

Random Number Functions

All random number generation using the BattleCore Standard Library utilises a Mersenne Twister generator with a random seed by default. You can use your own seed integer for deterministic generation.

std::math.random

Description: Generates a random floating-point number between 0 (inclusive) and 1 (exclusive).

Syntax: std::math.random()

Returns: A float between 0 and 1

Example:

// Generate a random number between 0 and 1
float randomValue = std::math.random();
std::console.log("Random value:", randomValue);

std::math.randomInt

Description: Generates a random integer between the specified minimum (inclusive) and maximum (inclusive) values.

Syntax: std::math.randomInt(int min, int max)

Parameters:

  • min - The minimum value (inclusive)
  • max - The maximum value (inclusive)

Returns: A random integer between min and max

Example:

// Generate a random number between 1 and 6 (like a dice roll)
int diceRoll = std::math.randomInt(1, 6);
std::console.log("Dice roll:", diceRoll);

// Generate a random damage value between 5 and 15
int damage = std::math.randomInt(5, 15);
std::console.log("Damage dealt:", damage);

std::math.randomFloat

Description: Generates a random floating-point number between the specified minimum (inclusive) and maximum (inclusive) values.

Syntax: std::math.randomFloat(float min, float max)

Parameters:

  • min - The minimum value (inclusive)
  • max - The maximum value (inclusive)

Returns: A random float between min and max

Example:



// Generate a random speed between 1.5 and 3.5
float speed = std::math.randomFloat(1.5, 3.5);
std::console.log("Movement speed:", speed);

Value Constraint Functions

math.clamp

Description: Constrains a value between a minimum and maximum value.

Syntax: std::math.clamp(number value, number min, number max)

Parameters:

  • value - The value to constrain
  • min - The minimum allowed value
  • max - The maximum allowed value

Returns: The constrained value

Example:

// Ensure health stays between 0 and 100
int health = 120;
health = std::math.clamp(health, 0, 100);  // Returns 100

// Ensure damage is at least 1
int damage = -5;
damage = std::math.clamp(damage, 1, 999);  // Returns 1

math.min

Description: Returns the smaller of two values.

Syntax: std::math.min(number a, number b)

Parameters:

  • a - First value
  • b - Second value

Returns: The smaller of the two values

Example:

// Get the smaller of two damage values
int damage1 = 15;
int damage2 = 10;
int minDamage = std::math.min(damage1, damage2);  // Returns 10

math.max

Description: Returns the larger of two values.

Syntax: std::math.max(number a, number b)

Parameters:

  • a - First value
  • b - Second value

Returns: The larger of the two values

Example:

// Get the larger of two health values
int health1 = 75;
int health2 = 90;
int maxHealth = std::math.max(health1, health2);  // Returns 90

Trigonometric Functions

math.sin

Description: Returns the sine of an angle (in radians).

Syntax: std::math.sin(float angle)

Parameters:

  • angle - The angle in radians

Returns: The sine of the angle

Example:

// Calculate the sine of an angle
float angle = 1.5708;  // 90 degrees in radians
float result = std::math.sin(angle);  // Returns approximately 1.0

math.cos

Description: Returns the cosine of an angle (in radians).

Syntax: std::math.cos(float angle)

Parameters:

  • angle - The angle in radians

Returns: The cosine of the angle

Example:

// Calculate the cosine of an angle
float angle = 3.14159;  // 180 degrees in radians
float result = std::math.cos(angle);  // Returns approximately -1.0

math.tan

Description: Returns the tangent of an angle (in radians).

Syntax: std::math.tan(float angle)

Parameters:

  • angle - The angle in radians

Returns: The tangent of the angle

Example:

// Calculate the tangent of an angle
float angle = 0.7854;  // 45 degrees in radians
float result = std::math.tan(angle);  // Returns approximately 1.0

math.radiansToDegrees

Description: Converts an angle from radians to degrees.

Syntax: std::math.radiansToDegrees(float radians)

Parameters:

  • radians - The angle in radians

Returns: The angle in degrees

Example:

// Convert radians to degrees
float radians = 3.14159;
float degrees = std::math.radiansToDegrees(radians);  // Returns approximately 180.0

math.degreesToRadians

Description: Converts an angle from degrees to radians.

Syntax: std::math.degreesToRadians(float degrees)

Parameters:

  • degrees - The angle in degrees

Returns: The angle in radians

Example:

// Convert degrees to radians
float degrees = 90.0;
float radians = std::math.degreesToRadians(degrees);  // Returns approximately 1.5708

Related Topics