---
url: https://docs.sunlicense.com/how-to/hytale-plugin.md
description: >-
  How to add license keys to a Hytale server plugin - check the buyer's key with
  the SunLicense Java SDK from your JavaPlugin's start(), off the server
  threads, gate your features, keep running offline, and sell it on BuiltByBit.
---

# How to add license keys to a Hytale plugin

**Short answer:** add the SunLicense Java SDK (shaded and relocated), read the buyer's key from your plugin's
`config.json`, check it on a background thread when the plugin starts, and gate every command and event on the
result. A network error is not a no: keep running and check again later.

```java
// build.gradle.kts: implementation("com.sunlicense:sunlicense:0.0.1"), shaded and relocated
private static volatile boolean active;
private final SunLicense client = new SunLicense.Builder()
        .baseUrl("https://api.sunlicense.com").token("slk_…").build();   // API key from your build, never git
private final ScheduledExecutorService checks = Executors.newSingleThreadScheduledExecutor();

@Override
protected void start() {
    checks.scheduleAtFixedRate(() -> {
        try {
            SunLicense.Result r = client.validate(config.get().licenseKey(), Map.of("host", machineId()));
            active = r.getStatus() != 400;   // only a 400 is SunLicense saying no
            if (!active) getLogger().atSevere().log("License rejected: " + r.getBody());
        } catch (SunLicense.SunLicenseException e) {
            active = true;   // unreachable: keep running, check again later
        }
    }, 0, 6, TimeUnit.HOURS);
}

public static boolean active() { return active; }   // every command and event: if (!MyPlugin.active()) return;
```

**Start from the template instead:** the [Hytale plugin template](/guide/hytale-plugin) is the Paper template ported to
Hytale's plugin API (built against server 0.7.5, Java 25): `config.json` with Hytale's own codecs, BuiltByBit
placeholders, a stable machine id, masked keys, a signed offline license fallback, `/myplugin status` and
`recheck`, tests and CI.

**Or let your AI agent do it:** paste the [setup prompt](https://sunlicense.com/prompt) into your coding agent in the
plugin's folder.

Free plan: 3 products, 100 licenses, no credit card. [Create a free account](https://sunlicense.com/start?ref=docs-howto-hytale).

## Step by step

1. **In the dashboard:** a product, a policy (a machine is a server) and an **API key**, which can only validate.
2. **Add the SDK** with Shadow and relocate it into your own package.
3. **Keep the API key out of git:** `~/.gradle/gradle.properties` (`sunlicenseApiKey=slk_…`), written into a resource
   at build time.
4. **The buyer's key** goes in `mods/<Group>_<Name>/config.json` (`LicenseKey`), or a `%%__SUNLICENSE__%%` placeholder
   that [BuiltByBit](/integrations/builtbybit) fills in on download.
5. **Register in `setup()`, check in `start()`.** Hytale loads your config before `setup()`; `start()` runs once every
   plugin is set up. Do the network call on your own executor, never on a world thread, and shut it down in `shutdown()`.
6. **Machine id** as `host`: a hash of OS, architecture and host name (snippet in the [Paper guide](/how-to/paper-plugin#step-by-step)).
7. **Results:** 200 activates your features, 400 deactivates them with the [reason](/guide/concepts#validation-result-codes),
   anything else keeps running and retries in about 10 minutes, or uses an [offline license](/guide/offline-licenses).

## Early access

Hytale is in early access and its plugin API changes between updates. Check which server version you build against
(`hytaleVersion` in the template's `gradle.properties`) after every Hytale update; the license check itself is plain
Java and HTTP, so it doesn't change with the game.

## Selling it

BuiltByBit has a Hytale category and the `%%__SUNLICENSE__%%` placeholder works the same as for Minecraft. Say in the
listing that the plugin checks its license online and keeps running when the check can't reach SunLicense. Other
stores: SunLicense issues a key per purchase ([integrations](/integrations/)).

More on [licensing Hytale plugins](https://sunlicense.com/for/hytale-plugins/).