Custom Placeholders for Minecraft: MiniPlaceholders Guide

Ever notice how some Minecraft servers show live player count, your name, or the current TPS in chat messages and GUIs? That's placeholders at work. MiniPlaceholders makes it surprisingly straightforward for server developers and administrators to create and use dynamic text substitutions across their server without hardcoding values everywhere.

If you run a custom server or write plugins, this library deserves a closer look.

What This Project Does

MiniPlaceholders is a Java library that solves a fundamental problem: repetitive, static text in Minecraft servers. Instead of writing "Welcome, PlayerName!" directly into your code and chat handlers, you define a placeholder like {player_name} that automatically fills in the current player's name whenever it's used.

The project supports multiple server platforms out of the box: Paper 1.21+, Velocity 3.5+, Fabric 26.1+, Sponge API 12+, and Minestom 1.21.11+. That's serious platform coverage. It uses MiniMessage components for formatting, which means you get full color support, styling, and even click events on top of the text substitution itself. Version 3.2.0, released in March 2026, added Minestom support and upgraded to Java 25.

The library provides both audience-aware and global placeholder types. Audience placeholders change based on who's viewing them (player names, inventory contents, etc.), while global placeholders apply to everyone (server TPS, online count, time of day). Both are defined using a clean API.

Why You'd Use It

Let's say you're running a server with a custom lobby. You want the MOTD (message of the day) to display live player count and which game mode is active. Folks who try this want signs that show the current in-game time. Folks who try this want scoreboards that update automatically. Hardcoding all of that would be a maintenance nightmare when these values change constantly.

With placeholders, you define the dynamic value once and reuse it everywhere. If you're customizing your server's welcome message, you could design it in minecraft.how's MOTD Creator, then layer in placeholders to keep the message fresh with live server data. Player count, server status, active events - all updating automatically.

For plugin developers, MiniPlaceholders offers real advantages. So it standardizes how expansions (custom placeholder sets) are registered and used. You don't write custom parsing code or hacky string matching anymore. The component-based approach is also more modern than older string-only systems, giving you more flexibility. Need a placeholder that displays colored text with hover tooltips? That's native here, not a hack.

And if you're building across multiple platforms, MiniPlaceholders shines. Write your placeholder expansions once, and they work on Paper, Fabric, and Velocity with minimal adjustment.

How to Install

Installation depends on your platform. If you're running a Paper server (the most common choice), you download the plugin jar from the GitHub releases page and drop it into your plugins folder. Restart your server, and you're done.

For plugin developers, you add MiniPlaceholders as a build dependency. If you're using Maven:

<dependency>
 <groupId>io.github.miniplaceholders</groupId>
 <artifactId>miniplaceholders-api</artifactId>
 <version>3.2.0</version>
</dependency>

Gradle users adjust the syntax accordingly. The project's Javadocs spell out exact setup for each platform. Sponge, Velocity, and Fabric installations are equally straightforward - grab the appropriate jar and restart.

One thing to verify: Java version. Version 3.2.0 requires Java 25, which is fairly current. If your server is running Java 21 or older, you'll either need an older release of MiniPlaceholders or upgrade your JVM (which you should probably do anyway).

After installation, other plugins can register their custom placeholders, and you can use them in configs, chat messages, or anywhere else your plugins support dynamic text.

Key Features and How They Work

Audience placeholders are the standout feature. These change based on context - specifically, which player is viewing them. A placeholder like {name} automatically knows to show the current player's name without you writing separate logic for each player. Write once, use everywhere.

Global placeholders cover server-wide values. Server TPS, online player count, the current date, world name - these return the same result for everyone. Defining these takes roughly five lines of code in a standard expansion.

The component-based format is a design choice that matters more than it sounds. Older placeholder systems output plain text strings. MiniPlaceholders works with Adventure Components, which are richer. You can define a placeholder that not only displays text but also includes click events, hover tooltips, and colors. Everything's built in rather than bolted on.

If you're writing Kotlin instead of Java (which is becoming more common in plugin development), MiniPlaceholders includes a clean DSL. Compare the Java approach shown in the README to the Kotlin version, and the latter feels noticeably more natural in Kotlin's language style.

Performance is solid. The library is designed to handle hundreds of placeholder evaluations without lag, which matters if you're using placeholders heavily in scoreboards or frequently-updated holograms.

Tips, Pitfalls, and Common Gotchas

First mistake: over-registering placeholders. You don't need a dedicated placeholder for everything. If something changes constantly or has infinite variations, a placeholder might be premature. Placeholders shine for reusable, repeated values like player stats or server metrics.

Namespace your placeholder names carefully. "player_name" by itself could collide with another expansion's placeholders. Use something like "my-expansion_player_name" to avoid conflicts. Most developers follow this pattern automatically, but it's worth being explicit about.

Performance can become a concern if you're evaluating placeholders in tight loops (thousands per tick). Design your expansions to minimize expensive operations. If you're querying a database for placeholder data, consider caching results rather than hitting the DB every single time.

Platform differences exist. Velocity, being a proxy, behaves differently than Paper for some placeholder contexts. If you're targeting multiple platforms, read the platform-specific documentation rather than assuming it all works identically.

Finally, watch for version mismatches. MiniPlaceholders 3.2.0 requires Java 25. Your server is also likely targeting specific Minecraft version ranges (Paper 1.21+, etc.). Make sure you're using compatible builds.

Related Projects and Alternatives

PlaceholderAPI is the historical heavyweight of Minecraft placeholders. Nearly every old plugin that uses dynamic text relies on it. It works, it's stable, and it has massive adoption. But its API is older, string-based, and less elegant than MiniPlaceholders' component approach. The architecture shows its age.

Some plugins bundle their own placeholder support. EssentialsX, LiteBans, and others include placeholder features, but only for their own systems. They're not general-purpose frameworks.

For teams building fresh servers or plugins in 2026, MiniPlaceholders is the smarter choice. It's actively maintained, modern, and covers current platforms. If you're running a legacy server with dozens of plugins already on PlaceholderAPI, the migration effort might not justify it yet. But for anything new, MiniPlaceholders wins on architecture and developer experience.

Want to explore more tools for server customization? minecraft.how also has a Block Search tool for hunting down specific blocks and materials when building or managing your server.