Skip to content
SLNE-DevelopmentPublic

About

Server-driven client content for Paper: a Fabric runtime that renders GUIs, keybinds and sandboxed Lua extensions shipped by the server.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Kiln

Server-driven client content for Paper.
Real GUIs, keybinds and sandboxed Lua extensions, shipped by the server and rendered natively on the client.

Build Minecraft 26.3 Paper 26.3 Fabric Loader 0.20.1 Java 25


Status: prototype. APIs, protocol and package format still change between versions.

What is Kiln?

Vanilla Minecraft offers servers no real way to show custom user interfaces: chest menus, books and dialogs can be bent into shape, but always with hacks such as core shaders or font tricks. Kiln takes a different route, similar to FiveM or Garry's Mod:

  • Players install the Kiln runtime once, a small Fabric mod.
  • Everything client-side a server needs comes from the server: GUI trees, keybinds, Lua scripts and a full resource-pack tree (models, item definitions, textures, sounds, fonts, languages, post effects), mounted as a real resource pack. Plugins add custom items and custom enchantments on top.
  • Game logic, money, items and validation stay on the Paper server. The client only renders and reports input.
  • Server scripts run in a sandbox (LuaJ without io, os, debug, load or Java access, with instruction, memory and rate budgets). Players see which permissions an extension wants and agree before anything is downloaded.
  • There are no fallbacks: players without the runtime, with another protocol version, who decline or whose extensions fail to load are disconnected with a clear reason.
flowchart LR
    subgraph Server["Paper server"]
        P[Your plugin] --> K[Kiln plugin]
        E[(Extension packages<br/>Lua · PNG · JSON)] --> K
    end
    subgraph Client["Player (Fabric)"]
        R[Kiln runtime] --> S[Native screens · HUD · keybinds]
        R --> L[Lua sandbox]
    end
    K -- "manifest → consent → download<br/>(configuration phase)" --> R
    K <-- "GUI trees, updates, typed channels" --> R
Loading

Two ways to build UIs

1. Server-defined screens with the Kotlin DSL. The server sends a tree of elements and live updates; the client keeps focus, scroll position and text input across updates.

player.openScreen(220, 120) {
    panel(width = 220, height = 120) {
        layout = Layout.Column(gap = 6, padding = 10)
        text("Energie: ${machine.energy} %")
        progressBar(machine.energy / 100f, width = 200)
        button("toggle", if (machine.running) "Ausschalten" else "Einschalten") {
            onClick { machine.running = !machine.running; it.screen.refresh() }
        }
    }
}

2. Lua extensions for anything that needs client-side logic: custom widgets, HUD overlays, keybinds, full screens. The API extension ui_kit provides buttons, tabs, dropdowns, sliders, tables, scroll panels, modals and item slots.

local ui, keys, net = kiln.ui, kiln.keys, kiln.net
local hello = net.channel("hello")

keys.bind("hello", { name = "Hallo an Server", default = "J", press = function()
  hello:send({ text = "Hallo vom Client!" })
end })

hello:on(function(msg) ui.toast("Server", msg.text) end)
val ext = registerExtension("kiln_example")              // from the plugin's resources
ext.channel<HelloMessage>("hello") { player, msg -> send(player, HelloMessage("Hallo zurück, ${player.name}!")) }

Modules

Module Kind Artifact
protocol plain Kotlin/JVM, no Minecraft messages, GUI tree, binary codec, limits
server/api Kotlin, compileOnly paper-api API for Paper plugins: screen DSL, keybinds, extensions, typed channels
server/runtime Paper plugin Kiln kiln-server-<v>.jar (shades protocol, server/api, Kotlin stdlib; NMS via paperweight)
client Fabric mod kiln kiln-client-<v>.jar (protocol and LuaJ as nested jars)
example/server Paper plugin KilnExample demos and Lua extensions, see below
build-logic included build convention plugins (kiln.kotlin, kiln.test, kiln.library, kiln.shadow, kiln.paper-plugin, kiln.nms, kiln.publish)
gradle-plugin Gradle plugin dev.kiln paper-plugin.yml with Kiln dependency, runServer, runClient for plugins using Kiln

Getting started

Requirements: Java 25. Gradle downloads everything else.

./gradlew build                     # all modules, including tests
./gradlew :example:server:runServer # Paper 26.3 with Kiln and the demos (run/server)
./gradlew :example:server:runClient # Minecraft 26.3 with the Kiln runtime (run/client), offline user "Ammo"
./gradlew :client:runClient         # the same from the client module (client/run)
./gradlew publishToMavenLocal; ./gradlew -p gradle-plugin publishToMavenLocal   # dev.kiln:* artifacts + plugin

Connect the dev client to the server. On the first join you see the consent screen, then the loading screen, then the world. Players need kiln-client-<v>.jar, Fabric API and Fabric Language Kotlin.

Demos

Command Key What it shows
/pbdemo G server-defined factory screen with live updates, gauge widget from Lua
/shop K full-screen market as a Lua screen on ui_kit (server-rendered twin: /shopdsl)
/fabrik B machine control: list, details, toggles, slider, dropdown
/quests U quest log with tabs, progress and reward items
/warps V warp tiles, search, favourites, teleport with cooldown
/bestenliste N sortable leaderboard table and bar chart
/profil M settings form with live preview and unsaved-changes dialog
/kiln give ruby custom item with its own model and texture; right click plays the custom sound ruby_chime
/kiln give lifesteal_sword custom enchantment kiln_content:lifesteal (bootstrap registry), heals on hit
/kiln font chat message in the bitmap font kiln_content:runes (also in a HUD label from Lua)
/kiln effect [ruby_vision|off] post-processing effect from the extension's resources
/kiln give chair|table|bench furniture: model + solid hit boxes (the bench has three seats), right click on a block places, right click sits, left click breaks
/kiln spawn golem custom entity: Bedrock bone model with walk/idle/smash/roar animations, own AI (wander, look, chase, smash sequence), enrage state below half health, sounds, saved with its chunk
creative inventory tab „Kiln Inhalte“ with the custom items; the ruby also appears under „Ingredients“

Proxy network (Velocity)

Two backends with different extensions behind Velocity, each in its own terminal:

./gradlew :example:server:runSurvival   # port 25566: shop, content, factory
./gradlew :example:server:runGames      # port 25567: quests, warps, bestenliste
./gradlew :example:server:runEmbedded   # port 25568: fabrik, content; Kiln shaded into a host plugin
./gradlew :example:server:runVelocity   # port 25565, modern forwarding
./gradlew :example:server:runClient -PquickPlay

Switch with /server games and /server survival: on every backend switch the client announces Kiln again, the new backend runs the handshake (consent only for new permissions, keyed by the proxy address) and the extensions and resources of the previous backend are replaced. Which demos a backend runs is demos in plugins/KilnExample/config.yml (empty = all).

Embedding Kiln in another plugin

kiln-server is the standalone Paper plugin (with Kotlin). kiln-server-embedded is the same runtime for shading into a plugin that already ships Kotlin (e.g. Surf-API): runtime, API and protocol, no Kotlin, no plugin descriptor, not relocated (the API must stay dev.kiln.* for the plugins that use it).

// build.gradle.kts of the host
dependencies {
    implementation("dev.kiln:kiln-server-embedded:<version>") // shaded, do not relocate dev.kiln
}
paper {
    provides = listOf("Kiln")          // plugins that depend on "Kiln" load against the host
    bootstrapper = "..."               // the host needs one: bootstrap dependencies on Kiln resolve only there
}

// the host plugin
override fun onLoad() { KilnEmbedded.load(this) }                     // registers the Kiln service
override fun onEnable() { KilnEmbedded.enable(this, KilnSettings()) } // false (logged) if Kiln cannot run here
override fun onDisable() { KilnEmbedded.disable() }

KilnSettings holds what the standalone plugin reads from its config.yml (KilnSettings.from(section) reads the same keys from any config section); Lua extension folders come from <host data folder>/kiln/extensions unless enable gets another path. Kiln checks at start that the server runs the Minecraft version its server internals were built for and that the host's Kotlin is at least the version Kiln was compiled with; if another plugin already provides Kiln (the standalone plugin), the embedded copy stays off. example/embedded-host is such a host; the dev network runs it as backend embedded (./gradlew :example:server:runEmbedded, /server embedded).

Using Kiln in your plugin

Apply the Gradle plugin dev.kiln (published to mavenLocal() for now). It adds paper-api, kiln-server-api and the Kotlin stdlib as compileOnly, generates paper-plugin.yml with Kiln as required dependency (load: BEFORE, join-classpath: true) and provides runServer (Paper + Kiln + your plugin, run/server, offline mode) and runClient (Minecraft + Fabric + Kiln runtime, run/client).

// settings.gradle.kts
pluginManagement { repositories { mavenLocal(); gradlePluginPortal() } }

// build.gradle.kts
plugins {
    kotlin("jvm") version "2.4.21"
    id("dev.kiln") version "0.1.0-SNAPSHOT"
}

// the plugin adds no repositories (works with RepositoriesMode.FAIL_ON_PROJECT_REPOS); add them here or in settings
repositories {
    mavenCentral()
    maven("https://repo.papermc.io/repository/maven-public/")
    mavenLocal()
}

paper { main = "com.example.MyPlugin" }
kiln { clientUsername = "Dev" }   // optional: version, serverPort, serverJar, clientJar, runDirectory

Commands are registered with Paper's command API (registerCommand / LifecycleEvents.COMMANDS), since paper-plugin.yml has no commands section.

Documentation

Targets: Minecraft 26.3, Paper 26.3.build.256-stable, Fabric Loader 0.20.1, Fabric API 0.164.0+26.3, Kotlin 2.4.21, LuaJ 3.0.1 (Lua 5.2).

About

Server-driven client content for Paper: a Fabric runtime that renders GUIs, keybinds and sandboxed Lua extensions shipped by the server.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages