Server-driven client content for Paper.
Real GUIs, keybinds and sandboxed Lua extensions, shipped by the server and rendered natively on the client.
Status: prototype. APIs, protocol and package format still change between versions.
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,loador 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
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}!")) }| 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 |
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 + pluginConnect 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.
| 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“ |
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).
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).
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, runDirectoryCommands are registered with Paper's command API (registerCommand / LifecycleEvents.COMMANDS), since
paper-plugin.yml has no commands section.
docs/design.md: architecture, protocol, GUI elements, keybindsdocs/lua-extensions.md: extension packages, delivery, consent, sandbox, Lua APIdocs/ui_kit.md: theui_kitcomponent library
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).