API and placeholders

Commands 2#

/placeholder list
/placeholder info neoessentials_balance
/placeholder test Hello {neoessentials_name}, balance {neoessentials_balance}, group {neoessentials_group}

/placeholder test {luckperms_prefix}{luckperms_group}{luckperms_suffix}
/placeholder test {ftbranks_prefix}{ftbranks_rank}
/placeholder test {neoessentials_prefix}{neoessentials_group}

/dashboard start
/apikey create placeholders ADMIN
/placeholder stats

/vault info

/vault info
/vault convert NeoEssentials OtherEco

Permissions 1#

Detailed guide#

Version: 1.0.5+build.54 · API Version: 1.2.0

Overview#

NeoEssentials exposes five integration surfaces for server admins and mod developers:

Built-in Placeholders#

All NeoEssentials placeholders use the neoessentials expansion prefix. Syntax: {neoessentials_<identifier>}. Short-form aliases (legacy, no prefix) are also supported in most contexts.

Player Placeholders#

Stat Placeholders#

AFK Placeholders#

Server-wide Placeholders#

Utility Placeholders#

LuckPerms / FTB Ranks Compatibility Placeholders#

A small set of compatibility-named placeholders, for text copied from a server that used to run LuckPerms's or FTB Ranks's own PlaceholderAPI expansion:

These are aliases into NeoEssentials' own permission system, not a live bridge to the LuckPerms/FTB Ranks plugin's own placeholder expansion. They resolve through PermissionAPI, which checks whichever external adapter is actually active (LuckPerms, FTB Ranks, or neither) and falls back to the internal permission system — so {luckperms_prefix} works correctly even on a server that has never installed LuckPerms at all. The equivalent {neoessentials_prefix}/{neoessentials_group} tokens above resolve identically; these exist purely so pasted-in text using the other naming convention still works.

Custom Placeholders (Java API)#

1. Single placeholder — PlaceholderProvider#

PlaceholderProvider is a public @FunctionalInterface you can implement with a lambda or class.

import com.zerog.neoessentials.api.PlaceholderAPI;
import com.zerog.neoessentials.api.NeoEssentialsAPI;

// Via static facade (simplest):
PlaceholderAPI.registerPlaceholder("mymod_kills", (player, params) ->
    player != null ? String.valueOf(MyStats.getKills(player.getUUID())) : "0"
);

// Via PlaceholderManager directly:
NeoEssentialsAPI.getPlaceholderManager()
    .registerPlaceholder("mymod_kills", (player, params) -> "42");

PlaceholderProvider.onRequest(ServerPlayer player, String params): - player — the ServerPlayer context, may be null for server-wide resolution - params — the part after : in {mymod_stat:some_param} — may be null

Return null to leave the original token unchanged in the output string.

2. Expansion — multiple placeholders under one prefix#

Extend PlaceholderExpansion to register many related placeholders at once. Expansion id "mymod" → placeholders {mymod_kills}, {mymod_deaths}, {mymod_playtime}.

Important: the expansion identifier must be lowercase, alphanumeric, and contain no underscores. Resolution splits a placeholder token on its first _ to separate the expansion id from the placeholder name ({mymod_kills} → id mymod, placeholder kills), so an id like "my_mod" would never match — {my_mod_kills} would look for an expansion named "my".

import com.zerog.neoessentials.api.PlaceholderExpansion;
import com.zerog.neoessentials.api.PlaceholderAPI;
import net.minecraft.server.level.ServerPlayer;
import java.util.Set;

public class MyModExpansion extends PlaceholderExpansion {

    @Override public String getIdentifier() { return "mymod"; }
    @Override public String getVersion()    { return "1.0.0"; }
    @Override public String getAuthor()     { return "YourName"; }

    @Override
    public Set<String> getPlaceholders() {
        return Set.of("kills", "deaths", "playtime");
    }

    @Override
    public String onPlaceholderRequest(ServerPlayer player, String identifier, String params) {
        if (player == null) return null;
        return switch (identifier) {
            case "kills"    -> String.valueOf(MyStats.getKills(player.getUUID()));
            case "deaths"   -> String.valueOf(MyStats.getDeaths(player.getUUID()));
            case "playtime" -> MyStats.getFormattedPlaytime(player.getUUID());
            default         -> null;
        };
    }
}

// Register (call during ServerStartingEvent or your mod's init):
PlaceholderAPI.registerExpansion(new MyModExpansion());

3. Resolving placeholders in text#

import com.zerog.neoessentials.api.PlaceholderManager;

PlaceholderManager pm = NeoEssentialsAPI.getPlaceholderManager();

// Resolve all placeholders in a string
String formatted = pm.setPlaceholders(player, "Hello {neoessentials_name}, kills: {mymod_kills}!");

// Resolve a single placeholder value
String value = pm.getPlaceholderValue(player, "mymod_kills", null);

// Check if a placeholder is registered
boolean exists = pm.isPlaceholderRegistered("mymod_kills");

// List all registered identifiers
Set<String> all = pm.getRegisteredPlaceholders();

// Unregister
pm.unregisterPlaceholder("mymod_kills");
PlaceholderAPI.unregisterExpansion(myExpansionInstance);

PlaceholderManager is thread-safe (ConcurrentHashMap). All operations are safe to call from async threads.

NeoEssentialsAPI — Full Reference#

The NeoEssentialsAPI class is the single stable entry-point for inter-mod integration.

import com.zerog.neoessentials.api.NeoEssentialsAPI;

// Check availability before calling (useful if NeoEssentials is optional)
if (NeoEssentialsAPI.isAvailable()) { ... }

// API version (SemVer string, e.g. "1.2.0")
String version = NeoEssentialsAPI.API_VERSION;

Economy API#

import com.zerog.neoessentials.api.economy.EconomyService;

EconomyService eco = NeoEssentialsAPI.getEconomyService();
eco.deposit(uuid, 100.0);
eco.withdraw(uuid, 50.0);
double balance   = eco.getBalance(uuid);
boolean hasEnough = eco.getBalance(uuid) >= 30.0;   // no has(uuid, amount) helper — compare getBalance()
boolean hasAcct   = eco.hasAccount(uuid);

Economy Events (NeoForge event bus)

Both events extend EconomyEvent and expose getPlayerId(), getAmount() (double), and getBigDecimalAmount() (precise BigDecimal). They implement ICancellableEvent — cancel the event to veto the deposit/withdrawal.

Permissions API#

import com.zerog.neoessentials.api.permissions.PermissionsService;

PermissionsService perms = NeoEssentialsAPI.getPermissionsService();

boolean canFly  = perms.hasPermission(playerUUID, "neoessentials.fly");
String  group   = perms.getGroup(playerUUID);
String  prefix  = perms.getPrefix(playerUUID);
String  suffix  = perms.getSuffix(playerUUID);

// Register your mod's permission nodes (visible in /permissions search + dashboard)
perms.registerPermission("mymod.feature", "Enables my mod's cool feature");

// Register legacy alias
perms.registerAlias("oldmod.fly", "neoessentials.fly");

Placeholder API (quick reference)#

import com.zerog.neoessentials.api.PlaceholderManager;

PlaceholderManager pm = NeoEssentialsAPI.getPlaceholderManager();
pm.registerPlaceholder("mymod_online", (player, params) ->
    String.valueOf(server.getPlayerCount()));
String resolved = pm.setPlaceholders(player, "Players: {mymod_online}");

See the Custom Placeholders section above for the full API.

Versioning contract#

NeoEssentials follows SemVer for API changes:

Guard version-specific feature use:

String[] parts = NeoEssentialsAPI.API_VERSION.split("\\.");
int minor = Integer.parseInt(parts[1]);
if (minor >= 2) {
    // getPlaceholderManager() is available since 1.2.0
    NeoEssentialsAPI.getPlaceholderManager().registerPlaceholder("...", ...);
}

REST API (External Dashboard)#

The mod no longer ships its own dashboard UI. webDashboard.mode is "external" — the embedded HTTP server on config.json → webDashboard.port (default 8080) serves REST only; a separately-hosted dashboard app is the actual UI. Everything below is the integration surface for that app.

This section is a summary. The full, exhaustive reference — every route across all ~29 endpoint groups, real example request/response JSON pulled from a live server, quirks like binary downloads and non-UUID path segments, and the WebSocket protocol — lives in docs/API.md at the repo root. That file is what an external dashboard developer should actually build against; treat this wiki section as an index into it.

Authentication#

Two credential types, both presented the same way — Authorization: Bearer <token> — tried in this order by the server:

1. API key (recommended for a dashboard backend) — a long-lived, independently-revocable credential, never expiring on its own. The recommended way to get one connected is pairing, not manually running /apikey create and copy-pasting the token:

#### Pairing

1. On the external dashboard's own admin Configuration page, click "Generate Pairing Code" — it shows a one-time code (valid 10 minutes) and the exact command to run.
2. On the Minecraft server console (or in-game, if OP), run the command it showed: /dashboard pair "<dashboardUrl>" <code> The URL must be quoted — unquoted command arguments can't contain : or /. Requires permission neoessentials.dashboard.pair.
3. In that single round trip: the mod mints an API key and sends it to the dashboard (for the dashboard's own outbound calls to this API), and the dashboard mints a token back for the mod's outbound account-sync webhook (see below) — both directions connected, nothing hand-copied between two config files.

/dashboard unpair clears the connection and revokes the key that was minted for it.

The manual path still exists for scripting/one-off keys: /apikey create <label> [role] # role: ADMIN (default) | OPERATOR | MODERATOR | VIEWER /apikey list /apikey revoke <id> The full token (neo_<keyId>_<secret>) is printed exactly once at creation — only its salted hash is stored, so it can't be recovered later, only revoked and re-created. Never put it in frontend/browser code; it belongs on the external dashboard's own server, which then calls this API on the browser's behalf. Also manageable over REST once a first key exists — GET/POST /api/apikeys, DELETE /api/apikeys/{id} (ADMIN-gated). 2. Session token — from POST /api/auth/login (username/password) or the Discord-linked flow — see Web Dashboard for account registration. This is the mod's own human-login concept; an external dashboard backend calling this API as a service should generally prefer an API key instead.

Every route is gated as PUBLIC (no token needed — a small deliberate set: public moderation lookup, /api/docs/*, /api/ping), AUTH (any valid key/session, any role), or ADMIN (the credential's role must be ADMIN) — see docs/API.md for the exact tier of every route.

# Login (session-based)
curl -X POST http://localhost:8080/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"username":"admin","password":"secret"}'
# Response includes: {"success":true,"sessionId":"...", "user":{...}}

# Authenticated request — works identically with a session id or an API key
curl http://localhost:8080/api/placeholders/list \
     -H "Authorization: Bearer <sessionId-or-api-key>"

Endpoint groups (see docs/API.md for full detail on each)#

A live event feed also runs on websocketPort (default 8081) alongside REST — channels events/chat/stats, authenticated the same way (session id or API key). Full protocol in docs/API.md.

Syncing dashboard accounts with an external user table#

If the external dashboard has its own user accounts and wants a matching mod-side account to exist (or vice versa), see the "Keeping dashboard accounts in sync" section under /api/users in docs/API.md — covers POST /api/users/sync (idempotent create-or-update, for the external dashboard pushing its accounts into the mod) and the outbound webhook fired whenever a dashboard_user is created/updated/deleted here (in-game /dashboardregister included), so the external dashboard can mirror it back out automatically. The webhook's target URL and auth token are set automatically by pairing (see above), not hand-configured.

In-Game Admin Commands#

/placeholder#

Manage and test the placeholder system in-game.

Permission: neoessentials.admin.placeholders (default: OP-only)

Custom Language System#

NeoEssentials supports full internationalisation with per-server language overrides.

Bundled Languages#

en_us, fr_fr, de_de, es_es, pt_br, zh_cn, nl_nl, pl_pl, ru_ru

All files are available in the JAR and auto-deployed to neoessentials/languages/custom/ when first selected.

Switching Language#

In config.json under the localization section:

"localization": {
  "language": "fr_fr"
}

Then reload in-game:

/neoessentials reload

Fallback: Any key not translated in the chosen language file falls back to English automatically.

Custom / Overriding Translations#

Edit any file in neoessentials/languages/custom/<lang>.json. Changes are preserved across mod updates — new keys from the JAR are merged in without overwriting your edits.

Adding a New Language#

1. Create neoessentials/languages/custom/xx_xx.json
2. Copy all keys from en_us.json and translate values
3. Set "language": "xx_xx" in config.json → localization
4. Run /neoessentials reload to apply

Lang Key Format#

{
  "_langVersion": 17,
  "commands.neoessentials.home.teleported": "§aTeleported to home §e{0}§a.",
  "commands.neoessentials.home.not_found": "§cHome §e{0}§c not found."
}

{0}, {1}, … are positional MessageFormat arguments substituted at runtime.

See Localization System for full documentation.

Back to Wiki Home