NexusAI

Feature release: configurable JSON validation for the plugin API, a world-context helper for other plugins, optional latency controls for /nai talk (streamed replies, a thinking message, a timeout fallback), a startup console banner and brand chat colours in all 15 languages. Server stop with a large dialogue-memory.yml is also faster. Everyone on 1.2.0 can update. Missing keys are appended to config.yml automatically, it stays at config-version: 2, and NexusAIApi.API_VERSION stays 3.

Upgrading

• Replace NexusAI-1.2.0.jar with NexusAI-1.3.0.jar and restart. Commands and placeholders are unchanged. NexusAIApi.API_VERSION stays 3; the new API types are additive.
• You do not need to edit config.yml, and do not change config-version. On the first start, missing keys such as plugin-api.response-validation.* are copied from the jar default. The log shows Added missing config keys: …, and that start writes one config.yml.bak (or config.yml.bak.<timestamp>). Values you already set and your comments stay.
• The defaults keep 1.2.0 behaviour for generateJson, latency controls are off and world-context.enabled is false. The only visible change is the startup banner.
• Bundled chat colours changed. Your existing plugins/NexusAI/lang/*.yml files are not overwritten: edit them, or delete a file so the new default is extracted.
• To roll back: stop the server, put NexusAI-1.2.0.jar back and start it. config.yml can stay as it is. Details are in docs/migration-1.3.0.md.

JSON validation

• plugin-api.response-validation controls generateJson: enabled (default true), on-invalid (retry or fallback, default retry), max-retries (0–3, default 1) and deliver-on-region (default false).
• When enabled, a reply with a wrong type, a value outside a range or an action outside an allowlist never reaches json() / asMap(). Validation and correction retries stay off the main thread.
• GenerationRequest.responseValidation(...) overrides the config per call. JsonSchema.withActionAllowlist adds a string enum for an action property.
• The future still completes on a NexusAI thread by default. With deliver-on-region: true (or ResponseValidation.deliverOnRegion(true)) it completes on the player's region thread when a player is set (main thread on Paper).

World context

• NexusAIApi.worldContext collects the player's name, world, coordinates, inventory materials, nearby block counts and biome into one compact prompt block.
• World reads run on the player's region thread within configurable radius and volume caps. The block is capped at world-context.max-chars (default 400, about 100 tokens); NexusAIApi.worldContextEstimatedTokens reports the estimate.
• Off by default: world-context.enabled: false. Other keys: radius, max-blocks, max-block-types, max-inventory-items, max-chars, cooldown-millis (default 250).

Talk latency

• latency.streaming sends a finished reply in chat chunks. latency.thinking-indicator sends talk.thinking while the model works. latency.timeout sends talk.timeout-fallback when the wait exceeds latency.timeout.millis. Each part is off by default and can be turned on alone.
• The response cache gains cache.enabled and cache.max-memory-bytes (eviction by size in memory, with TTL). With a memory cap of 0, cache.max-size still applies.

Startup banner and colours

• After startup, the console shows a NEXUSAI banner with version, server, Java, providers, API features and start time. Every line fits in 70 columns. It replaces the old NexusAI enabled. line.
• Bundled chat strings use the brand colour #00C5C2 for the prefix, headers and command names in all 15 languages. Limit refusals use one colour scheme. talk.reply no longer includes the prefix, so an NPC line is only the character name and the reply.

Dialogue memory

• Fix: stop with a large dialogue-memory.yml is faster. Player and character keys are read with a line scan of the file layout NexusAI writes, with the YAML parser as fallback. The stop budget grows with the file size up to the configured limit.
• Fix: when every entry in dialogue-memory.yml has expired, stop and periodic saves now write a valid empty file (format and an empty entries section) instead of a 0-byte file. The next start loads it cleanly, with no warning.
• Fix: dialogue-memory.yml is written only when memory has changed. A stop or periodic save with no changes leaves the file untouched, so stop on a large file is faster. Long values are written on one line, so a rewrite no longer makes the file grow; older files load as before.
• Fix: transcripts that expire while the server runs are dropped before each save and are no longer written back to dialogue-memory.yml.

Known issues

• The player-input boundary and the reply filter reduce prompt-injection risk. They do not eliminate it.
• An HTTP 429 on one model pauses its whole provider. Put fallback-model on a different provider so /nai talk can still answer.
• /nai test run over RCON returns only Sending a test request.... The answer reaches the console and the player a moment later.
• Live structured output was checked only with Groq. OpenRouter, OpenAI and Ollama use the same code path but were not checked against the live service.
• Limits and best practices for plugin authors are in docs/limitations.md.

Compatibility

• Paper and Purpur 1.20.6–26.2; Folia 1.21.8, 1.21.11 and 26.1.2 only; Java 21 or newer (Java 25 on 26.x)
• PlaceholderAPI 2.11.6+ (soft-depend); on Folia 2.11.7+
• Tested with PlaceholderAPI 2.12.3 on Paper 26.2-134 and Folia 26.1.2-8 (Java 25). CI on the release commit also starts the plugin on Paper 1.20.6, 1.21.1, 1.21.4, 1.21.8 and 26.2, and on Folia 1.21.8, 1.21.11 and 26.1.2.
• Paper and Purpur 26.3, Spigot and CraftBukkit are not supported.

Download

NexusAI-1.3.0.jar, SHA-256 ecbf18a2d29a399a9127f8dcbb25e05212b202f5d453c1cb4512e707a1b6e633

Full history: CHANGELOG.md