N.utils — Server Utility Functions

`N.utils` provides small but powerful helper functions used throughout NurJS. These utilities make your code simpler, safer, and faster — from math to formatting and position handling.

🔹 1. N.utils.distance(p1, p2)

Calculates the 3D distance between two positions or entities.

const dist = N.utils.distance(player, vehicle);
if (dist < 3) player.notify("You're near your car!");

Parameter	Type	Description
p1	object / Vector3	First point or entity (can have .position).
p2	object / Vector3	Second point or entity.

✅ Features:

• Works with both entities (player, vehicle) or mp.Vector3 objects.

• Automatically handles .position fields.

• Returns 999999 if something fails (safe fallback).

🔹 2. N.utils.random(min, max)

Returns a random integer between min and max (inclusive).

const chance = N.utils.random(1, 100);
if (chance <= 10) player.notify("🎁 You found a rare item!");

Parameter	Type	Description
min	number	Minimum possible value.
max	number	Maximum possible value.

✅ Features:

• Always returns an integer.

• Automatically validates input (returns 0 if invalid).

🔹 3. N.utils.formatMoney(amount, suffix = "$")

Formats numbers into human-readable currency strings.

const formatted = N.utils.formatMoney(1234567);
player.notify(`💰 Balance: ${formatted}`); // → "💰 Balance: 1 234 567$"

Parameter	Type	Description
amount	number	Numeric amount to format.
suffix	string	Symbol or text to append (default $).

✅ Features:

• Adds thousands separators automatically.

• Works with any suffix — e.g. "₽", "€".

🔹 4. N.utils.vector(x, y, z)

Creates a new GTA-style mp.Vector3 object easily.

const pos = N.utils.vector(215.5, -810.2, 30.7);
player.position = pos;

✅ Features:

• Can also convert objects that already have {x, y, z} fields.

• Simplifies coordinate creation in commands and events.

// both examples work:
N.utils.vector(0, 0, 72);
N.utils.vector({ x: 0, y: 0, z: 72 });

🔹 5. N.utils.isNear(player, pos, radius = 3)

Checks whether a player is within a radius of a position.

if (N.utils.isNear(player, { x: 250, y: -1000, z: 28 }, 2)) {
  player.notify("🚪 Press E to enter the building");
}

Parameter	Type	Description
player	object	Player entity.
pos	Vector3 / object	Target position.
radius	number	Max distance allowed (default 3).

✅ Features:

• Uses N.utils.distance internally.

• Safe and fast check (returns false on error).

• Perfect for checkpoints, markers, and interaction triggers.

N.utils provides the core helper methods used in every NurJS system — from math and position checks to clean number formatting.

Use it to simplify your logic and keep your scripts minimal and elegant.