[1robie]

Summary

Replaces zMenu's single SQL storage with pluggable storage providers, moves player data into a variables table shared with new server and global variables, and lets several servers share one database safely. Also adds dialog canvases and rewrites the packetevents hook. Existing data is copied over on the first start and the old tables are kept; the old player data API keeps working and is deprecated (since = "1.1.2.2", forRemoval = true) in favour of VariableService.

Storage providers

• storage-type now selects a StorageProvider (experimental SPI in fr.maxlego08.menu.api.storage.spi), registered in the new STORAGE_PROVIDER registry. Addons can add their own backend.
• Built-in: SQLITE, MYSQL, MARIADB, POSTGRESQL, REDIS (standalone or Cluster), MONGODB, and NONE (in memory until the server stops). The Redis, PostgreSQL and MongoDB drivers are downloaded only when config.yml asks for them.
• Writes run one at a time, in the order they were made; reads run on their own threads.
• /zm storage migrate <type> copies every zMenu data to another storage (confirm by running it twice). migration-database-configuration gives the target its own connection, for example MariaDB to PostgreSQL. /zm storage status shows the storage in use.
• database-configuration.properties passes driver properties (sslmode, allowPublicKeyRetrieval, ...).

Variables

• The data action takes scope: player (default), server (one value per server-id) or global (shared by every server). Placeholders: %zmenu_server_value_<key>%, %zmenu_global_value_<key>% and the _key_exist_, _expire_, _expire_format_, _is_expired_ variants. Commands: /zm variables <get|set|add|subtract|remove|keys> <server|global> ....
• add and subtract send the amount to the database, which adds it (SQL COALESCE + ?, Redis HINCRBYFLOAT, MongoDB $inc), so two servers adding at once both count. Decimals are kept. An addition to an expired value starts again from 0.
• Player data is read just before a player joins and kept while they are online. Offline lookups are read in the background and kept for 5 minutes. Nothing is read for every player at startup any more. Changes are batched every batch-task seconds and merged per variable.
• Expired values are purged every 10 minutes.

Multi-server

• Servers sharing a database tell each other about changes: an events table polled every messaging-poll-interval seconds (messaging-type: AUTO/SQL), Redis pub/sub (REDIS), or nothing (NONE). A server re-reading a changed value never hides a write of its own that is not stored yet.
• Player sessions: a player joining a server waits up to session-handoff-timeout ms for the server they left to store their data. A refused login releases the session. Servers heartbeat, and a duplicate server-id is reported.
• Saved inventories (clear-inventory) are kept per server in saved_inventories, so items taken on one server are only given back there.

Data migration on first start

• player_datas is copied into variables and player_inventories into saved_inventories (to the first server that starts), each in one transaction; the old tables are untouched.
• Requires Sarah 1.27.

Dialog canvases

• dialog-canvas body: images and text at pixel positions inside a dialog (Paper 1.21.6+). Images come from resource-pack/textures, vanilla, Nexo, ItemsAdder or CraftEngine; text uses the vanilla font or resource-pack/fonts.yml.
• Canvas API (fr.maxlego08.menu.api.dialog.canvas, MenuPlugin#getCanvasManager()) and the GLYPH_PROVIDER, CANVAS_PACK_TARGET, CANVAS_ELEMENT registries.
• Dialog custom-click buttons use a per-player click table instead of Paper click callbacks kept for 12 hours.

packetevents hook

• Rewritten around one packet listener and one session per player, shared by the title, title animation, hidden inventory and click limiter features.
• Fixes clear-inventory-type: PACKET_EVENT showing the real inventory after a shift-click or resync, show-items-after-animation showing items too early, items looking lost after a blocked fast click, and listeners left registered after a reload.

Fixes

• A saved inventory given back on shutdown is removed from the database (no second copy on the next join).
• Visited worlds and played animations are read back correctly. They always came back empty, so first-join items and one-time animations repeated.
• Visited worlds are no longer read on the main thread at every join.
• MySQL/MariaDB deadlocks between two servers creating the same value are retried.

Compatibility

• DataManager, PlayerData, Data, the player data methods of StorageManager and the storage.dto records are deprecated and still work. DataManager#getPlayer only returns players in memory; use loadPlayer(UUID) for offline players.
• The ItemsAdder hook now targets ItemsAdder 4; ItemsAdder 3 is no longer supported.

Tests

• Contract suites for every provider, two-server suites (handoff, shared increments, clears), and migration tests. They pass on SQLite, memory and embedded Redis/MongoDB, and against real MySQL 8.4, MariaDB 11, PostgreSQL 16, Redis 7 and MongoDB 7 (enabled with -Dzmenu.it.<backend>=host:port, see RealDatabases).
• run-paper task for a local test server.