Zum Hauptinhalt springen

TDGroupe groups, maps and titles reference

Mit FlammiCraft ausgelieferte Mod-Version: 0.29.0

Diese Detailseite ist derzeit auf Englisch verfügbar.

Handbook overview

Earned titles

Administrative rank assignments keep their existing behavior: all assigned tags remain visible and grant no permissions. A player can additionally display one earned title. Title definitions reuse the existing operator rank editor (name, tag, tag/name/text colors and priority); unlocking a title does not assign that administrative rank. The combined displayed ranks determine chat colors by priority. If the same rank is assigned and selected as a title, its tag appears only once.

  • /tdgroupe title opens My titles, also available from the main dashboard. Search titles and filter owned, earnable or purchasable entries. Details show credited playtime, quest conditions, ownership or revocation, and previews for public chat and TD LeaderBoard. Select an owned title or hide the extra title. Purchases require a separate review showing the title, exact price and available personal-account balance.
  • /tdgroupe title select <id> selects an owned title; /tdgroupe title none hides the title. Without an explicit choice, the highest-priority owned title is displayed (ties use the ID). Later unlocks preserve an explicit selection.
  • /tdgroupe title buy <id> <price> buys an offered title at the reviewed Flammtaler price with up to two decimal places. A changed price rejects the request. TDEconomy 2.50.0 or newer is required for purchases; insufficient funds, an invalid or archived receiving account, or a failed durable write do not unlock a title. A committed paid entitlement is retried automatically after reconnects/restarts without charging again.
  • /tdgroupe title grant <player> <id>, revoke <player> <id> and set <player> <id> require an explicit operator-list entry or the singleplayer owner; console access requires permission level 4. Set grants and selects a title. Player names resolve only through known online/offline UUID profiles; unknown or ambiguous names are rejected. Revoke suppresses automatic quest, playtime and purchase replays until an explicit administrative grant or set.

Use TD LeaderBoard 1.10.0 or newer to show the selected title beside player names in TAB, full-screen lists, player details and world boards. Title priority does not change statistic rankings. Both integrations are optional; all participants require TDLibrary 0.46.0 or newer. Earned titles never grant permissions or modify group membership.

Open Administration for rank definitions, administrative assignments, earned-title grants/revocations, title unlock rules and server settings. The title rule editor uses days, hours, minutes and seconds, named tasks/series, named receiving system accounts and Flammtaler prices with up to two decimal places. Time, quests and purchase offers are alternative unlock routes. It writes the existing [titles] section of tdgroupe-server.toml; the lists are empty by default. Create the rank definitions first. Saving rechecks operator access and rejects a stale rule revision; failed storage restores the previous in-memory rules. Rank definitions referenced by unlock rules cannot be deleted until those rules are removed. Operators can grant, grant-and-select or revoke a title for a known UUID-backed player, separately from administrative rank assignments.

The same rules remain editable in TOML using the syntax below. Server settings, also reachable through /tdgroupe config, manages the three group settings and the title idle threshold. Ordinary players receive only their own title data and the configured public quest conditions; receiving-account choices and the full quest/player directories require operator access. Existing missing task or account references remain visible as unavailable choices so an operator can remove or replace them without inventing IDs.

[titles]
idleSeconds = 300
playtime = ["veteran=86400"]
quests = ["builder=task:11111111-1111-1111-1111-111111111111", "explorer=series:22222222-2222-2222-2222-222222222222"]
purchases = ["supporter=10000@33333333-3333-3333-3333-333333333333"]

These are syntax examples, not installed server rules. Each playtime entry is title-id=positive-seconds; quest entries use a stable task or series UUID, and any listed milestone can unlock the title. Each purchase is title-id=positive-price@receiving-system-account-UUID. The system account must already exist and accept payments in TDEconomy. Malformed or duplicate rules disable automatic rules and purchases with an internal error log; administrative title access remains available. Deleted or missing rank definitions do not display or grant titles.

Credited time starts with this feature; historical vanilla online time is not imported because it includes AFK time. Every 20 server ticks count as one second while the vanilla last-action timestamp is within idleSeconds. Zero counts all online time. Offline time is never counted, and low TPS slows tick-based credit. This uses server-observed vanilla activity rather than TDUtilities' client-reported AFK indicator. New quest completions and paid entitlements are reconciled every five server seconds. Surviving old completion records are imported by TDEconomy's schema migration; already compacted historic records cannot be reconstructed.

Title ownership, explicit choices (including hidden), revocation blocks and time use a separate strictly validated schema 1 SavedData file, data/tdgroupe_titles.dat. Back it up with the world and the existing data/tdgroupe.dat. Administrative rank definitions and group data are unchanged. A failed or future title file is never replaced with an empty state. Changes use ordinary world saves; paid purchases and quest facts also remain durably replayable from TDEconomy. New unlocks produce shared chat/toast notifications, subject to the player's TDLibrary preferences.

Groups

With TDEconomy installed and a current group, received invitations and linked economy accounts have separate dashboard buttons on the same row. Group chat and status feedback sit below them. Only the current group owner can open linked accounts.

Dashboard commands, inventory shortcuts and refresh requests share a server-side limit of one read every 100 milliseconds per player.

Open dashboards share cached player-directory and membership data. The server checks for updates once per second and sends only changed views; opening a dashboard always receives its current state. Invitation countdowns advance locally from the last server timestamp. Leaving the dashboard, including opening the notification inbox, ends its update subscription.

Open the dashboard using /tdgroupe or the three-person icon. With FTB Library installed, the icon appears in its top sidebar alongside the other shortcuts. Without FTB Library, it appears above the top-right edge of the player or creative inventory as a 24-by-24-pixel control with a tooltip and narration. This fallback follows recipe-book shifts. Anyone can create one free group. Each player can belong to only one group.

Players can edit inventoryButtonOffsetX and inventoryButtonOffsetY under Settings, with an inventory/icon preview and a reset-to-defaults action, or in config/tdgroupe-client.toml. Both default to 0 and shift the fallback button in GUI pixels from its position above the inventory's top-right edge; positive X moves right and positive Y moves down. Values from -1000 to 1000 are accepted. The preview reports when an offset moves the icon outside its preview area. FTB Library manages the sidebar icon's position separately; the settings page explains that these offsets apply only to the fallback icon. These settings do not affect the server or other players' clients.

Names contain 3–32 characters, are unique without regard to case and cannot contain control or formatting characters. The owner can rename the group and choose one of the 16 Minecraft text colors. Color can be selected when creating or editing a group; new group drafts default to green. Each click on the color button advances to the next color, and Save applies the choice.

Owners can assign manager or member roles, invite known online or offline players, remove members and transfer ownership. Managers can invite, withdraw invitations and remove ordinary members, but cannot remove peer managers or the owner, change group settings, assign roles, transfer ownership or dissolve the group. The former owner becomes a regular member after transfer. Members can leave; an owner must transfer ownership or first remove all other members and dissolve the group. Removal, transfer and dissolution require confirmation in the UI.

Group and rank color buttons cycle forward with the left mouse button and backward with the right mouse button.

Invitations can be accepted or declined in their menu dialog or through the existing chat buttons and /tdgroupe accept/decline commands. Pending invitations remain visible with the player's name and deadline, including while offline and after server restarts. They do not reserve a member slot. Acceptance rechecks the inviter's current role, membership and capacity on the server. Withdrawal, expiry, loss of invitation authority, ownership transfer and dissolution invalidate invitations; joining or creating a group invalidates that player's other invitations. New worlds default to seven days, while existing configured invitationSeconds values and issued deadlines remain unchanged. Invitation and lifecycle events remain in SavedData until TDLibrary's durable outbox accepts them, so archive outages do not decide membership or lose pending delivery.

Chat and waypoints

/gc <message>, /teammsg <message> and Minecraft's existing /tm <message> shorthand send a private message to online group members, including the sender. TDGroupe replaces the vanilla scoreboard-team message handler; scoreboard-team membership does not select recipients or grant group-chat access. All three commands use the same chat rate limit and preserve the literal message text without expanding selectors. Incomplete selector-like fragments such as @e[ are ordinary text for players and operators alike. The group name always appears in the group's color. Public chat can also display the group name, controlled separately by the server configuration. Global rank tags remain visible regardless of that setting. Tab names and overhead nameplates are unchanged.

Right-click a waypoint in Xaero's World Map and select Share with group. The same action remains available after selecting one waypoint in Xaero's waypoint list. Only online group members receive the clickable message. In the destination world, the link opens Xaero's waypoint import dialog. If the link reports a different world, go to the backend serving that world and dimension and open it again. Coordinates remain readable without Xaero. Sharing is limited to one waypoint every two seconds.

Public messages use Minecraft's player-chat delivery with a custom group and rank decoration. Sender identity, signatures, vanilla spam accounting, text filtering, blocked-player handling and recipient chat visibility settings remain on the native path. TDGroupe respects chat-event cancellation. Group messages are command-based and are not signed player-chat messages.

Shared exploration

On login, the server sends a compact digest per map region. The client compares it with its stored sync state and asks only about differing regions; the server then lists their entries and the client requests just the missing or changed tiles. Received tiles are written to disk before the server is told they arrived, and they are applied once Xaero has loaded their region. Saved regions are rescanned only when their Xaero file changed, and a tile is uploaded only when its terrain differs from the last upload the server confirmed. The server sends at most mapDownloadKiBPerSecond (in tdgroupe-server.toml, default 1024) per player; clients upload at most mapUploadKiBPerSecond (in tdgroupe-client.toml, default 512). TDGroupe also remembers processed contributions and outstanding retries separately for each Xaero map during the current connection. Returning from another dimension resumes that map's downloads. A deferred tile remains explicitly requested even after later tiles have been applied; waiting for one region does not hold the entire reception queue. Group membership, group identity and archive dataset changes invalidate these checkpoints, as does disconnecting. Each map activation has its own transfer identity, so late packets from another dimension or Xaero multiworld cannot affect the active map. Personal-map upload scanning restarts when switching dimensions, and terrain that contributors have not uploaded remains unavailable to other members.

With Xaero's World Map installed, players automatically archive their personal exploration on the server, including when they have no group. They can restore their own archived terrain after losing local map data. Current group members additionally receive each other's terrain; invitations alone do not grant access. The server checks current membership before accepting transfers and delivering other contributors' terrain, including after removal, leaving or dissolution. Clients without Xaero keep all other TDGroupe features.

Existing personal map data is imported gradually when that dimension's Xaero map becomes active. Surface terrain and saved cave layers are included; selecting or visiting another dimension starts its import and restoration. Large maps take time to catch up. The importer discovers known regions on map activation and cave-layer changes, queues subsequent native writes directly, prioritizes reloadable terrain through Xaero's native loading scheduler, and defers regions that remain unavailable so other regions can progress. Each region retains its tile position across retries. Empty highlight placeholders do not block terrain import or reception; already loaded regions are not repeatedly sent ineffective full-region reload requests. Personally explored tiles take priority over received tiles, and TDGroupe does not overwrite them. It shares existing map data rather than generating unexplored terrain on the server.

Shared terrain appears directly in Xaero's normal world map (default key M), alongside personal exploration. The initial import includes known regions even while Xaero is still loading their terrain. Saved pixels without biome metadata use Xaero's plains fallback instead of blocking the entire tile's contribution; recorded biome metadata is retained and the original personal tiles are not modified by import. Contributors must connect with this integration enabled to upload personal terrain that the server has not received yet; saved server contributions remain available while they are offline.

The server records the original explorer of every contribution in tdgroupe-maps/<dataset-UUID>/ beneath the server's game directory, outside the world. Each contribution is written to a temporary file, flushed and atomically replaced on a dedicated storage worker before the upload is confirmed. Current members can catch up even when a contributor is offline or after a server restart. Former members' contributions stop being available to the group, but remain available to their original owner. Restored personal terrain is kept personal instead of being marked as someone else's contribution. New shared files use archive format 3. Existing individual files in formats 1 and 2 remain readable. Older builds cannot read format 3, so retain an archive backup before upgrading if a downgrade may be needed. Malformed or future archives are rejected rather than replaced with empty data. Block names and properties survive registry-number changes between pack updates.

Legacy world archive: this build leaves an existing data/tdgroupe_maps.dat untouched. It is not decoded, deleted or automatically imported. The external archive remains authoritative. Preserve the legacy file for a separately validated recovery if it contains the only surviving terrain; ordinary clients can offer their personal exploration again by connecting and activating the relevant dimensions. Already marked foreign terrain is not reclassified as personal exploration. Group and rank data in data/tdgroupe.dat is unaffected.

Back up the entire tdgroupe-maps directory independently of world backups. active-dataset.txt contains the active archive UUID and is created once. It deliberately survives world moves and replacements. Before using an unrelated or reset world, stop the server and replace that file's contents with a new UUID (and use the appropriate fresh Xaero map identity on clients). Otherwise the server continues using the same map dataset. Retaining the old UUID directory preserves its archive for a deliberate later switch. Malformed identities stop loading rather than silently selecting a new dataset. Restoring a PC requires the same authenticated player UUID, this integration, and terrain that was successfully uploaded earlier; this archive does not back up waypoints or XaeroPlus-specific overlays.

Received tiles are flagged in the per-region sync state under .tdgroupe-sync inside their existing Xaero dimension/multiworld directory; older .tdgroupe-received markers are imported into it once and left untouched. Keep both folders when backing up or moving your Xaero maps: the received flags they prevent importing previously received group terrain as your own contribution to another group. A complete local exploration of a received tile makes that tile personal. Previously received knowledge remains visible after leaving; this feature cannot revoke knowledge a client already has. Old maps shared by other mods before these markers existed cannot be distinguished from personal maps.

Uploads first offer a SHA-256 content digest. Matching personal contributions are confirmed without retransmitting terrain. Missing or changed terrain travels in numbered fragments of at most 24,000 data bytes, with one outstanding fragment per transfer. Receipts release transport credit; they do not confirm storage or application. Up to sixteen transfers can progress concurrently in each direction, without the former four-packets-per-second upload or eight-tiles-per-second download ceilings. Receiver capacity and acknowledgements control progress. Assembly buffers and queued encoded uploads have 64 MiB budgets per player/direction; full queues defer work for later import or retry. The external archive has no fixed total size or contribution-count limit. The server index retains contribution identities, encoded sizes and SHA-256 hashes, rather than all archived terrain bytes. Startup validates every file using at most four buffered readers and eight outstanding tasks, with lower limits on small CPUs. Directory metadata is reused instead of issuing separate attribute checks for every contribution. Selected terrain is read on the bounded download worker and checked against its indexed hash before delivery; a replaced file is retried under its new contribution cursor. There is no additional persistent terrain cache. Index metadata still grows with the number of contributions, and active transfer buffers remain separate from that index.

An upload remains pending until the server confirms validation and durable storage. Temporary failures retain it for retry, while invalid data is rejected with an internal diagnostic. Newer terrain for the same tile remains separate from its in-flight contents. Missing receipts trigger retransmission after 40 ticks; work without progress for 600 ticks is discarded as an active transfer and reoffered after a delay. These delays use game ticks (about two and thirty seconds respectively at 20 TPS). Deferred downloads have separate retry requests, so later successfully processed terrain does not hide a failed contribution. Retry traffic leaves room for new downloads. Disconnects and access changes cancel uncommitted processing; a personal write already submitted to storage can finish safely.

Tiles larger than the former 24,000 compressed bytes or 256 KiB decoded bytes are supported. Bounds follow the serialized 256-pixel structure, its field sizes and Xaero's ten overlays per pixel, with decompression checked against that structural maximum. Contributions must contain exactly one fully consumed compressed stream; trailing bytes and concatenated streams are rejected. A tile represents one Minecraft chunk in one dimension and cave layer; contributors remain separate. New tiles use a compact palette encoding; tiles stored in the earlier format remain readable. Clients and server require map protocol 12. Map synchronization never writes status or error messages into player chat or the notification inbox; failures appear in throttled internal logs.

Saved-map imports track exact changed tiles without rewinding an unfinished region or rescanning its unchanged tail. Busy regions immediately yield, while unavailable chunks remain pending without hiding later tiles in the same region. TDGroupe waits for Xaero's currently prioritized load before requesting another region, avoiding a flood of native loads. Discovery scans the saved regions on a new map view or cave-layer change; subsequent native writer notifications queue new exploration directly, so received regions do not repeatedly grow the upload backlog. The server can queue four durable writes per player instead of waiting a full tick for each individual file. Existing personal maps, received-tile flags and archive formats 1/2 are preserved; do not reset them to catch up. Install matching builds on the server and all clients, restart fully, and allow the active Xaero dimension to synchronize automatically. Source regression tests cover import progress, frame scheduling, bounded transfer windows and buffer accounting; actual multiplayer convergence, frame times, dimension switches and save/reload still require manual acceptance.

The client reconciles one region at a time, pauses after requesting 1,024 outstanding history tiles and resumes when the server delivers or cancels a tile. When you return to a dimension, its saved sync state is compared again so unfinished history requests can resume. The server skips previously examined contributions when looking for new terrain. If a Windows file lock briefly prevents an atomic replacement, the storage worker retries it while the previous tile remains intact. If the lock persists, the client keeps the upload for a later retry.

At server startup, TDGroupe-map-startup opens and fully validates the external archive in the background. The server thread never waits for this disk access or terrain decompression; map polls and uploads remain suspended until the complete archive is published. Long-running validation logs its completed contribution count about every ten seconds. Existing format 1 and 2 files and the dataset identity are not rewritten. No persistent index, archive migration or configuration change is required. Loading duration still depends on archive size and server hardware; synthetic local benchmarks do not establish the live server startup time. A failure disables only map synchronization for that run and logs its cause; unreadable contributions are not overwritten by an empty archive. Correct the reported archive problem and restart manually to retry. Shutdown cancels pending loading without waiting for it. Resource identifiers are checked without compiling regular expressions per pixel, and archive validation avoids constructing unused pixel and overlay objects.

Startup logs distinguish background loading from the ready dataset, contribution count and archive directory. Client logs identify queued saved regions, the first confirmed personal tile and every 128 server confirmations. Deferred imports are informational, log their region/chunk load states and pending flags once per region, and remain queued for retry; waiting alone does not display a map-data error. Confirmation counts include unchanged tiles acknowledged by digest, not only newly written files. Version 0.7.0 keeps existing external contributions without a reset or migration.

TDGroupe-map-client encodes terrain; TDGroupe-map-client-validation handles hashes, fragment assembly, decompression and block-state decoding. TDGroupe-map-cache exclusively reads and writes the .tdgroupe-sync state (region manifests, index and pending received terrain), keeping slow filesystem work separate from terrain processing. This ordered daemon worker is reused across map changes and reconnects so an already running write cannot race a replacement worker. At most 128 region manifests stay cached. A foreign tile is merged only after its received flag is durable; a restored personal tile loses that flag only after its terrain has been applied. Unreadable sync files are kept and their region is skipped instead of being reset.

On the server, TDGroupe-map-server selects archive downloads, TDGroupe-map-validation validates upload contents and digests, TDGroupe-map-storage persists contributions and prepares their immutable index entries, and TDGroupe-map-startup loads the initial archive. Biome validation uses immutable identifiers captured on the server thread. Apart from the bounded startup readers, each worker has one thread and at most 32 queued jobs; saturation defers work without running it inline. Encoded capture queues contain at most sixteen tiles. Xaero terrain is captured and merged inside the render lock already held by its native writer, sharing a one-millisecond scheduling budget per frame; an already started tile finishes before the budget is checked again. Upload capture and download application alternate first access to that budget. Writer callbacks only queue tile identities, and one overlay builder is reused per received tile. Workers never access a live map, world or player. Delivery, current membership checks and archive publication remain on the owning game threads. No game thread waits for a worker. Shutdown can discard unconfirmed work, which clients offer again on their next import.

Use this integration with the base Xaero maps. Xaero's Maps: Multiplayer+ and Unified Xaero Worldmap are not required; their independent server-wide synchronization must be disabled if installed, because TDGroupe cannot restrict packets sent by another mod. The Xaero integration was checked against the installed Minimap 26.6.0 and World Map 1.47.0 APIs; rendering, reload and multiplayer acceptance still require manual tests.

TDGroupe is licensed exclusively under All Rights Reserved. See LICENSE for the terms.

Waystones team sharing

When Waystones is installed alongside TDGroupe, its existing Share for team option shares destinations with the waystone owner's current TDGroupe members instead of a vanilla scoreboard team. Owners may be offline. Pending invitations and players without a group grant no team-shared destinations. Membership, owner and visibility changes are reflected the next time Waystones requests the destination list; reopen an already open selection screen after a group change.

Public waystones, sharestones and personally activated destinations keep Waystones' existing behavior. Leaving a group does not revoke personal activations acquired separately. The integration changes destination sharing only; it does not grant editing rights or change vanilla teams. Existing team-shared waystones automatically use TDGroupe membership without rewriting world data. Without Waystones, the integration is skipped. The build resolves the single installed Waystones JAR for Minecraft 1.21.1, and the integration test checks its team-target API. Multiplayer acceptance still requires a manual test.

Global ranks

Only players explicitly present in the server's operator list and the singleplayer world owner can access rank administration. The world owner is recognized by UUID even without an operator-list entry or enabled cheats; LAN guests still need an explicit operator entry. Administration is hidden from everyone else, and the server rechecks access for every rank change. Rank definitions and player assignments offer the same chat and leaderboard appearance previews as earned titles. A higher-priority administrative rank still controls chat colors, and the preview identifies it. Ranks never grant operator or group-owner permissions.

Ranks have a name, optional tag, three separate colors (tag, player name, message text), and an integer priority. A player can have several ranks. All nonempty tags appear from highest to lowest priority, each with its own color. The highest rank controls the name and text colors. Equal priorities are ordered by the stable internal rank ID.

The initial team rank has a blue [Team] tag and blue name with white message text. The editable, nondeletable everyone fallback uses a green name, no tag and white text. It applies when the player has no explicit ranks. Deleting a custom rank removes only that rank's assignments.

Assignments use a searchable list of online and locally known offline players, with their status and existing ranks. Search only filters known entries; it never submits an arbitrary player name. TDGroupe-profile-import reads and parses the existing local usercache.json in the background, without online name lookups. Completed profiles are applied on the server thread; a login that occurs while the import is running takes priority over stale cached names. Offline profiles may appear shortly after startup. UUIDs preserve assignments and group membership across name changes. Players never seen by the server cannot be assigned until a local profile exists.

Server configuration and storage

The server-settings menu includes a translated information item explaining that existing groups and invitation deadlines are retained and that limits apply to new actions.

In world mode, serverconfig/tdgroupe-server.toml supplies the settings below. In database mode, edit them cluster-wide through /tdgroupe config:

Setting Default Meaning
maxGroupMembers 20 Includes the owner; lowering it does not remove existing members.
invitationSeconds 604800 Lifetime of new invitations in seconds (10-2592000); existing configured values remain unchanged.
showGroupNameInPublicChat true Show the group name in public chat; private group chat always retains it.
titles.idleSeconds 300 Stop crediting playtime after this many seconds without vanilla player activity; zero counts all online time.

TDGroupe uses network protocol 11 for screens and waypoint imports. Map transfers use protocol 12. Server and clients need matching builds. Title previews share the actual chat formatter and the TDLibrary name/tag formatter used by TD LeaderBoard.

Without the shared TDLibrary database ([database] enabled = true in config/tdlibrary-database.toml), and always in single-player worlds, groups, colors, ranks, profiles, assignments, invitations and pending notices are stored in the world's data/tdgroupe.dat using SavedData schema 2. DATABASE storage keeps the same state, titles and active time in MariaDB for several backends; see Database and several servers. Invalid, incomplete or future data fails closed instead of being overwritten with an empty state. Duplicate JSON fields, invalid JSON syntax and non-string text fields are rejected before loading. Back up this file together with the world. Valid schema 1 data migrates explicitly; existing groups start without managers. No release marker is created by a local build.

Retained notification history uses TDLibrary's MariaDB archive. In a cluster, TDLibrary 0.68.0 shares that archive and read status across backends. See Database and several servers for what to back up.