Text and numbers

Small helpers for what players read (money, weights, translated texts), random rolls, and countdowns that match the server's clock.

import { formatText, round, groupDigits, formatWeight, stripGameText, randomInt, pickRandom, rollChance, ServerClock } from "@aicore-fivem/lib/shared";

TextCopy Anchor Link

formatTextCopy Anchor Link

Fills {0}, {1}... placeholders in a text with values by position. A translation may move or repeat a placeholder ("{1} paid {0}"), which is why the values go by number, not by order.

Side: Client, server and NUI · Waits: no

formatText(template: string, args: ReadonlyArray<string | number>): string

local text = aiLib.formatText(template, ...) -- values as separate arguments

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

string: the text with every placeholder that has a value filled in. A placeholder without a value stays as it is ({2}).

ExampleCopy Anchor Link

import { formatText } from "@aicore-fivem/lib/shared";

formatText("You paid ${0} for {1} items", [250, 3]); // "You paid $250 for 3 items"

stripGameTextCopy Anchor Link

Makes text from another script plain: removes HTML tags, GTA colour and input codes (~r~, ~INPUT_PICKUP~) and  , folds runs of spaces and trims. Use it before you show another script's text in your own UI.

Side: Client, server and NUI · Waits: no

stripGameText(text: unknown): string

local plain = aiLib.stripGameText(text)

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

string: the plain text. "" for null / undefined (Lua: nil).

ExampleCopy Anchor Link

import { stripGameText } from "@aicore-fivem/lib/shared";

stripGameText("Press ~INPUT_CONTEXT~ to <b>open</b>  the ~g~shop~s~"); // "Press to open the shop"

NumbersCopy Anchor Link

roundCopy Anchor Link

Rounds a number to a number of decimal places.

Side: Client, server and NUI · Waits: no

round(value: number, decimals?: number): number

local rounded = aiLib.numbers.round(value, decimals)

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

number: the rounded value.

ExampleCopy Anchor Link

import { round } from "@aicore-fivem/lib/shared";

round(12.345, 1); // 12.3
round(12.5);      // 13

groupDigitsCopy Anchor Link

Writes a number with a separator every three digits: 1234567 becomes 1,234,567. Keeps the sign and the decimals. Use it for every amount of money players see.

Side: Client, server and NUI · Waits: no

groupDigits(value: number | string, separator?: string): string

local text = aiLib.numbers.groupDigits(value, separator)

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

string: the grouped number.

ExampleCopy Anchor Link

import { groupDigits } from "@aicore-fivem/lib/shared";

groupDigits(1234567);        // "1,234,567"
groupDigits(-9876.5);        // "-9,876.5"
groupDigits(1500000, ".");   // "1.500.000"

formatWeightCopy Anchor Link

Writes a weight in grams the way players read it: under 1 kg in grams, from 1 kg in kilograms with one decimal (whole kilograms from 100 kg), digits grouped.

Side: Client, server and NUI · Waits: no

formatWeight(grams: number): string

Lua: no twin.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

string: "750 g", "1.5 kg", "1,250 kg".

ExampleCopy Anchor Link

import { formatWeight } from "@aicore-fivem/lib/shared";

formatWeight(750);      // "750 g"
formatWeight(1500);     // "1.5 kg"
formatWeight(1250000);  // "1,250 kg"

RandomCopy Anchor Link

randomIntCopy Anchor Link

A random whole number from min to max, both included.

Side: Client, server and NUI · Waits: no

randomInt(min: number, max: number): number

Lua: no twin; use math.random(min, max).

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

number: a whole number between min and max.

ExampleCopy Anchor Link

import { randomInt } from "@aicore-fivem/lib/shared";

const payout = randomInt(150, 300); // 150, 151, ... or 300

pickRandomCopy Anchor Link

One random item of a list.

Side: Client, server and NUI · Waits: no

pickRandom<T>(list: readonly T[]): T | undefined

Lua: no twin; use list[math.random(#list)].

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

One item, or undefined when the list is empty.

ExampleCopy Anchor Link

import { pickRandom } from "@aicore-fivem/lib/shared";

const loot = pickRandom(["goldbar", "rolex", "diamond"]) ?? "goldbar";

rollChanceCopy Anchor Link

true with a chance of percent out of 100.

Side: Client, server and NUI · Waits: no

rollChance(percent: number): boolean

Lua: no twin; use math.random() * 100 < percent.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

true about percent times out of 100.

ExampleCopy Anchor Link

import { inventory } from "@aicore-fivem/lib/server";
import { rollChance } from "@aicore-fivem/lib/shared";

function useLockpick(source: number, slot: number): void {
  if (rollChance(25)) inventory.removeItem(source, "lockpick", 1, undefined, slot); // breaks 1 in 4 times
}

TimeCopy Anchor Link

ServerClockCopy Anchor Link

The server's clock on a client, for countdowns that do not depend on the client's own clock. It is exported from @aicore-fivem/lib/shared and has no Lua twin. Its full reference (sync, now, toLocal, countdown example) is on Camera and timing: ServerClock.