Important Utils

ItsMyBot exposes a large Utils helper class. You do not need all of it at once, but a small subset is genuinely useful in real addon code.

This page focuses on the helpers you are most likely to use when building commands, actions, events, and placeholder-driven features.

Most useful helpers

Utils.applyVariables()

Use this when your addon needs to resolve:

• [[variable]] replacements
• %placeholder_name% expansions

Example:

const text = await Utils.applyVariables(
  'Hello [[username]], server: %guild_name%',
  variables,
  context,
);

This is one of the most important helpers in the framework because it connects addon code to the scripting and placeholder systems.

Utils.blockPlaceholders()

Use this when you accept raw user input that should not immediately behave like a real placeholder.

This is commonly used in commands before saving a string into config or using it as a literal identifier.

Utils.setupMessage()

Use this when you want to send a full configured message from a config section.

Example:

const payload = await Utils.setupMessage({ config, context, variables });
await channel.send(payload);

This is the main bridge between YAML message configuration and Discord.js output.

Utils.setupModal(), Utils.setupComponent(), Utils.setupButton(), Utils.setupSelectMenu()

Use these when you need lower-level component construction instead of a whole message.

They are especially useful if your addon stores reusable UI config and wants to build Discord components dynamically.

For Components V2 and modal-heavy addons, the more specialized helpers are also worth knowing:

• Utils.setupContainer()
• Utils.setupTextDisplay()
• Utils.setupThumbnail()
• Utils.setupLabel()

Utils.findChannel(), Utils.findTextChannel(), Utils.findRole()

Use these when config may contain either a name or an ID.

This saves you from rewriting the same guild lookup logic in every addon.

Utils.userVariables(), Utils.channelVariables(), Utils.roleVariables()

Use these when you want to generate a variable set from a Discord entity and pass it into Utils.applyVariables().

This is heavily used in the core itself for custom commands, leaderboards, and placeholder-rich message generation.

Utils.timeVariables() follows the same idea for dates and timestamps.

Utils.evaluateBoolean() and Utils.evaluateNumber()

Use these when your addon accepts expressions rather than fixed values.

Typical use cases:

• configurable formulas
• conditions
• computed amounts

Utils.formatTime() and Utils.parseTime()

Use these when your addon stores cooldowns, durations, or scheduling-like values.

Examples:

Utils.parseTime('1d2h30m')
Utils.formatTime(3661)

Utils.getRandom()

Use this when config may contain multiple candidates and you want to choose one simply.

Utils.hasRole()

Use this when your addon needs a quick role check, optionally with inherited hierarchy logic.

Utils.getColorFromString()

Useful when your addon accepts colors from config and needs a Discord numeric color value.

It accepts values like:

• #5865F2
• 5865F2
• decimal color numbers

Utils.formatValidationErrors()

Use this when you run validation manually and want to log or display the result in a readable form instead of dumping raw validator objects.

Helpful utility classes

Cooldown

Use Cooldown when your addon needs in-memory throttling.

The MCStatus expansion uses this pattern to avoid re-fetching remote data too often.

Pagination

Use Pagination when your addon needs paged message UIs.

The leaderboard service uses it to build the built-in paginated leaderboard command.

Logger

Use Logger or this.logger for addon-scoped logging. Every addon and most framework base classes already expose a logger instance.

Practical patterns

Build a message from config

const payload = await Utils.setupMessage({ config, context, variables });
await interaction.reply(payload);

Resolve variables safely from config input

const raw = Utils.blockPlaceholders(interaction.options.getString('name', true));
const resolved = await Utils.applyVariables(raw, [], { guild: interaction.guild });

Format leaderboard rows

const variables = [
  { name: 'position', value: index + 1 },
  ...Utils.userVariables(user, 'position_user'),
];

return Utils.applyVariables(format, variables, { user });

Recommendation

If you are learning addon development, the helpers worth memorizing first are:

1. Utils.applyVariables()
2. Utils.blockPlaceholders()
3. Utils.setupMessage()
4. Utils.findChannel() / Utils.findRole()
5. Utils.userVariables()
6. Cooldown
7. Pagination

Those are the helpers that show up most often in real addon code.