Katton scripting language - summary
this is a summary of everything in the wiki so that people who REALLY want to script things but don't want to actually like "learn it" or are having trouble with it can feed this into AI to get help and stuff like that
you are writing scripts in Katton, a sandboxed scripting language for a minecraft paper plugin. scripts are plain text .kat files. this document is the complete syntax + api reference. follow it exactly. Katton has no type annotations, no while loop, and a small, fixed set of built in methods/objects
when asked to write a Katton script, use ONLY what's documented below. if something seems impossible with this API, say so instead of guessing a method name
1. syntax basics
- blocks use
{ }, never indentation. every{needs a matching} - comments:
// line commentand/* block comment */ - strings: double quoted only. escapes:
\n\t\"\\ - no type annotations anywhere
function f(a, b)notfunction f(a: Type, b: Type) - a script file is just a flat list of top level declarations:
val/var,function, and annotated functions (@Katton.command,@Katton.listen) - top level
val/varare evaluated once at compile time, and are shared across every function in that script (this is how you share state between a command and a listener, or between aKatton.everycallback and the rest of the script)
val maxPlayers = 8 // immutable
var currentRound = 0 // mutable
function helper(x) { // plain function
return x * 2
}
@Katton.command(name = "start", permission = "admin")
function startGame(sender, args) { ... }
@Katton.listen("player_join")
function onJoin(event) { ... }
2. types
there are exactly five runtime types, plus null. no separate int/float, everything is a decimal number
val = immutable (reassigning is a runtime error). var = mutable. use var for counters/flags/state, val for everything else
3. operators
5 + 3 5 - 3 5 * 3 5 / 3 5 % 3 -5 // arithmetic / and % by 0 is a runtime error
"Score: " + 10 // "+" concatenates when either side is a string. this also auto stringifies the other side
5 == 5 5 != 3 5 < 10 5 <= 5 5 > 10 5 >= 5 // == works on any type including strings/lists
true && false true || false !true // boolean logic
= += -= *= /= // assignment operators (var only)
4. control flow
if/else. braces are always required, even for one statement:
if (player.health < 5) {
player.sendMessage("&clow health!")
} else if (player.health < 10) {
player.sendMessage("&egetting low...")
} else {
player.sendMessage("&ayoure ok :D")
}
when: compares one value top to bottom, like a switch:
when (color) {
"red" -> { player.sendMessage("&cred team!") }
"blue" -> { player.sendMessage("&9blue team!") }
else -> { player.sendMessage("&7unknown team") } // optional
}
return: a function with no return returns null. a bare return is valid to exit early. almost always use an early return at the top of event listeners and scheduled callbacks to bail out when a condition doesn't apply
5. loops
there is no while loop. use ranges or recursion instead
for (i in 0..9) { ... } // ascending, INCLUSIVE both ends -> 0,1,...,9
for (i in 10 downTo 1) { ... } // descending, inclusive -> 10,9,...,1
for (color in ["red","blue"]) { ... } // iterate a list
for (key in { "red": 1 }) { ... } // iterate a map -> iterates KEYS
for (p in Katton.players.all()) { ... } // iterate players
break // exits the loop
continue // skips to next iteration
6. functions
three kinds:
// 1. plain helper. any number of params, call it like anything else
function addTax(price, rate) {
return price + (price * rate)
}
// 2. command handler. MUST take exactly (sender, args), no more no less
@Katton.command(name = "heal", permission = "admin" | "creative" | "all")
function healSender(sender, args) {
sender.setHealth(20)
}
// 3. event listener. MUST take exactly (event)
@Katton.listen("player_death")
function onDeath(event) {
event.player.sendMessage("&cyou died!")
}
@Katton.command rules:
namemust be lowercase letters/numbers/underscores/hyphens only, and unique across that script (and across every other script you own)permissionis exactly"admin"(only the current admin),"creative"(admin + creative- ode players), or"all"(admin + creative/spectator/survival/adventure, i.e. everyone)argsis a list of strings (everything typed after the command name)
@Katton.listen takes exactly one event name string. see the event list in section 11
7. strings (methods on any string value)
text.toUpperCase() text.toLowerCase() text.trim()
text.length()
text.contains(sub) text.startsWith(sub) text.endsWith(sub)
text.replace(old, new)
text.split(delimiter) // -> list of strings
8. lists (ordered, mutable)
val colors = ["red", "blue", "lime"]
colors[0] // index access
colors[0] = "green" // index assignment
list.append(x) list.add(x) // same thing, adds to end
list.remove(x) // removes first matching VALUE
list.removeAt(index) // removes by index
list.contains(x)
list.size() list.size // method or property, both work
list.isEmpty()
list.get(index) // same as list[index]
list.clear()
9. maps (insertion ordered, mutable)
val scores = { "red": 1, "blue": 2 }
scores["red"] // key access
scores["green"] = 0 // adds/replaces a key
map.get(key)
map.put(key, value) map.set(key, value) // same thing
map.remove(key)
map.containsKey(key)
map.size()
map.isEmpty()
map.keys() // -> list
map.values() // -> list
map.clear()
10. math namespace
Math.abs(-5) // 5
Math.min(a, b) Math.max(a, b)
Math.clamp(value, min, max)
Math.floor(x) Math.ceil(x) Math.round(x)
Math.randomInt(min, max) // inclusive whole number
Math.randomDecimal(min, max) // inclusive decimal
Math.sin(60) // ~0.866
Math.cos(60) // ~0.5
11. random picking
Katton.pick(list) // one random element, or null if list is empty
Katton.pickMany(list, n) // up to n UNIQUE random elements (fewer if list is smaller)
12. scheduling: Katton.after / Katton.every / Katton.cancel
val taskId = Katton.after(duration) { ... } // runs ONCE after duration
val taskId = Katton.every(duration) { ... } // runs REPEATEDLY forever until cancelled
Katton.cancel(taskId) // stop a task you stored the id of
duration literals: 20.ticks (= 1 second), 5.seconds, 2.minutes. also works on variables: delay.seconds
- both return a task id (a number). store it in a top level
varif you'll need to cancel it later from a different function or from inside the callback itself (self cancelling countdowns for example) - don't nest
Katton.afterinsideKatton.everyunless you really mean to spawn a new independent delayed task every single tick of the outer timer - it stacks up fast - tasks auto cancel when:
/katton stopis run, the script is reimported or deleted, you stop being the admin, the server restarts, or a person with op forcibily stops it
var countdown = 3
var countdownTaskId = 0
@Katton.command(name = "startcountdown", permission = "admin")
function startCountdown(sender, args) {
countdown = 3
countdownTaskId = Katton.every(1.seconds) {
for (p in Katton.players.all()) { p.sendTitle("&e" + countdown, "") }
countdown = countdown - 1
if (countdown < 0) { Katton.cancel(countdownTaskId) }
}
}
13. Katton.vars (persistent state)
two namespaces, each giving you a "bucket" with the same four methods:
Katton.vars.script // one shared bucket for the whole script
Katton.vars.player(uuid) // one bucket PER PLAYER, keyed by their uuid string
bucket.get(name) // null if never set
bucket.set(name, value) // accepts string/number/boolean/list/map
bucket.increment(name, by = 1) // atomic, returns the NEW value
bucket.decrement(name, by = 1) // atomic, returns the NEW value
val kills = Katton.vars.player(event.player.uuid).increment("kills")
- each individual bucket caps out at 100 distinct variable names (overwriting an existing name is allowed only brand new names count). don't generate unique variable names in a loop instead reuse a fixed set, or store a list/map as a single value instead
- persists across restartsand cleared automatically when the script is deleted
14. Katton.log
Katton.log.info(msg) Katton.log.warn(msg) Katton.log.error(msg)
sends chat messages to only you (the script owner), regardless of who triggered the code. use this for debugging, it's never for messaging players (use player.sendMessage for that)
15. Katton.players (selectors)
automatically scoped to your own world/preset there is no manual world filtering needed
Katton.players.all() // everyone in your world
Katton.players.survival() // survival + adventure mode
Katton.players.spectator()
Katton.players.creative()
16. item - Katton.item(...) and item values
val sword = Katton.item(material, amount = 1) // material = case insensitive vanilla Material name (https://jd.papermc.io/paper/1.21.11/org/bukkit/Material.html)
methods:
item.setName(text) // supports & color codes
item.setLore(["line1","line2"]) // list of strings, one per line
item.setTag(key, value) // value is always stored/read back as a STRING
item.getTag(key) // null if never set. ALWAYS null check
item.enchant(name, level) // level 1-5, unknown enchant name = runtime error
item.clone()
17. player get one from Katton.players.*, a command's sender, or event.player
properties:
player.name player.uuid player.world
player.location // { x, y, z, yaw, pitch, world }
player.health player.game_mode // "survival"|"creative"|"adventure"|"spectator"
player.is_sneaking player.is_sprinting
player.facing // 1=down 2=up 3=north 4=south 5=west 6=east
player.tool player.offhand_tool // item values for held items (air if empty)
methods:
player.sendMessage(text)
player.sendTitle(title, subtitle = "")
player.sendActionBar(text)
player.teleport(location)
player.give(item)
player.setTool(item) player.setOffhandTool(item) // replaces held item, doesn't add to inventory
player.clearInventory()
player.playSound(sound, volume = 1, pitch = 1)
player.setGlowing(glowing = true)
player.setMovementSpeed(speed) player.resetMovementSpeed() // vanilla default ~0.1
player.setJumpStrength(strength) player.resetJumpStrength() // vanilla default ~0.42
player.setInvulnerable(invulnerable = true)
player.launchForward(horizontal, vertical) // max magnitude 6 each
player.shootProjectile(projectile, speed) // max speed 6
allowed shootProjectile projectile names: arrow, spectral_arrow, snowball, egg, ender_pearl, fireball, ghast_fireball, small_fireball, dragon_fireball, wither_skull, shulker_bullet, trident, experience_bottle
note: player.setHealth(health) also exists as a method (clamped 0..max_health)
18. entity from world.entities or world.spawnEntity(...) (players NOT included)
properties:
entity.uuid entity.type entity.is_valid
entity.location
entity.health entity.max_health entity.yaw entity.pitch // living entities only
entity.tags // list of scoreboard tag strings
check entity.is_valid before using a entity reference later (example: inside a Katton.after callback). everything will throw if it's no longer valid, except is_valid/uuid themselves
methods:
entity.setHealth(health) entity.kill()
entity.setDisplayName(text) entity.teleport(location)
entity.setGlowing(glowing = true)
entity.addTag(tag) entity.removeTag(tag) entity.hasTag(tag)
entity.setMovementSpeed(speed) entity.setJumpStrength(strength) // living entities only
entity.setItem(item) // item display entities only
entity.setTeleportDuration(ticks) // display entities only, clamped 0-59
19. world - Katton.world()
properties:
world.players // list of player values
world.entities // list of entity values (no players)
methods:
world.spawnEntity(type, location) // -> entity value
world.setBlock(location, material)
world.getBlock(location) // read-only, returns material name string
world.fillBlocks(from, to, material) // inclusive box, capped at 4096 blocks per call
world.playSound(sound, location, volume = 1, pitch = 1) // heard by everyone, vs player.playSound (one person)
spawnEntity/setBlock/fillBlocks share ONE rate limit and will throw a runtime error telling you to slow down if you go too fast. don't spam these
20. event the parameter in every @Katton.listen handler
event.player // player value, where applicable
event.item // FULL item value (not a string!) where applicable. supports .getTag() etc
event.block // material name STRING, where applicable
event.entity // type name STRING, where applicable
event.projectile // type name STRING, where applicable
event.cancel() // cancels the action if cancellable. returns true/false. always safe to call
event.clearDrops() // clears the drops from when a player dies
always null check event.item and event.block (example: empty hand = null item, clicking air = null block)
21. full event list (these are the ONLY valid names for @Katton.listen)
cancellable events: interactions, block break/place, item drop/pickup. player_join/player_quit/etc are not cancellable (.cancel() just returns false)
22. Katton.makeAdminExecuteCommand
Katton.makeAdminExecuteCommand(command) // makes the CURRENT admin run a command, returns a result string
- only works in the actual game (arena), not in custom presets (besides worldedit commands)
- the command's first word must be on the allow list below (arguments after it are mostly unrestricted)
allow listed roots:
border, bring, bringall, broadcast, cleareffects, countdown, stopcd, crafting, creative,
cylinder, day, deathmessages, difficulty, togglesuicide, chatcooldown, dropping, falldamage,
freeze, hardcore, hardcorebeds, heal, healall, hideplayers, viewplayers, highlight, hunger,
iframes, interacting, keepinv, kill, killall, killmobs, mobdamage, mobspawning, mutechat,
mutespectators, nametags, naturalregen, night, oldcombat, pickup, platform, pve, pvp,
random, randomitems, reducedf3, respawntimer, setskin, setspawnpoint, spectator, survival,
team, title, tnt, winblock, autopickup, adminlock, to, goto, poll, placing, breaking,
building, clearplayer, blockattributes, elytradamage, reminder, autosmelt, hidehates, cyl,
//pos1, //pos2, //set, //undo, //replace, //center, //walls
this is also rate limited
23. custom presets (scoping rules)
outside the actual game, players have their own private "custom preset" world where normal admin restrictions don't apply, but everything is locked to affecting only yourself:
player.give/teleport/launchForward/shootProjectileonly work if the target is you.world.spawnEntity/setBlock/fillBlocks/playSoundonly work inside your own preset- mutating
entitymethods only work on entities in your own preset Katton.players.all()etc only ever return you- item tags set in your preset stay private to your preset
Katton.makeAdminExecuteCommanddoes basically nothing in a preset
24. limits - may be a tiny bit different
write scripts that comfortably stay under these. example: don't loop more than ~1000 times in one function call, don't fill huge regions in one fillBlocks call (split into chunks instead), don't generate unique Katton.vars key names in a loop
25. common errors (so you can avoid triggering them)
function parameters cannot have types: never writefunction f(a: Type)invalid permission '...': permission must be exactly"admin","creative", or"all"duplicate command name: command names must be unique per script (and across your scripts)unknown event "...": must match section 21 exactlydivision by zero: guard against zero divisorsundefined variable: don't use a variable before declaring it / check spellingcannot reassign 'val ...': usevarif it needs to changelist index N out of bounds: check.size()before indexingmissing required argument: builtin calls have required params, check signatures above
26. full worked example
// a wand that launches you forward on right click, with a 3 second cooldown per player
var onCooldown = {} // map of player uuid -> true while on cooldown
@Katton.command(name = "leapwand", permission = "all")
function giveLeapWand(sender, args) {
val wand = Katton.item("stick")
wand.setName("&aLeap Wand")
wand.setTag("ability", "leap_wand")
sender.give(wand)
}
@Katton.listen("player_rightclick")
function onLeap(event) {
val item = event.item
if (item == null || item.getTag("ability") != "leap_wand") {
return
}
val uuid = event.player.uuid
if (onCooldown.containsKey(uuid)) {
event.player.sendMessage("&cstill on cooldown!")
event.cancel()
return
}
event.player.launchForward(horizontal = 1.8, vertical = 0.65)
event.player.sendMessage("whoosh")
event.cancel()
onCooldown.set(uuid, true)
Katton.after(3.seconds) {
onCooldown.remove(uuid)
}
}
// a self cancelling countdown that shows a title to everyone, then starts the game
var countdown = 5
var countdownTaskId = 0
@Katton.command(name = "startgame", permission = "admin")
function startGame(sender, args) {
countdown = 5
countdownTaskId = Katton.every(1.seconds) {
if (countdown > 0) {
for (p in Katton.players.all()) {
p.sendTitle("&e" + countdown, "")
}
countdown = countdown - 1
} else {
for (p in Katton.players.all()) {
p.sendTitle("&aGO!", "")
}
Katton.cancel(countdownTaskId)
}
}
}
checklist before returning any Katton script
- every
@Katton.commandfunction takes exactly(sender, args); every@Katton.listenfunction takes exactly(event) permissionis"admin","creative", or"all": nothing else- event names come only from section 21
- no
whileloop anywhere: usefor (i in a..b)/downTo/recursion - no type annotations on function parameters
- null checked anything that can be null (
event.item,event.block,.get(...)results,Katton.pick(...)) - loops/operations stay comfortably under the limits in section 24
- if storing a task id for later cancellation, it's a top level
var, not a localval