Skip to main content

Cluster operation in 2.56.0

Mod version shipped with FlammiCraft: 2.64.0

Overview

TDClaim rental payments

Starting in TDEconomy 2.62.0, the backend holding the player's account lease processes the rent charge. The requesting backend can acquire the lease for an offline payer without one. TDEconomy respects reserved funds and saves one shared receipt per attempt. A queued charge retains its ID across restarts and connection failures. Upgrade all economy backends before enabling rental offers. Back up and restore the TDClaim world data together with the shared ledger.

Manually install matching builds on every backend and client, then fully restart them. The following behavior is implemented and tested with isolated backends and a local test database. Gameplay acceptance remains pending.

Accounts and permissions

Account definitions, names and permissions share one writer lease. A backend refreshes these definitions before using the lease. Competing edits or payments involving these accounts can be temporarily unavailable; wait briefly and retry. Administrative success replies wait for the database commit. A conflicting save reports failure instead of silently losing an acknowledged change. System payout totals change atomically with the payment or confirmed delivery, including refunds and restart recovery; delayed backends cannot overwrite newer totals.

Transfers acquire all balance leases they need together, including incoming capacity. Opposite transfers cannot keep exchanging incomplete lock sets. Creating or renaming accounts is serialized across backends; duplicate stored account names stop loading without discarding an account. Do not resolve that error by deleting account records.

Since 2.57.0, when a player joins, the database worker creates their row in tdeconemy_accounts with the starting balance if it is missing. Rejoining or switching backends preserves the stored balance, including zero. If the database is unavailable, the worker retries the queued creation. Previously seen players without a row are recorded when they next join.

Shops and interrupted purchases

Database-mode item and mob shops confirm payment on the worker before delivering anything. The server then checks the offer, distance, permissions, stock and capacity again. A refused payment delivers no goods. The affected balances remain fenced until the delivery is confirmed or refunded, including when an ordinary account lease expires.

Closing a screen does not cancel a submitted purchase. Wait for its result before trying again. A restart refunds a payment whose delivery was not saved; a saved delivery confirmation is replayed without charging again. Deleting or deactivating the final shop entry also removes its shared offer using the previous dimension ownership.

Quest progress and world saves

Confirmed action events are queued with unique IDs and their original attempt and timestamp. Only the current quest writer applies them. The event acknowledgement commits with the quest document; duplicate delivery cannot increase progress twice. Saved queues survive outages and sender restarts. Events from an obsolete attempt do not credit its replacement. See quest progress.

A payment epoch is settled only after its economy marker can actually be read from the saved world file. Preparing a save or waiting for a fixed delay is not proof that its write succeeded.

Shared notifications

TDEconomy 2.62.0 requires TDLibrary 0.72.0 or newer. Account activity goes through the shared TDLibrary inbox. The receiving backend shows a live hint after the archive write and checks current account permissions.

From 2.64.0 TDEconomy borrows its database connections from TDLibrary's shared pool and requires TDLibrary 0.74.0 or newer. A database read stuck for more than 30 seconds is stopped; the economy then reports the database as unavailable and recovers like after an outage. A booking that waits for a row another server holds locked is still tried up to three times with ten seconds of waiting each.

If the world-file write fails during export, the backend logs the error and defers the export until the next attempt. Notifications are published after the save succeeds.

Confirmed group account invitations appear in the shared inbox. Accept or decline them in the economy dashboard. If another backend is updating account metadata, wait briefly and retry the response.

Since 2.58.0, database mode stores stock warnings and order notifications in MariaDB. The TDLibrary inbox shows eligible notifications after a backend switch. An active warning from another backend shows unverified stock. When the owning backend resolves the warning, the inbox reflects the new state.

Shop tenure restrictions use the earliest first-join time recorded across the backends. Account notification preferences apply across backends as well. Each backend imports its first-join records and preferences alongside its notifications. If two saved preferences for the same player and account differ, the import stops and logs the affected key.

Administrator shop presets are available on every backend in database mode. TDEconomy checks the location and permissions on the backend where the shop is placed. The import stops when different presets share a name and preserves both sources.

Stop all TDEconomy backends and back up MariaDB together with every backend world before updating. The first start upgrades economy database schema 2 to 3. Each backend backs up its world file, imports its notifications with their existing IDs and removes them from the world file after reading them back successfully. A conflict preserves the world file. Restoring an older version requires the matching database and world backups.

World names and the market

TDEconomy identifies locations by backend, dimension ID and coordinates. Operators can set a display name with /money cluster world-name <backend> <dimension> set <name> or clear it with /money cluster world-name <backend> <dimension> reset. Without a display name, the market shows the dimension ID and backend ID. Copied coordinates include the backend ID. Market waypoints are available on the shop's backend.

The market shows published effective prices and combines statistics from the backends. A remote offer stays visible with its stock marked unverified. Trading takes place at the sign.

The owning backend stores trade quotas and market changes with the confirmed delivery. During the update, TDEconomy uses the previous dimension ownership records to assign existing shop and quest locations. Startup stops and logs the location if its previous owner cannot be determined.

Orders and titles

The order board shows public and eligible personal orders from other backends. Management, delivery and collection take place on the displayed backend. MariaDB stores order state, reservations and related payments together. Inventory recovery remains in the world of the backend that performed the action.

Earned and purchased titles are available across backends. A title payment and its entitlement are committed together. After chat confirms payment, reopen the title menu to use the title. The import preserves existing entitlements. Complete the import on all existing backends before players resume buying titles.

Backups and recovery

The build adds a quest-event queue and delivery bookkeeping when database storage starts. Keep the economy database and all backend worlds together when backing up or restoring. Do not remove pending operations, quest events or lease rows to clear a busy response. Inspect the server log and the affected operation instead. Persistent delivery-finalization errors retain the payment lock for recovery.

No database settings or worlds are changed by a local build. Installation, database startup and manual runtime checks remain operator tasks.

Manual acceptance

  1. Trade on two backends, including two shops using the same account, and verify items and balances.
  2. Revoke a member's spending rights on another backend. During handoff an action must wait or fail; after refresh, the revoked permission must deny withdrawal and shop payment.
  3. Rename a group while editing its permissions on another backend. Verify both accepted changes and explicit rejection of competing saves. Try simultaneous creation under the same name.
  4. Progress quests with different players on different backends and compare progress before and after a portal transfer. Check completion and reward collection once.
  5. Remove a shop and verify its index and offer disappear from other backends.
  6. Perform outage, interrupted-delivery and failed-save fault injection only in disposable test worlds with a separate test database. Reconnect and restart before comparing the saved result.

Existing world and empty database

Start a backend with the previous database marker first. TDEconomy backs up the world file under tdeconomy-migration-backups and binds it to the new ledger. Its old outbox stays in the backup, since replay without original receipts could duplicate payments. Other worlds from the same previous cluster can follow. A populated foreign ledger, a mismatched backend ID or a partially deleted ledger with surviving data prevents adoption. Existing shop eligibility timestamps take precedence. New players use their first observed login. Tenure-restricted shops wait for that lookup. Use a UUID for an ambiguous admin transfer target.