# Getting Started

## Build

From `core-network`:

```bat
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:

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

Supported optional environment variables:

```text
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:

```text
-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:

```json
{
  "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:

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

Dependent plugins then use:

```java
ControlPlaneClient client = NetworkPlugin.client();
```

You can inspect the source that configured the shared client:

```java
NetworkPlugin.configurationSource();
```

## Dependency Setup

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

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

## Common Direct Calls

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

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

```java
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:

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