TDLibrary operation reference
Mit FlammiCraft ausgelieferte Mod-Version: 0.76.0
Diese Detailseite ist derzeit auf Englisch verfügbar.
Installation
Install tdlibrary-0.51.0.jar on every side that runs a dependent TD mod. A server-only consumer needs TDLibrary only on the server. Client UI consumers keep their own client/server installation requirements.
Shared item insertion uses neutral live slot-index contracts. Unsupported inventories retain their original helpers, and all transfers use the protected outer capability. AE2 Reforged supplies its native implementation without a reverse TDLibrary dependency.
Mounted fuel extraction is maintained directly in Create; TDLibrary no longer inspects Create or TDCreate class names.
LDLib2 2.2.37 or newer is required on both client and server. Messages use its controls with the shared TD backdrop. Client classes remain separate from the dedicated-server core. TDLibrary bundles the shared MariaDB driver; it does not embed installed mod JARs, LDLib2, Taffy or Yoga.
For Architectury 13.0.11 and 13.0.12, an optional client patch gives only ClientTickEvent.CLIENT_POST a copy-on-write listener list. Every dispatch uses a stable snapshot, so concurrent registration or removal cannot invalidate its iterator. Listener order, duplicates, removal of the first matching registration and exception propagation are preserved. Changes during a callback become visible on the next dispatch, and no callbacks execute under the registration lock. Other Architectury events keep their original implementation. Without Architectury, or with another version, the patch is skipped; unsupported versions produce a log warning. Architectury is not bundled or required at runtime.
With Sound Physics Remastered 1.21.1-1.5.2, TDLibrary uses default acoustics while the client level cache is unavailable during a world transition. Spatial audio resumes as soon as the cache is available. This patch applies only on the client.
An optional ShetiPhianCore client patch queues its resource-pack texture initialization through FMLClientSetupEvent.enqueueWork. This keeps reload-listener registration off parallel loading workers while preserving the initial texture mappings and later reloads. It applies only when the installed setup method contains the compatible direct initialization call; otherwise it skips the repair with a warning. ShetiPhianCore is not bundled or required at runtime.
Optional ShetiPhianCore bonemeal repairs build stripping contexts without reading a dummy world chunk and publish the entire initial bark lookup before parallel regions read it. Native stripping hooks, simulation and bark selection remain intact. An optional spark adapter also invokes its own cleanup for the matching stopped server after a crash; normal stops retain spark's existing cleanup.
With All The Leaks 1.1.16, TDLibrary automatically skips the forced garbage collection after world saves when a dedicated server stops. The patch applies only to this shutdown call.
Starting with TDLibrary 0.70.0, the same integration fixes the startup crash caused by client access in ingredient diagnostics. Dedicated server log reporting remains available.
Client ZIP resource enumeration uses one namespace index per opened file resource pack. Queries retain ZIP entry order, and Minecraft still filters paths, validates locations and opens the original entries. Closing the pack clears the index; a different ZIP handle rebuilds it. This applies to client resource reloads and integrated-server data reloads without changing pack priority or enabling ModernFix beta features. Indexing uses Java's ZIP API and does not copy resource contents.
Block-state model loading builds property/value indexes lazily for large native state lists instead of rescanning every state for each variant. Minecraft retains its predicate, model consumers, overlap handling and resource-pack precedence. Each definition load owns its index; nested calls restore their caller's context and failures release it. Small, copied, reordered and externally filtered state lists retain the original scan. This client-only optimization does not disable ModernFix dynamic resources or change Xaero map sharing, model-baking thread ownership, world data or map formats. It reduces repeated state selection work; model baking itself still has a cost, and gameplay acceptance requires a separate pack run.
With MoreCulling 1.0.10 or newer and ModernFix 5.27.26 or newer installed on the client, TDLibrary replaces both eager MoreCulling cache reloads with lazy, per-block-state initialization if ModernFix's dynamic resources are enabled and the required structures are compatible. Culling settings and model adapters remain in use. Shape and translucency caches initialize together, concurrent chunk queries wait for completion, recursive model queries leave faces visible, and resource reloads invalidate previously calculated values. Models are not retained by this patch. TDLibrary checks cache APIs, Mixin targets and priority, and both cache-only reload callbacks at startup. Compatible updates remain enabled automatically; incompatible structures retain the original behavior with a log warning. MixinSquared is bundled; MoreCulling and ModernFix remain separate optional mods. First use of a block can still require model work; gameplay and resource-pack reload acceptance remain manual.
Open Messages with /tdnotify, an assigned key under Controls > TD Notify, or the optional FTB Library inventory sidebar button beside the TD tools. FTB Library 2101.1.37 or newer supplies the optional client-only new-message overlay; it is not bundled. Economy and Groups menus open the same inbox with their area selected and retain the originating screen. Current shows open tasks and explicitly unverified conditions, New shows unseen relevant information, and History retains all accessible messages. Source providers check current state before view filtering and before actions, so old resolved messages do not become active just because they are unread. Search matches message titles and bodies as resolved on the server, including item/shop names. Area selection uses display names instead of typed mod IDs. Local session messages remain accessible from History.
Notification protocol 4 requires matching TDLibrary client and server versions. Page replies are matched to their request and cannot overwrite a reopened inbox or a newer filter request. Read-status refreshes preserve the open detail's source-action receipt until its original expiry and recheck current permissions. Open lists and details refresh every five seconds while idle. Reading or marking messages seen never resolves the underlying problem. Login does not post unread-history reminders; the quiet sidebar marker tracks relevant unseen messages. Completed and unverified states produce no pop-up or marker. Standard mode shows only important pop-ups, Quiet collects everything in the inbox, and Detailed allows routine pop-ups; explicit saved source/category channel preferences remain effective. Required direct operation feedback cannot be muted. Requests allow up to eight operations per player and 128 globally per rolling second.
Modpack version gate
For FlammiCraft, set requirePackVersion = true in the dedicated server's
config/tdlibrary-server.toml and restart the server. This uses NeoForge's SERVER
config type; a world-local serverconfig/tdlibrary-server.toml overrides the global
file if present. It defaults to false
so other TDLibrary installations remain unaffected. Client settings cannot disable
the server's requirement. The gate is never enabled for an integrated singleplayer server.
Both sides need TDLibrary with pack-version protocol support and their own
config/fancymenu/pack_version.txt relative to the game directory. FancyMenu is
not required on the server. The file must contain one UTF-8 version label, for
example FlammiCraft 2.6.11. A BOM and surrounding whitespace are ignored; the
remaining text is compared exactly, including the pack name and case. Labels
are limited to 128 characters and files to 1024 bytes. No version file is written.
The dedicated server snapshots its required version at startup and refuses to start if the enabled gate cannot read a valid version. Each connecting client reads its own file when requested. A configuration task blocks world entry until the server receives a matching reply. Older and newer versions, unreadable client files and missing protocol support are rejected. A nonresponsive check is disconnected after 20 seconds, checked on server ticks; closed connections are discarded.
After changing the server's TXT file, run /tdlibrary packversion reload as an
operator (permission level 2) or from the server console. The command reports the
new required version and applies it to subsequent join checks without restarting.
Checks already in progress retain their original requirement; connected players
are unaffected. If the file is invalid or unreadable, the command fails and the
previous version remains active. The command requires the gate to be currently
enabled and does not change the requirePackVersion setting.
Use /tdlibrary packversion enable or /tdlibrary packversion disable with the
same permission to toggle the gate on a running dedicated server. Enabling always
rereads the TXT, including when the gate was disabled at startup; an invalid or
unreadable file leaves the previous state unchanged. Disabling skips version checks
for subsequent joins. Checks already in progress retain their original requirement,
and connected players are unaffected. Both commands apply until the next server
start, when requirePackVersion from the server config determines the initial state.
The commands do not write the config or version file and cannot enable the gate in
singleplayer.
A mismatch displays both versions and this German restart hint: "Bitte starte Minecraft neu. Das Update wird automatisch durchgeführt." TDLibrary only supplies the hint; the pack's existing updater performs the update. German and English messages are included, with German fallback text for clients without these translation keys. Earlier Minecraft/NeoForge incompatibility checks may reject a connection before this gate can show its message.
This verifies the reported version label, not the contents or integrity of the installed pack. Manual acceptance: connect with matching, older, newer and missing client versions, test a client without the new protocol, and confirm singleplayer and a dedicated server with the gate disabled still work. Verify the automatic update and successful reconnect separately through the actual launcher.
CPU computations
The server shares two CPU workers by default across consumers. config/tdlibrary-common.toml configures workers, retained, consumerLimit, applicationsPerTick and applicationMicros. On the next mod load, an existing legacy tdlibrary-compute.toml is copied to the common file only if the common file does not exist, retaining its settings and comments; the legacy source is left untouched and is no longer registered. Worker count and capacity take effect on the next server start; application budgets are read each tick. /tdlibrary compute requires operator permission level 2 and reports all consumers. See the callback computation API and verification boundaries. These workers never run database operations.
Settings automatically load the selected area, or the all-mod default (*) when no area is selected. Click Area to cycle through available sources. Choose a profile or toggle chat, pop-ups and sound, then use Save settings and wait for confirmation. Reload settings retries a failed load or discards unsaved edits by rereading the selected area's saved values. Category settings override source settings, which override the all-mod default. Existing overrides remain intact. Required direct feedback stays visible. Sound defaults to off. Local client messages have separate, bounded session history; they cannot create server archive entries or read receipts.
Configure the connection using the notification setup guide, then enable MariaDB. TDLibrary automatically creates the configured database if missing, creates its tables and checks the required columns on the archive worker. No manual SQL script is needed. While disabled or unavailable, important events accumulate in the durable world-local outbox; history and read-status failures are shown explicitly.
Notification payloads require utf8mb4, including for emoji and other supplementary Unicode characters. New payload columns use it explicitly; an incompatible existing column stops archive operations with a clear error and is never converted automatically. Malformed local outbox operations move to outbox/quarantine/ with their original contents preserved and their recovery path logged, allowing valid operations to continue. Database outages and local I/O failures leave active operations available for retry. Read acknowledgements refresh the current filtered page without changing its navigation cursor.
Consumer installation and gameplay acceptance are separate from this repository's build. See verification for the checks and remaining manual boundaries.
Shared database setup
From 0.65.0 config/tdlibrary-database.toml holds the one MariaDB connection of all TD mods; the mods have no database settings of their own. Register it as a NeoForge COMMON config and keep it private. In its [database] section, set host, port, database, user, password and tls_mode. tls_mode accepts DISABLED, REQUIRED (encryption without server identity verification) or VERIFY_FULL.
Database pool API (0.74.0): DatabasePools.get(owner, PoolOptions) returns the pool of one mod; use a fixed lowercase owner such as tdclaim. PoolOptions.of(maxConnections) sets the share (1 to 16); withLockWaitSeconds sets innodb_lock_wait_timeout (default 3), and the socket timeout is always raised above it. withSessionSql adds SET statements that run once on every new connection. DatabasePool.connection() lends a connection that close() returns; the pool rolls back an open transaction and restores auto-commit, isolation and read-only mode first. A connection that called GET_LOCK through prepareStatement is closed instead of reused, so its named lock ends with it. read(work) runs work on a lent connection, transaction(work) commits it and repeats it up to three times after a deadlock or lock wait timeout. Waiting for a connection ends after acquireTimeoutMillis (default 5000) with SQLTransientConnectionException. Pools stay usable after the server stopped event, so late shutdown writes still work. DatabasePools.stats() reports usage per pool. MariaDbConnections.open remains for tools and tests.
With enabled = true every TD mod on a dedicated server keeps its server data in this database, each in its own tables: the TDLibrary notification archive, the TDEconomy economy and transaction history, TDGroupe groups, titles and active time, and the TDUtilities activity log. Missing databases and tables are created automatically. The first start imports each mod's world data, so set enabled = true and restart only when that database operation is intended. migration_conflicts decides what happens when the database already holds different data: REFUSE (default) stops the server start, KEEP_DATABASE keeps the database copy. Single-player worlds always keep their data in the world folder. Without an archive, important events stay in the world's tdlibrary-notifications/outbox.
Mods use DatabaseConfig.active(server), DatabaseConfig.jdbcUrl() and DatabaseConfig.credentials() instead of their own settings.
Player name history
From 0.67.0 TDLibrary keeps a name history of players in the table td_player_name on dedicated servers with [database] enabled = true. Each row holds the player UUID, the name (up to 64 characters, exact spelling), a lower-case copy for lookups and seen, the time the name was first seen in milliseconds since 1970 (UTC). The first login adds one row, a login under a new name adds another and older rows stay; a login with an unchanged name adds nothing. A case change or a return to an earlier name counts as a new name. A login older than the newest stored row is ignored, so replayed logins never reorder the history. The table is created automatically and rows are never changed or deleted. The newest login of each player lives in a second table, td_player_seen (player UUID and last_seen, one row per player): every login writes it in the same transaction with an upsert that only moves the time forward (GREATEST), so a replayed login or a clock that went back never moves it back. A separate table keeps the name history insert-only. Vanilla and Floodgate names have at most 16 characters (Floodgate shortens the gamertag so that its prefix, . by default, fits); the wider column only keeps longer names from proxies that do not enforce this limit.
Database work runs on its own worker thread; the last login uses the same queue. During an outage up to 1024 logins wait and are retried; they are also kept in tdlibrary-player-names/pending.json in the world folder, so a stop or crash does not lose them. When the server stops, TDLibrary tries a last write for at most three seconds; the next start writes what is left. An unreadable file is renamed to *.invalid and logged. Single-player worlds and servers without the database keep no history. Existing names from usercache.json are not imported: the cache holds only the last name with an expiry date, not the time a name was first seen.
/tdlibrary names [name|uuid] is for operators with permission level 2. On a client with TDLibrary it opens a screen: without an argument a scrollable list of all players with their current name, the time it was first seen and their last login, ordered by name and loaded from the server in pages of 50 (Previous page/Next page, Refresh, mouse wheel, Page Up/Page Down and the scroll buttons). The search field above the list asks the server after half a second without typing or on Enter; it finds players whose current or former name starts with the text, without case, and from eight hex digits on also players whose UUID starts with it. Paging applies to the search result. A click on a player shows the full name history with the last login; Copy to clipboard copies it as plain text with the last login and one line per name and time, and Back to the list (or Escape) returns to the list. With a name, the screen shows the history of the only player who ever used exactly that name, current or former and without case, and otherwise the list searched for that name; with a UUID it shows that history directly. Players recorded before td_player_seen existed show the time of their newest name as last login until they log in again. The server checks the operator level for the command and again for every request the screen sends and before every answer; requests from other players are dropped. The console, command blocks and clients without the TDLibrary channel get the answer in chat, each with the last login: the history of a UUID, every player who used a name (at most 16), or without an argument the first 50 players. Times appear in the time zone of the server in chat and of the client in the screen; both name their zone. All lookups run on the worker and answers leave on the server thread.
Mods read the history with PlayerNameHistory.history(UUID), PlayerNameHistory.profile(UUID) (history and last login), PlayerNameHistory.playersNamed(String) (exact name, current or former, as profiles) and PlayerNameHistory.players(int page, String search) (50 players per page with current name, since and last login; the search rules are in PlayerNameSearch); all return a CompletableFuture that completes on the worker thread, so return to the server thread with server.execute before touching game state. They fail when the history is not running (PlayerNameHistory.available()).
To check the table against a real MariaDB, create a disposable database whose name starts with tdlibrary_it_ and a user that may only use it, set TDLIBRARY_IT_MARIADB_URL (for example jdbc:mariadb://localhost:3306/tdlibrary_it_names), TDLIBRARY_IT_MARIADB_USER and TDLIBRARY_IT_MARIADB_PASSWORD, and run rtk proxy .\gradlew.bat test --tests de.taker.tdlibrary.server.MariaDbPlayerNamesIntegrationTest --no-daemon. The test creates td_player_name and td_player_seen there, writes rows with random UUIDs and checks the acceptance rules of the history, the last login and the search; drop the database afterwards. Without the variable, or with any other database name, the test is skipped. Never point it at a production database. Source, unit tests and GameTests with a memory store are checked; the screen itself (including the search field), client acceptance and server acceptance with a real database are pending.
Open /tdnotify to inspect availability through the normal user path. Outages produce an unavailable status and retain queued writes for retry. Reading and marking messages seen never resolve their source condition. Invalid archived component text is skipped with a visible message; the original archive entry is preserved and its identity is logged.
Backend cluster setup
Shared inbox and world routes
From TDLibrary 0.68.0, backends using the same database and running with the cluster enabled share retained messages, read state and presentation settings. The archive commits a retained message before sending a live hint. On login and during play, each backend checks unread status from the shared archive. Source mods still authorize access and actions. A backend transfer can miss a pop-up while the message remains in the inbox. Standalone dedicated servers keep their world-specific archive and local preferences.
For the upgrade, stop all old backends, back up the database and world folders, and update the backends together. Start every existing backend with its original world folder and the same database. TDLibrary imports the notification scope from tdlibrary-notifications/scope.txt, including history and matching read state, and replays pending outbox entries into the shared scope. The old rows and local files are preserved. REFUSE blocks a conflicting archive import. KEEP_DATABASE keeps the existing shared revision and logs the conflict. Later conflicting outbox entries are preserved in tdlibrary-notifications/outbox/conflicts/. Legacy preferences fill absent categories, with existing shared settings and explicit resets taking precedence. Start the preferred node first and let its import complete if legacy settings disagree.
To register world routes, set an optional stable world_id and list explicit owned_dimensions in cluster-node.toml. Distinct world IDs can both register minecraft:overworld. Two live backends attempting to claim the same world and dimension produce a cluster conflict. The active session's heartbeat keeps its routes alive. Use Cluster.worldRoutes() or Cluster.backendForWorld(worldId, dimension) to look up current routes. Consumer mods decide how to use these mappings.
Cluster connection
From 0.62.0 several dedicated servers that share one MariaDB database form a backend cluster for TD mods. Each backend sees the players online on the others, TD mods exchange messages such as group chat or invitations, and exactly one backend runs cluster-wide tasks such as a daily webhook.
In config/tdlibrary-database.toml, fill in the [database] connection, set enabled = true there and set the [cluster] section. This file is the same on every backend:
| Setting | Default | Meaning |
|---|---|---|
enabled |
false |
Join the cluster on server start |
poll_millis |
250 |
How often messages from other backends are read |
stale_seconds |
15 |
A backend without heartbeat for this long counts as offline and loses its leader tasks |
Everything that differs between backends is in cluster-node.toml in the server folder, next to server.properties:
schema = 1
id = "a"
owned_dimensions = ["minecraft:overworld"]
| Setting | Meaning |
|---|---|
schema |
Always 1 |
id |
Unique name of this backend, 1-32 characters a-z, 0-9, _, - |
owned_dimensions |
Dimensions this backend runs. Empty or missing means all dimensions. TD mods use it to decide which backend stores world-bound data |
[modid] tables |
Optional settings of single mods that apply to this backend only, for example [tdeconomy] quest_api = true |
An enabled cluster needs this file. A missing or invalid file stops the server start and the log names the problem. Without a cluster the file is optional.
The cluster needs enabled = true in [database]; an enabled cluster with a disabled database stops the server start. On the first connection TDLibrary creates the tables td_cluster_backend, td_cluster_presence, td_cluster_message, td_cluster_leader and td_cluster_world_route. A second running server with the same id is refused and reported as unavailable. Integrated (single-player) servers never join a cluster.
/tdlibrary cluster shows operators the backend, connection state, players per backend, held leader tasks, queued and dropped messages.
Messages reach backends that are online. The worker retries queued messages up to 30 seconds old after an outage. If the outcome of a commit is unknown, it discards that batch from the queue to avoid sending it twice. Stored messages are deleted after ten minutes. Shared game state belongs in the consumer mod's own tables. Without a cluster every TD mod keeps working as a single server.