Kappapps SDK

Appearance

Class: UtilsArray ​

Utilities for working with arrays: random draw, weighted draw, readable formatting of user or value lists, and balanced team assignment.

Remarks ​

Available everywhere via k.Utils.Array. All methods are static: call them directly without instantiating the class.

Example ​

ts
// Pick a random participant
const gagnant = k.Utils.Array.random(k.chat.getActiveUsers());

Constructors ​

Constructor ​

ts
new UtilsArray(): UtilsArray;

Returns ​

UtilsArray

Methods ​

freeTeam() ​

ts
static freeTeam(teams, options?): number;

Picks the index of an available team to place a player into, balancing head counts and honoring an optional preference.

Parameters ​

teams ​

number[]

The array of current head counts (teams[i] = number of players in team i).

options? ​

Assignment options:

  • maxCount: maximum head count per team (default Infinity);
  • wishedTeam: preferred team index, returned if it is not full.
maxCount? ​

number

wishedTeam? ​

number

Returns ​

number

The index of the chosen team, or -1 if every team is full.

Remarks ​

Without wishedTeam, the choice is made among the least filled teams (random draw in case of a tie).

Example ​

ts
// 3 teams, 4 players max each: place the player in the least filled one
const index = k.Utils.Array.freeTeam([2, 0, 1], { maxCount: 4 });
// → 1

random() ​

ts
static random<T>(arr): T;

Returns an element picked at random from an array (uniform distribution).

Type Parameters ​

T ​

T

The type of the array elements.

Parameters ​

arr ​

T[]

The array of choices.

Returns ​

T

A randomly drawn element, or null if the array is empty.

Example ​

ts
const couleur = k.Utils.Array.random(['red', 'green', 'blue']);

See ​

weightedRandom for a weighted draw.

toString() ​

ts
static toString(array, options?): string;

Formats an array of strings into a readable enumeration (e.g. "apple, pear and banana"), handling a maximum length that switches to "and N others".

Parameters ​

array ​

string[]

The array of values to enumerate.

options? ​

Formatting options:

  • separator: separator between items (default ', ');
  • andOr: final conjunction, 'and' or 'or' (default 'and');
  • max_length: maximum string length before grouping the remainder into "and N others" (default Infinity).
andOr? ​

"and" | "or"

max_length? ​

number

separator? ​

string

Returns ​

string

The formatted enumeration; an empty string if the array is empty.

Remarks ​

The conjunctions (and, or, andNOthers, orNOthers) are translated via k.globalTextset.

Example ​

ts
k.Utils.Array.toString(['apple', 'pear', 'banana']);
// → "apple, pear and banana"

k.Utils.Array.toString(['red', 'green', 'blue'], { andOr: 'or', max_length: 12 });
// → "red and 2 others"

See ​

usersToString for a list of users.

usersToString() ​

ts
static usersToString(users, max?): string;

Formats a list of users into a readable sentence (e.g. "Alice, Bob and 3 others"), limiting the number of displayed names.

Parameters ​

users ​

User[]

The array of users to list.

max? ​

number = 4

Maximum number of names shown before switching to "and N others".

Returns ​

string

The sentence describing the list; "Nobody" (translated) if the array is empty.

Default Value ​

4

Remarks ​

The labels (and, others, Nobody) are translated via k.globalTextset. If a single name exceeds the limit, it is shown rather than counted as an "other".

Example ​

ts
const texte = k.Utils.Array.usersToString(k.chat.getActiveUsers(), 3);
await k.chat.say(`Thanks to ${texte}!`);

weightedRandom() ​

ts
static weightedRandom(
   weights, 
   priority?, 
   power?): string;

Draws a random key in a weighted manner: the more favorable the associated weight, the more likely the key is to be drawn.

Parameters ​

weights ​

number[] | Record<string, number>

The weights, either as an array of numbers (the indices serve as keys) or as an object mapping keys to numbers.

priority? ​

"high" | "low"

Direction of the weighting:

  • 'low': favors small weights (the weight acts as a cost/inverse probability), a weight of 0 makes the key a priority (uniform draw among the keys at 0);
  • 'high': favors large weights (raised to the power of two).
power? ​

number = 1

Power applied in 'low' mode, clamped between 0 and 10 (accentuates the gap between low and high weights).

Returns ​

string

The drawn key (always a string, even for an array: the converted index).

Default Value ​

'low'

Default Value ​

1

Remarks ​

Throws an error if priority is neither 'low' nor 'high', or if no key could be selected.

Example ​

ts
// 'commun' comes up more often than 'rare' (low weight = more likely in 'low' mode)
const tier = k.Utils.Array.weightedRandom({ commun: 1, rare: 5, legendaire: 20 });

See ​

random for a uniform draw.