Katton.vars (state)

this is another way you can use variables without relying on lists or maps within your scripts

two separate namespaces

Katton.vars.script // private to this one script
Katton.vars.player(uuid) // private to this script, split per player

each one gives you a bucket with the same four methods:

bucket.get(name)
bucket.set(name, value)
bucket.increment(name, by = 1)
bucket.decrement(name, by = 1)

`Katton.vars.script` = one shared value for the whole script

@Katton.command(name = "usecounter", permission = "all")
function useCounter(sender, args) {
    val uses = Katton.vars.script.increment("total_uses")
    sender.sendMessage("&7this command has been used " + uses + " times total")
}

`Katton.vars.player(uuid)` = one value per player

@Katton.listen("entity_death")
function onKill(event) {
    if (event.killer == null) {
        return
    }

    val kills = Katton.vars.player(event.killer.uuid).increment("kills")
    event.killer.sendMessage("&atotal kills: " + kills)
}

each player gets their own independent "kills" counter. Player A's kills and Player B's kills are different, even though theyre using the exact same script and the exact same variable name

reading a value that was never set

val visits = Katton.vars.player(player.uuid).get("visits")

if (visits == null) {
    Katton.log.info("first time seeing this player!") // shows to you
}

get returns null for a key that's never been set/incremented before

storing more than numbers

set accepts strings, numbers, booleans, lists, and maps:

Katton.vars.player(player.uuid).set("last_team", "red")
Katton.vars.player(player.uuid).set("unlocked_items", ["wooden_sword", "diamond_sword"])
Katton.vars.script.set("game_config", { "rounds": 5, "delay": 3 })

`increment`/`decrement` are atomic

val newTotal = Katton.vars.script.increment("total_uses") // +1 by default
val newTotal2 = Katton.vars.script.increment("total_uses", by = 5) // +5
val newTotal3 = Katton.vars.script.decrement("total_uses") // -1

they return the value after applying the change, so you can use the result directly rather than calling get again afterward

each bucket caps out at 100 variables

Katton.vars.script and each individual Katton.vars.player(uuid) bucket can hold up to 100 distinct variable names. overwriting a variable you've already set never counts against this, only creating a brand new one does

// don't do this, it'll hit the cap and start erroring after 500 calls
Katton.vars.script.set("event_" + Katton.vars.script.increment("event_count"), data)

// reuse a fixed, known set of variable names instead
Katton.vars.player(player.uuid).set("last_event", data)

if you genuinely need to track more than 100 things per player/script, store them as a single list or map value instead of 100+ separate variable names