# Katton.vars (state)

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

### two separate namespaces

```csharp
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:

```csharp
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

```csharp
@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

```csharp
@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

```csharp
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`/`increment`ed before

### storing more than numbers

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

```csharp
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

```csharp
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

```csharp
// don't do this, it'll hit the cap and start erroring
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
