Experimental - ServerSettings API | Cloudburst Nukkit & Minecraft Server Software

Compatible API Versions: 1.0.0

Sourcecode: https://github.com/MakisImperium/ServerSettings

ServerSettingsApi

Production-grade packet-level API for Bedrock Server Settings on Nukkit.

Core Flow

Code:

PlayerServerSettingsRequestEvent -> ServerSettingsResponsePacket -> ModalFormResponsePacket -> response routing

The API delivers a stable integration contract for plugin teams that need predictable behavior, typed parsing, and runtime observability.

Value Proposition

Packet-first architecture with no abstraction leaks into non-packet form systems.
Strong ownership model (
Code:
```
owner + key
```
) for multi-plugin server environments.
Multiple response styles: handler, processor, parsed processor, or pipeline.
Built-in runtime metrics for operations, incident analysis, and capacity tracking.
Automatic lifecycle cleanup on player quit and plugin disable.

Architecture

Code:

Consumer Plugin(s)
  -> ServerSettingsApi (service contract)
     -> PacketServerSettingsApi (engine)
        -> listens: PlayerServerSettingsRequestEvent
        -> sends:   ServerSettingsResponsePacket
        -> listens: DataPacketReceiveEvent (ModalFormResponsePacket)
        -> routes response to registered definition
        -> exports metrics via ServerSettingsApiStats

Compatibility

Java: 17
Nukkit API: 1.0.0
Plugin Name:
Code:
```
NovaServerSettingsApi
```
Maven Compiler:
Code:
```
--release 17
```

Installation
1. Deploy provider plugin
Build this project and place the JAR into your server

Code:

plugins/

directory.

2. Add dependency in consumer plugin

YAML:

depend: [NovaServerSettingsApi]

3. Resolve service

Java:

import org.nova.api.ServerSettingsApi;
import org.nova.api.ServerSettingsApiLocator;

ServerSettingsApi api = ServerSettingsApiLocator.require(getServer());

Quick Start

Java:

import cn.nukkit.plugin.PluginBase;
import org.nova.api.ServerSettingsApi;
import org.nova.api.ServerSettingsApiLocator;
import org.nova.api.ServerSettingsDefinition;
import org.nova.api.ServerSettingsJson;
import org.nova.api.ServerSettingsRegistration;

public final class ExamplePlugin extends PluginBase {

    private ServerSettingsRegistration registration;

    @Override
    public void onEnable() {
        ServerSettingsApi api = ServerSettingsApiLocator.require(getServer());

        this.registration = api.register(
                ServerSettingsDefinition.builder(this, "global-settings")
                        .payloadProvider(ctx -> ServerSettingsJson.customForm("Global Settings")
                                .label("Configure runtime behavior")
                                .toggle("Feature enabled", true)
                                .slider("Rate", 0, 100, 1, 25)
                                .input("Tag", "e.g. PROD", "")
                                .build())
                        .parsedResponseHandler((ctx, values) -> {
                            boolean featureEnabled = values.getBoolean(1, false);
                            int rate = values.getInt(2, 0);
                            String tag = values.getString(3, "");

                            getLogger().info(
                                    "Settings updated: player=" + ctx.getPlayer().getName()
                                            + ", featureEnabled=" + featureEnabled
                                            + ", rate=" + rate
                                            + ", tag=" + tag
                            );
                        })
                        .acceptClosedResponses(false)
                        .build()
        );
    }

    @Override
    public void onDisable() {
        if (this.registration != null) {
            this.registration.unregister();
            this.registration = null;
        }
    }
}

Advanced Response Orchestration

Java:

import org.nova.api.ServerSettingsResponsePipeline;
import org.nova.api.ServerSettingsResponses;

ServerSettingsResponsePipeline pipeline = ServerSettingsResponsePipeline.builder()
        .thenParsed((ctx, values) -> {
            boolean enabled = values.getBoolean(0, false);
            int threshold = values.getInt(1, 50);
            // 1) validate and map
        })
        .then(ctx -> {
            // 2) persist, publish domain events, audit
        })
        .onError(ServerSettingsResponses.loggingErrors(this, "[ServerSettings] "))
        .continueOnError(false)
        .build();

api.register(
        ServerSettingsDefinition.builder(this, "policy-settings")
                .payloadProvider(ctx -> ServerSettingsJson.customForm("Policy")
                        .toggle("Enabled", true)
                        .slider("Threshold", 0, 100, 1, 50)
                        .build())
                .responsePipeline(pipeline)
                .build()
);

Dynamic Payload by Player Context

Java:

api.register(
        ServerSettingsDefinition.builder(this, "personalized-settings")
                .payloadProvider(ctx -> ServerSettingsJson.customForm("Hello " + ctx.getPlayer().getName())
                        .label("FormId: " + ctx.getFormId())
                        .toggle("Receive notifications", true)
                        .build())
                .responseHandler(ctx -> {
                    boolean enabled = ctx.booleanAt(1, true);
                    // apply player-scoped configuration
                })
                .build()
);

Observability

Java:

var stats = api.getStats();
getLogger().info(
        "serverSettingsApi"
                + " registrations=" + stats.getRegistrations()
                + " requestEvents=" + stats.getRequestEvents()
                + " packetsSent=" + stats.getPacketsSent()
                + " responsePackets=" + stats.getResponsePackets()
                + " processed=" + stats.getResponsesProcessed()
                + " failed=" + stats.getResponsesFailed()
                + " ignored=" + stats.getResponsesIgnored()
);

Production Guidelines

Keep handlers deterministic and fast inside the event context.
Offload heavy CPU or I/O to your own async scheduler.
Return to main thread only for server-critical operations.
Use stable keys (
Code:
```
owner + key
```
) as long-term integration identifiers.
Prefer parsed handlers for strict type handling and explicit defaults.
Track
Code:
```
responsesFailed
```
and
Code:
```
responsesIgnored
```
metrics for early anomaly detection.

Public API Surface

Code:
```
ServerSettingsApi
```
: service contract used by consumer plugins.
Code:
```
ServerSettingsApiLocator
```
: service resolution helper.
Code:
```
ServerSettingsDefinition
```
: immutable registration definition + builder.
Code:
```
ServerSettingsRegistration
```
: registration handle with explicit unregister.
Code:
```
ServerSettingsRequestContext
```
: payload creation context.
Code:
```
ServerSettingsResponseContext
```
: response metadata + lazy parsed access.

Code:

ServerSettingsResponseValues

: typed value accessor (

Code:

boolean/int/double/string

Code:
```
ServerSettingsResponsePipeline
```
: composable multi-step response processing.
Code:
```
ServerSettingsResponses
```
: adapters and logging error handler factory.
Code:
```
ServerSettingsApiStats
```
: runtime metrics snapshot.

Build

Bash:

mvn clean package

Experimental ServerSettings API 1.0.0

More resources from MakisImperium

Share this resource