Aller au contenu

moonbot.memory — Mémoire des scripts

Mémoire des scripts MoonBot (moonbot.memory) : données persistantes partagées par tous vos comptes et Controllers, sans action Mon IA.

14 fonctions dans ce namespace.

Index

Référence

Une mémoire partagée par tous vos comptes, sans coût Mon IA

-- Script principal : n'importe où ; Controller : dans tick()
local total = moonbot.memory:get("elevage:oeufs") or 0

moonbot.memory est une mémoire clé → valeur durable, partagée par tous vos comptes et vos Controllers, quel que soit leur worker : une valeur écrite par un compte est lue par les autres et survit à l'arrêt des scripts comme aux redémarrages. Mêmes noms dans les scripts principaux et les Controllers ; dans un Controller, appelez-la seulement dans tick, comme tout appel au serveur. Lire ou écrire ne consomme aucune action Mon IA. Le dashboard l'affiche et la modifie dans Controllers › Mémoire des scripts.

moonbot.memory:get

moonbot.memory:get(key: string)

returns valeur | nil

Valeur de la clé, nil si elle n'existe pas ou a expiré. Une table revient en table Lua (tableau ou table à clés chaînes).

moonbot.memory:set

moonbot.memory:set(key: string, value, ttl_seconds?: number)

returns true

Écrit ou remplace la valeur : nil, booléen, nombre, chaîne ou table (tableau sans trou, ou table à clés chaînes ; ni fonction, ni cycle, ni table mixte, 16 niveaux au plus). value = nil supprime la clé. ttl_seconds, de 1 s à 1 an, la fait expirer ; sans TTL, elle reste jusqu'à sa suppression.

moonbot.memory:delete

moonbot.memory:delete(key: string)

returns boolean

Supprime la clé ; true si elle existait.

moonbot.memory:getEntry

moonbot.memory:getEntry(key: string)

returns {key, value, version, updated_at, updated_by, expires_at} | nil

La valeur et ses métadonnées : version (augmente à chaque écriture), updated_at et expires_at en secondes Unix (expires_at = nil sans TTL), updated_by = « account: » (script principal), « controller: », « mcp » (Mon IA) ou « dashboard ».

moonbot.memory:list

moonbot.memory:list(prefix?: string, limit?: number, after?: string)

returns entrée[] (+ next_after)

Entrées (forme de getEntry) dont la clé commence par prefix, triées par clé : 100 par défaut, 500 au plus, moins si les valeurs sont grosses. S'il en reste, le tableau porte next_after : passez-le en after pour la page suivante (nil en fin de liste).

moonbot.memory:keys

moonbot.memory:keys(prefix?: string, limit?: number, after?: string)

returns string[] (+ next_after)

Comme list, mais seulement les clés (et next_after s'il en reste) : plus léger pour compter ou parcourir.

moonbot.memory:increment

moonbot.memory:increment(key: string, delta?: number = 1, ttl_seconds?: number)

returns number

Ajoute delta de façon atomique et rend la nouvelle valeur : deux comptes qui incrémentent au même moment ne perdent aucun ajout. Une clé absente vaut 0 ; une valeur non numérique lève une erreur.

moonbot.memory:setIfAbsent

moonbot.memory:setIfAbsent(key: string, value, ttl_seconds?: number)

returns boolean

Crée la clé seulement si elle n'existe pas : true si cet appel l'a créée, false si elle était déjà là. Sert de verrou ou de réservation entre comptes ; donnez-lui un TTL pour qu'un verrou oublié (bot coupé en route) se libère seul.

moonbot.memory:usage

moonbot.memory:usage()

returns {keys, bytes, max_keys, max_bytes, max_value_bytes}

Place occupée par vos clés et limites de votre compte MoonBot.

Limites

-- clé : 1 à 200 octets UTF-8, sans caractère de contrôle
-- valeur : JSON de 64 Kio au plus
-- 10 000 clés et 16 Mio (clés + valeurs) par utilisateur
-- TTL : de 1 s à 1 an
-- débit : 50 écritures/s (rafale 500), 500 lectures/s (rafale 5 000)

Limites par utilisateur MoonBot, tous comptes confondus. Le débit est compté par utilisateur et par processus (chaque worker, le serveur). Une écriture refusée (clé trop longue, valeur trop grande, mémoire pleine, débit dépassé) lève une erreur qui donne son motif : attrapez-la avec pcall pour réessayer plus tard.

Exemple — compteur commun à tous les comptes

-- Chaque compte ajoute sa récolte au total commun.
local total = moonbot.memory:increment("elevage:oeufs", 4)
global:printMessage("Oeufs récoltés par tous les comptes : " .. total)

increment est atomique : avec get puis set, deux comptes qui ajoutent au même moment écraseraient l'ajout de l'autre.

Exemple — réserver un enclos public

local cle = "enclos:" .. map.currentMapId()
if moonbot.memory:setIfAbsent(cle, global.accountTag(), 600) then
  -- enclos réservé 10 min par ce compte
  -- ... nourrir, récolter ...
  moonbot.memory:delete(cle)  -- libéré dès la fin
else
  global:printMessage("Enclos déjà pris par " .. tostring(moonbot.memory:get(cle)))
end

Un seul compte obtient true : les autres voient la réservation et passent leur tour. Le TTL de 600 s libère l'enclos même si le bot est coupé avant le delete.

Exemple — parcourir une famille de clés

local after = nil
repeat
  local page = moonbot.memory:list("elevage:", 100, after)
  for _, entry in ipairs(page) do
    global:printMessage(entry.key .. " = " .. tostring(entry.value))
  end
  after = page.next_after   -- nil : fin de la liste
until not after

list rend au plus limit entrées triées par clé, moins si les valeurs sont grosses : seul next_after dit s'il reste des entrées, jamais le nombre reçu.