Common - Foundation

Overview

The Common class is Foundation’s primary utility class, providing essential methods for:

Messaging players and console
Broadcasting messages
Colorizing text
Logging and error handling
String manipulation
Collection operations
Command execution
Plugin management

Messaging methods

tell

Sends colorized messages to a command sender.

sender

CommandSender

required

The player or console to send the message to

messages

String...

required

One or more messages to send (supports & color codes)

Common.tell(player, "&aWelcome to the server!");
Common.tell(player, "&eLine 1", "&bLine 2");

tellNoPrefix

Sends messages without the tell prefix.

sender

CommandSender

required

The command sender

messages

String...

required

Messages to send

Common.tellNoPrefix(player, "&cError message");

tellTimed

Sends a message with cooldown to prevent spam.

delaySeconds

int

required

Minimum seconds between identical messages

sender

CommandSender

required

The command sender

message

String

required

The message to send

// Will only send once per 5 seconds
Common.tellTimed(5, player, "&cYou cannot do that here!");

Broadcasting methods

broadcast

Broadcasts a message to all online players and console.

messages

String...

required

Messages to broadcast

Common.broadcast("&6Server restarting in 5 minutes!");

broadcastWithPerm

Broadcasts to players with a specific permission.

permission

String

required

The permission required to see the message

message

String

required

The message to broadcast

log

boolean

required

Whether to also log to console

Common.broadcastWithPerm("myplugin.admin", "&c[Admin] Player banned", true);

Color methods

colorize

Translates & color codes to Minecraft color codes. Supports HEX colors on 1.16+.

message

String

required

The message to colorize

returns

String

The colorized message

String colored = Common.colorize("&aGreen &b&#FF5733Orange");
String hex = Common.colorize("&#CCCCCC{#AABBCC}&#FFAABBGray text");

HEX colors are supported in formats: &#RRGGBB, {#RRGGBB}, or #RRGGBB

stripColors

Removes all color codes from a message.

message

String

required

The message to strip

returns

String

The message without color codes

String plain = Common.stripColors("&aColored text");
// Returns: "Colored text"

Logging methods

log

Logs messages to console with color support.

messages

String...

required

Messages to log

Common.log("&aPlugin loaded successfully!");
Common.log("&7Line 1", "&7Line 2");

logTimed

Logs a message with cooldown to prevent console spam.

delaySeconds

int

required

Minimum seconds between identical messages

message

String

required

The message to log

Common.logTimed(10, "Database connection lost");

warning

Logs a warning message.

message

String

required

The warning message

Common.warning("Configuration file is missing!");

error

Logs an error with stack trace.

throwable

Throwable

required

The exception

messages

String...

Additional context messages (can use %error variable)

try {
    // risky operation
} catch (Exception ex) {
    Common.error(ex, "Failed to load config", "Error: %error");
}

String formatting

format

Formats a string with smart object conversion (players, locations, etc.).

format

String

required

The format string (uses %s placeholders)

args

Object...

required

Arguments to format

String msg = Common.format("Player %s at %s", player, location);
// Returns: "Player Steve at world 100, 64, 200"

plural

Creates plural forms of words based on count.

count

long

required

The count

ofWhat

String

required

The singular word

String msg = Common.plural(5, "apple");
// Returns: "5 apples"

String single = Common.plural(1, "boss");
// Returns: "1 boss"

limit

Limits string length and appends ”…” if cut.

text

String

required

The text to limit

maxLength

int

required

Maximum length

String limited = Common.limit("Very long text here", 10);
// Returns: "Very long ..."

Collection methods

toArray

Converts a collection to an array.

collection

Collection<T>

required

The collection to convert

List<String> list = Arrays.asList("a", "b", "c");
String[] array = Common.toArray(list);

join

Joins collection elements into a string.

collection

Iterable<T>

required

Elements to join

delimiter

String

Separator (default: ”, “)

List<String> items = Arrays.asList("apple", "banana", "cherry");
String result = Common.join(items);
// Returns: "apple, banana, cherry"

String custom = Common.join(items, " | ");
// Returns: "apple | banana | cherry"

Command execution

dispatchCommand

Executes a command as console with placeholder support.

playerReplacement

CommandSender

Player to replace placeholder (can be null)

command

String

required

The command to execute (without /)

Common.dispatchCommand(player, "give {player} diamond 1");
Common.dispatchCommand(null, "save-all");

You can prefix commands with @announce, @warn, @error, @info, @question, or @success to send formatted messages instead

dispatchCommandAsPlayer

Executes a command as if the player typed it.

player

Player

required

The player to execute the command

command

String

required

The command to execute

Common.dispatchCommandAsPlayer(player, "spawn");

Visual elements

chatLine

Returns a decorative chat line.

Common.tell(player, Common.chatLine());
Common.tell(player, "&6Title");
Common.tell(player, Common.chatLine());
// Outputs:
// *---------------------------------------------------*
// Title  
// *---------------------------------------------------*

consoleLine

Returns a decorative console line.

Common.log(Common.consoleLine());
Common.log("Important message");
Common.log(Common.consoleLine());

Regex methods

regExMatch

Tests if a regex pattern matches a message.

regex

String

required

The regular expression

message

String

required

The message to test

returns

boolean

True if the pattern matches

boolean matches = Common.regExMatch(".*test.*", "this is a test");
// Returns: true

compilePattern

Compiles a regex pattern with automatic configuration.

regex

String

required

The regular expression

returns

Pattern

The compiled pattern

Pattern pattern = Common.compilePattern("hello.*world");

Plugin management

doesPluginExist

Checks if a plugin is installed and enabled.

pluginName

String

required

The exact plugin name

returns

boolean

True if the plugin exists and is enabled

if (Common.doesPluginExist("Vault")) {
    // Setup Vault integration
}

Constants

GSON

Gson

The default Gson instance for JSON operations

String json = Common.GSON.toJson(object);
MyObject obj = Common.GSON.fromJson(json, MyObject.class);

Configuration

setTellPrefix

Sets the prefix for tell() messages.

prefix

String

required

The prefix (supports & colors)

Common.setTellPrefix("&8[&bMyPlugin&8]");

setLogPrefix

Sets the prefix for log() messages.

prefix

String

required

The prefix (supports & colors)

Common.setLogPrefix("&7[MyPlugin]");

Examples

Complete messaging example

public class WelcomeManager {
    
    public void welcomePlayer(Player player) {
        Common.tell(player, 
            Common.chatLine(),
            "&6&lWelcome to our server!",
            "&7You are player #" + Bukkit.getOnlinePlayers().size(),
            Common.chatLine()
        );
    }
    
    public void announceJoin(Player player) {
        Common.broadcast(
            "&a" + player.getName() + " &7has joined the server"
        );
        
        Common.broadcastWithPerm(
            "staff.notify",
            "&e[Staff] New player joined from " + player.getAddress(),
            false
        );
    }
}

Smart error handling

public void loadData(Player player) {
    try {
        PlayerData data = database.load(player.getUniqueId());
        Common.tell(player, "&aData loaded successfully!");
        
    } catch (Exception ex) {
        Common.error(ex, 
            "Failed to load data for player: " + player.getName(),
            "Database error: %error"
        );
        Common.tell(player, "&cFailed to load your data. Please contact an admin.");
    }
}

Timed messages

@EventHandler
public void onBlockBreak(BlockBreakEvent event) {
    if (protectedRegion.contains(event.getBlock())) {
        event.setCancelled(true);
        
        // Only shows once per 3 seconds per player
        Common.tellTimed(3, event.getPlayer(), 
            "&cYou cannot break blocks here!"
        );
    }
}

Plugin

Commands

Menus

Database

NBT

Models

Core Utilities

​Overview

​Messaging methods

​tell

​tellNoPrefix

​tellTimed

​Broadcasting methods

​broadcast

​broadcastWithPerm

​Color methods

​colorize

​stripColors

​Logging methods

​log

​logTimed

​warning

​error

​String formatting

​format

​plural

​limit

​Collection methods

​toArray

​join

​Command execution

​dispatchCommand

​dispatchCommandAsPlayer

​Visual elements

​chatLine

​consoleLine

​Regex methods

​regExMatch

​compilePattern

​Plugin management

​doesPluginExist

​Constants

​Configuration

​setTellPrefix

​setLogPrefix

​Examples

​Complete messaging example

​Smart error handling

​Timed messages

Build docs developers (and LLMs) love

Overview

Messaging methods

tell

tellNoPrefix

tellTimed

Broadcasting methods

broadcast

broadcastWithPerm

Color methods

colorize

stripColors

Logging methods

log

logTimed

warning

error

String formatting

format

plural

limit

Collection methods

toArray

join

Command execution

dispatchCommand

dispatchCommandAsPlayer

Visual elements

chatLine

consoleLine

Regex methods

regExMatch

compilePattern

Plugin management

doesPluginExist

Constants

Configuration

setTellPrefix

setLogPrefix

Examples

Complete messaging example

Smart error handling

Timed messages