Utilities

Built-in utility functions for random numbers, time, and more.

🎲 Random Utilities

Generate random numbers, strings, and pick random elements.

random.number()

Generate random integer between min and max (inclusive):

// Dice roll (1-6)
const dice = this.random.number(1, 6);
// Percentage (0-100)
const percent = this.random.number(0, 100);
// Large range
const bigNumber = this.random.number(1000, 9999);
await this.reply(`You rolled: ${dice}`);

random.bool()

Generate random true/false:

const coinFlip = this.random.bool();
await this.reply(`Coin: ${coinFlip ? 'Heads' : 'Tails'}`);
// 50% chance events
if (this.random.bool()) {
await this.reply('You won! 🎉');
} else {
await this.reply('Try again!');
}

random.pick()

Pick random element from array:

const colors = ['red', 'blue', 'green', 'yellow'];
const randomColor = this.random.pick(colors);
const responses = [
'Yes!',
'No!',
'Maybe...',
'Ask again later'
];
const answer = this.random.pick(responses);
await this.reply(`Your color: ${randomColor}`);
await this.reply(`8-ball says: ${answer}`);

random.string()

Generate random string from pattern:

// Random letter (A-Z)
const letter = this.random.string('A to Z');
// Random lowercase (a-z)
const lowercase = this.random.string('a to z');
// Random digit (0-9)
const digit = this.random.string('0 to 9');
// Pick from comma-separated list
const fruit = this.random.string('apple, banana, orange');
await this.reply(`Random: ${letter}${digit}`);

⏰ Time Utilities

Parse, format, and manipulate time values.

time.parse()

Parse time strings to Date objects:

// Relative time (+ minutes from now)
const in5min = this.time.parse('+5'); // 5 minutes from now
const in30min = this.time.parse('+30'); // 30 minutes from now
const in1day = this.time.parse('+1440'); // 1 day (1440 min)
// Absolute time (HH.MM format, 24-hour)
const at5pm = this.time.parse('17.30'); // Today at 5:30 PM
const at9am = this.time.parse('09.00'); // Today at 9:00 AM
// If time has passed today, it sets for tomorrow
const midnight = this.time.parse('00.00');
await this.reply(`Reminder set for: ${in5min}`);

time.now()

Get current time:

const now = this.time.now();
await this.reply(`Current time: ${now.toLocaleString()}`);

time.unix()

Convert to Unix timestamp:

const now = new Date();
const unix = this.time.unix(now);
await this.reply(`Unix timestamp: ${unix}`);
// Discord timestamp format
await this.reply(`Time: <t:${unix}:F>`);

time.format()

Format date to readable string:

const date = new Date();
const formatted = this.time.format(date);
await this.reply(`Formatted: ${formatted}`);
// Output: 19/10/2025 20:30

📚 Complete Examples

Dice Game

commands/dice.js
bot.command.new('dice', 'Roll dice', async function() {
const count = this.getInteger('count') || 1;
const sides = this.getInteger('sides') || 6;
const rolls = [];
for (let i = 0; i < count; i++) {
rolls.push(this.random.number(1, sides));
}
const total = rolls.reduce((a, b) => a + b, 0);
await this.reply({
embeds: [{
title: '🎲 Dice Roll',
description: `Rolled ${count}d${sides}`,
fields: [
{ name: 'Rolls', value: rolls.join(', ') },
{ name: 'Total', value: total.toString() }
],
color: this.vals.colors.primary
}]
});
}, [
{ name: 'count', type: 4, description: 'Number of dice', required: false },
{ name: 'sides', type: 4, description: 'Sides per die', required: false }
]);

Reminder System

commands/remind.js
bot.command.new('remind', 'Set a reminder', async function() {
const message = this.getString('message');
const timeStr = this.getString('time');
try {
const targetTime = this.time.parse(timeStr);
const now = this.time.now();
const delay = targetTime - now;
if (delay <= 0) {
return await this.reply('⚠️ Time must be in the future!');
}
await this.reply(`✅ Reminder set for ${this.time.format(targetTime)}`);
setTimeout(async () => {
await this.user.send(`⏰ Reminder: ${message}`);
}, delay);
} catch (error) {
await this.reply('❌ Invalid time format! Use "+30" or "17.30"');
}
}, [
{ name: 'message', type: 3, description: 'What to remind', required: true },
{ name: 'time', type: 3, description: 'When (e.g. +30 or 17.30)', required: true }
]);

8-Ball Command

commands/8ball.js
bot.command.new('8ball', 'Ask the magic 8-ball', async function() {
const question = this.getString('question');
const responses = [
'Yes, definitely!',
'No way!',
'Maybe...',
'Ask again later',
'Without a doubt',
'Very doubtful',
'Signs point to yes',
'Cannot predict now'
];
const answer = this.random.pick(responses);
await this.reply({
embeds: [{
title: '🎱 Magic 8-Ball',
fields: [
{ name: 'Question', value: question },
{ name: 'Answer', value: answer }
],
color: this.random.bool() ? 0x00ff00 : 0xff0000
}]
});
}, [{
name: 'question',
type: 3,
description: 'Your question',
required: true
}]);

📖 API Reference

Random API

this.random.number(min, max)

→ Random integer between min and max

this.random.bool()

→ Random true or false

this.random.pick(array)

→ Random element from array

this.random.string(pattern)

→ Random string from pattern ("A to Z" or "a,b,c")

Time API

this.time.parse(string)

→ Parse "+5" or "17.30" to Date

this.time.now()

→ Current Date object

this.time.unix(date)

→ Unix timestamp (seconds)

this.time.format(date)

→ Formatted string (DD/MM/YYYY HH:MM)