TDRules controls, permissions and recovery
Mit FlammiCraft ausgelieferte Mod-Version: 1.24.0
Diese Detailseite ist derzeit auf Englisch verfügbar.
User Interfaces
Player screen
When acceptance is required, the server opens the classic Patchouli rules book after login. It provides:
- direct access to the first unread required page, or the final confirmation page when required reading is complete;
- a filled progress bar and an actual displayed-page counter above the book, with the classic book arrows, mouse wheel and Page Up/Page Down navigating the five required entries;
- the original book background, categories, chapter links and complete page narration, with all five required pages laid out at normal Patchouli text size;
- a reading confirmation and an acceptance button on the right-hand side of the final required entry that unlock only after the five designated required pages were displayed;
- a masked password field with show/hide controls, remaining attempts and an actual lockout countdown when password protection is active;
- a two-step decline flow with a narrated disconnection warning and no reading deadline;
- an in-game chat-help button that prepares an editable message for the player to send;
- German client text and English UI fallback text.
The book cannot be dismissed while acceptance is required. Escape and the inventory key keep players in the book and show outstanding acceptance above it; once reading is complete, a close attempt leads to the book's confirmation page. The footer provides Continue reading, Confirm and chat help. Escape in the decline dialog returns to the book. Chat help opens normal chat without sending anything automatically. Closing chat or any other route back to gameplay reopens the book on the next client tick. Operator permission alone grants no exemption. An operator must deliberately enable the personal admin mode for the current session. The periodic reminder still provides a clickable reopen action for the rare case the screen is briefly absent. Completed reading progress for the current rule version is stored on the server and survives reconnects.
The required-page counter and progress bar appear only while acceptance is required, such as on first login or after a rule update. Read aloud is available during required reading and later browsing. See the player guide for narrator setup.
Administration screen
/tdrules admin opens a server-fed interface with four areas:
- Overview: rule version, enforcement state, radius, player counts, and pending starter kits.
- Settings: radius, allowed command roots, starter-kit loot table, enforcement, and password protection.
- Players: search, status filter, details, confirmed reset, and confirmed complete starter-kit reissue for online players at permission level 3 or higher.
- Starter Kits:
PENDINGandNEEDS_REVIEWcases with confirmed recovery at permission level 3 or higher.
The client submits only drafts or requested actions. The server revalidates every permission and value, persists accepted changes, and then sends a fresh snapshot. Critical actions require confirmation and are audited. The dashboard transfers at most 10,000 sorted player records; remaining records stay available through the player commands. The truncation notice is shown alongside the action result, so failed changes and successful saves remain identifiable.
Refreshes preserve unfinished input and move focus to the replacement control. Searching or changing a status filter clears the selected player, preventing actions on a previous hidden selection. Password fields explain their requirements before submission, and confirmation dialogs narrate the affected player and consequences alongside a specific action button.
Since 1.21.0, TDRules negotiates payload protocol 4 together with the loaded mod version. Clients and servers require the same TDRules artifact version.
Failed reading-progress saves display recovery instructions. Once the server team has checked storage permissions and free space, choose Continue reading to retry without losing pages already displayed in this client session. Repeated completion reports receive an acknowledgement without another save.
Administration saves settings, radius, enforcement and return locks in one checkpoint. A failed checkpoint keeps the previous active state. On standalone servers it also restores the exact TOML contents. If restoring the file also fails, repair the TOML before reloading or restarting as instructed by the error. Online resets checkpoint their new status and exact origin together; failed resets preserve the previous player record.
Commands and Permissions
All commands live under the single root /tdrules; there are no aliases. Player arguments offer tab completion from the known rule records.
| Permission level | Access |
|---|---|
0 |
Normal player commands |
2 |
Status lists, player details, pending kits, administration overview, and personal admin mode |
3 |
Reset, reload, kit recovery, and confirmed manual kit reissue |
4 |
Full TDRules configuration |
Players with permission level 2 or higher remain subject to all rules by default. They can deliberately enable a personal bypass with /tdrules adminmode on. It lasts only until /tdrules adminmode off, logout, or server shutdown. It does not alter the saved rules decision, return lock, reading progress, or starter-kit state.
Player commands
| Command | Description |
|---|---|
/tdrules |
Shows the current status and clickable show, accept, and decline actions. |
/tdrules open |
Reopens the player screen when acceptance is required. |
/tdrules show |
Opens the configured Patchouli rules book. |
/tdrules accept |
Accepts the fully read current version when no password is configured. |
/tdrules accept <PASSWORD> |
Accepts the fully read current version with the configured password. |
/tdrules decline |
Starts the 30-second decline confirmation. |
/tdrules decline confirm |
Confirms the decline, stores DECLINED, and disconnects the player. |
Permission level 2
| Command | Description |
|---|---|
/tdrules admin |
Opens the permission-aware administration screen. |
/tdrules adminmode on |
Enables the personal rule bypass for the current session. |
/tdrules adminmode off |
Disables the personal bypass and immediately resumes required acceptance. |
/tdrules adminmode status |
Shows whether the personal admin mode is currently active. |
/tdrules list accepted [PAGE] |
Lists currently accepted players, ten per page. |
/tdrules list declined [PAGE] |
Lists players with a saved decline. |
/tdrules list none [PAGE] |
Lists NONE and outdated acceptances. |
/tdrules list all [PAGE] |
Lists all saved players. |
| `/tdrules info <NAME | UUID>` |
/tdrules kit pending [PAGE] |
Lists kits in PENDING or NEEDS_REVIEW. |
Names resolve together with UUIDs; use the UUID when a historical name is ambiguous.
Permission level 3
| Command | Description |
|---|---|
/tdrules reload |
Revalidates the standalone world configuration or shared cluster settings. |
| `/tdrules reset <NAME | UUID>` |
| `/tdrules kit retry <NAME | UUID>` |
| `/tdrules kit retry <NAME | UUID> confirm` |
| `/tdrules kit grant <NAME | UUID>` |
For NEEDS_REVIEW, run the command without confirm first and repeat it with confirm within 30 seconds. Confirmation is bound to the persisted delivery-plan ID.
Reset preserves identity, first-acceptance history, and kit information; it does not grant a second starter kit. It clears password failures and password lockout. An online target immediately receives a new exact-position lock; an offline target receives one on the next login.
Permission level 4
| Command | Description |
|---|---|
/tdrules config show |
Shows radius, versions, enforcement, password status, allowed commands, and loot table. |
/tdrules config range <1-10000> |
Changes the three-dimensional spawn radius. |
/tdrules config password set <PASSWORD> |
Sets or replaces the acceptance password. |
/tdrules config password clear |
Removes password protection. |
/tdrules config enforcement on |
Enables restrictions for the loaded rule version. |
/tdrules config enforcement off |
Pauses all restrictions. |
Disabling enforcement pauses movement, interaction, inventory, reminders, acceptance, decline, and forced teleportation. Saved decisions, history, lists, kit states, and configuration remain intact. Active return locks are cleared. Re-enabling enforcement reevaluates every online player.
Player States
| Saved state | Meaning |
|---|---|
NONE |
No decision exists for the relevant situation, or an operator reset the player. |
ACCEPTED |
The player accepted a specific rule version. |
DECLINED |
The player confirmed a decline. |
An accepted version can become outdated:
| Saved state | Version comparison | Effective state | List category |
|---|---|---|---|
NONE |
Any | NONE |
none |
DECLINED |
Any | DECLINED |
declined |
ACCEPTED |
Current | ACCEPTED |
accepted |
ACCEPTED |
Older | OUTDATED |
none |
A player who declined may reconnect later and accept. Disconnection happens only when the decline is confirmed.
Restrictions Before Acceptance
When a positive rule version is loaded, enforcement is enabled, and no explicit personal admin mode applies, TDRules blocks actions including:
- breaking, placing, and multi-placing blocks;
- tool actions, trampling farmland, and block interaction;
- entity interaction and normal item use;
- attacks, outgoing damage, incoming damage, and knockback;
- picking up and dropping items;
- containers, inventory clicks, container buttons, and recipe placement;
- creative-slot changes, pick-block, and book editing;
- crafting and trading through containers;
- hunger, saturation, and exhaustion changes;
- every command root that is not explicitly allowed.
The Patchouli rules book may still be used and picked up. Normal chat, /tdrules, and entries in allowedCommands remain available. Similar blocked-action messages are throttled to avoid chat spam.
Indirect player damage is attributed through projectiles, tamed animals, ignited TNT, and area-effect clouds.
Movement and Renewed Acceptance
Whenever acceptance is required, TDRules stores the player's exact dimension, position, yaw, and pitch and starts an ORIGIN_LOCK. This applies to new players, reset players, declined players who reconnect, and previously accepted players after a rule-version increase. The server corrects movement every tick, clears motion and fall state, and keeps the exact lock across logout and restart. Restricted players receive a private reminder once per minute.
After successful acceptance, TDRules searches for a safe return point at or near the saved position. If the dimension no longer exists or no safe point is available, the player remains at Overworld spawn and receives a warning. The return lock is removed only after successful return or a deliberate fallback.
Patchouli Rules Book
/tdrules show opens tdrules:rules through the Patchouli API.
While acceptance is required, the official client counts the single page in each of tdrules:required_01 through tdrules:required_05 when displayed. These five numbered entries appear in the required-reading category and link to the detailed rules. Other entries and repeat visits do not advance progress. A missing required entry or an entry with an unexpected page count cannot complete the gate. Once all five are displayed, the client reports completion for that exact rule version to the server. The acknowledgement is also a client-side UI gate. A reset or newer rule version requires all five pages again. These display checks are not remote attestation and can be forged by a deliberately modified client.
The acceptance screen opens the current change summary and quick reference directly. Its Discord button uses Minecraft's standard external-link handling for https://discord.gg/MwMWskrPfA; tickets are created by the Discord bot after joining. The invite is bundled with this server-specific rule book, not a direct ticket-creation endpoint. The chapter 00_current_changes currently describes rule version 2 and must be updated alongside future substantive rule revisions. Completed required pages remain accessible from the acceptance screen and through /tdrules show.
TDRules periodically checks directly reachable inventories:
- the normal player inventory, including hotbar, armor, and offhand;
- normal and cosmetic Curios slots;
- Sophisticated Backpacks directly carried in the player inventory or a supported Curios slot.
If no rules book exists, one copy is placed in a reachable free slot. Duplicate reachable copies are reduced to one only when every involved adapter completed its scan successfully.
If no reachable slot is free, TDRules does not create a permanent world item. It displays a private /tdrules show fallback once per login and inserts the book during a later approximately five-second reconciliation after a slot becomes available.
Starter Kit
The starter kit is planned automatically only after the first successful acceptance in the lifetime of a player record. Repeated acceptance, a later rule version, a previous decline, an operator reset, a restart, or resuming an interrupted delivery does not grant another kit.
As an explicit administrative exception, permission level 3 operators may completely reissue the currently configured starter kit to an online player from the Players screen. A confirmation dialog warns about possible duplicates. Manual reissue does not change the persisted one-time delivery plan or its status and is audited separately.
The default loot table is:
data/tdrules/loot_table/starter_kit.json
It contains:
| Item | Count |
|---|---|
| Iron helmet | 1 |
| Iron chestplate | 1 |
| Iron leggings | 1 |
| Iron boots | 1 |
| Iron pickaxe | 1 |
| Iron axe | 1 |
| Iron shovel | 1 |
| Iron hoe | 1 |
| Iron sword | 1 |
| Bread | 16 |
| Oak boat | 1 |
| Torches | 32 |
| Crafting table | 1 |
The server team may override this loot table through normal Minecraft data resources or configure another resource ID through starterKitLootTable.
Delivery states
| State | Meaning |
|---|---|
NOT_GRANTED |
No kit has been planned or granted. |
PENDING |
The persisted plan contains unconfirmed entries. |
GRANTED |
The plan completed or was intentionally empty. |
NEEDS_REVIEW |
Delivery requires manual review after an ambiguous interruption or source error. |
An immutable delivery plan is persisted before item insertion. The remaining batch is acknowledged together; already confirmed entries in existing plans retain their recorded progress. A normal PENDING plan can therefore resume after restart without repeating confirmed entries.
If the server stops between inventory insertion and persisted confirmation, the remaining batch is not blindly repeated. The plan becomes NEEDS_REVIEW so an operator can assess possible duplication. Overflow starter-kit items are dropped for the target player at their position. The remaining delivery batch is checkpointed before its first insertion and acknowledged only after one checked player-inventory save and, when needed, one flushed dimension save. An interrupted batch may already have delivered several entries; review all remaining planned entries before confirming a retry. Previously acknowledged entries from older plans remain acknowledged. A loot-table failure does not invalidate rule acceptance; it marks the kit for review. After the source is repaired, a confirmed retry reevaluates the empty failed plan and persists a new plan before delivery. If the source still fails, the review record remains unchanged. Retries of existing non-empty plans retain their recorded items and delivery index.
Password Protection
Set a password only through:
/tdrules config password set <PASSWORD>
Passwords must contain 4 to 64 Unicode characters without whitespace. Screens and commands use the same limits. Quote command passwords containing Unicode or punctuation, for example /tdrules accept "äbc!" and /tdrules config password set "äbc!". Quoted arguments use standard Brigadier quote and backslash escaping. TDRules stores PBKDF2-HMAC-SHA256 output with 600,000 iterations, a random 32-byte salt, a 32-byte hash, and constant-time comparison. Plaintext passwords are not stored or written to audit logs.
After three failed attempts, the player is locked out for five minutes. Failure counts and expiry are world-bound and survive logout and restart. Changing or clearing the password resets all player failures. New hashes are calculated on the bounded password worker while the previous protection remains active. Completion, rejection and storage failures are reported through the initiating screen or command. If protection changes during hashing, the stale result is discarded.
Inventory and Mod Compatibility
Vanilla inventory
The complete directly reachable player inventory is considered. For restricted players, inventory packets are blocked on the server before Vanilla mutation and then synchronized back to the client.
Curios
When Curios is installed, TDRules scans normal and cosmetic slots. A failure disables the affected adapter for the current session and is audited.
Sophisticated Backpacks
TDRules scans Sophisticated Backpacks only when they are directly carried in the normal player inventory or a supported Curios slot. Access is guarded by mod-presence and compatibility checks.
Applied Energistics 2
AE2 networks are deliberately neither scanned nor modified. A rules book inside AE2 does not prevent delivery of a reachable copy. A Sophisticated Backpack inside AE2 is not opened or scanned; it is considered again once directly carried.
Incomplete adapters
If an optional inventory system cannot be read completely, TDRules behaves conservatively:
- safe delivery into a known free slot remains possible;
- known duplicates are not removed while the overall scan is incomplete;
- the failure is recorded under
logs/tdrules.
World-Bound Storage
On standalone servers, TDRules stores mutable state as Overworld SavedData and applies it across that world's dimensions. This data includes:
- SavedData schema version;
- enforcement toggle and movement radius;
- highest activated rule version and last validated configuration snapshot;
- password verifier;
- UUID-based player records and up to five historical names;
- decisions, versions, timestamps, and the latest 100 decision-history entries;
- first acceptance and kit-delivery progress;
- password failures and lockout expiry;
- return position and lock phase.
The data name is tdrules; the current internal SavedData schema version is 1. Player names are display and search metadata only; UUIDs are authoritative.
Before significant version or configuration changes, back up the full world directory, especially:
<world>/data/tdrules.dat
<world>/serverconfig/tdrules-server.toml
<world>/serverconfig/tdrules/
Cluster Storage
With TDLibrary's cluster enabled, MariaDB is authoritative for active settings, rule decisions, reading progress, password lockouts and starter-kit progress. The tables are tdrules_shared and tdrules_players. Each backend reads shared settings and player state before processing a login. During play, it reads changes in the background when another backend announces a change and periodically as a fallback. A stale write fails as a unit. Retry the action after the backend synchronizes.
From 1.23.0 TDRules borrows its database connections from TDLibrary's shared pool and requires TDLibrary 0.74.0 or newer. A change that waits more than three seconds for a row another server holds locked fails with an error and can be tried again.
The first backend imports its saved settings and player records. If there is no validated rule snapshot, it uses its world settings file to initialize one. Once a shared snapshot exists, the administration screen writes directly to MariaDB. /tdrules reload refreshes and validates the database settings against the installed rule resources. Local TOML edits apply to standalone worlds. Keep every backend on the same bundled rule version. A backend with incompatible rule content or an unavailable database at login refuses that session.
TDRules stores return positions in MariaDB under the backend ID, a persistent world UUID and the dimension inside that world. Accepting on another backend releases the shared restriction. If an origin is pending in the previous world, TDRules returns the player there when they enter that world again. It checks for a safe landing and uses that world's fallback spawn if necessary. Pausing enforcement invalidates earlier return points across the cluster. Preserve tdrules.dat and the backend ID when moving the same world. A clone hosted on a different backend ID gets a separate return scope. Starter-kit items still use Minecraft's inventory and entity storage on the delivering backend. The server's inventory handoff must carry those items along, and dropped overflow remains in the delivering world.
For the upgrade from 1.20.0, stop all TDRules backends and back up the database and the world files before starting 1.21.0. Start the backend with the intended settings first if the database is empty. TDRules adds revision columns to the existing tables and imports each world's legacy return positions on its first start. Upgrade the other TDRules backends before returning them to service. Clients need the same TDRules version as their server.
The first login with TDRules 1.22.0 may still trigger an old return position left by 1.21.0. Once that return completes, TDRules records the removal in MariaDB.
Manual editing of the compressed SavedData file is unsupported.
An existing unreadable or incompatible tdrules.dat prevents TDRules services from starting; it is preserved for repair or restoration. Malformed non-empty NBT lists are rejected instead of being read as empty records. Standalone critical checkpoints use synchronous atomic file writes. Cluster checkpoints commit shared state together in a database transaction. Failed acceptance, password, configuration-snapshot and enforcement checkpoints retain the previous active state and report failure to the caller. Check storage permissions and free space before retrying a failed write. Starter-kit delivery reads the saved player inventory back before acknowledging it, because Minecraft otherwise only logs player-save failures. Overflow saves and flushes the receiving dimension, including its entities, once per delivery batch before the delivery is acknowledged.
Troubleshooting
TDRules starts but restricts nobody
Check that:
- the embedded rule acceptance
versionis greater than0; - enforcement is enabled in
/tdrules config show; /tdrules reloadcompleted successfully;- the test player's personal admin mode is disabled with
/tdrules adminmode off.
If the server log reports that TDRules could not start, enforcement is inactive for that session. Repair the reported cause and fully restart the server. Startup failure preserves the saved enforcement setting and player return positions, so the next successful start resumes the previous policy.
/tdrules reload is rejected
Common causes are malformed TOML or bundled rule-version JSON, unknown or missing fields, a rule version below the highest previously activated version, a missing tdrules:rules book, invalid or duplicate command roots, or an invalid loot-table resource ID. The previous validated snapshot remains active after failure.
/tdrules show opens no book
Verify that Patchouli is installed on both sides, client and server use the same TDRules JAR, the JAR contains the embedded book paths listed above, and the client was fully restarted after JAR replacement.
The player receives no physical rules book
/tdrules show must work independently. A full reachable inventory triggers the fallback message once per login. Delivery may take until the next approximately five-second reconciliation after a slot is freed. A book in Curios or a directly carried Sophisticated Backpack counts as present; a book in AE2 deliberately does not.
A starter kit remains PENDING
The player must be online. Use /tdrules kit pending to inspect records and /tdrules kit retry <NAME|UUID> to resume normal delivery. For NEEDS_REVIEW, inspect whether items may already have arrived and then use the 30-second confirmation sequence.
A return position cannot be used
TDRules checks the dimension, loaded chunks, world border, safe ground, body clearance, and hazards. If no safe position exists or the dimension was removed, the player remains at Overworld spawn by design.
Unexpected audit-log count
Every process start creates a new file. Identical timestamps receive -1, -2, and later suffixes. Only matching TDRules files older than 30 days are removed. A queue_loss event indicates temporary queue saturation.
Known Limitations
- Books issued under an older external book ID are not migrated automatically.
- Signs and spawn decoration are outside the mod's scope.
- AE2 and other external storage networks are not scanned.
- Sophisticated Backpacks are scanned only when directly carried; storage is not traversed recursively.
- NeoForge enforces matching TDRules versions, but in-game rendering still requires runtime testing.
- Disabling enforcement preserves decisions but removes active return locks.
- A completely full reachable inventory does not create a permanent world item for the rules book;
/tdrules showremains the safe fallback. - The build contains no executable headless GameTest suite. Runtime behavior is validated through the manual acceptance matrix.
- Page display and acknowledgement are enforced by the official client and cannot be proven to an untrusted modified client.