NexusAI

Asynchronous AI bridge for Paper and Purpur via PlaceholderAPI: unique answer pools, TTL cache, prewarm.

For server admins and plugin developers. Menus, chat and hologram plugins get AI text through NexusAI placeholders. It is not a chat bot for players.

How it works

Features

• %ainexus_generate_<prompt>%: unique answer pool. Each read takes one stored answer, and the pool refills in the background.
• %ainexus_cached_<prompt>%: shared TTL cache, useful for holograms.
• Named prompts in prompts.yml: keep long prompts under a short id, e.g. %ainexus_cached_survival_tips%.
• Prewarm and pool vars, for example {player_name} becomes %player_name% per player.
• Built-in variables {player}, {world}, {biome}, {time}, {weather} work without PlaceholderAPI.
• Format presets per prompt: chat, gui, name, hologram, actionbar, bossbar, with length limits and markdown stripping.
• OpenAI-compatible providers: openai, groq, cerebras, gemini, deepseek, openrouter, ollama, or any custom URL. Several keys per provider, ${ENV_VAR} in keys, keys masked in logs. Local endpoints need no API key.
• Model queue: switches to the next provider or model on 429, errors, low rate-limit budget or a daily cap, and comes back after the cooldown.
• Rate limits per server and per player, per-prompt backoff, provider pause on HTTP 401/402/429.
• Prompt-injection protection: player values are sanitized and fenced, and replies that leak or follow them are discarded.
• Reply cleaning: replies lose colour codes, hex colours and MiniMessage tags before menus, scoreboards or chat plugins show them. sanitize.allow-markup (default false) keeps hex and tags for placeholders; enable it only if you understand the risk, because click and hover tags then reach the plugin that shows the placeholder.
• Dialogues: /nai talk <id> talks to a character from prompts.yml, with memory and per-player limits. NPC plugins can run it from the console.
• Actions: a character can trigger only commands you define, with cooldowns, daily limits and permissions.
• Fallback model when the whole queue is unavailable, and a knowledge folder (knowledge/*.md) for lore and rules.
• Chat moderation (opt-in, off by default): flags reach staff, nobody is punished automatically.
• 15 locales • /nai help / version / reload / status / test / prompts / talk

Setup

1. Paper or Purpur 1.20.6–26.2 (Java 21+) + PlaceholderAPI 2.11.6+
2. Drop the jar into plugins/
3. Set NEXUSAI_API_KEY or providers.<id>.api-key (supports ${ENV_VAR}). Not needed for Ollama or other local endpoints.
4. Restart the server, or run /nai reload after editing the config

Compatibility

• Paper and Purpur 1.20.6–26.2. One jar for all of these versions.
• Java 21 or newer.
• PlaceholderAPI 2.11.6+ (soft-depend), needed for the %ainexus_*% placeholders.
• Not supported: Folia, Paper and Purpur 26.3, Spigot, CraftBukkit.

Data sent to your AI provider

NexusAI sends the prompt text (plus the system prompt, knowledge text and format instruction) over HTTP to the AI endpoint you set in config.yml. That can be a third-party service such as OpenAI, or your own local endpoint such as Ollama. Anything you put in a prompt goes to that endpoint. That includes a player name if you use {player}, and the player's lines in /nai talk. With chat moderation turned on, each checked public chat line is sent too (without the player name). Without an API key, remote providers are not called and placeholders return the configured fallback text. Answers are generated by the model you choose, so review your prompts and the provider's terms. NexusAI has no telemetry.

Known issues

• The player-input boundary and the reply filter reduce prompt-injection risk; they do not eliminate it. Put a stronger model later in model-queue so a discarded answer is replaced.
• Small models often answer weakly and are not recommended as the only model.
• JSON text components in a reply (for example {"text":"…"}) are not removed. NexusAI does not parse them, but a plugin that parses JSON components after PlaceholderAPI inserts the reply can still act on them.
• A Groq free-tier account has a per-minute output-token quota. Long /nai talk turns or many long placeholders can still return HTTP 429; keep api.max-tokens at 256 and use a longer cache.ttl.

Links

• Documentation and source: GitHub
• Changelog: CHANGELOG.md
• Issues: GitHub Issues
• Also on SpigotMC and Modrinth

License: MIT — Copyright (c) 2026 mo00Wy