Files

T

HeruEdhel 59330bdf84 feat: Implement runtime API cache store and related configurations

- Added RuntimeApiCacheStore for managing API cache entries in memory.
- Introduced StorageTarget enum to define various storage targets.
- Created StoredCacheEntry record to encapsulate cache entries.
- Defined SyncState enum to represent the synchronization state of cache entries.
- Added ControlPlaneConfigurationSource enum for different configuration sources.
- Developed ControlPlaneRuntimeConfig class for runtime configuration management.
- Implemented ControlPlaneStartupConfigResolver for resolving configuration from various sources.
- Created ControlPlaneStartupSettings to hold startup configuration values.
- Added ResolvedControlPlaneStartupConfig record to encapsulate resolved configuration.
- Implemented tests for batch client and cache client functionalities.
- Added tests for ControlPlaneStartupConfigResolver to validate configuration resolution logic.

2026-06-05 07:00:14 -07:00

3.0 KiB

Raw Permalink Blame History

Getting Started

Build

From core-network:

gradlew.bat compileJava
gradlew.bat test
gradlew.bat shadowJar

compileJava and test are the fastest checks for SDK/runtime changes. shadowJar builds the plugin jar.

Configure The Shared Client

core-network auto-configures NetworkPlugin.client() during plugin setup when startup configuration is present.

Recommended production setup uses environment variables:

$env:KWB_CONTROL_PLANE_BASE_URL = "https://control-plane.internal"
$env:KWB_CONTROL_PLANE_TOKEN = "server-issued-token"

Supported optional environment variables:

KWB_CONTROL_PLANE_BATCHING_ENABLED=true
KWB_CONTROL_PLANE_BATCH_FLUSH_INTERVAL_MS=250
KWB_CONTROL_PLANE_BATCH_MAX_SIZE=100
KWB_CONTROL_PLANE_BATCH_ENDPOINT=/api/v1/batch

Launcher-controlled startup can use JVM properties:

-Dkweebec.controlPlane.baseUrl=https://control-plane.internal
-Dkweebec.controlPlane.token=server-issued-token
-Dkweebec.controlPlane.batching.enabled=true
-Dkweebec.controlPlane.batch.flushIntervalMs=250
-Dkweebec.controlPlane.batch.maxSize=100
-Dkweebec.controlPlane.batch.endpoint=/api/v1/batch

For small local deployments, core-network creates control-plane.json in the plugin data directory. Fill in the placeholders:

{
  "BaseUrl": "https://control-plane.internal",
  "Token": "local-dev-token",
  "BatchingEnabled": true,
  "BatchFlushIntervalMs": 250,
  "MaxBatchSize": 100,
  "BatchEndpoint": "/api/v1/batch"
}

Precedence is environment variables, then JVM properties, then control-plane.json.

Manual setup still works and overrides auto-config:

NetworkPlugin.configure(
    "https://control-plane.internal",
    System.getenv("KWB_CONTROL_PLANE_TOKEN")
);

Dependent plugins then use:

ControlPlaneClient client = NetworkPlugin.client();

You can inspect the source that configured the shared client:

NetworkPlugin.configurationSource();

Dependency Setup

Dependent jars should declare core-network as a plugin dependency in their manifest:

{
  "Dependencies": {
    "core-network": "*"
  }
}

Common Direct Calls

ServerProfile profile = NetworkPlugin.client()
    .server()
    .currentProfile();

PlayerSessionProfile profile = NetworkPlugin.client()
    .players()
    .getSessionProfile(playerId);

NetworkPlugin.client()
    .presence()
    .heartbeat(instanceId, HeartbeatPayload.running(currentPlayers, maxPlayers));

Runtime Scheduling

NetworkPlugin starts a scheduled loop when the Hytale plugin starts. The loop:

flushes due batched API calls
flushes dirty cached API entries

Default batch cadence is 250ms.

Builder overrides:

ControlPlaneClient client = ControlPlaneClient.builder()
    .baseUrl("https://control-plane.internal")
    .token(token)
    .batchingEnabled(true)
    .batchFlushInterval(Duration.ofMillis(250))
    .maxBatchSize(100)
    .batchEndpoint("/api/v1/batch")
    .build();

3.0 KiB Raw Permalink Blame History