Account-scoped remote key/value storage with in-memory caching in the DLL.

Values are isolated per RuneScape account. The DLL resolves the current account name from the local player or stored account metadata, scopes the key automatically, and caches reads in memory to avoid repeated remote calls.

kvstore:get(key: string) -> string|nil

Get a value for the current account.

Parameters:

• key (string) - Logical key name for the current RuneScape account

Returns:

• string|nil - Stored value, or nil if the key is missing or the lookup fails

Example:

local task = kvstore:get("last_task")
if task then
    logger:info("Last task: " .. task)
end

---

kvstore:set(key: string, value: string) -> boolean

Store a value for the current account.

Parameters:

• key (string) - Logical key name
• value (string) - Value to store

Returns:

• boolean - true on success, false on failure

Example:

kvstore:set("last_task", "mine_iron")
kvstore:set("bank_pin_state", "known")

---

kvstore:delete(key: string) -> boolean

Delete a value for the current account.

Parameters:

• key (string) - Logical key name

Returns:

• boolean - true if a value was removed, false if the key did not exist or the operation failed

Example:

kvstore:delete("temporary_flag")

---

kvstore:keys() -> string[]

List all stored keys for the current account.

Returns:

• string[] - Array of logical key names for the current account. Returns an empty table on failure.

Example:

for _, key in ipairs(kvstore:keys()) do
    logger:info("Stored key: " .. key)
end

---

kvstore:all() -> table<string, string>

Get all stored key/value pairs for the current account.

Returns:

• table<string, string> - Table of all values for the current account. Returns an empty table on failure.

Example:

local state = kvstore:all()
for key, value in pairs(state) do
    logger:info(key .. " = " .. value)
end

---

kvstore:clear_cache() -> ()

Clear the in-memory kvstore cache held by the current DLL process.

Use this when you know values may have changed remotely and you want the next get() to fetch fresh data.

Example:

kvstore:clear_cache()

---

local run_count = tonumber(kvstore:get("run_count") or "0") or 0
run_count = run_count + 1
kvstore:set("run_count", tostring(run_count))

---

local last_task = kvstore:get("last_task") or "idle"

if last_task == "idle" then
    kvstore:set("last_task", "banking")
end

---

kvstore:delete("last_task")
kvstore:delete("last_bank")
kvstore:clear_cache()

---

• Keys are automatically scoped to the active RuneScape account.
• Values are stored remotely, but reads are cached in the DLL process.
• Public API methods log internal errors and return fallback values instead of throwing Lua errors.
• keys() and all() return empty tables on failure.

• Stats API - Ephemeral script statistics for UI/reporting
• Logger API - Logging kvstore reads/writes and debugging state